agents.yaml 0.2.2 → 0.3.0

package/AGENTS.md

@@ -21,3 +21,7 @@ The CLI can help discover package and local `AGENTS.md` files, add selected path
 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.
+
+The CLI uses Comline for command definitions, options, variadic path arguments, help, and shell completion. Clack handles the interactive flow. Pass full runtime argv to `run`; Comline removes the runtime and entry-point arguments.
+
+`add` and `remove` require one or more paths. Use `--` before dash-prefixed paths. Unknown or misplaced options fail before command execution. Both text and JSON validation set a nonzero exit status when the index is invalid.

package/README.md

@@ -19,14 +19,35 @@ agents init
 agents discover
 agents discover --include-dot-directories
 agents add ./node_modules/react/AGENTS.md
+agents add ./react/AGENTS.md "./my package/AGENTS.md"
+agents remove ./react/AGENTS.md "./my package/AGENTS.md"
 agents validate
+agents validate --json
+agents --help
+agents --version
 ```
 
 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.
+`add` and `remove` accept one or more paths. Use `--` before paths that start with a dash. Unknown commands and flags, flags used with the wrong command, and missing required paths produce an error before the command runs.
+
+Boolean switches accept `true`, `false`, `1`, and `0`, either with `=` or as the next argument. Repeated switches use the last value. Validation exits with status 1 for an invalid document index, including with `--json`.
+
+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.
+
+## Shell Completion
+
+Generate a completion script with `agents completion <target>`, or install it into your shell's configured completion directory:
+
+```sh
+agents completion install bash
+agents completion install zsh
+agents completion install fish
+agents completion install nushell
+agents completion install carapace
+```
+
+Choose the target you use, then open a new shell. Completion setup requires the target shell's completion system to be enabled; setup errors explain any missing requirements. Commands and flags complete automatically. `add` completes filesystem paths, and `remove` suggests paths listed in `agents.yaml`, including after the first path.
 
 ## Benchmark
 
@@ -34,12 +55,7 @@ to search those directories too.
 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`.
+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
 

package/dist/index.mjs

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import { MultiSelectPrompt } from "@clack/core";
 import * as clack from "@clack/prompts";
