@agentrel/core

Pure-function parsers, drift analyzer, and synthesizer for AgentRel. This is the L1 logic library — no node:fs, no node:http, no node:https, no analytics SDKs. Safe to use from Node, Bun, Cloudflare Workers, or any other JavaScript runtime that ships ES modules.

If you're a CLI user, install agentrel instead. This package is for embedding the drift detector into your own tooling.

Install

npm install @agentrel/core

Quick start

import { analyzeDrift, parseMarkdown, renderScanJson } from '@agentrel/core'

const agents = parseMarkdown('AGENTS.md', agentsMdContent)
const claude = parseMarkdown('CLAUDE.md', claudeMdContent)

const conflicts = analyzeDrift(agents, claude)
const json = renderScanJson({ conflicts }, ['AGENTS.md', 'CLAUDE.md'])

The library is platform-agnostic: you supply file contents as strings (no IO). Two seams let you wire IO from your runtime:

• FileSource — list() + read(path) for ingesting target files
• FileTarget — write(path, content) for writing synthesized output

Node implementations live in the agentrel CLI package as NodeFileSource and NodeFileTarget. Edge / worker implementations are yours to write.

Public API

// Drift detection
export function analyzeDrift(a: ParsedConfig, b: ParsedConfig): Conflict[]
export function parseMarkdown(path: string, content: string): ParsedConfig

// Bootstrap
export function init(source: FileSource, target: FileTarget, opts?: InitOptions): Promise<InitResult>
export function synthesize(signals: InitSignals): SynthesizedFiles

// Rendering
export function renderScanJson(result: ScanResult, filesScanned: readonly string[]): string
// (HumanRenderer lives in the `agentrel` CLI package — needs picocolors.)

// Errors — all extend AgentrelError, all carry what / why / nextStep
export class AgentrelError extends Error { readonly exitCode: 1 | 2 }
export class ParseError extends AgentrelError {}
export class IOError extends AgentrelError {}
export class ConfigError extends AgentrelError {}
export class AlreadyExistsError extends AgentrelError {} // exit 1
export class NoIdeDetectedError extends AgentrelError {} // exit 1

Types: Conflict, ConflictKind, ConflictLocation, FileSource, FileTarget, ParsedConfig, ParsedSection, FencedBlock, ScanResult, ScanJsonReport, InitResult, InitOptions, InitSignals, SynthesizedFiles, Severity, Renderer.

Constants: SEVERITY_WEIGHTS, MIN_SCORE, MAX_SCORE, DRIFT_HEADER, NO_DRIFT_MESSAGE, NO_CONFIG_FILES_MESSAGE, CLAUDE_SKILL_DATA_POLICY_DISCLOSURE.

What's a "conflict"?

Two detection paths run per scan:

• Command drift — for each intent heading (Build / Test / Dev / Install) present in both files, compare the first fenced code block. Different commands emit a command conflict.
• Forbidden-behavior drift — prescriptive prose statements ("always X", "never Y") in matching topic clusters that disagree emit a forbidden-behavior conflict.

One-sided absence (a section in only one file) is not drift.

Trust posture

The published package has no fetch / http / https imports, no analytics SDKs, no postinstall script. The only runtime dependency is gray-matter for YAML frontmatter parsing. Trust-posture-as-code lint enforcement (NFR7) lands in v0.2.

License

Apache-2.0