@a16njs/plugin-agentsmd 1.0.1

package/README.md

@@ -0,0 +1,73 @@
+# @a16njs/plugin-agentsmd
+
+[![npm version](https://img.shields.io/npm/v/@a16njs/plugin-agentsmd.svg)](https://www.npmjs.com/package/@a16njs/plugin-agentsmd)
+[![codecov](https://codecov.io/gh/Texarkanine/a16n/graph/badge.svg?flag=plugin-agentsmd)](https://codecov.io/gh/Texarkanine/a16n)
+
+[AGENTS.md](https://agents.md/) plugin for a16n. Discovers and emits AGENTS.md files at any directory depth.
+
+## Installation
+
+This plugin is bundled with the `a16n` CLI. For programmatic use:
+
+```bash
+npm install @a16njs/plugin-agentsmd
+```
+
+## Supported Types
+
+| Type | AGENTS.md Format | Description |
+|------|------------------|-------------|
+| **GlobalPrompt** | root `AGENTS.md` | Always-active instructions |
+| **FileRule** | `<dir>/AGENTS.md` | Directory-scoped instructions (directory-shaped globs only) |
+
+AGENTS.md is plain markdown with no frontmatter, globs, skills, commands, or ignore rules, so **converting into AGENTS.md is lossy** for everything else:
+
+- FileRules whose globs are not directory-shaped (e.g. `*.ts`) are skipped with a warning
+- Skills, manual prompts, and agent-ignore rules are reported as unsupported
+
+Converting *out of* AGENTS.md is lossless.
+
+## Supported Files
+
+### Discovery
+
+- `AGENTS.md` — root instructions (GlobalPrompt)
+- `<dir>/AGENTS.md` — nested instructions at any depth (FileRule with `globs: ['<dir>/**']`)
+
+Per the [AGENTS.md standard](https://agents.md/), a nested AGENTS.md provides instructions scoped to its subtree. a16n encodes that scoping as a directory-shaped glob so it converts into native path-scoped rules:
+
+- Cursor: `.cursor/rules/<dir>/AGENTSMD.mdc` with `globs: <dir>/**`
+- Claude Code: `.claude/rules/<dir>/AGENTSMD.md` with `paths:` frontmatter
+
+Discovery skips dot-directories and `node_modules`.
+
+### Emission
+
+- **GlobalPrompt** → root `AGENTS.md` (multiple prompts are concatenated, with a `merged` warning)
+- **GlobalPrompt** discovered from a nested `CLAUDE.md` → `<same-dir>/AGENTS.md`
+- **FileRule** with a single directory-shaped glob (`<dir>/**` or `<dir>/**/*`) → `<dir>/AGENTS.md`
+- Everything else → warning or unsupported (see above)
+
+Emission deterministically overwrites target files (output depends only on the converted items, so repeated conversions converge). Replacing a pre-existing `AGENTS.md` whose content differs produces an `overwritten` warning.
+
+When converting AGENTS.md into Cursor/Claude rules, a16n emits `AGENTSMD.*` rule filenames. See the plugin docs for rationale and collision behavior details: <https://texarkanine.github.io/a16n/plugin-agentsmd>.
+
+## Usage
+
+```typescript
+import agentsmdPlugin from '@a16njs/plugin-agentsmd';
+import { A16nEngine } from '@a16njs/engine';
+
+const engine = new A16nEngine([agentsmdPlugin]);
+
+// Discover AGENTS.md files
+const result = await agentsmdPlugin.discover('./my-project');
+console.log(`Found ${result.items.length} items`);
+
+// Emit to AGENTS.md format
+await agentsmdPlugin.emit(result.items, './my-project');
+```
+
+## Documentation
+
+Full documentation available at <https://texarkanine.github.io/a16n/plugin-agentsmd>.

package/dist/discover.d.ts

@@ -0,0 +1,17 @@
+import { type DiscoveryResult, type Workspace } from '@a16njs/models';
+/**
+ * Discover AGENTS.md files in a project directory tree.
+ *
+ * Mapping (see Issue #50 and the a16n IR model):
+ * - Root `AGENTS.md` → GlobalPrompt (always-applied instructions)
+ * - Nested `<dir>/AGENTS.md` → FileRule with `globs: ['<dir>/**']` and
+ *   `relativeDir: '<dir>'` — the AGENTS.md standard scopes nested files to
+ *   their subtree ("the closest AGENTS.md wins"), which the IR expresses as
+ *   a directory-shaped glob. This is what lets nested AGENTS.md files
+ *   convert into Cursor `globs:` rules and Claude `paths:` rules.
+ *
+ * @param rootOrWorkspace - Root directory path or Workspace instance
+ * @returns All customizations found and any warnings
+ */
+export declare function discover(rootOrWorkspace: string | Workspace): Promise<DiscoveryResult>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EAIpB,KAAK,SAAS,EAOf,MAAM,gBAAgB,CAAC;AA0CxB;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CAkD5F"}

package/dist/discover.js

@@ -0,0 +1,98 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { CustomizationType, WarningCode, createId, inferGlobalPromptName, resolveRoot, CURRENT_IR_VERSION, } from '@a16njs/models';
+/**
+ * Recursively find all AGENTS.md files in a directory tree.
+ * Returns POSIX-style paths relative to root (e.g., "AGENTS.md", "web/AGENTS.md").
+ *
+ * Skips dot-directories (e.g. `.git`, `.cursor`) and `node_modules`,
+ * matching the traversal rules of the other bundled plugins.
+ */
+async function findAgentsFiles(root, currentDir = '') {
+    const results = [];
+    const fullPath = currentDir ? path.join(root, currentDir) : root;
+    try {
+        const entries = await fs.readdir(fullPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            const relativePath = currentDir
+                ? `${currentDir}/${entry.name}`
+                : entry.name;
+            if (entry.isFile() && entry.name === 'AGENTS.md') {
+                results.push(relativePath);
+            }
+            else if (entry.isDirectory()) {
+                const nested = await findAgentsFiles(root, relativePath);
+                results.push(...nested);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read
+    }
+    return results;
+}
+/**
+ * Discover AGENTS.md files in a project directory tree.
+ *
+ * Mapping (see Issue #50 and the a16n IR model):
+ * - Root `AGENTS.md` → GlobalPrompt (always-applied instructions)
+ * - Nested `<dir>/AGENTS.md` → FileRule with `globs: ['<dir>/**']` and
+ *   `relativeDir: '<dir>'` — the AGENTS.md standard scopes nested files to
+ *   their subtree ("the closest AGENTS.md wins"), which the IR expresses as
+ *   a directory-shaped glob. This is what lets nested AGENTS.md files
+ *   convert into Cursor `globs:` rules and Claude `paths:` rules.
+ *
+ * @param rootOrWorkspace - Root directory path or Workspace instance
+ * @returns All customizations found and any warnings
+ */
+export async function discover(rootOrWorkspace) {
+    const root = resolveRoot(rootOrWorkspace);
+    const items = [];
+    const warnings = [];
+    const agentsFiles = await findAgentsFiles(root);
+    for (const file of agentsFiles) {
+        const fullPath = path.join(root, ...file.split('/'));
+        try {
+            const content = await fs.readFile(fullPath, 'utf-8');
+            const dir = path.posix.dirname(file);
+            const depth = dir === '.' ? 0 : dir.split('/').length;
+            if (dir === '.') {
+                // Root AGENTS.md → always-applied GlobalPrompt
+                items.push({
+                    id: createId(CustomizationType.GlobalPrompt, file),
+                    type: CustomizationType.GlobalPrompt,
+                    version: CURRENT_IR_VERSION,
+                    sourcePath: file,
+                    name: inferGlobalPromptName(file),
+                    content,
+                    metadata: { nested: false, depth },
+                });
+            }
+            else {
+                // Nested AGENTS.md → subtree-scoped FileRule
+                items.push({
+                    id: createId(CustomizationType.FileRule, file),
+                    type: CustomizationType.FileRule,
+                    version: CURRENT_IR_VERSION,
+                    sourcePath: file,
+                    relativeDir: dir,
+                    content,
+                    globs: [`${dir}/**`],
+                    metadata: { nested: true, depth },
+                });
+            }
+        }
+        catch (error) {
+            warnings.push({
+                code: WarningCode.Skipped,
+                message: `Could not read ${file}: ${error.message}`,
+                sources: [file],
+            });
+        }
+    }
+    return { items, warnings };
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"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"}

package/dist/emit.d.ts

@@ -0,0 +1,31 @@
+import { type AgentCustomization, type EmitResult, type EmitOptions, type Workspace } from '@a16njs/models';
+/**
+ * Emit agent customizations as AGENTS.md files.
+ *
+ * Placement:
+ * - GlobalPrompt → root `AGENTS.md`. `relativeDir` is deliberately ignored:
+ *   it describes file organization inside a rules directory, not scoping —
+ *   an always-applied prompt's only faithful AGENTS.md location is the root.
+ * - GlobalPrompt with `metadata.nested === true` and a `sourcePath` (nested
+ *   CLAUDE.md discovered by the claude plugin) → `dirname(sourcePath)/AGENTS.md`,
+ *   preserving the directory scoping those files carry. Falls back to the
+ *   root when the source directory is unusable (always-applied content is
+ *   never dropped).
+ * - FileRule whose globs are a single directory-shaped pattern (`<dir>/**`
+ *   or `<dir>/**\/*`) → `<dir>/AGENTS.md`. Other FileRules cannot be
+ *   represented in AGENTS.md and are skipped with a warning.
+ * - All other types are returned in `unsupported`.
+ *
+ * Write semantics: deterministic overwrite — output is a pure function of
+ * the input items, so repeated emission is idempotent. Multiple items
+ * targeting the same file are concatenated (`\n\n` joined, input order) with
+ * a `Merged` warning. Replacing a pre-existing file whose content differs
+ * produces an `Overwritten` warning; byte-identical re-writes stay silent.
+ *
+ * @param models - The customizations to emit
+ * @param rootOrWorkspace - Root directory path or Workspace instance to write to
+ * @param options - Optional emit options (e.g., dryRun)
+ * @returns Info about what was written (or would be written) and any issues
+ */
+export declare function emit(models: AgentCustomization[], rootOrWorkspace: string | Workspace, options?: EmitOptions): Promise<EmitResult>;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,WAAW,EAIhB,KAAK,SAAS,EAKf,MAAM,gBAAgB,CAAC;AAkDxB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,IAAI,CACxB,MAAM,EAAE,kBAAkB,EAAE,EAC5B,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CAyGrB"}

package/dist/emit.js

@@ -0,0 +1,174 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { WarningCode, isGlobalPrompt, isFileRule, resolveRoot, } from '@a16njs/models';
+/**
+ * Matches a directory-shaped glob: `<dir>/**` or `<dir>/**\/*`.
+ * Group 1 captures the directory part.
+ */
+const DIR_SHAPED_GLOB = /^(.+?)\/\*\*(\/\*)?$/;
+/** Glob metacharacters that disqualify a captured directory part. */
+const GLOB_METACHARS = /[*?[\]{}]/;
+/**
+ * Validate a POSIX-style relative directory and confirm it stays inside root.
+ * Returns the normalized relative dir ('' for root), or null when the input
+ * is absolute, contains empty/'..' segments, or escapes the root.
+ */
+function resolveSafeDir(root, dir) {
+    if (!dir || dir === '.')
+        return '';
+    if (dir.startsWith('/') || /^[A-Za-z]:/.test(dir))
+        return null;
+    const segments = dir.split('/');
+    if (segments.some(s => s === '' || s === '.' || s === '..'))
+        return null;
+    const resolved = path.resolve(root, ...segments);
+    const resolvedRoot = path.resolve(root);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+        return null;
+    }
+    return segments.join('/');
+}
+/**
+ * Extract the target directory for a FileRule, when its globs are exactly one
+ * directory-shaped pattern with a clean (metacharacter-free) directory part.
+ * Returns the POSIX relative dir, or null when the rule cannot be represented
+ * as a directory-scoped AGENTS.md.
+ */
+function fileRuleTargetDir(root, rule) {
+    if (rule.globs.length !== 1)
+        return null;
+    const glob = rule.globs[0].replace(/^\.\//, '');
+    const match = DIR_SHAPED_GLOB.exec(glob);
+    if (!match)
+        return null;
+    const dir = match[1];
+    if (GLOB_METACHARS.test(dir))
+        return null;
+    return resolveSafeDir(root, dir);
+}
+/**
+ * Emit agent customizations as AGENTS.md files.
+ *
+ * Placement:
+ * - GlobalPrompt → root `AGENTS.md`. `relativeDir` is deliberately ignored:
+ *   it describes file organization inside a rules directory, not scoping —
+ *   an always-applied prompt's only faithful AGENTS.md location is the root.
+ * - GlobalPrompt with `metadata.nested === true` and a `sourcePath` (nested
+ *   CLAUDE.md discovered by the claude plugin) → `dirname(sourcePath)/AGENTS.md`,
+ *   preserving the directory scoping those files carry. Falls back to the
+ *   root when the source directory is unusable (always-applied content is
+ *   never dropped).
+ * - FileRule whose globs are a single directory-shaped pattern (`<dir>/**`
+ *   or `<dir>/**\/*`) → `<dir>/AGENTS.md`. Other FileRules cannot be
+ *   represented in AGENTS.md and are skipped with a warning.
+ * - All other types are returned in `unsupported`.
+ *
+ * Write semantics: deterministic overwrite — output is a pure function of
+ * the input items, so repeated emission is idempotent. Multiple items
+ * targeting the same file are concatenated (`\n\n` joined, input order) with
+ * a `Merged` warning. Replacing a pre-existing file whose content differs
+ * produces an `Overwritten` warning; byte-identical re-writes stay silent.
+ *
+ * @param models - The customizations to emit
+ * @param rootOrWorkspace - Root directory path or Workspace instance to write to
+ * @param options - Optional emit options (e.g., dryRun)
+ * @returns Info about what was written (or would be written) and any issues
+ */
+export async function emit(models, rootOrWorkspace, options) {
+    const root = resolveRoot(rootOrWorkspace);
+    const dryRun = options?.dryRun ?? false;
+    const written = [];
+    const warnings = [];
+    const unsupported = [];
+    // Bucket items by target directory ('' = repo root), preserving input order.
+    const buckets = new Map();
+    const addToBucket = (dir, item) => {
+        const bucket = buckets.get(dir);
+        if (bucket) {
+            bucket.push(item);
+        }
+        else {
+            buckets.set(dir, [item]);
+        }
+    };
+    for (const model of models) {
+        if (isGlobalPrompt(model)) {
+            let dir = '';
+            if (model.metadata?.nested === true && model.sourcePath) {
+                const sourceDir = path.posix.dirname(model.sourcePath.split(path.sep).join('/'));
+                dir = resolveSafeDir(root, sourceDir) ?? '';
+            }
+            addToBucket(dir, model);
+        }
+        else if (isFileRule(model)) {
+            const dir = fileRuleTargetDir(root, model);
+            if (dir === null || dir === '') {
+                // '' means the glob resolved to the root itself, which a dir-scoped
+                // rule cannot legitimately do — treat it like any other unrepresentable glob.
+                warnings.push({
+                    code: WarningCode.Skipped,
+                    message: `FileRule skipped: globs cannot be represented as a directory-scoped AGENTS.md (${model.globs.join(', ')})`,
+                    sources: model.sourcePath ? [model.sourcePath] : [],
+                });
+                continue;
+            }
+            addToBucket(dir, model);
+        }
+        else {
+            unsupported.push(model);
+        }
+    }
+    // Deterministic output order: root first, then directories sorted.
+    const dirs = [...buckets.keys()].sort((a, b) => a === '' ? -1 : b === '' ? 1 : a.localeCompare(b));
+    for (const dir of dirs) {
+        const items = buckets.get(dir);
+        const targetDir = dir ? path.join(root, ...dir.split('/')) : root;
+        const targetPath = path.join(targetDir, 'AGENTS.md');
+        const relPath = dir ? `${dir}/AGENTS.md` : 'AGENTS.md';
+        const sources = items
+            .map(i => i.sourcePath)
+            .filter((s) => s !== undefined);
+        const content = items.map(i => i.content.trim()).join('\n\n') + '\n';
+        let existing = null;
+        try {
+            existing = await fs.readFile(targetPath, 'utf-8');
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === 'ENOENT') {
+                existing = null;
+            }
+            else {
+                throw error;
+            }
+        }
+        const isNewFile = existing === null;
+        if (!dryRun) {
+            await fs.mkdir(targetDir, { recursive: true });
+            await fs.writeFile(targetPath, content, 'utf-8');
+        }
+        written.push({
+            path: targetPath,
+            type: items[0].type,
+            itemCount: items.length,
+            isNewFile,
+            sourceItems: items,
+        });
+        if (items.length > 1) {
+            warnings.push({
+                code: WarningCode.Merged,
+                message: `Merged ${items.length} items into ${relPath}`,
+                sources,
+            });
+        }
+        if (!isNewFile && existing !== content) {
+            warnings.push({
+                code: WarningCode.Overwritten,
+                message: `Replaced existing ${relPath}`,
+                sources,
+            });
+        }
+    }
+    return { written, warnings, unsupported };
+}
+//# sourceMappingURL=emit.js.map

package/dist/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { type A16nPlugin } from '@a16njs/models';
+/**
+ * AGENTS.md plugin for a16n.
+ *
+ * Discovers AGENTS.md files at any directory depth (root → GlobalPrompt,
+ * nested → directory-scoped FileRule) and emits GlobalPrompts and
+ * directory-shaped FileRules back to AGENTS.md files.
+ *
+ * AGENTS.md is plain markdown with no frontmatter, globs, or skills, so
+ * conversion into this format is lossy for most customization types; the
+ * standard warning channels (`skipped`, `merged`, `overwritten`) and the
+ * `unsupported` result surface exactly what could not be represented.
+ *
+ * No `pathPatterns`: AGENTS.md files have no fixed directory prefix (they
+ * live at any depth), so this plugin opts out of the engine's path-reference
+ * scanning rather than misreporting it.
+ */
+declare const agentsmdPlugin: A16nPlugin;
+export default agentsmdPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,gBAAgB,CAAC;AAIpE;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,cAAc,EAAE,UAUrB,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import { CustomizationType } from '@a16njs/models';
+import { discover } from './discover.js';
+import { emit } from './emit.js';
+/**
+ * AGENTS.md plugin for a16n.
+ *
+ * Discovers AGENTS.md files at any directory depth (root → GlobalPrompt,
+ * nested → directory-scoped FileRule) and emits GlobalPrompts and
+ * directory-shaped FileRules back to AGENTS.md files.
+ *
+ * AGENTS.md is plain markdown with no frontmatter, globs, or skills, so
+ * conversion into this format is lossy for most customization types; the
+ * standard warning channels (`skipped`, `merged`, `overwritten`) and the
+ * `unsupported` result surface exactly what could not be represented.
+ *
+ * No `pathPatterns`: AGENTS.md files have no fixed directory prefix (they
+ * live at any depth), so this plugin opts out of the engine's path-reference
+ * scanning rather than misreporting it.
+ */
+const agentsmdPlugin = {
+    id: 'agentsmd',
+    name: 'AGENTS.md',
+    supports: [
+        CustomizationType.GlobalPrompt,
+        CustomizationType.FileRule,
+    ],
+    discover,
+    emit,
+};
+export default agentsmdPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,cAAc,GAAe;IACjC,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE;QACR,iBAAiB,CAAC,YAAY;QAC9B,iBAAiB,CAAC,QAAQ;KAC3B;IAED,QAAQ;IACR,IAAI;CACL,CAAC;AAEF,eAAe,cAAc,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@a16njs/plugin-agentsmd",
+  "version": "1.0.1",
+  "description": "AGENTS.md plugin for a16n",
+  "license": "AGPL-3.0",
+  "author": "Texarkanine",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Texarkanine/a16n.git",
+    "directory": "packages/plugin-agentsmd"
+  },
+  "homepage": "https://texarkanine.github.io/a16n/plugin-agentsmd",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@a16njs/models": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}