agents.yaml 0.2.0 → 0.2.2

package/AGENTS.md

@@ -19,3 +19,5 @@ Agents should treat paths listed in `documents` as promoted supplemental guidanc
 The CLI can help discover package and local `AGENTS.md` files, add selected paths to `agents.yaml`, remove paths, initialize the root breadcrumb, and validate that referenced files still exist.
 
 Discovery only considers direct dependencies under a project's `node_modules`; nested dependency `AGENTS.md` files are not automatically activated.
+
+Discovery skips dot-prefixed directories by default. Use `agents discover --include-dot-directories` when hidden project directories should be scanned too.

package/README.md

@@ -17,12 +17,30 @@ pnpm run build
 ```sh
 agents init
 agents discover
+agents discover --include-dot-directories
 agents add ./node_modules/react/AGENTS.md
 agents validate
 ```
 
 Run `agents` with no command for the interactive flow.
 
+Discovery skips dot-prefixed directories by default so local caches and tool
+state do not dominate scan time. Use `--include-dot-directories` when you need
+to search those directories too.
+
+## Benchmark
+
+```sh
+pnpm --filter agents.yaml bench
+```
+
+The benchmark creates a temporary discovery fixture, compares default discovery
+against `--include-dot-directories`, prints median/min/max timings, and removes
+the fixture when it exits. Fixture size can be tuned with
+`AGENTS_BENCH_HIDDEN_DIRS`, `AGENTS_BENCH_FILES_PER_HIDDEN_DIR`,
+`AGENTS_BENCH_VISIBLE_PACKAGES`, `AGENTS_BENCH_ITERATIONS`, and
+`AGENTS_BENCH_WARMUPS`.
+
 ## File Format
 
 ```yaml

package/dist/index.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
+import { MultiSelectPrompt } from "@clack/core";
 import * as clack from "@clack/prompts";
+import { styleText } from "node:util";
 import { access, opendir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import * as YAML from "yaml";
@@ -13,8 +15,8 @@ function resolveFromRoot(root, input) {
 }
 function formatProjectPath(root, target) {
 	const relative = path.relative(root, target).split(path.sep).join(path.posix.sep);
-	if (relative.startsWith("..")) return target;
-	return relative.startsWith(".") ? relative : `./${relative}`;
+	if (relative === ".." || relative.startsWith("../")) return target;
+	return relative.startsWith("./") ? relative : `./${relative}`;
 }
 //#endregion
 //#region src/agents-file.ts
@@ -172,16 +174,16 @@ const skippedDirectories = new Set([
 	"dist",
 	"build"
 ]);
-async function discoverAgentDocuments(root) {
+async function discoverAgentDocuments(root, options = {}) {
 	const found = [];
-	await walk(root, root, found);
+	await walk(root, root, found, options);
 	return found.filter((document) => document.path !== "./AGENTS.md").sort((left, right) => left.path.localeCompare(right.path));
 }
 async function describeAgentDocument(root, agentsDocumentPath) {
 	const absolutePath = resolveFromRoot(root, agentsDocumentPath);
 	return documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath)));
 }
-async function walk(root, directory, found) {
+async function walk(root, directory, found, options) {
 	let handle;
 	try {
 		handle = await opendir(directory);
@@ -195,12 +197,16 @@ async function walk(root, directory, found) {
 				await scanDirectNodeModules(root, absolutePath, found);
 				continue;
 			}
-			if (!skippedDirectories.has(entry.name)) await walk(root, absolutePath, found);
+			if (!shouldSkipDirectory(entry.name, options)) await walk(root, absolutePath, found, options);
 			continue;
 		}
 		if (entry.isFile() && entry.name === "AGENTS.md") found.push(await documentEntry(root, absolutePath, await readPackageDescription(path.dirname(absolutePath))));
 	}
 }
+function shouldSkipDirectory(name, options) {
+	if (skippedDirectories.has(name)) return true;
+	return !options.includeDotDirectories && name.startsWith(".");
+}
 async function scanDirectNodeModules(root, nodeModulesPath, found) {
 	let handle;
 	try {
@@ -261,7 +267,7 @@ const helpText = `agents
 Usage:
   agents
   agents init [--force]