+import { cli, completionResponse, help, interpretArguments, optional, options, parseBooleanOption, required } from "comline";
 import { styleText } from "node:util";
 import { access, opendir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import * as YAML from "yaml";
 import { z } from "zod";
+import { readFileSync } from "node:fs";
 //#region src/paths.ts
 function cwd() {
 	return process.cwd();
@@ -147,7 +149,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;
@@ -163,8 +166,104 @@ function isNotFound(error) {
 	return error instanceof Error && "code" in error && error.code === "ENOENT";
 }
 //#endregion
+//#region src/cli.ts
+function parseBooleanSwitch(value) {
+	const last = value.split(",").at(-1) ?? "";
+	if (![
+		"",
+		"true",
+		"false",
+		"0",
+		"1"
+	].includes(last)) throw new Error(`Expected a boolean switch, received ${JSON.stringify(last)}`);
+	return parseBooleanOption(last);
+}
+function booleanSwitch(description, example) {
+	return {
+		description,
+		example,
+		parse: parseBooleanSwitch,
+		required: false
+	};
+}
+const commonSchema = z.object({
+	help: z.boolean().default(false),
+	version: z.boolean().default(false)
+});
+const commonOptions = {
+	help: {
+		...booleanSwitch("Show usage", "--help"),
+		flag: "h"
+	},
+	version: {
+		...booleanSwitch("Show the installed version", "--version"),
+		flag: "v"
+	}
+};
+const jsonOption = booleanSwitch("Print JSON", "--json");
+function common(description) {
+	return options(description, commonSchema, commonOptions);
+}
+const agents = cli({
+	cliName: "agents",
+	cliDescription: "Discover and curate agent-readable documentation in agents.yaml.",
+	routes: optional({
+		init: null,
+		discover: null,
+		add: required({ "$...paths": null }),
+		remove: required({ "$...paths": null }),
+		validate: null,
+		help: null,
+		version: null
+	}),
+	routeOptions: {
+		"": common("Choose an action interactively"),
+		init: options("Initialize breadcrumb files", commonSchema.extend({ force: z.boolean().default(false) }), {
+			...commonOptions,
+			force: booleanSwitch("Append the breadcrumb even if already mentioned", "--force")
+		}),
+		discover: options("Discover supplemental AGENTS.md files", commonSchema.extend({
+			json: z.boolean().default(false),
+			"include-dot-directories": z.boolean().default(false)
+		}), {
+			...commonOptions,
+			json: jsonOption,
+			"include-dot-directories": booleanSwitch("Search hidden directories", "--include-dot-directories")
+		}),
+		"add/$...paths": common("Promote one or more AGENTS.md files"),
+		"remove/$...paths": common("Remove one or more promoted paths"),
+		validate: options("Validate agents.yaml", commonSchema.extend({ json: z.boolean().default(false) }), {
+			...commonOptions,
+			json: jsonOption
+		}),
+		help: common("Show usage"),
+		version: common("Show the installed version")
+	},
+	positionalCompletions: {
+		"add/$...paths": { fileSystem: "files" },
+		"remove/$...paths": { provide: async () => {
+			const { documents } = await loadAgentsFile(cwd());
+			return documents.map(({ path, description }) => ({
+				value: path,
+				...description ? { description } : {}
+			}));
+		} }
+	}
+});
+function earlyCommand(argv) {
+	const { options: occurrences } = interpretArguments(agents.definition, argv.slice(2));
+	for (const key of ["help", "version"]) {
+		const occurrence = occurrences.findLast((option) => option.key === key);
+		if (occurrence && parseBooleanSwitch(occurrence.value)) return key;
+	}
+}
+function packageVersion() {
+	const source = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+	return z.object({ version: z.string() }).parse(JSON.parse(source)).version;
+}
+//#endregion
 //#region src/discover.ts
-const skippedDirectories = new Set([
+const skippedDirectories = /* @__PURE__ */ new Set([
 	".git",
 	".hg",
 	".svn",
@@ -262,98 +361,54 @@ function isPackageJson(value) {
 }
 //#endregion
 //#region src/run.ts
-const helpText = `agents
-
-Usage:
-  agents
-  agents init [--force]
-  agents discover [--json] [--include-dot-directories]
-  agents add <path...>
-  agents remove <path...>
-  agents validate [--json]
-
-agents.yaml is a curated table of contents for promoted AGENTS.md guidance.`;
 async function run(argv) {
-	const parsed = parseArgs(argv);
+	const completion = await completionResponse(agents.definition, argv);
+	if (completion !== void 0) {
+		process.stdout.write(completion);
+		return;
+	}
+	const early = earlyCommand(argv);
+	if (early === "help") {
+		console.log(help(agents.definition));
+		return;
+	}
+	if (early === "version") {
+		console.log(packageVersion());
+		return;
+	}
+	const { inputs, warnings } = agents(argv);
+	if (warnings.length > 0) throw new Error(warnings.map((warning) => warning.message).join("\n"));
 	const root = cwd();
-	switch (parsed.command) {
-		case void 0:
+	switch (inputs.case) {
+		case "":
 			await interactive(root);
 			return;
 		case "help":
-			console.log(helpText);
+			console.log(help(agents.definition));
 			return;
 		case "version":
-			console.log("0.1.0");
+			console.log(packageVersion());
 			return;
 		case "init":
-			await commandInit(root, parsed.flags.get("force") === true);
+			await commandInit(root, inputs.opts.force);
 			return;
 		case "discover":
 			await commandDiscover(root, {
-				json: parsed.flags.get("json") === true,
-				includeDotDirectories: parsed.flags.get("include-dot-directories") === true
+				json: inputs.opts.json,
+				includeDotDirectories: inputs.opts["include-dot-directories"]
 			});
 			return;
-		case "add":
-			await commandAdd(root, parsed.values);
+		case "add/$...paths":
+			await commandAdd(root, inputs.params.paths);
 			return;
-		case "remove":
-			await commandRemove(root, parsed.values);
+		case "remove/$...paths":
+			await commandRemove(root, inputs.params.paths);
 			return;
 		case "validate":
-			await commandValidate(root, parsed.flags.get("json") === true);
+			await commandValidate(root, inputs.opts.json);
 			return;
 	}
 }
-function parseArgs(argv) {
-	const flags = /* @__PURE__ */ new Map();
-	const values = [];
-	let command;
-	for (let index = 0; index < argv.length; index += 1) {
-		const arg = argv[index];
-		if (!arg) continue;
-		if (arg === "--help" || arg === "-h") {
-			command = "help";
-			continue;
-		}
-		if (arg === "--version" || arg === "-v") {
-			command = "version";
-			continue;
-		}
-		if (arg.startsWith("--")) {
-			const [rawName, inlineValue] = arg.slice(2).split("=", 2);
-			if (!rawName) continue;
-			if (inlineValue !== void 0) {
-				flags.set(rawName, inlineValue);
-				continue;
-			}
-			flags.set(rawName, true);
-			continue;
-		}
-		if (!command && isCommand(arg)) {
-			command = arg;
-			continue;
-		}
-		values.push(arg);
-	}
-	return {
-		command,
-		values,
-		flags
-	};
-}
-function isCommand(value) {
-	return [
-		"add",
-		"discover",
-		"help",
-		"init",
-		"remove",
-		"validate",
-		"version"
-	].includes(value);
-}
 async function commandInit(root, force) {
 	clack.intro("agents init");
 	const result = await initProject(root, { force });
@@ -394,6 +449,7 @@ async function commandRemove(root, paths) {
 }
 async function commandValidate(root, json) {
 	const result = await validateAgentsFile(root);
+	if (!result.ok) process.exitCode = 1;
 	if (json) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
@@ -402,7 +458,6 @@ async function commandValidate(root, json) {
 	if (result.errors.length > 0) clack.note(result.errors.join("\n"), "Errors");
 	if (result.warnings.length > 0) clack.note(result.warnings.join("\n"), "Warnings");
 	clack.outro(result.ok ? "agents.yaml is valid." : "agents.yaml needs attention.");
-	if (!result.ok) process.exitCode = 1;
 }
 async function interactive(root) {
 	clack.intro("agents");
@@ -451,8 +506,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() {
@@ -474,6 +529,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)}`;
@@ -482,7 +538,7 @@ function styleDocumentOption(option, state) {
 }
 //#endregion
 //#region src/index.ts
-run(process.argv.slice(2)).catch((error) => {
+run(process.argv).catch((error) => {
 	const message = error instanceof Error ? error.message : String(error);
 	console.error(`agents: ${message}`);
 	process.exitCode = 1;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "agents.yaml",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A CLI for discovering and curating agent-readable documentation in agents.yaml.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jeremybanka/agents.yaml.git"
   },
+  "type": "module",
   "bin": {
     "agents": "./dist/index.mjs"
   },
@@ -15,20 +16,20 @@
     "README.md",
     "AGENTS.md"
   ],
-  "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",
+    "comline": "0.8.1",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@types/node": "25.9.2",
-    "typescript": "6.0.3"
+    "@types/node": "26.6.1",
+    "typescript": "7.0.2"
   },
   "engines": {
-    "node": "26.3.0",
-    "pnpm": "11.5.2"
+    "node": "26.9.0",
+    "pnpm": "12.4.2"
   },
   "scripts": {
     "bench": "node src/discover.bench.ts",

package/src/cli.ts

@@ -0,0 +1,140 @@
+import {
+	cli,
+	interpretArguments,
+	optional,
+	options,
+	parseBooleanOption,
+	required,
+	type CliOption,
+} from "comline"
+import { readFileSync } from "node:fs"
+import { z } from "zod"
+import { loadAgentsFile } from "./agents-file.ts"
+import { cwd } from "./paths.ts"
+
+function parseBooleanSwitch(value: string): boolean {
+	// Comline joins repeated occurrences with commas. The last switch wins.
+	const last = value.split(",").at(-1) ?? ""
+	if (!["", "true", "false", "0", "1"].includes(last)) {
+		throw new Error(
+			`Expected a boolean switch, received ${JSON.stringify(last)}`,
+		)
+	}
+	return parseBooleanOption(last)
+}
+
+function booleanSwitch(
+	description: string,
+	example: string,
+): CliOption<boolean> {
+	return { description, example, parse: parseBooleanSwitch, required: false }
+}
+
+const commonSchema = z.object({
+	help: z.boolean().default(false),
+	version: z.boolean().default(false),
+})
+
+const commonOptions = {
+	help: {
+		...booleanSwitch("Show usage", "--help"),
+		flag: "h",
+	},
+	version: {
+		...booleanSwitch("Show the installed version", "--version"),
+		flag: "v",
+	},
+} satisfies Record<string, CliOption<boolean>>
+
+const jsonOption = booleanSwitch("Print JSON", "--json")
+
+function common(description: string) {
+	return options(description, commonSchema, commonOptions)
+}
+
+export const agents = cli({
+	cliName: "agents",
+	cliDescription:
+		"Discover and curate agent-readable documentation in agents.yaml.",
+	routes: optional({
+		init: null,
+		discover: null,
+		add: required({ "$...paths": null }),
+		remove: required({ "$...paths": null }),
+		validate: null,
+		help: null,
+		version: null,
+	}),
+	routeOptions: {
+		"": common("Choose an action interactively"),
+		init: options(
+			"Initialize breadcrumb files",
+			commonSchema.extend({ force: z.boolean().default(false) }),
+			{
+				...commonOptions,
+				force: booleanSwitch(
+					"Append the breadcrumb even if already mentioned",
+					"--force",
+				),
+			},
+		),
+		discover: options(
+			"Discover supplemental AGENTS.md files",
+			commonSchema.extend({
+				json: z.boolean().default(false),
+				"include-dot-directories": z.boolean().default(false),
+			}),
+			{
+				...commonOptions,
+				json: jsonOption,
+				"include-dot-directories": booleanSwitch(
+					"Search hidden directories",
+					"--include-dot-directories",
+				),
+			},
+		),
+		"add/$...paths": common("Promote one or more AGENTS.md files"),
+		"remove/$...paths": common("Remove one or more promoted paths"),
+		validate: options(
+			"Validate agents.yaml",
+			commonSchema.extend({ json: z.boolean().default(false) }),
+			{ ...commonOptions, json: jsonOption },
+		),
+		help: common("Show usage"),
+		version: common("Show the installed version"),
+	},
+	positionalCompletions: {
+		"add/$...paths": { fileSystem: "files" },
+		"remove/$...paths": {
+			provide: async () => {
+				const { documents } = await loadAgentsFile(cwd())
+				return documents.map(({ path, description }) => ({
+					value: path,
+					...(description ? { description } : {}),
+				}))
+			},
+		},
+	},
+})
+
+export function earlyCommand(argv: string[]): "help" | "version" | undefined {
+	// Interpret before validation so `add --help` does not require a path.
+	// Using Comline's occurrences also respects grouped flags and literal `--`.
+	const { options: occurrences } = interpretArguments(
+		agents.definition,
+		argv.slice(2),
+	)
+	for (const key of ["help", "version"] as const) {
+		const occurrence = occurrences.findLast((option) => option.key === key)
+		if (occurrence && parseBooleanSwitch(occurrence.value)) return key
+	}
+	return undefined
+}
+
+export function packageVersion(): string {
+	const source = readFileSync(
+		new URL("../package.json", import.meta.url),
+		"utf8",
+	)
+	return z.object({ version: z.string() }).parse(JSON.parse(source)).version
+}

package/src/index.ts

@@ -2,7 +2,7 @@
 
 import { run } from "./run.ts"
 
-run(process.argv.slice(2)).catch((error: unknown) => {
+run(process.argv).catch((error: unknown) => {
 	const message = error instanceof Error ? error.message : String(error)
 	console.error(`agents: ${message}`)
 	process.exitCode = 1

package/src/run.test.ts

@@ -0,0 +1,226 @@
+import * as clack from "@clack/prompts"
+import { spawnSync } from "node:child_process"
+import {
+	mkdir,
+	mkdtemp,
+	readFile,
+	readdir,
+	rm,
+	writeFile,
+} from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { loadAgentsFile, saveAgentsFile } from "./agents-file.ts"
+import { agents } from "./cli.ts"
+import { run } from "./run.ts"
+
+vi.mock("@clack/prompts", async (importOriginal) => ({
+	...(await importOriginal<typeof import("@clack/prompts")>()),
+	intro: vi.fn(),
+	select: vi.fn(),
+	cancel: vi.fn(),
+}))
+
+const entry = fileURLToPath(new URL("./index.ts", import.meta.url))
+let root: string
+
+beforeEach(async () => {
+	root = await mkdtemp(path.join(tmpdir(), "agents-cli-"))
+})
+
+afterEach(async () => {
+	vi.clearAllMocks()
+	await rm(root, { recursive: true, force: true })
+})
+
+function invoke(...args: string[]) {
+	const result = spawnSync(process.execPath, [entry, ...args], {
+		cwd: root,
+		encoding: "utf8",
+		env: { ...process.env, NO_COLOR: "1", FORCE_COLOR: undefined },
+		timeout: 10_000,
+	})
+	if (result.error) throw result.error
+	return result
+}
+
+describe("agents command-line interface", () => {
+	it("keeps the no-command interactive flow and cancellation", async () => {
+		vi.mocked(clack.select).mockResolvedValueOnce(clack.CANCEL_SYMBOL)
+		await run([process.execPath, entry])
+		expect(clack.select).toHaveBeenCalledWith(
+			expect.objectContaining({ message: "What would you like to do?" }),
+		)
+		expect(clack.cancel).toHaveBeenCalledWith("Cancelled.")
+	})
+
+	it("adds and removes multiple paths without splitting special characters", async () => {
+		const paths = ["./space name/AGENTS.md", "./comma,equals=/AGENTS.md"]
+		for (const document of paths) {
+			await mkdir(path.dirname(path.join(root, document)), { recursive: true })
+			await writeFile(path.join(root, document), "# Instructions\n")
+		}
+
+		expect(invoke("init").status).toBe(0)
+		expect(invoke("add", ...paths).status).toBe(0)
+		const added = await loadAgentsFile(root)
+		expect(added.documents.map((document) => document.path).sort()).toEqual(
+			paths.toSorted(),
+		)
+		expect(invoke("remove", ...paths).status).toBe(0)
+		expect((await loadAgentsFile(root)).documents).toEqual([])
+	})
+
+	it("treats help and version spellings after -- as literal paths", async () => {
+		const paths = ["--help", "-v", "-dash/AGENTS.md"]
+		expect(invoke("add", "--", ...paths).status).toBe(0)
+		expect(
+			(await loadAgentsFile(root)).documents
+				.map((document) => document.path)
+				.sort(),
+		).toEqual(paths.map((document) => `./${document}`).sort())
+		expect(invoke("remove", "--", ...paths).status).toBe(0)
+		expect((await loadAgentsFile(root)).documents).toEqual([])
+	})
+
+	it.each([
+		["add"],
+		["remove"],
+		["discovr"],
+		["--unknown"],
+		["init", "--json"],
+		["init", "--force=maybe"],
+		["add", "./AGENTS.md", "--typo"],
+		["validate", "--json", "--force"],
+	])(
+		"rejects invalid usage without executing a command: %j",
+		async (...args) => {
+			const result = invoke(...args)
+			expect(result.status).toBe(1)
+			expect(result.stdout).toBe("")
+			expect(result.stderr).toContain("agents:")
+			expect(await readdir(root)).toEqual([])
+		},
+	)
+
+	it.each([
+		["help"],
+		["--help"],
+		["-h"],
+		["add", "--help"],
+		["remove", "-h"],
+		["add", "-vh"],
+	])("shows generated help without requiring paths: %j", async (...args) => {
+		// Help must work even in a project with an invalid document index.
+		await writeFile(path.join(root, "agents.yaml"), "not: [valid yaml")
+		const result = invoke(...args)
+		expect(result.status).toBe(0)
+		expect(result.stderr).toBe("")
+		expect(result.stdout).toContain("add <paths...>")
+		expect(result.stdout).toContain("remove <paths...>")
+		expect(result.stdout).toContain("--include-dot-directories")
+	})
+
+	it.each([["version"], ["--version"], ["-v"], ["add", "--version"]])(
+		"prints the package version: %j",
+		async (...args) => {
+			const manifest = JSON.parse(
+				await readFile(new URL("../package.json", import.meta.url), "utf8"),
+			) as { version: string }
+			const result = invoke(...args)
+			expect(result.status).toBe(0)
+			expect(result.stderr).toBe("")
+			expect(result.stdout).toBe(`${manifest.version}\n`)
+		},
+	)
+
+	it("honors explicit booleans and the last repeated switch", async () => {
+		expect(invoke("init").status).toBe(0)
+		const breadcrumb = await readFile(path.join(root, "AGENTS.md"), "utf8")
+		expect(
+			invoke("init", "--force", "--force=false", "--force=false").status,
+		).toBe(0)
+		expect(await readFile(path.join(root, "AGENTS.md"), "utf8")).toBe(
+			breadcrumb,
+		)
+		expect(invoke("init", "--force=false", "--force").status).toBe(0)
+		expect(
+			(await readFile(path.join(root, "AGENTS.md"), "utf8")).match(/Consult/g),
+		).toHaveLength(2)
+	})
+
+	it("discovers hidden directories on request and keeps JSON output clean", async () => {
+		await mkdir(path.join(root, ".hidden"))
+		await writeFile(
+			path.join(root, ".hidden", "AGENTS.md"),
+			"# Hidden instructions\n",
+		)
+		const ordinary = invoke("discover", "--json")
+		expect(ordinary.status).toBe(0)
+		expect(JSON.parse(ordinary.stdout)).toEqual([])
+		const hidden = invoke("--json", "discover", "--include-dot-directories")
+		expect(hidden.status).toBe(0)
+		expect(hidden.stderr).toBe("")
+		expect(JSON.parse(hidden.stdout)).toEqual([{ path: "./.hidden/AGENTS.md" }])
+	})
+
+	it("sets the validation exit status in both text and JSON modes", async () => {
+		expect(invoke("init").status).toBe(0)
+		const valid = invoke("validate", "--json")
+		expect(valid.status).toBe(0)
+		expect(JSON.parse(valid.stdout)).toMatchObject({ ok: true, errors: [] })
+		await saveAgentsFile(root, {
+			version: 1,
+			documents: [{ path: "./missing/AGENTS.md" }],
+		})
+		const invalid = invoke("validate", "--json")
+		expect(invalid.status).toBe(1)
+		expect(invalid.stderr).toBe("")
+		expect(JSON.parse(invalid.stdout)).toMatchObject({
+			ok: false,
+			errors: [expect.stringContaining("file does not exist")],
+		})
+		expect(invoke("validate").status).toBe(1)
+	})
+
+	it("generates completion scripts without loading the document index or changing files", async () => {
+		await writeFile(path.join(root, "agents.yaml"), "not: [valid yaml")
+		const result = invoke("completion", "bash")
+		expect(result.status).toBe(0)
+		expect(result.stderr).toBe("")
+		expect(result.stdout).toContain("_comline")
+		expect(result.stdout).not.toContain("What would you like to do?")
+		expect(await readdir(root)).toEqual(["agents.yaml"])
+		expect(await readFile(path.join(root, "agents.yaml"), "utf8")).toBe(
+			"not: [valid yaml",
+		)
+	})
+
+	it("completes listed paths after each remove argument without removing documents", async () => {
+		const file = {
+			version: 1 as const,
+			documents: [
+				{ path: "./one/AGENTS.md" },
+				{ path: "./two/AGENTS.md", description: "Second document" },
+			],
+		}
+		await saveAgentsFile(root, file)
+		const result = invoke("__complete", "remove", "./one/AGENTS.md", "./t")
+		expect(result.status).toBe(0)
+		expect(result.stderr).toBe("")
+		expect(result.stdout).toContain("./two/AGENTS.md\tSecond document")
+		expect(await loadAgentsFile(root)).toEqual(file)
+	})
+
+	it("offers filesystem completion for every add argument", async () => {
+		for (const words of [
+			["add", ""],
+			["add", "./one/AGENTS.md", ""],
+		]) {
+			const result = await agents.complete({ words })
+			expect(result.fileSystem).toBe("files")
+		}
+	})
+})

package/src/run.ts

@@ -1,5 +1,6 @@
 import { MultiSelectPrompt } from "@clack/core"
 import * as clack from "@clack/prompts"
+import { completionResponse, help } from "comline"
 import { styleText } from "node:util"
 import {
 	addDocuments,
@@ -8,132 +9,70 @@ import {
 	removeDocuments,
 	validateAgentsFile,
 } from "./agents-file.ts"
+import { agents, earlyCommand, packageVersion } from "./cli.ts"
 import { describeAgentDocument, discoverAgentDocuments } from "./discover.ts"
 import { cwd, formatProjectPath, resolveFromRoot } from "./paths.ts"
 
-type Command =
-	| "add"
-	| "discover"
-	| "help"
-	| "init"
-	| "remove"
-	| "validate"
-	| "version"
-
-type ParsedArgs = {
-	command: Command | undefined
-	values: string[]
-	flags: Map<string, string | boolean>
-}
-
 type DocumentOption = {
 	value: string
 	label: string
 	disabled?: boolean
 }
 
-const helpText = `agents
-
-Usage:
-  agents
-  agents init [--force]
-  agents discover [--json] [--include-dot-directories]
-  agents add <path...>
-  agents remove <path...>
-  agents validate [--json]
+export async function run(argv: string[]): Promise<void> {
+	const completion = await completionResponse(agents.definition, argv)
+	if (completion !== undefined) {
+		process.stdout.write(completion)
+		return
+	}
 
-agents.yaml is a curated table of contents for promoted AGENTS.md guidance.`
+	const early = earlyCommand(argv)
+	if (early === "help") {
+		console.log(help(agents.definition))
+		return
+	}
+	if (early === "version") {
+		console.log(packageVersion())
+		return
+	}
 
-export async function run(argv: string[]): Promise<void> {
-	const parsed = parseArgs(argv)
+	const { inputs, warnings } = agents(argv)
+	if (warnings.length > 0) {
+		throw new Error(warnings.map((warning) => warning.message).join("\n"))
+	}
 	const root = cwd()
 
-	switch (parsed.command) {
-		case undefined:
+	switch (inputs.case) {
+		case "":
 			await interactive(root)
 			return
 		case "help":
-			console.log(helpText)
+			console.log(help(agents.definition))
 			return
 		case "version":
-			console.log("0.1.0")
+			console.log(packageVersion())
 			return
 		case "init":
-			await commandInit(root, parsed.flags.get("force") === true)
+			await commandInit(root, inputs.opts.force)
 			return
 		case "discover":
 			await commandDiscover(root, {
-				json: parsed.flags.get("json") === true,
-				includeDotDirectories:
-					parsed.flags.get("include-dot-directories") === true,
+				json: inputs.opts.json,
+				includeDotDirectories: inputs.opts["include-dot-directories"],
 			})
 			return
-		case "add":
-			await commandAdd(root, parsed.values)
+		case "add/$...paths":
+			await commandAdd(root, inputs.params.paths)
 			return
-		case "remove":
-			await commandRemove(root, parsed.values)
+		case "remove/$...paths":
+			await commandRemove(root, inputs.params.paths)
 			return
 		case "validate":
-			await commandValidate(root, parsed.flags.get("json") === true)
+			await commandValidate(root, inputs.opts.json)
 			return
 	}
 }
 
-function parseArgs(argv: string[]): ParsedArgs {
-	const flags = new Map<string, string | boolean>()
-	const values: string[] = []
-	let command: Command | undefined
-
-	for (let index = 0; index < argv.length; index += 1) {
-		const arg = argv[index]
-		if (!arg) continue
-
-		if (arg === "--help" || arg === "-h") {
-			command = "help"
-			continue
-		}
-
-		if (arg === "--version" || arg === "-v") {
-			command = "version"
-			continue
-		}
-
-		if (arg.startsWith("--")) {
-			const [rawName, inlineValue] = arg.slice(2).split("=", 2)
-			if (!rawName) continue
-			if (inlineValue !== undefined) {
-				flags.set(rawName, inlineValue)
-				continue
-			}
-
-			flags.set(rawName, true)
-			continue
-		}
-
-		if (!command && isCommand(arg)) {
-			command = arg
-			continue
-		}
-
-		values.push(arg)
-	}
-
-	return { command, values, flags }
-}
-
-function isCommand(value: string): value is Command {
-	return [
-		"add",
-		"discover",
-		"help",
-		"init",
-		"remove",
-		"validate",
-		"version",
-	].includes(value)
-}
-
 async function commandInit(root: string, force: boolean): Promise<void> {
 	clack.intro("agents init")
 	const result = await initProject(root, { force })
@@ -216,6 +155,9 @@ async function commandRemove(root: string, paths: string[]): Promise<void> {
 
 async function commandValidate(root: string, json: boolean): Promise<void> {
 	const result = await validateAgentsFile(root)
+	if (!result.ok) {
+		process.exitCode = 1
+	}
 	if (json) {
 		console.log(JSON.stringify(result, null, 2))
 		return
@@ -232,9 +174,6 @@ async function commandValidate(root: string, json: boolean): Promise<void> {
 	clack.outro(
 		result.ok ? "agents.yaml is valid." : "agents.yaml needs attention.",
 	)
-	if (!result.ok) {
-		process.exitCode = 1
-	}
 }
 
 async function interactive(root: string): Promise<void> {
@@ -290,10 +229,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() {
@@ -317,6 +256,8 @@ ${styleText("cyan", clack.S_BAR_END)}
 `
 		},
 	}).prompt()
+
+	return typeof selected === "symbol" ? clack.CANCEL_SYMBOL : selected
 }
 
 function styleDocumentOption(

package/dist/index.d.mts

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