agentsmap 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# agentsmap
+
+CLI tool for the [AGENTS.map](https://github.com/ygwyg/agents.map) specification — discover, validate, and resolve `AGENTS.md` instruction files.
+
+## Install
+
+```bash
+npm install -g agentsmap
+```
+
+Or run directly with `npx`:
+
+```bash
+npx agentsmap init
+```
+
+## Commands
+
+### `agentsmap init`
+
+Scan your repo for `AGENTS.md` files and generate an `AGENTS.map.md` at the root.
+
+```bash
+agentsmap init
+```
+
+Interactive by default — prompts you for each file's purpose. Use `--non-interactive` to auto-infer purposes from file contents:
+
+```bash
+agentsmap init --non-interactive
+```
+
+### `agentsmap validate`
+
+Check that your `AGENTS.map.md` is valid: all listed paths exist, required fields are present, no duplicates, no path traversal.
+
+```bash
+agentsmap validate
+```
+
+Use this in CI to catch stale entries:
+
+```yaml
+# .github/workflows/agents-map.yml
+- run: npx agentsmap validate
+```
+
+Exits with code 1 on errors. Warnings (like unlisted `AGENTS.md` files) don't fail the check.
+
+### `agentsmap resolve <path>`
+
+Show which `AGENTS.md` files apply to a given path, ranked by specificity.
+
+```bash
+agentsmap resolve src/services/payments/checkout.ts
+```
+
+Output:
+
+```
+2 AGENTS.md file(s) apply to src/services/payments/checkout.ts:
+
+(most specific)
+  services/payments/AGENTS.md
+    Purpose: PCI rules, Stripe integration patterns.
+    Matched pattern: services/payments/**
+    Specificity: 6
+    Owners: @payments-team
+
+(#2)
+  AGENTS.md
+    Purpose: Global repo conventions.
+    Matched pattern: **
+    Specificity: 0
+```
+
+Use `--json` for machine-readable output:
+
+```bash
+agentsmap resolve src/payments/checkout.ts --json
+```
+
+### `agentsmap discover`
+
+Find all `AGENTS.md` files in your repo and show whether they're listed in the map.
+
+```bash
+agentsmap discover
+```
+
+Output shows listed files with `+` and unlisted with `?`, along with suggested purposes.
+
+## Programmatic API
+
+You can import the parser, resolver, and validator directly:
+
+```typescript
+import { parseMarkdown } from "agentsmap/parser";
+import { resolveEntries } from "agentsmap/resolver";
+import { validate } from "agentsmap/validator";
+
+const map = parseMarkdown(markdownContent);
+const matches = resolveEntries(map, "src/payments/checkout.ts");
+const result = validate(map, "/path/to/repo");
+```
+
+## How it works
+
+`AGENTS.map.md` is a plain Markdown file at your repo root that indexes all `AGENTS.md` files:
+
+```markdown
+# AGENTS.map
+
+## Entries
+
+- Path: /AGENTS.md
+  - Purpose: Global repo conventions.
+  - Applies to: /**
+
+- Path: /services/payments/AGENTS.md
+  - Purpose: PCI rules, Stripe patterns.
+  - Applies to: /services/payments/**
+  - Owners: @payments-team
+```
+
+When an agent enters your repo, it reads this file, matches entries by glob pattern, and loads the most specific instructions. If the map is missing or stale, agents fall back to scanning — nothing breaks.
+
+Full spec: [spec/v1.md](https://github.com/ygwyg/agents.map/blob/main/spec/v1.md)
+
+## License
+
+MIT

package/dist/discoverer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Discover AGENTS.md files by scanning the filesystem.
+ */
+/**
+ * Recursively scan a directory for AGENTS.md files.
+ * Returns POSIX-style relative paths from rootDir.
+ */
+export declare function discoverAgentFiles(rootDir: string): string[];
+/**
+ * Read the first meaningful line from an AGENTS.md file to infer a purpose.
+ * Skips blank lines and heading markers.
+ */
+export declare function inferPurpose(filePath: string): string;

package/dist/discoverer.js

@@ -0,0 +1,102 @@
+/**
+ * Discover AGENTS.md files by scanning the filesystem.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Directories to always skip when scanning. */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".hg",
+    ".svn",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".tox",
+    "vendor",
+    ".bundle",
+    "target",
+    "coverage",
+    ".cache",
+    ".turbo",
+]);
+/**
+ * Recursively scan a directory for AGENTS.md files.
+ * Returns POSIX-style relative paths from rootDir.
+ */
+export function discoverAgentFiles(rootDir) {
+    const results = [];
+    scanDir(rootDir, rootDir, results);
+    return results.sort();
+}
+function scanDir(currentDir, rootDir, results) {
+    let entries;
+    try {
+        entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    }
+    catch {
+        // Permission denied or other read error — skip
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+                // Allow .github but skip other dot directories
+                if (entry.name !== ".github")
+                    continue;
+            }
+            scanDir(path.join(currentDir, entry.name), rootDir, results);
+        }
+        else if (entry.isFile() && entry.name === "AGENTS.md") {
+            const relativePath = path
+                .relative(rootDir, path.join(currentDir, entry.name))
+                .replace(/\\/g, "/");
+            results.push(relativePath);
+        }
+    }
+}
+/**
+ * Read the first meaningful line from an AGENTS.md file to infer a purpose.
+ * Skips blank lines and heading markers.
+ */
+export function inferPurpose(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const lines = content.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip empty lines
+            if (!trimmed)
+                continue;
+            // If it's a heading, extract the heading text
+            const headingMatch = trimmed.match(/^#+\s+(.+)$/);
+            if (headingMatch) {
+                const heading = headingMatch[1].trim();
+                // Skip generic headings
+                if (/^agents(\.md)?$/i.test(heading))
+                    continue;
+                return heading;
+            }
+            // Skip horizontal rules
+            if (/^[-=*]{3,}$/.test(trimmed))
+                continue;
+            // Skip HTML comments
+            if (trimmed.startsWith("<!--"))
+                continue;
+            // Use first meaningful text line (truncated)
+            const maxLen = 120;
+            if (trimmed.length > maxLen) {
+                return trimmed.slice(0, maxLen) + "...";
+            }
+            return trimmed;
+        }
+    }
+    catch {
+        // Can't read file — fall through to placeholder
+    }
+    return "TODO: Describe this file's purpose.";
+}

