agents.yaml 0.2.1 → 0.2.3

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.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/index.mjs

@@ -15,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
@@ -147,7 +147,8 @@ async function initProject(root, options) {
 			messages.push("AGENTS.md already mentions agents.yaml");
 			return { messages };
 		}
-		await writeFile(projectAgentsPath, source.trimEnd().length === 0 ? `# Project Instructions\n\n${breadcrumb}\n` : `${source.trimEnd()}\n\n${breadcrumb}\n`, "utf8");
+		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;
@@ -164,7 +165,7 @@ function isNotFound(error) {
 }
 //#endregion
 //#region src/discover.ts
-const skippedDirectories = new Set([
+const skippedDirectories = /* @__PURE__ */ new Set([
 	".git",
 	".hg",
 	".svn",
@@ -174,16 +175,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);
@@ -197,12 +198,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 {
@@ -263,7 +268,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]
@@ -286,7 +291,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);
@@ -353,9 +361,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;
 	}
@@ -444,8 +452,8 @@ async function interactive(root) {
 	}
 	await commandAdd(root, selected);
 }
-function chooseDocumentsToEnable(options) {
-	return new MultiSelectPrompt({
+async function chooseDocumentsToEnable(options) {
+	const selected = await new MultiSelectPrompt({
 		options,
 		required: false,
 		render() {
@@ -467,6 +475,7 @@ ${styleText("cyan", clack.S_BAR_END)}
 `;
 		}
 	}).prompt();
+	return typeof selected === "symbol" ? clack.CANCEL_SYMBOL : selected;
 }
 function styleDocumentOption(option, state) {
 	if (option.disabled) return `${styleText("gray", clack.S_CHECKBOX_INACTIVE)} ${styleText(["strikethrough", "gray"], option.label)}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents.yaml",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
@@ -17,20 +17,21 @@
   ],
   "type": "module",
   "dependencies": {
-    "@clack/core": "1.4.1",
-    "@clack/prompts": "1.5.1",
-    "yaml": "2.9.0",
-    "zod": "4.4.3"
+    "@clack/core": "1.5.1",
+    "@clack/prompts": "1.8.1",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@types/node": "25.9.2",
-    "typescript": "6.0.3"
+    "@types/node": "25.9.6",
+    "typescript": "7.0.2"
   },
   "engines": {
-    "node": "26.3.0",
-    "pnpm": "11.5.2"
+    "node": "26.8.2",
+    "pnpm": "12.4.1"
   },
   "scripts": {
+    "bench": "node src/discover.bench.ts",
     "build": "vp pack",
     "dev": "src/index.ts",
     "test": "vp test"

package/src/discover.bench.ts

@@ -0,0 +1,219 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { performance } from "node:perf_hooks"
+import { discoverAgentDocuments, type DiscoverOptions } from "./discover.ts"
+
+type BenchmarkCase = {
+	name: string
+	options?: DiscoverOptions
+}
+
+type BenchmarkResult = {
+	name: string
+	docs: number
+	medianMs: number
+	minMs: number
+	maxMs: number
+}
+
+const hiddenDirectories = readPositiveInteger("AGENTS_BENCH_HIDDEN_DIRS", 250)
+const filesPerHiddenDirectory = readPositiveInteger(
+	"AGENTS_BENCH_FILES_PER_HIDDEN_DIR",
+	8,
+)
+const visiblePackages = readPositiveInteger("AGENTS_BENCH_VISIBLE_PACKAGES", 25)
+const iterations = readPositiveInteger("AGENTS_BENCH_ITERATIONS", 7)
+const warmups = readPositiveInteger("AGENTS_BENCH_WARMUPS", 1)
+
+const cases: BenchmarkCase[] = [
+	{ name: "default" },
+	{
+		name: "include dot directories",
+		options: { includeDotDirectories: true },
+	},
+]
+
+const root = await mkdtemp(path.join(tmpdir(), "agents-yaml-bench-"))
+
+try {
+	await createFixture(root)
+	const results: BenchmarkResult[] = []
+
+	for (const benchmarkCase of cases) {
+		for (let index = 0; index < warmups; index += 1) {
+			await discoverAgentDocuments(root, benchmarkCase.options)
+		}
+
+		results.push(await runCase(root, benchmarkCase))
+	}
+
+	printResults(results)
+} finally {
+	await rm(root, { recursive: true, force: true })
+}
+
+async function createFixture(root: string): Promise<void> {
+	await writeFile(
+		path.join(root, "agents.yaml"),
+		"version: 1\n\ndocuments: []\n",
+		"utf8",
+	)
+	await writeFile(path.join(root, "AGENTS.md"), "# Root guidance\n", "utf8")
+
+	await createDirectDependency(root)
+	await createVisibleProjectDocuments(root)
+	await createHiddenCache(root)
+}
+
+async function createDirectDependency(root: string): Promise<void> {
+	const dependencyPath = path.join(root, "node_modules", "direct-lib")
+	await mkdir(dependencyPath, { recursive: true })
+	await writeFile(
+		path.join(dependencyPath, "AGENTS.md"),
+		"# Direct dependency guidance\n",
+		"utf8",
+	)
+	await writeFile(
+		path.join(dependencyPath, "package.json"),
+		JSON.stringify({
+			name: "direct-lib",
+			description: "Direct fixture dependency.",
+		}),
+		"utf8",
+	)
+}
+
+async function createVisibleProjectDocuments(root: string): Promise<void> {
+	for (let index = 0; index < visiblePackages; index += 1) {
+		const packagePath = path.join(root, "packages", `visible-${index}`)
+		await mkdir(packagePath, { recursive: true })
+		await writeFile(
+			path.join(packagePath, "AGENTS.md"),
+			"# Visible project guidance\n",
+			"utf8",
+		)
+	}
+}
+
+async function createHiddenCache(root: string): Promise<void> {
+	for (let index = 0; index < hiddenDirectories; index += 1) {
+		const cachePath = path.join(root, ".cache", `entry-${index}`, "nested")
+		await mkdir(cachePath, { recursive: true })
+		await writeFile(
+			path.join(cachePath, "AGENTS.md"),
+			"# Hidden cache guidance\n",
+			"utf8",
+		)
+
+		for (
+			let fileIndex = 0;
+			fileIndex < filesPerHiddenDirectory;
+			fileIndex += 1
+		) {
+			await writeFile(
+				path.join(cachePath, `file-${fileIndex}.txt`),
+				"x".repeat(100),
+				"utf8",
+			)
+		}
+	}
+}
+
+async function runCase(
+	root: string,
+	benchmarkCase: BenchmarkCase,
+): Promise<BenchmarkResult> {
+	const durations: number[] = []
+	let docs = 0
+
+	for (let index = 0; index < iterations; index += 1) {
+		const start = performance.now()
+		const discovered = await discoverAgentDocuments(root, benchmarkCase.options)
+		const duration = performance.now() - start
+
+		docs = discovered.length
+		durations.push(duration)
+	}
+
+	const sorted = [...durations].sort((left, right) => left - right)
+	const medianMs = sorted[Math.floor(sorted.length / 2)]
+	const minMs = sorted[0]
+	const maxMs = sorted[sorted.length - 1]
+
+	if (medianMs === undefined || minMs === undefined || maxMs === undefined) {
+		throw new Error("Benchmark did not record any durations")
+	}
+
+	return {
+		name: benchmarkCase.name,
+		docs,
+		medianMs,
+		minMs,
+		maxMs,
+	}
+}
+
+function printResults(results: BenchmarkResult[]): void {
+	console.log("agents discover benchmark")
+	console.log(
+		[
+			`fixture: hiddenDirectories=${hiddenDirectories}`,
+			`filesPerHiddenDirectory=${filesPerHiddenDirectory}`,
+			`visiblePackages=${visiblePackages}`,
+			`iterations=${iterations}`,
+			`warmups=${warmups}`,
+		].join(", "),
+	)
+	console.log("")
+	console.log(
+		[
+			pad("case", 24),
+			pad("docs", 8),
+			pad("median", 10),
+			pad("min", 10),
+			pad("max", 10),
+		].join(""),
+	)
+	console.log("-".repeat(62))
+
+	for (const result of results) {
+		console.log(
+			[
+				pad(result.name, 24),
+				pad(String(result.docs), 8),
+				pad(formatMs(result.medianMs), 10),
+				pad(formatMs(result.minMs), 10),
+				pad(formatMs(result.maxMs), 10),
+			].join(""),
+		)
+	}
+
+	const defaultResult = results.find((result) => result.name === "default")
+	const includeDotResult = results.find(
+		(result) => result.name === "include dot directories",
+	)
+	if (defaultResult && includeDotResult && defaultResult.medianMs > 0) {
+		const ratio = includeDotResult.medianMs / defaultResult.medianMs
+		console.log("")
+		console.log(`include dot directories median: ${ratio.toFixed(1)}x default`)
+	}
+}
+
+function readPositiveInteger(name: string, fallback: number): number {
+	const raw = process.env[name]
+	if (!raw) return fallback
+
+	const value = Number.parseInt(raw, 10)
+	if (Number.isInteger(value) && value > 0) return value
+
+	throw new Error(`${name} must be a positive integer`)
+}
+
+function formatMs(value: number): string {
+	return `${value.toFixed(1)}ms`
+}
+
+function pad(value: string, width: number): string {
+	return value.padEnd(width, " ")
+}

package/src/discover.test.ts

@@ -132,6 +132,26 @@ describe("agents.yaml dependency discovery", () => {
 			},
 		])
 	})
+
+	it("skips dot-prefixed directories by default", async () => {
+		const root = await createTempProject()
+		const hiddenAgentsPath = path.join(root, ".cache", "AGENTS.md")
+		await mkdir(path.dirname(hiddenAgentsPath), { recursive: true })
+		await writeFile(hiddenAgentsPath, "# Hidden cache guidance\n", "utf8")
+
+		await expect(discoverAgentDocuments(root)).resolves.toEqual([])
+	})
+
+	it("can include dot-prefixed directories when requested", async () => {
+		const root = await createTempProject()
+		const hiddenAgentsPath = path.join(root, ".cache", "AGENTS.md")
+		await mkdir(path.dirname(hiddenAgentsPath), { recursive: true })
+		await writeFile(hiddenAgentsPath, "# Hidden cache guidance\n", "utf8")
+
+		await expect(
+			discoverAgentDocuments(root, { includeDotDirectories: true }),
+		).resolves.toEqual([{ path: "./.cache/AGENTS.md" }])
+	})
 })
 
 async function createTempProject(): Promise<string> {

package/src/discover.ts

@@ -7,6 +7,10 @@ export type DiscoveredDocument = {
 	description?: string
 }
 
+export type DiscoverOptions = {
+	includeDotDirectories?: boolean
+}
+
 const skippedDirectories = new Set([
 	".git",
 	".hg",
@@ -20,9 +24,10 @@ const skippedDirectories = new Set([
 
 export async function discoverAgentDocuments(
 	root: string,
+	options: DiscoverOptions = {},
 ): Promise<DiscoveredDocument[]> {
 	const found: DiscoveredDocument[] = []
-	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))
@@ -44,6 +49,7 @@ async function walk(
 	root: string,
 	directory: string,
 	found: DiscoveredDocument[],
+	options: DiscoverOptions,
 ): Promise<void> {
 	let handle
 	try {
@@ -61,8 +67,8 @@ async function walk(
 				continue
 			}
 
-			if (!skippedDirectories.has(entry.name)) {
-				await walk(root, absolutePath, found)
+			if (!shouldSkipDirectory(entry.name, options)) {
+				await walk(root, absolutePath, found, options)
 			}
 			continue
 		}
@@ -79,6 +85,11 @@ async function walk(
 	}
 }
 
+function shouldSkipDirectory(name: string, options: DiscoverOptions): boolean {
+	if (skippedDirectories.has(name)) return true
+	return !options.includeDotDirectories && name.startsWith(".")
+}
+
 async function scanDirectNodeModules(
 	root: string,
 	nodeModulesPath: string,

package/src/paths.ts

@@ -15,9 +15,9 @@ export function formatProjectPath(root: string, target: string): string {
 		.relative(root, target)
 		.split(path.sep)
 		.join(path.posix.sep)
-	if (relative.startsWith("..")) {
+	if (relative === ".." || relative.startsWith("../")) {
 		return target
 	}
 
-	return relative.startsWith(".") ? relative : `./${relative}`
+	return relative.startsWith("./") ? relative : `./${relative}`
 }

package/src/run.ts

@@ -37,7 +37,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]
@@ -62,7 +62,11 @@ export async function run(argv: string[]): Promise<void> {
 			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)
@@ -137,9 +141,14 @@ async function commandInit(root: string, force: boolean): Promise<void> {
 	clack.outro("Project breadcrumb is ready.")
 }
 
-async function commandDiscover(root: string, json: boolean): Promise<void> {
-	const documents = await discoverAgentDocuments(root)
-	if (json) {
+async function commandDiscover(
+	root: string,
+	options: { json: boolean; includeDotDirectories: boolean },
+): Promise<void> {
+	const documents = await discoverAgentDocuments(root, {
+		includeDotDirectories: options.includeDotDirectories,
+	})
+	if (options.json) {
 		console.log(JSON.stringify(documents, null, 2))
 		return
 	}
@@ -281,10 +290,10 @@ async function interactive(root: string): Promise<void> {
 	await commandAdd(root, selected)
 }
 
-function chooseDocumentsToEnable(
+async function chooseDocumentsToEnable(
 	options: DocumentOption[],
-): Promise<string[] | symbol | undefined> {
-	return new MultiSelectPrompt<DocumentOption>({
+): Promise<string[] | typeof clack.CANCEL_SYMBOL | undefined> {
+	const selected = await new MultiSelectPrompt<DocumentOption>({
 		options,
 		required: false,
 		render() {
@@ -308,6 +317,8 @@ ${styleText("cyan", clack.S_BAR_END)}
 `
 		},
 	}).prompt()
+
+	return typeof selected === "symbol" ? clack.CANCEL_SYMBOL : selected
 }
 
 function styleDocumentOption(