-  agents discover [--json]
+  agents discover [--json] [--include-dot-directories]
   agents add <path...>
   agents remove <path...>
   agents validate [--json]
@@ -284,7 +290,10 @@ async function run(argv) {
 			await commandInit(root, parsed.flags.get("force") === true);
 			return;
 		case "discover":
-			await commandDiscover(root, parsed.flags.get("json") === true);
+			await commandDiscover(root, {
+				json: parsed.flags.get("json") === true,
+				includeDotDirectories: parsed.flags.get("include-dot-directories") === true
+			});
 			return;
 		case "add":
 			await commandAdd(root, parsed.values);
@@ -351,9 +360,9 @@ async function commandInit(root, force) {
 	clack.note(result.messages.join("\n"), "Updated");
 	clack.outro("Project breadcrumb is ready.");
 }
-async function commandDiscover(root, json) {
-	const documents = await discoverAgentDocuments(root);
-	if (json) {
+async function commandDiscover(root, options) {
+	const documents = await discoverAgentDocuments(root, { includeDotDirectories: options.includeDotDirectories });
+	if (options.json) {
 		console.log(JSON.stringify(documents, null, 2));
 		return;
 	}
@@ -432,20 +441,45 @@ async function interactive(root) {
 		clack.outro("No unlisted supplemental AGENTS.md files found.");
 		return;
 	}
-	const selected = await clack.multiselect({
-		message: "Choose documents to enable",
-		options: candidates.map((doc) => ({
-			value: doc.path,
-			label: doc.path
-		})),
-		required: false
-	});
-	if (clack.isCancel(selected) || selected.length === 0) {
+	const selected = await chooseDocumentsToEnable(candidates.map((doc) => ({
+		value: doc.path,
+		label: doc.path
+	})));
+	if (clack.isCancel(selected) || selected === void 0 || selected.length === 0) {
 		clack.cancel("No documents selected.");
 		return;
 	}
 	await commandAdd(root, selected);
 }
+function chooseDocumentsToEnable(options) {
+	return new MultiSelectPrompt({
+		options,
+		required: false,
+		render() {
+			const prefix = `${styleText("cyan", clack.S_BAR)}  `;
+			const selected = this.value ?? [];
+			return `${styleText("gray", clack.S_BAR)}
+${clack.symbol(this.state)}  Choose documents to enable
+${prefix}${clack.limitOptions({
+				options: this.options,
+				cursor: this.cursor,
+				columnPadding: prefix.length,
+				style: (option, active) => styleDocumentOption(option, {
+					active,
+					selected: selected.includes(option.value)
+				})
+			}).join(`
+${prefix}`)}
+${styleText("cyan", clack.S_BAR_END)}
+`;
+		}
+	}).prompt();
+}
+function styleDocumentOption(option, state) {
+	if (option.disabled) return `${styleText("gray", clack.S_CHECKBOX_INACTIVE)} ${styleText(["strikethrough", "gray"], option.label)}`;
+	const checkbox = state.selected ? styleText("green", clack.S_CHECKBOX_SELECTED) : state.active ? styleText("cyan", clack.S_CHECKBOX_ACTIVE) : styleText("dim", clack.S_CHECKBOX_INACTIVE);
+	return `${state.active ? styleText("cyan", ">") : " "} ${checkbox} ${state.active ? option.label : styleText("dim", option.label)}`;
+}
 //#endregion
 //#region src/index.ts
 run(process.argv.slice(2)).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents.yaml",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
   ],
   "type": "module",
   "dependencies": {
+    "@clack/core": "1.4.1",
     "@clack/prompts": "1.5.1",
     "yaml": "2.9.0",
     "zod": "4.4.3"
@@ -30,6 +31,7 @@
     "pnpm": "11.5.2"
   },
   "scripts": {
+    "bench": "node src/discover.bench.ts",
     "build": "vp pack",
     "dev": "src/index.ts",
     "test": "vp test"

package/src/agents-file.ts

@@ -1,209 +1,224 @@
-import { access, readFile, writeFile } from 'node:fs/promises'
-import path from 'node:path'
-import * as YAML from 'yaml'
-import { z } from 'zod'
-import { resolveFromRoot } from './paths.ts'
+import { access, readFile, writeFile } from "node:fs/promises"
+import path from "node:path"
+import * as YAML from "yaml"
+import { z } from "zod"
+import { resolveFromRoot } from "./paths.ts"
 
 export type AgentsDocumentEntry = {
-  path: string
-  description?: string | undefined
+	path: string
+	description?: string | undefined
 }
 
 export type AgentsFile = {
-  version: 1
-  documents: AgentsDocumentEntry[]
+	version: 1
+	documents: AgentsDocumentEntry[]
 }
 
 export type ValidationResult = {
-  ok: boolean
-  errors: string[]
-  warnings: string[]
+	ok: boolean
+	errors: string[]
+	warnings: string[]
 }
 
 const fileSchema = z.object({
-  version: z.literal(1),
-  documents: z.array(
-    z.object({
-      path: z.string().min(1),
-      description: z.string().min(1).optional(),
-    }),
-  ),
+	version: z.literal(1),
+	documents: z.array(
+		z.object({
+			path: z.string().min(1),
+			description: z.string().min(1).optional(),
+		}),
+	),
 })
 
 const breadcrumb = `Consult \`./agents.yaml\` when working with outside dependencies.`
 
 export async function loadAgentsFile(root: string): Promise<AgentsFile> {
-  const filePath = agentsPath(root)
-
-  try {
-    const source = await readFile(filePath, 'utf8')
-    const parsed = YAML.parse(source) as unknown
-    return fileSchema.parse(parsed)
-  } catch (error) {
-    if (isNotFound(error)) {
-      return { version: 1, documents: [] }
-    }
-
-    if (error instanceof z.ZodError) {
-      throw new Error(
-        `Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(', ')}`,
-      )
-    }
-
-    throw error
-  }
+	const filePath = agentsPath(root)
+
+	try {
+		const source = await readFile(filePath, "utf8")
+		const parsed = YAML.parse(source) as unknown
+		return fileSchema.parse(parsed)
+	} catch (error) {
+		if (isNotFound(error)) {
+			return { version: 1, documents: [] }
+		}
+
+		if (error instanceof z.ZodError) {
+			throw new Error(
+				`Invalid agents.yaml: ${error.issues.map((issue) => issue.message).join(", ")}`,
+			)
+		}
+
+		throw error
+	}
 }
 
-export async function saveAgentsFile(root: string, file: AgentsFile): Promise<void> {
-  const normalized = {
-    version: file.version,
-    documents: file.documents.map((doc) => ({
-      path: doc.path,
-      ...(doc.description ? { description: doc.description } : {}),
-    })),
-  }
-
-  await writeFile(agentsPath(root), YAML.stringify(normalized, { lineWidth: 0 }), 'utf8')
+export async function saveAgentsFile(
+	root: string,
+	file: AgentsFile,
+): Promise<void> {
+	const normalized = {
+		version: file.version,
+		documents: file.documents.map((doc) => ({
+			path: doc.path,
+			...(doc.description ? { description: doc.description } : {}),
+		})),
+	}
+
+	await writeFile(
+		agentsPath(root),
+		YAML.stringify(normalized, { lineWidth: 0 }),
+		"utf8",
+	)
 }
 
 export async function addDocuments(
-  root: string,
-  documents: AgentsDocumentEntry[],
+	root: string,
+	documents: AgentsDocumentEntry[],
 ): Promise<AgentsFile> {
-  const file = await loadAgentsFile(root)
-  const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
-
-  for (const document of documents) {
-    const existing = byPath.get(document.path)
-    byPath.set(document.path, {
-      path: document.path,
-      ...(existing?.description ? { description: existing.description } : {}),
-      ...(document.description ? { description: document.description } : {}),
-    })
-  }
-
-  const next = {
-    version: 1 as const,
-    documents: [...byPath.values()].sort((left, right) => left.path.localeCompare(right.path)),
-  }
-
-  await saveAgentsFile(root, next)
-  return next
+	const file = await loadAgentsFile(root)
+	const byPath = new Map(file.documents.map((doc) => [doc.path, doc]))
+
+	for (const document of documents) {
+		const existing = byPath.get(document.path)
+		byPath.set(document.path, {
+			path: document.path,
+			...(existing?.description ? { description: existing.description } : {}),
+			...(document.description ? { description: document.description } : {}),
+		})
+	}
+
+	const next = {
+		version: 1 as const,
+		documents: [...byPath.values()].sort((left, right) =>
+			left.path.localeCompare(right.path),
+		),
+	}
+
+	await saveAgentsFile(root, next)
+	return next
 }
 
 export async function removeDocuments(
-  root: string,
-  paths: string[],
+	root: string,
+	paths: string[],
 ): Promise<{ file: AgentsFile; removed: string[] }> {
-  const file = await loadAgentsFile(root)
-  const pathSet = new Set(paths)
-  const removed: string[] = []
-  const documents = file.documents.filter((doc) => {
-    if (pathSet.has(doc.path)) {
-      removed.push(doc.path)
-      return false
-    }
-
-    return true
-  })
-
-  const next = { version: 1 as const, documents }
-  await saveAgentsFile(root, next)
-  return { file: next, removed }
+	const file = await loadAgentsFile(root)
+	const pathSet = new Set(paths)
+	const removed: string[] = []
+	const documents = file.documents.filter((doc) => {
+		if (pathSet.has(doc.path)) {
+			removed.push(doc.path)
+			return false
+		}
+
+		return true
+	})
+
+	const next = { version: 1 as const, documents }
+	await saveAgentsFile(root, next)
+	return { file: next, removed }
 }
 
-export async function validateAgentsFile(root: string): Promise<ValidationResult> {
-  const errors: string[] = []
-  const warnings: string[] = []
-  let file: AgentsFile
-
-  try {
-    file = await loadAgentsFile(root)
-  } catch (error) {
-    return {
-      ok: false,
-      errors: [error instanceof Error ? error.message : String(error)],
-      warnings,
-    }
-  }
-
-  const seen = new Set<string>()
-  for (const [index, document] of file.documents.entries()) {
-    const label = `documents[${index}] ${document.path}`
-
-    if (seen.has(document.path)) {
-      errors.push(`${label}: duplicate path`)
-    }
-    seen.add(document.path)
-
-    if (path.basename(document.path) !== 'AGENTS.md') {
-      warnings.push(`${label}: path does not end with AGENTS.md`)
-    }
-
-    try {
-      await access(resolveFromRoot(root, document.path))
-    } catch {
-      errors.push(`${label}: file does not exist`)
-    }
-  }
-
-  try {
-    const source = await readFile(path.join(root, 'AGENTS.md'), 'utf8')
-    if (!source.includes('./agents.yaml') && !source.includes('agents.yaml')) {
-      warnings.push('AGENTS.md does not mention agents.yaml')
-    }
-  } catch {
-    warnings.push('AGENTS.md is missing the agents.yaml breadcrumb')
-  }
-
-  return {
-    ok: errors.length === 0,
-    errors,
-    warnings,
-  }
+export async function validateAgentsFile(
+	root: string,
+): Promise<ValidationResult> {
+	const errors: string[] = []
+	const warnings: string[] = []
+	let file: AgentsFile
+
+	try {
+		file = await loadAgentsFile(root)
+	} catch (error) {
+		return {
+			ok: false,
+			errors: [error instanceof Error ? error.message : String(error)],
+			warnings,
+		}
+	}
+
+	const seen = new Set<string>()
+	for (const [index, document] of file.documents.entries()) {
+		const label = `documents[${index}] ${document.path}`
+
+		if (seen.has(document.path)) {
+			errors.push(`${label}: duplicate path`)
+		}
+		seen.add(document.path)
+
+		if (path.basename(document.path) !== "AGENTS.md") {
+			warnings.push(`${label}: path does not end with AGENTS.md`)
+		}
+
+		try {
+			await access(resolveFromRoot(root, document.path))
+		} catch {
+			errors.push(`${label}: file does not exist`)
+		}
+	}
+
+	try {
+		const source = await readFile(path.join(root, "AGENTS.md"), "utf8")
+		if (!source.includes("./agents.yaml") && !source.includes("agents.yaml")) {
+			warnings.push("AGENTS.md does not mention agents.yaml")
+		}
+	} catch {
+		warnings.push("AGENTS.md is missing the agents.yaml breadcrumb")
+	}
+
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings,
+	}
 }
 
 export async function initProject(
-  root: string,
-  options: { force: boolean },
+	root: string,
+	options: { force: boolean },
 ): Promise<{ messages: string[] }> {
-  const messages: string[] = []
-
-  try {
-    await access(agentsPath(root))
-    messages.push('agents.yaml already exists')
-  } catch {
-    await saveAgentsFile(root, { version: 1, documents: [] })
-    messages.push('created agents.yaml')
-  }
-
-  const projectAgentsPath = path.join(root, 'AGENTS.md')
-  try {
-    const source = await readFile(projectAgentsPath, 'utf8')
-    if (source.includes('agents.yaml') && !options.force) {
-      messages.push('AGENTS.md already mentions agents.yaml')
-      return { messages }
-    }
-
-    const next =
-      source.trimEnd().length === 0
-        ? `# Project Instructions\n\n${breadcrumb}\n`
-        : `${source.trimEnd()}\n\n${breadcrumb}\n`
-    await writeFile(projectAgentsPath, next, 'utf8')
-    messages.push('updated AGENTS.md')
-  } catch (error) {
-    if (!isNotFound(error)) throw error
-    await writeFile(projectAgentsPath, `# Project Instructions\n\n${breadcrumb}\n`, 'utf8')
-    messages.push('created AGENTS.md')
-  }
-
-  return { messages }
+	const messages: string[] = []
+
+	try {
+		await access(agentsPath(root))
+		messages.push("agents.yaml already exists")
+	} catch {
+		await saveAgentsFile(root, { version: 1, documents: [] })
+		messages.push("created agents.yaml")
+	}
+
+	const projectAgentsPath = path.join(root, "AGENTS.md")
+	try {
+		const source = await readFile(projectAgentsPath, "utf8")
+		if (source.includes("agents.yaml") && !options.force) {
+			messages.push("AGENTS.md already mentions agents.yaml")
+			return { messages }
+		}
+
+		const next =
+			source.trimEnd().length === 0
+				? `# Project Instructions\n\n${breadcrumb}\n`
+				: `${source.trimEnd()}\n\n${breadcrumb}\n`
+		await writeFile(projectAgentsPath, next, "utf8")
+		messages.push("updated AGENTS.md")
+	} catch (error) {
+		if (!isNotFound(error)) throw error
+		await writeFile(
+			projectAgentsPath,
+			`# Project Instructions\n\n${breadcrumb}\n`,
+			"utf8",
+		)
+		messages.push("created AGENTS.md")
+	}
+
+	return { messages }
 }
 
 function agentsPath(root: string): string {
-  return path.join(root, 'agents.yaml')
+	return path.join(root, "agents.yaml")
 }
 
 function isNotFound(error: unknown): boolean {
-  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+	return error instanceof Error && "code" in error && error.code === "ENOENT"
 }