package/dist/generator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Generate AGENTS.map.md files.
+ */
+import type { AgentsMap } from "./types.js";
+/** Build a default scope from the path of an AGENTS.md file. */
+export declare function defaultScope(agentsPath: string): string[];
+/** Create a new AgentsMap structure from discovered files. */
+export declare function createMap(entries: Array<{
+    path: string;
+    purpose: string;
+    owners?: string[];
+    tags?: string[];
+}>): AgentsMap;
+/** Serialize an AgentsMap to Markdown format. */
+export declare function toMarkdown(map: AgentsMap): string;

package/dist/generator.js

@@ -0,0 +1,58 @@
+/**
+ * Generate AGENTS.map.md files.
+ */
+import * as path from "node:path";
+/** Build a default scope from the path of an AGENTS.md file. */
+export function defaultScope(agentsPath) {
+    const dir = path.posix.dirname(agentsPath);
+    if (dir === ".") {
+        // Root AGENTS.md applies to everything
+        return ["**"];
+    }
+    return [`${dir}/**`];
+}
+/** Create a new AgentsMap structure from discovered files. */
+export function createMap(entries) {
+    return {
+        schema_version: 1,
+        entries: entries.map((e) => {
+            const entry = {
+                path: e.path,
+                scope: defaultScope(e.path),
+                purpose: e.purpose,
+            };
+            if (e.owners && e.owners.length > 0)
+                entry.owners = e.owners;
+            if (e.tags && e.tags.length > 0)
+                entry.tags = e.tags;
+            return entry;
+        }),
+    };
+}
+/** Serialize an AgentsMap to Markdown format. */
+export function toMarkdown(map) {
+    const lines = [];
+    lines.push("# AGENTS.map");
+    lines.push("");
+    lines.push("This file lists where nested AGENTS.md files live and what they're for.");
+    lines.push("The AGENTS.md files themselves are authoritative for their subtrees.");
+    lines.push("");
+    lines.push("## Entries");
+    lines.push("");
+    for (const entry of map.entries) {
+        lines.push(`- Path: /${entry.path}`);
+        lines.push(`  - Purpose: ${entry.purpose}`);
+        lines.push(`  - Applies to: ${entry.scope.map((s) => `/${s}`).join(", ")}`);
+        if (entry.owners && entry.owners.length > 0) {
+            lines.push(`  - Owners: ${entry.owners.join(", ")}`);
+        }
+        if (entry.tags && entry.tags.length > 0) {
+            lines.push(`  - Tags: ${entry.tags.join(", ")}`);
+        }
+        if (entry.last_reviewed) {
+            lines.push(`  - Last reviewed: ${entry.last_reviewed}`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * agentsmap — CLI tool for the AGENTS.map specification.
+ *
+ * Discover, validate, and resolve AGENTS.md instruction files.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * agentsmap — CLI tool for the AGENTS.map specification.
+ *
+ * Discover, validate, and resolve AGENTS.md instruction files.
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { parseMap, findMap } from "./parser.js";
+import { validate } from "./validator.js";
+import { resolveEntries, formatMatch } from "./resolver.js";
+import { discoverAgentFiles, inferPurpose } from "./discoverer.js";
+import { createMap, toMarkdown } from "./generator.js";
+const program = new Command();
+program
+    .name("agentsmap")
+    .description("CLI tool for the AGENTS.map specification — discover, validate, and resolve AGENTS.md files.")
+    .version("0.1.0");
+// ──────────────────────────────────────────────────────────────────────────────
+// init
+// ──────────────────────────────────────────────────────────────────────────────
+program
+    .command("init")
+    .description("Scan for AGENTS.md files and generate an AGENTS.map.md file.")
+    .option("--non-interactive", "Skip interactive prompts; use inferred or placeholder purposes.")
+    .action(async (opts) => {
+    const cwd = process.cwd();
+    console.log(chalk.blue("Scanning for AGENTS.md files..."));
+    const files = discoverAgentFiles(cwd);
+    if (files.length === 0) {
+        console.log(chalk.yellow("No AGENTS.md files found in this directory tree."));
+        console.log(chalk.dim("Create an AGENTS.md file and run this command again."));
+        process.exit(0);
+    }
+    console.log(chalk.green(`Found ${files.length} AGENTS.md file(s):\n`));
+    for (const file of files) {
+        console.log(`  ${chalk.cyan(file)}`);
+    }
+    console.log();
+    const entries = [];
+    if (opts.nonInteractive) {
+        // Non-interactive: infer purpose from file content
+        for (const file of files) {
+            const fullPath = path.join(cwd, file);
+            const purpose = inferPurpose(fullPath);
+            entries.push({ path: file, purpose });
+            console.log(`  ${chalk.cyan(file)} ${chalk.dim("->")} ${purpose}`);
+        }
+    }
+    else {
+        // Interactive: prompt for each purpose
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+        for (const file of files) {
+            const fullPath = path.join(cwd, file);
+            const inferred = inferPurpose(fullPath);
+            const defaultText = inferred !== "TODO: Describe this file's purpose." ? inferred : "";
+            const hint = defaultText ? chalk.dim(` (default: "${defaultText}")`) : "";
+            const answer = await question(`${chalk.cyan(file)} - Purpose${hint}: `);
+            const purpose = answer.trim() || defaultText || "TODO: Describe this file's purpose.";
+            entries.push({ path: file, purpose });
+        }
+        rl.close();
+    }
+    const map = createMap(entries);
+    const content = toMarkdown(map);
+    const outputPath = path.join(cwd, "AGENTS.map.md");
+    // Check if file already exists
+    if (fs.existsSync(outputPath)) {
+        console.log(chalk.yellow(`\nAGENTS.map.md already exists. Overwriting.`));
+    }
+    fs.writeFileSync(outputPath, content, "utf-8");
+    console.log(chalk.green(`\nCreated ${chalk.bold("AGENTS.map.md")} with ${entries.length} entries.`));
+    console.log(chalk.dim("Run `agentsmap validate` to check the generated file."));
+});
+// ──────────────────────────────────────────────────────────────────────────────
+// validate / check
+// ──────────────────────────────────────────────────────────────────────────────
+const validateAction = () => {
+    const cwd = process.cwd();
+    const mapPath = findMap(cwd);
+    if (!mapPath) {
+        console.log(chalk.red("No AGENTS.map.md found."));
+        console.log(chalk.dim("Run `agentsmap init` to create one."));
+        process.exit(1);
+    }
+    console.log(chalk.blue(`Validating ${chalk.bold("AGENTS.map.md")}...\n`));
+    let map;
+    try {
+        const result = parseMap(cwd);
+        map = result.map;
+    }
+    catch (err) {
+        console.log(chalk.red(`Parse error: ${err.message}`));
+        process.exit(1);
+    }
+    const result = validate(map, cwd);
+    const errors = result.diagnostics.filter((d) => d.severity === "error");
+    const warnings = result.diagnostics.filter((d) => d.severity === "warning");
+    for (const diag of errors) {
+        console.log(`  ${chalk.red("error")}  ${diag.message}`);
+    }
+    for (const diag of warnings) {
+        console.log(`  ${chalk.yellow("warn")}   ${diag.message}`);
+    }
+    if (errors.length === 0 && warnings.length === 0) {
+        console.log(chalk.green("All checks passed. No issues found."));
+    }
+    else {
+        console.log();
+        if (errors.length > 0) {
+            console.log(chalk.red(`${errors.length} error(s)`));
+        }
+        if (warnings.length > 0) {
+            console.log(chalk.yellow(`${warnings.length} warning(s)`));
+        }
+    }
+    if (!result.valid) {
+        process.exit(1);
+    }
+};
+program
+    .command("validate")
+    .description("Validate the AGENTS.map.md file in the current directory.")
+    .action(validateAction);
+program
+    .command("check")
+    .description("Alias for validate.")
+    .action(validateAction);
+// ──────────────────────────────────────────────────────────────────────────────
+// resolve
+// ──────────────────────────────────────────────────────────────────────────────
+program
+    .command("resolve <target-path>")
+    .description("Show which AGENTS.md files apply to a given path.")
+    .option("--json", "Output in JSON format.")
+    .action((targetPath, opts) => {
+    const cwd = process.cwd();
+    let map;
+    try {
+        const result = parseMap(cwd);
+        map = result.map;
+    }
+    catch (err) {
+        console.log(chalk.red(err.message));
+        process.exit(1);
+    }
+    const matches = resolveEntries(map, targetPath);
+    if (opts.json) {
+        const output = matches.map((m) => ({
+            path: m.entry.path,
+            purpose: m.entry.purpose,
+            matchedPattern: m.matchedPattern,
+            specificity: m.specificity,
+            owners: m.entry.owners,
+            tags: m.entry.tags,
+        }));
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    if (matches.length === 0) {
+        console.log(chalk.yellow(`No AGENTS.md files apply to "${targetPath}".`));
+        return;
+    }
+    console.log(chalk.blue(`${matches.length} AGENTS.md file(s) apply to ${chalk.bold(targetPath)}:\n`));
+    for (let i = 0; i < matches.length; i++) {
+        const match = matches[i];
+        const rank = i + 1;
+        const label = i === 0 ? chalk.green("(most specific)") : chalk.dim(`(#${rank})`);
+        console.log(`${label}`);
+        console.log(formatMatch(match));
+        console.log();
+    }
+});
+// ──────────────────────────────────────────────────────────────────────────────
+// discover
+// ──────────────────────────────────────────────────────────────────────────────
+program
+    .command("discover")
+    .description("Scan for all AGENTS.md files and show their listing status.")
+    .action(() => {
+    const cwd = process.cwd();
+    console.log(chalk.blue("Scanning for AGENTS.md files...\n"));
+    const files = discoverAgentFiles(cwd);
+    if (files.length === 0) {
+        console.log(chalk.yellow("No AGENTS.md files found."));
+        return;
+    }
+    // Try to load existing map
+    let listedPaths = new Set();
+    let hasMap = false;
+    try {
+        const result = parseMap(cwd);
+        listedPaths = new Set(result.map.entries.map((e) => e.path));
+        hasMap = true;
+    }
+    catch {
+        // No map file or parse error — treat everything as unlisted
+    }
+    const listed = [];
+    const unlisted = [];
+    for (const file of files) {
+        if (listedPaths.has(file)) {
+            listed.push(file);
+        }
+        else {
+            unlisted.push(file);
+        }
+    }
+    if (hasMap) {
+        if (listed.length > 0) {
+            console.log(chalk.green(`Listed in AGENTS.map.md (${listed.length}):`));
+            for (const f of listed) {
+                console.log(`  ${chalk.green("+")} ${f}`);
+            }
+            console.log();
+        }
+        if (unlisted.length > 0) {
+            console.log(chalk.yellow(`Not listed in AGENTS.map.md (${unlisted.length}):`));
+            for (const f of unlisted) {
+                const purpose = inferPurpose(path.join(cwd, f));
+                console.log(`  ${chalk.yellow("?")} ${f}`);
+                console.log(`    ${chalk.dim(`Suggested purpose: ${purpose}`)}`);
+            }
+            console.log();
+            console.log(chalk.dim('Run `agentsmap init` to regenerate the map, or manually add entries.'));
+        }
+        else {
+            console.log(chalk.green("All AGENTS.md files are listed in the map."));
+        }
+    }
+    else {
+        console.log(`Found ${files.length} AGENTS.md file(s):\n`);
+        for (const f of files) {
+            const purpose = inferPurpose(path.join(cwd, f));
+            console.log(`  ${chalk.cyan(f)}`);
+            console.log(`    ${chalk.dim(purpose)}`);
+        }
+        console.log();
+        console.log(chalk.dim("No AGENTS.map.md found. Run `agentsmap init` to create one."));
+    }
+    // Also check for entries in the map that point to missing files
+    if (hasMap) {
+        const result = parseMap(cwd);
+        const missingEntries = result.map.entries.filter((e) => !files.includes(e.path));
+        if (missingEntries.length > 0) {
+            console.log();
+            console.log(chalk.red(`Stale entries in AGENTS.map.md (file missing):`));
+            for (const e of missingEntries) {
+                console.log(`  ${chalk.red("x")} ${e.path}`);
+            }
+        }
+    }
+});
+// ──────────────────────────────────────────────────────────────────────────────
+// Run
+// ──────────────────────────────────────────────────────────────────────────────
+program.parse();

package/dist/parser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse AGENTS.map.md files.
+ */
+import type { AgentsMap } from "./types.js";
+/** Find the AGENTS.map.md file in the given directory. */
+export declare function findMap(dir: string): string | null;
+/** Parse an AGENTS.map.md file from a given directory. */
+export declare function parseMap(dir: string): {
+    map: AgentsMap;
+    filePath: string;
+};
+/** Parse AGENTS.map.md content into an AgentsMap structure. */
+export declare function parseMarkdown(content: string): AgentsMap;

package/dist/parser.js

@@ -0,0 +1,105 @@
+/**
+ * Parse AGENTS.map.md files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+const MAP_FILENAME = "AGENTS.map.md";
+/** Find the AGENTS.map.md file in the given directory. */
+export function findMap(dir) {
+    const mapPath = path.join(dir, MAP_FILENAME);
+    if (fs.existsSync(mapPath)) {
+        return mapPath;
+    }
+    return null;
+}
+/** Parse an AGENTS.map.md file from a given directory. */
+export function parseMap(dir) {
+    const filePath = findMap(dir);
+    if (!filePath) {
+        throw new Error(`No AGENTS.map.md found in ${dir}. Run \`agentsmap init\` to create one.`);
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const map = parseMarkdown(content);
+    return { map, filePath };
+}
+/** Parse AGENTS.map.md content into an AgentsMap structure. */
+export function parseMarkdown(content) {
+    const entries = [];
+    const lines = content.split("\n");
+    let currentEntry = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Match "- Path: /some/path" or "- Path: some/path"
+        const pathMatch = trimmed.match(/^-\s+Path:\s+\/?(.+)$/i);
+        if (pathMatch) {
+            // Save previous entry if complete
+            if (currentEntry && currentEntry.path) {
+                entries.push(finalizeEntry(currentEntry));
+            }
+            currentEntry = { path: pathMatch[1].trim() };
+            continue;
+        }
+        if (!currentEntry)
+            continue;
+        // Match "- Purpose: ..."
+        const purposeMatch = trimmed.match(/^-\s+Purpose:\s+(.+)$/i);
+        if (purposeMatch) {
+            currentEntry.purpose = purposeMatch[1].trim();
+            continue;
+        }
+        // Match "- Applies to: ..." (one or more comma-separated globs)
+        const scopeMatch = trimmed.match(/^-\s+Applies\s+to:\s+(.+)$/i);
+        if (scopeMatch) {
+            currentEntry.scope = scopeMatch[1]
+                .split(",")
+                .map((s) => s.trim())
+                .map((s) => (s.startsWith("/") ? s.slice(1) : s));
+            continue;
+        }
+        // Match "- Owners: ..."
+        const ownersMatch = trimmed.match(/^-\s+Owners?:\s+(.+)$/i);
+        if (ownersMatch) {
+            currentEntry.owners = ownersMatch[1]
+                .split(",")
+                .map((o) => o.trim());
+            continue;
+        }
+        // Match "- Tags: ..."
+        const tagsMatch = trimmed.match(/^-\s+Tags?:\s+(.+)$/i);
+        if (tagsMatch) {
+            currentEntry.tags = tagsMatch[1]
+                .split(",")
+                .map((t) => t.trim());
+            continue;
+        }
+        // Match "- Last reviewed: ..."
+        const reviewedMatch = trimmed.match(/^-\s+Last\s+reviewed:\s+(.+)$/i);
+        if (reviewedMatch) {
+            currentEntry.last_reviewed = reviewedMatch[1].trim();
+            continue;
+        }
+    }
+    // Don't forget the last entry
+    if (currentEntry && currentEntry.path) {
+        entries.push(finalizeEntry(currentEntry));
+    }
+    return {
+        schema_version: 1,
+        entries,
+    };
+}
+/** Finalize a partially-parsed entry with defaults for missing fields. */
+function finalizeEntry(partial) {
+    const entry = {
+        path: partial.path,
+        scope: partial.scope ?? ["**"],
+        purpose: partial.purpose ?? "",
+    };
+    if (partial.owners)
+        entry.owners = partial.owners;
+    if (partial.tags)
+        entry.tags = partial.tags;
+    if (partial.last_reviewed)
+        entry.last_reviewed = partial.last_reviewed;
+    return entry;
+}

package/dist/resolver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Path resolution and scope matching for AGENTS.map entries.
+ */
+import type { AgentsMap, ResolveMatch } from "./types.js";
+/**
+ * Calculate the specificity of a glob pattern.
+ * More specific patterns have higher scores.
+ *
+ * Heuristic:
+ * - Count non-wildcard path segments
+ * - "**" alone is least specific
+ * - Longer literal prefixes are more specific
+ */
+export declare function calculateSpecificity(pattern: string): number;
+/**
+ * Resolve which AGENTS.md entries apply to a given target path.
+ * Returns matches sorted by specificity (most specific first).
+ */
+export declare function resolveEntries(map: AgentsMap, targetPath: string): ResolveMatch[];
+/**
+ * Format a resolved match for human-readable display.
+ */
+export declare function formatMatch(match: ResolveMatch): string;

package/dist/resolver.js

@@ -0,0 +1,88 @@
+/**
+ * Path resolution and scope matching for AGENTS.map entries.
+ */
+import picomatch from "picomatch";
+/**
+ * Calculate the specificity of a glob pattern.
+ * More specific patterns have higher scores.
+ *
+ * Heuristic:
+ * - Count non-wildcard path segments
+ * - "**" alone is least specific
+ * - Longer literal prefixes are more specific
+ */
+export function calculateSpecificity(pattern) {
+    // Remove leading slash if present
+    const normalized = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+    // "**" alone matches everything — lowest specificity
+    if (normalized === "**")
+        return 0;
+    const segments = normalized.split("/");
+    let score = 0;
+    for (const seg of segments) {
+        if (seg === "**") {
+            // Double wildcard doesn't add specificity
+            score += 0;
+        }
+        else if (seg === "*") {
+            // Single wildcard adds minimal specificity
+            score += 1;
+        }
+        else if (seg.includes("*") || seg.includes("?")) {
+            // Partial wildcard — somewhat specific
+            score += 2;
+        }
+        else {
+            // Literal segment — most specific
+            score += 3;
+        }
+    }
+    return score;
+}
+/**
+ * Resolve which AGENTS.md entries apply to a given target path.
+ * Returns matches sorted by specificity (most specific first).
+ */
+export function resolveEntries(map, targetPath) {
+    // Normalize target path: strip leading slash and backslashes
+    const normalized = targetPath
+        .replace(/\\/g, "/")
+        .replace(/^\//, "");
+    const matches = [];
+    for (const entry of map.entries) {
+        for (const pattern of entry.scope) {
+            // Normalize pattern: strip leading slash
+            const normalizedPattern = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+            const isMatch = picomatch(normalizedPattern);
+            if (isMatch(normalized)) {
+                matches.push({
+                    entry,
+                    matchedPattern: pattern,
+                    specificity: calculateSpecificity(pattern),
+                });
+                // Only match the first (most specific) pattern per entry
+                break;
+            }
+        }
+    }
+    // Sort by specificity (most specific first)
+    matches.sort((a, b) => b.specificity - a.specificity);
+    return matches;
+}
+/**
+ * Format a resolved match for human-readable display.
+ */
+export function formatMatch(match) {
+    const lines = [];
+    lines.push(`  ${match.entry.path}`);
+    lines.push(`    Purpose: ${match.entry.purpose}`);
+    lines.push(`    Matched pattern: ${match.matchedPattern}`);
+    lines.push(`    Specificity: ${match.specificity}`);
+    if (match.entry.owners && match.entry.owners.length > 0) {
+        lines.push(`    Owners: ${match.entry.owners.join(", ")}`);
+    }
+    if (match.entry.tags && match.entry.tags.length > 0) {
+        lines.push(`    Tags: ${match.entry.tags.join(", ")}`);
+    }
+    return lines.join("\n");
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AGENTS.map type definitions (v1 spec).
+ */
+/** A single entry in the AGENTS.map.md file. */
+export interface AgentsMapEntry {
+    /** POSIX path relative to repo root. Must not contain ".." or start with "/". */
+    path: string;
+    /** Glob patterns indicating which paths this entry applies to. */
+    scope: string[];
+    /** 1-3 sentences explaining why/when to use this file. */
+    purpose: string;
+    /** Optional team handles, CODEOWNERS aliases, etc. */
+    owners?: string[];
+    /** Optional categorical labels. */
+    tags?: string[];
+    /** Optional date in YYYY-MM-DD format. */
+    last_reviewed?: string;
+}
+/** The parsed AGENTS.map structure. */
+export interface AgentsMap {
+    /** Must be 1 for this version of the spec. */
+    schema_version: number;
+    /** Array of entry objects. */
+    entries: AgentsMapEntry[];
+}
+/** Validation severity levels. */
+export type Severity = "error" | "warning";
+/** A single validation diagnostic. */
+export interface ValidationDiagnostic {
+    severity: Severity;
+    message: string;
+    /** The entry path this diagnostic relates to, if applicable. */
+    entryPath?: string;
+}
+/** Result of validation. */
+export interface ValidationResult {
+    valid: boolean;
+    diagnostics: ValidationDiagnostic[];
+}
+/** Result of resolving a target path against the map. */
+export interface ResolveMatch {
+    entry: AgentsMapEntry;
+    /** The specific scope pattern that matched. */
+    matchedPattern: string;
+    /** Specificity score (higher = more specific). */
+    specificity: number;
+}
+/** A discovered AGENTS.md file on disk. */
+export interface DiscoveredFile {
+    /** Relative POSIX path from the repo root. */
+    path: string;
+    /** Whether this file is listed in the current AGENTS.map. */
+    listed: boolean;
+    /** First meaningful line content, used for purpose inference. */
+    firstLine?: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * AGENTS.map type definitions (v1 spec).
+ */
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validation logic for AGENTS.map.md files.
+ */
+import type { AgentsMap, ValidationResult } from "./types.js";
+/** Validate an AGENTS.map structure against the v1 spec rules. */
+export declare function validate(map: AgentsMap, rootDir: string): ValidationResult;

package/dist/validator.js

@@ -0,0 +1,102 @@
+/**
+ * Validation logic for AGENTS.map.md files.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { discoverAgentFiles } from "./discoverer.js";
+/** Validate an AGENTS.map structure against the v1 spec rules. */
+export function validate(map, rootDir) {
+    const diagnostics = [];
+    // Check that entries is present and is an array
+    if (!Array.isArray(map.entries)) {
+        diagnostics.push({
+            severity: "error",
+            message: '"entries" must be an array.',
+        });
+        return { valid: false, diagnostics };
+    }
+    // Track paths for duplicate detection
+    const seenPaths = new Set();
+    for (const entry of map.entries) {
+        // Check required fields
+        if (!entry.path || typeof entry.path !== "string") {
+            diagnostics.push({
+                severity: "error",
+                message: "Entry is missing required field \"path\".",
+            });
+            continue;
+        }
+        if (!entry.scope || !Array.isArray(entry.scope) || entry.scope.length === 0) {
+            diagnostics.push({
+                severity: "error",
+                message: `Entry "${entry.path}": missing or empty required field "scope".`,
+                entryPath: entry.path,
+            });
+        }
+        if (!entry.purpose || typeof entry.purpose !== "string") {
+            diagnostics.push({
+                severity: "error",
+                message: `Entry "${entry.path}": missing required field "purpose".`,
+                entryPath: entry.path,
+            });
+        }
+        // Check path doesn't contain ".."
+        if (entry.path.includes("..")) {
+            diagnostics.push({
+                severity: "error",
+                message: `Entry "${entry.path}": path must not contain ".." segments.`,
+                entryPath: entry.path,
+            });
+        }
+        // Check path doesn't start with "/"
+        if (entry.path.startsWith("/")) {
+            diagnostics.push({
+                severity: "error",
+                message: `Entry "${entry.path}": path must not start with "/". Use relative POSIX paths.`,
+                entryPath: entry.path,
+            });
+        }
+        // Check for duplicate paths
+        const normalizedPath = entry.path.replace(/\\/g, "/");
+        if (seenPaths.has(normalizedPath)) {
+            diagnostics.push({
+                severity: "error",
+                message: `Duplicate entry for path "${entry.path}".`,
+                entryPath: entry.path,
+            });
+        }
+        seenPaths.add(normalizedPath);
+        // Check that the file actually exists
+        const fullPath = path.join(rootDir, entry.path);
+        if (!fs.existsSync(fullPath)) {
+            diagnostics.push({
+                severity: "error",
+                message: `Entry "${entry.path}": file does not exist at ${fullPath}.`,
+                entryPath: entry.path,
+            });
+        }
+        // Validate last_reviewed format if present
+        if (entry.last_reviewed) {
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.last_reviewed)) {
+                diagnostics.push({
+                    severity: "warning",
+                    message: `Entry "${entry.path}": last_reviewed "${entry.last_reviewed}" is not in YYYY-MM-DD format.`,
+                    entryPath: entry.path,
+                });
+            }
+        }
+    }
+    // Warn about AGENTS.md files that exist but aren't listed
+    const discoveredFiles = discoverAgentFiles(rootDir);
+    for (const file of discoveredFiles) {
+        if (!seenPaths.has(file)) {
+            diagnostics.push({
+                severity: "warning",
+                message: `Found AGENTS.md at "${file}" that is not listed in the map. Consider adding it.`,
+                entryPath: file,
+            });
+        }
+    }
+    const hasErrors = diagnostics.some((d) => d.severity === "error");
+    return { valid: !hasErrors, diagnostics };
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "agentsmap",
+  "version": "0.1.0",
+  "description": "CLI tool for the AGENTS.map specification — discover, validate, and resolve AGENTS.md instruction files.",
+  "type": "module",
+  "bin": {
+    "agentsmap": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./parser": {
+      "types": "./dist/parser.d.ts",
+      "import": "./dist/parser.js"
+    },
+    "./resolver": {
+      "types": "./dist/resolver.d.ts",
+      "import": "./dist/resolver.js"
+    },
+    "./validator": {
+      "types": "./dist/validator.d.ts",
+      "import": "./dist/validator.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "start": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "agents",
+    "agents.md",
+    "agents.map",
+    "ai",
+    "llm",
+    "cli",
+    "monorepo",
+    "agent-instructions"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ygwyg/agents.map.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/ygwyg/agents.map#readme",
+  "bugs": {
+    "url": "https://github.com/ygwyg/agents.map/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "picomatch": "^4.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "@types/picomatch": "^3.0.2",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.6"
+  }
+}