cyber-agentkit 0.0.0-stage → 0.7.1

package/dist/commands.js

@@ -0,0 +1,984 @@
+import { C as userReferencesDir, E as require_dist, M as pluginManifestName, S as repositoryRoot, _ as parseSections, a as interfaceLookup, b as projectReferencesDir, c as readExtends, d as parseReferenceName, f as fitsName, g as parseDocument, h as isMergeOperation, i as checkResolved, m as hasBody, n as referenceImplementations, o as listReferences, p as frontmatterPattern, r as checkReferences, s as searchReferences, t as whereReference, u as resolveReference, v as canonical, w as skillName, x as referenceLayers } from "./reference-where-BhymfNgA.js";
+import { dirname, join, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { command, exitCodes, t } from "clibuilder";
+import { CliError, document, encode, isCliError, printAnswer, result } from "clibuilder/axi";
+//#region src/command-output/collapse-home.ts
+/**
+* AXI §10: collapses the home directory to `~` so a path in a report is portable to another
+* machine.
+*/
+function collapseHome(home, path) {
+	return home && path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
+}
+//#endregion
+//#region src/references/create-reference.ts
+var import_dist = require_dist();
+/** No `#` title: `patch` matches by heading path, so a title would hold every section under it. */
+const defaultTemplate = `---
+description: What this reference covers, and when an agent should read it.
+tags: [topic]
+---
+
+## Overview
+
+Write the guidance here. Give each topic its own top-level \`##\` section.
+`;
+/** The interface's sections as `##` headings, in order, each stubbed `**Unsupported.**`. */
+function implementationTemplate(iface) {
+	const sections = iface.sections.map((name) => `## ${name}\n\n**Unsupported.** Replace this line with the section, or say in one sentence why it is not supported.\n`);
+	return parseTemplate(`---\ndescription: What this ${iface.id} implementation covers, and when an agent should read it.\nimplements: ${iface.id}@${iface.version}\n---\n\n${sections.join("\n")}`, `the ${iface.id} interface`);
+}
+function readTemplate(path) {
+	if (path === void 0) return parseTemplate(defaultTemplate, "the default template");
+	let content;
+	try {
+		content = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new Error(`cannot read the template ${path}: ${error.message}`);
+	}
+	return parseTemplate(content, `the template ${path}`);
+}
+function parseTemplate(content, label) {
+	let mapping = true;
+	const { metadata, body } = parseDocument(content, () => {
+		mapping = false;
+	});
+	if (!mapping) throw new Error(`${label} has frontmatter that is not a YAML mapping.`);
+	return {
+		content,
+		metadata,
+		body
+	};
+}
+/**
+* A title: the top level is a single heading holding every other one. `patch` matches by heading
+* path, so it would add the whole document under the title instead of patching its sections.
+*/
+function titleOf({ body }) {
+	const tree = parseSections(body, () => {});
+	const [only] = tree.children;
+	return tree.children.length === 1 && only?.children.length ? only.heading.trim() : void 0;
+}
+function hasDescription({ metadata }) {
+	return typeof metadata["description"] === "string" && metadata["description"].trim().length > 0;
+}
+/**
+* Sets or removes frontmatter keys and keeps the rest of the file as written: other keys, comments,
+* and the body. A file left with no key and no body is empty.
+*/
+function editFrontmatter(raw, keys) {
+	const match = frontmatterPattern.exec(raw);
+	const body = match ? raw.slice(match[0].length) : raw;
+	const doc = (0, import_dist.parseDocument)(match ? match[1] : "");
+	for (const [key, value] of Object.entries(keys)) if (value === void 0) doc.delete(key);
+	else {
+		const node = doc.createNode(value, { flow: Array.isArray(value) });
+		doc.set(key, node);
+	}
+	if (!doc.contents?.items?.length) return body.replace(/^(?:[ \t]*\r?\n)+/, "");
+	const gap = !match && body.trim() ? "\n" : "";
+	return `---\n${doc.toString({
+		lineWidth: 0,
+		flowCollectionPadding: false
+	})}---\n${gap}${body}`;
+}
+//#endregion
+//#region src/references/reference-write.ts
+/** A write refused. `usage` marks a wrong invocation (exit 2) rather than a refusal (exit 1). */
+var ReferenceWriteError = class extends Error {
+	code;
+	usage;
+	constructor(code, message, usage = false) {
+		super(message);
+		this.code = code;
+		this.usage = usage;
+	}
+};
+/** A bare, valid name, or a refusal naming the bare name to use. */
+function bareName(value) {
+	const name = parseReferenceName(value);
+	if (name.invalid) throw new ReferenceWriteError("reference-invalid", name.invalid);
+	if (name.plugin !== void 0) throw new ReferenceWriteError("reference-qualified", `a contribution is written under the bare name, which every tier resolves; ask for "${name.name}".`);
+	return name;
+}
+/** The repository the root sits in: a write to a source folder must land inside it, and never in an installed copy. */
+function insideRepository(folder, root) {
+	const repository = canonical(repositoryRoot(root) ?? resolve(root));
+	const target = canonical(folder);
+	if (target !== repository && !target.startsWith(repository + sep)) return false;
+	return !target.slice(repository.length).split(sep).includes("node_modules");
+}
+/** Resolves `--scope`, `--plugin`, and `--default` to the file a write acts on; more than one is a usage error. */
+function writeTarget(name, { root, home, scope, plugin, default: skill }) {
+	if ([
+		scope,
+		plugin,
+		skill
+	].filter((value) => value !== void 0).length > 1) throw new ReferenceWriteError("options-conflict", "pass one of --scope, --plugin, and --default.", true);
+	if (plugin !== void 0) {
+		const folder = resolve(plugin);
+		if (!pluginManifestName(folder)) throw new ReferenceWriteError("folder-invalid", `${folder} holds no plugin manifest, so it is not a plugin folder.`);
+		if (!insideRepository(folder, root)) throw new ReferenceWriteError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the plugin's source instead.`);
+		const dir = join(folder, "references");
+		return {
+			scope: "plugin",
+			dir,
+			path: join(dir, `${name.name}.md`)
+		};
+	}
+	if (skill !== void 0) {
+		const folder = resolve(skill);
+		if (skillName(folder) === void 0) throw new ReferenceWriteError("folder-invalid", `${folder} holds no SKILL.md, so it is not a skill folder.`);
+		if (!insideRepository(folder, root)) throw new ReferenceWriteError("folder-invalid", `${folder} is outside the repository, such as an installed copy; write to the skill's source instead.`);
+		const dir = join(folder, "references");
+		return {
+			scope: "default",
+			dir,
+			path: join(dir, `${name.name}.default.md`)
+		};
+	}
+	if (scope !== void 0 && scope !== "project" && scope !== "user") throw new ReferenceWriteError("options-invalid", "--scope is project or user.", true);
+	const dir = scope === "user" ? userReferencesDir(home) : projectReferencesDir(resolve(root));
+	return {
+		scope: scope === "user" ? "user" : "project",
+		dir,
+		path: join(dir, `${name.name}.md`)
+	};
+}
+function tryRead(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+}
+/** What answers a name, in one sentence a person reads. */
+function describeAnswer(resolved, display = (path) => path) {
+	if (resolved.status === "found") {
+		const top = resolved.trace.contributions.at(-1);
+		const by = top ? top.tier === "plugin" ? `plugin ${top.plugin}` : top.tier === "default" ? `the default of ${top.skill}` : `the ${top.tier} file ${display(top.path)}` : "nothing";
+		const stack = resolved.trace.stack.length ? `, on the stack ${resolved.trace.stack.join(" → ")}` : "";
+		return `"${resolved.name}" is answered by ${by}${stack}.`;
+	}
+	if (resolved.status === "ambiguous") return `"${resolved.name}" is ambiguous: ${resolved.message}; the options are ${(resolved.options ?? []).join(", ")}.`;
+	return `"${resolved.name}" is ${resolved.status}: ${resolved.message}.`;
+}
+/** The interface `create --implements` starts an implementation of, once the new name fits it. */
+function interfaceFor(id, name, layers, options) {
+	const parsed = parseReferenceName(id);
+	if (parsed.invalid || parsed.plugin !== void 0) throw new ReferenceWriteError("interface-invalid", `"${id}" is not an interface id.`);
+	const iface = interfaceLookup(layers, options)(id);
+	if (!iface.value) throw new ReferenceWriteError("interface-invalid", iface.failure?.message ?? `no interface ${id}`);
+	if (!fitsName(iface.value, name)) throw new ReferenceWriteError("interface-invalid", `an implementation of ${id} is named ${iface.value.cardinality === "one" ? id : `${id}.<key>`}, not "${name}".`);
+	return iface.value;
+}
+/**
+* Hides the new file: a `replace` with a body, or a `remove`, that applies above it. A folder that
+* is not a layer the stack reads has nothing above it.
+*/
+function hiddenBy(resolved, dir, path) {
+	const layers = resolved.trace.layers;
+	const at = layers.findIndex((layer) => layer.path === dir || layer.path === path);
+	if (at === -1) return void 0;
+	const target = layers[at];
+	const tiered = (tier) => tier === "managed" || tier === "project" || tier === "user";
+	const stackAt = target && !tiered(target.tier) ? resolved.trace.stack.indexOf(target.tier === "default" ? "default" : target.plugin ?? "") : -1;
+	const hider = layers.filter((layer, index) => {
+		if (!layer.file || layer.outcome !== "used") return false;
+		if (target && tiered(target.tier)) return index < at && tiered(layer.tier);
+		if (tiered(layer.tier)) return true;
+		const position = resolved.trace.stack.indexOf(layer.tier === "default" ? "default" : layer.plugin ?? "");
+		return stackAt !== -1 && position > stackAt;
+	}).find((layer) => layer.operation === "remove" || layer.operation === "replace" && !layer.empty);
+	return hider ? `${hider.tier}${hider.plugin ? ` ${hider.plugin}` : ""} ${hider.path} (${hider.operation})` : void 0;
+}
+/** A selection-only file keeps its own keys, `extends` among them; the template adds the keys it lacks. */
+function selectionKeys(existing, template, merge) {
+	const held = parseDocument(existing, () => {}).metadata;
+	const keys = {};
+	for (const [key, value] of Object.entries(template.metadata)) if (key !== "merge" && !(key in held)) keys[key] = value;
+	keys["merge"] = merge;
+	return keys;
+}
+function withBody(head, body) {
+	const text = body.replace(/^(?:[ \t]*\r?\n)+/, "");
+	return text ? `${head.replace(/\s*$/, "")}\n\n${text}` : head;
+}
+function createContribution(layers, args, options = {}) {
+	const name = bareName(args.name);
+	const target = writeTarget(name, args);
+	if (args.merge !== void 0 && !isMergeOperation(args.merge)) throw new ReferenceWriteError("options-invalid", `--merge is replace, patch, combine, or remove; got "${args.merge}".`, true);
+	const merge = args.merge;
+	if (args.template !== void 0 && args.implements !== void 0) throw new ReferenceWriteError("options-conflict", "pass --template or --implements, not both.");
+	if (merge === "remove" && args.template !== void 0) throw new ReferenceWriteError("options-conflict", "--merge remove writes no body, so it takes no --template.");
+	if (merge !== void 0 && target.scope === "default") throw new ReferenceWriteError("options-conflict", "a default is written with no merge; drop --merge.");
+	const existing = tryRead(target.path);
+	if (existing !== void 0 && hasBody(parseDocument(existing, () => {}).body)) throw new ReferenceWriteError("file-exists", `${(options.display ?? ((path) => path))(target.path)} already holds "${name.name}"; change it with the reference skill's Update mode.`);
+	const template = args.implements !== void 0 ? implementationTemplate(interfaceFor(args.implements, name.name, layers, options)) : merge === "remove" ? {
+		content: "",
+		metadata: {},
+		body: ""
+	} : readTemplate(args.template === void 0 ? void 0 : resolve(args.template));
+	const title = titleOf(template);
+	if (title) throw new ReferenceWriteError("template-title", `the template's top level is the single heading "${title}" holding the others; patch matches by heading path, so make its sections top-level.`);
+	const before = resolveReference(name, layers, options);
+	const hider = hiddenBy(before, target.dir, target.path);
+	if (hider) throw new ReferenceWriteError("hidden", `${hider} applies above it, so nothing would read the new file; change that contribution instead.`);
+	const operation = target.scope === "default" ? void 0 : args.implements !== void 0 ? "replace" : merge ?? (isMergeOperation(template.metadata["merge"]) ? template.metadata["merge"] : void 0) ?? (target.scope === "plugin" ? void 0 : "patch");
+	const content = existing === void 0 ? editFrontmatter(template.content, { merge: operation }) : withBody(editFrontmatter(existing, selectionKeys(existing, template, operation)), template.body);
+	const hints = hasDescription(parseDocument(content, () => {})) ? [] : ["it has no `description` in its frontmatter, so `list` and `search` show it blank"];
+	const result = {
+		name: name.name,
+		scope: target.scope,
+		path: target.path,
+		content,
+		dryRun: Boolean(args.dryRun),
+		hints
+	};
+	if (result.dryRun) return result;
+	mkdirSync(target.dir, { recursive: true });
+	writeFileSync(target.path, content, existing === void 0 ? { flag: "wx" } : {});
+	if (before.trace.layers.some((layer) => layer.path === target.dir || layer.path === target.path)) result.after = resolveReference(name, layers, options);
+	return result;
+}
+function selectContribution(layers, args, options = {}) {
+	const name = bareName(args.name);
+	const target = writeTarget(name, {
+		root: args.root,
+		home: args.home,
+		scope: args.scope
+	});
+	const scope = target.scope;
+	const existing = tryRead(target.path);
+	if (args.clear) {
+		if (args.options.length) throw new ReferenceWriteError("options-conflict", "--clear takes no option.", true);
+		if (!(existing === void 0 ? void 0 : readExtends(parseDocument(existing, () => {}).metadata["extends"], () => {}))) throw new ReferenceWriteError("no-selection", `the ${scope} tier holds no selection of "${name.name}". ${describeAnswer(resolveReference(name, layers, options), options.display)}`);
+		const content = editFrontmatter(existing, { extends: void 0 });
+		const deleted = !content.trim();
+		if (deleted) rmSync(target.path);
+		else writeFileSync(target.path, content);
+		return {
+			name: name.name,
+			scope,
+			path: target.path,
+			extends: [],
+			deleted,
+			after: resolveReference(name, layers, options)
+		};
+	}
+	if (!args.options.length) throw new ReferenceWriteError("options-missing", "name at least one option: a plugin or default.", true);
+	const before = resolveReference(name, layers, options);
+	const holders = new Set(before.trace.layers.flatMap(({ plugin, file }) => plugin !== void 0 && file ? [plugin] : []));
+	const picked = args.options.map((option) => option.endsWith(`/${name.name}`) ? option.slice(0, -name.name.length - 1) : option);
+	const wrong = picked.filter((option) => option !== "default" && !holders.has(option));
+	if (wrong.length) throw new ReferenceWriteError("option-invalid", `${wrong.join(", ")} ${wrong.length === 1 ? "is" : "are"} neither default nor a plugin holding "${name.name}"${holders.size ? `; the plugins holding it are ${[...holders].join(", ")}` : ""}.`);
+	const content = editFrontmatter(existing ?? "", { extends: picked });
+	mkdirSync(target.dir, { recursive: true });
+	writeFileSync(target.path, content);
+	return {
+		name: name.name,
+		scope,
+		path: target.path,
+		extends: picked,
+		deleted: false,
+		after: resolveReference(name, layers, options)
+	};
+}
+function deleteContribution(layers, args, options = {}) {
+	const name = bareName(args.name);
+	const target = writeTarget(name, args);
+	const shown = options.display ?? ((path) => path);
+	const before = resolveReference(name, layers, options);
+	const path = (target.scope === "project" || target.scope === "user" ? [target.path, join(target.dir, name.name, "README.md")] : [target.path]).find((candidate) => candidate !== options.without && existsSync(candidate));
+	if (!path) throw new ReferenceWriteError("no-file", `${shown(target.path)} does not exist, so there is no ${target.scope} contribution of "${name.name}" to delete. ${describeAnswer(before, options.display)} An installed plugin's, a managed, or an installed skill's contribution is never deleted.`);
+	const steps = readExtends(parseDocument(tryRead(path) ?? "", () => {}).metadata["extends"], () => {});
+	const dryRun = Boolean(args.dryRun);
+	if (!dryRun) {
+		rmSync(path);
+		if (dirname(path) !== target.dir) try {
+			rmdirSync(dirname(path));
+		} catch {}
+	}
+	const result = {
+		name: name.name,
+		scope: target.scope,
+		path,
+		dryRun,
+		after: resolveReference(name, layers, {
+			...options,
+			without: dryRun ? path : void 0
+		})
+	};
+	if (steps) result.selection = steps.map(({ target: step }) => step);
+	return result;
+}
+//#endregion
+//#region src/references/reference.command.ts
+const rootOption = {
+	description: "Directory the project tier is read from, and each folder above it up to the repository root; a project write goes to its `.agents/references/`. Defaults to the current directory.",
+	type: t.string().optional()
+};
+const traceOption = {
+	description: "Add the trace: every layer checked, with its outcome, and how the result was built.",
+	type: t.boolean().optional()
+};
+const defaultOption = {
+	description: "The calling skill's folder: its `references/<name>.default.md` joins as the `default` tier.",
+	type: t.string().optional()
+};
+function layerSource(plugin) {
+	return (args, home) => referenceLayers({
+		root: args.root ?? process.cwd(),
+		home,
+		platform: process.platform,
+		env: process.env,
+		plugin,
+		defaultSkill: args.default
+	});
+}
+/** A field with nothing to say is left out: `undefined`, an empty string, or an empty list. */
+function compact(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0 && field !== "" && !(Array.isArray(field) && !field.length)));
+}
+/** stderr, not stdout: an agent parses stdout. Rethrows what the cli already reports. */
+function fail(error, fallback) {
+	if (isCliError(error)) throw error;
+	if (error instanceof ReferenceWriteError) {
+		process.stderr.write(`error: ${error.code}: ${error.message}\n`);
+		throw CliError.reported(error.usage ? exitCodes.usage : exitCodes.error);
+	}
+	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
+	throw CliError.reported(exitCodes.error);
+}
+function usage(message) {
+	process.stderr.write(`error: usage: ${message}\n`);
+	throw CliError.reported(exitCodes.usage);
+}
+/** An answer with a failing exit code: the cli prints only what a returned answer holds, so print it first. */
+function answerThenFail(answer, format) {
+	const text = printAnswer(answer, format);
+	if (text !== void 0) process.stdout.write(text);
+	throw CliError.reported(exitCodes.error);
+}
+function writeWarnings(warnings) {
+	for (const { code, message } of warnings) process.stderr.write(`warning: ${code}: ${message}\n`);
+}
+function displayTrace(trace, home) {
+	const show = (path) => collapseHome(home, path);
+	return {
+		...trace,
+		contributions: trace.contributions.map((row) => ({
+			...row,
+			path: show(row.path)
+		})),
+		layers: trace.layers.map((layer) => ({
+			...layer,
+			path: show(layer.path)
+		}))
+	};
+}
+/** The text trace: a summary line, then each section with its contributions, then each layer. */
+function traceText(resolved, home) {
+	const trace = displayTrace(resolved.trace, home);
+	const lines = [`${resolved.name}: ${resolved.status}; stack: ${trace.stack.join(" → ") || "none"}; built by ${trace.builtBy}; harnesses: ${trace.harnesses.join(", ") || "none detected"}`];
+	if (resolved.message) lines.push(`  ${resolved.message}`);
+	if (trace.sections.length) {
+		lines.push("sections:");
+		for (const section of trace.sections) {
+			const how = section.removedBy ? `removed by ${section.removedBy}` : section.contributions.map(({ contribution, operation }) => `${contribution} (${operation})`).join(", ") || "no text";
+			lines.push(`  ${section.path}: ${how}`);
+		}
+	}
+	lines.push("layers:");
+	for (const layer of trace.layers) {
+		const who = layer.plugin ? ` ${layer.plugin}` : layer.skill ? ` ${layer.skill}` : "";
+		const how = layer.operation ? `; ${layer.operation} from ${layer.operationFrom}` : "";
+		const extendsNote = layer.extendsOutcome ? `; extends ${layer.extendsOutcome}` : "";
+		const selection = layer.selection ? "; selection" : "";
+		const frontmatter = layer.frontmatter && Object.keys(layer.frontmatter).length ? ` ${JSON.stringify(layer.frontmatter)}` : "";
+		lines.push(`  ${layer.tier}${who} ${layer.path}: ${layer.outcome}${how}${extendsNote}${selection}${frontmatter}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/** A name not found, for a person: the name, why, and, when ambiguous, the options `reference select` takes. */
+function errorText(entry) {
+	const options = entry.options?.length ? `; options: ${entry.options.join(", ")}` : "";
+	return `${entry.name}: ${entry.message}${options}`;
+}
+function showEntry(resolved, home, { metadata, trace }) {
+	if (resolved.status === "found" && !resolved.warnings.length && !metadata && !trace) return resolved.content;
+	return compact({
+		name: resolved.name,
+		status: resolved.status,
+		content: resolved.content,
+		code: resolved.code,
+		options: resolved.options,
+		metadata: metadata ? resolved.metadata : void 0,
+		warnings: resolved.warnings,
+		trace: trace ? displayTrace(resolved.trace, home) : void 0
+	});
+}
+/** One entry per name asked, as the array itself rather than under a `result` key. */
+const bareArray = {
+	toon: (entries) => encode(entries, "toon"),
+	json: (entries) => encode(entries, "json")
+};
+function showText(resolved) {
+	if (resolved.length === 1) {
+		const [only] = resolved;
+		return only.content === void 0 ? void 0 : document(only.content);
+	}
+	const blocks = resolved.map((entry) => entry.content === void 0 ? `<reference name="${entry.name}" status="${entry.status}" />` : `<reference name="${entry.name}">\n${entry.content}</reference>`);
+	return document(blocks.join("\n\n"));
+}
+function showCommand(layersFor) {
+	return command({
+		name: "show",
+		description: "Print one or more references, each composed from its contributions as their extends and merge declare.",
+		arguments: [{
+			name: "names",
+			description: "Reference names, without the `.md` extension; `<plugin>/<name>` builds that plugin’s own stack.",
+			type: t.array(t.string())
+		}],
+		options: {
+			root: rootOption,
+			default: defaultOption,
+			metadata: {
+				description: "Make every entry a record with its status and composed frontmatter.",
+				type: t.boolean().optional()
+			},
+			trace: traceOption
+		},
+		async run(args) {
+			const format = this.format;
+			if (!args.names.length) usage("name at least one reference.");
+			try {
+				const home = homedir();
+				const layers = await layersFor(args, home);
+				const display = (path) => collapseHome(home, path);
+				const lookup = interfaceLookup(layers, { display });
+				const resolved = args.names.map((name) => {
+					const entry = resolveReference(parseReferenceName(name), layers, { display });
+					for (const failure of checkResolved(entry, lookup).failures) {
+						if (failure.check === "compose") continue;
+						entry.warnings.push({
+							code: "interface-check",
+							message: `it fails its interface check (${failure.check}): ${failure.message}`
+						});
+					}
+					return entry;
+				});
+				const ok = resolved.every((entry) => entry.status === "found");
+				if (format === "text") {
+					for (const entry of resolved) {
+						writeWarnings(entry.warnings);
+						if (entry.status !== "found") process.stderr.write(`error: ${entry.code}: ${errorText(entry)}\n`);
+						if (args.trace) process.stderr.write(traceText(entry, home));
+					}
+					const answer = showText(resolved);
+					if (answer === void 0) throw CliError.reported(exitCodes.error);
+					return ok ? answer : answerThenFail(answer, format);
+				}
+				const flags = {
+					metadata: Boolean(args.metadata),
+					trace: Boolean(args.trace)
+				};
+				const answer = result(resolved.map((entry) => showEntry(entry, home, flags)), { render: bareArray });
+				return ok ? answer : answerThenFail(answer, format);
+			} catch (error) {
+				return fail(error, "Reference lookup failed.");
+			}
+		}
+	});
+}
+function listCommand(layersFor) {
+	return command({
+		name: "list",
+		description: "List every reference name, one row each, with its description, and its status when not found. A pattern keeps only the names it matches exactly.",
+		arguments: [{
+			name: "pattern",
+			description: "Exact name pattern, where `*` stands for any run of characters, such as `project-tracker.capabilities.*`.",
+			type: t.string().optional()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add one row per name per layer holding it, with its outcome."
+			}
+		},
+		async run(args) {
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const listing = listReferences(await layersFor(args, home), {
+					display,
+					pattern: args.pattern
+				});
+				const report = compact({
+					references: listing.references.length ? listing.references.map((row) => compact({
+						name: row.name,
+						description: row.description,
+						status: row.status === "found" ? void 0 : row.status,
+						options: row.options
+					})) : args.pattern ? `0 references match "${args.pattern}"` : "0 references — no layer holds one",
+					defaults: listing.defaults
+				});
+				if (args.trace) report.layers = listing.layers.map((row) => compact({
+					...row,
+					path: display(row.path)
+				}));
+				if (listing.warnings.length) report.warnings = listing.warnings;
+				return result(report);
+			} catch (error) {
+				return fail(error, "Reference listing failed.");
+			}
+		}
+	});
+}
+function searchCommand(layersFor) {
+	return command({
+		name: "search",
+		description: "Find references by name, description, tags, headings, or body, best match first.",
+		arguments: [{
+			name: "query",
+			description: "What the reference is about.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add the tier and plugin or skill of each match."
+			}
+		},
+		async run(args) {
+			const query = args.query.trim();
+			if (!query) usage("search needs a query.");
+			try {
+				const home = homedir();
+				const { matches, defaults } = searchReferences(query, await layersFor(args, home), { display: (path) => collapseHome(home, path) });
+				const report = compact({
+					references: matches.length ? matches.map(({ name, description, match, tier, plugin, skill, loadedBy }) => compact(args.trace ? {
+						name,
+						description,
+						match,
+						loadedBy,
+						tier,
+						plugin,
+						skill
+					} : {
+						name,
+						description,
+						match,
+						loadedBy
+					})) : `0 references match "${query}"`,
+					defaults
+				});
+				return result(report);
+			} catch (error) {
+				return fail(error, "Reference search failed.");
+			}
+		}
+	});
+}
+function whereCommand(layersFor) {
+	return command({
+		name: "where",
+		description: "Give the project and user files a customization or a selection of a reference is written to, who each reaches, and the heading paths of the document below each.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			default: defaultOption,
+			trace: {
+				...traceOption,
+				description: "Add every layer checked, with its outcome."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const display = (path) => collapseHome(home, path);
+				const report = whereReference(args.name, await layersFor(args, home), {
+					root: resolve(args.root ?? process.cwd()),
+					display
+				});
+				const output = compact({
+					name: report.name,
+					status: report.status,
+					places: report.places.map((place) => compact(place)),
+					options: report.options,
+					layers: args.trace ? report.layers.map((layer) => ({
+						...layer,
+						path: display(layer.path)
+					})) : void 0,
+					warnings: report.warnings
+				});
+				if (format === "text") writeWarnings(report.warnings);
+				const answer = result(output);
+				if (report.status !== "invalid") return answer;
+				process.stderr.write(`error: reference-invalid: ${parseReferenceName(args.name).invalid}\n`);
+				return answerThenFail(answer, format);
+			} catch (error) {
+				return fail(error, "Reference placement lookup failed.");
+			}
+		}
+	});
+}
+function parseAccept(value) {
+	if (value === void 0) return void 0;
+	const versions = value.split(",").map((part) => part.trim());
+	if (!versions.length || versions.some((part) => !/^[1-9]\d*$/.test(part))) usage(`--accept is a comma-separated list of versions, such as 1,2; got "${value}".`);
+	return versions.map(Number);
+}
+function implementationsCommand(layersFor) {
+	return command({
+		name: "implementations",
+		description: "List the implementations of an interface a consumer can load, each with its pin, description, and unsupported sections.",
+		arguments: [{
+			name: "id",
+			description: "Interface id, the name of its `<id>.interface` document without the suffix.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			accept: {
+				description: "Versions the consumer knows, comma-separated, such as 1,2. Defaults to the interface's `versions`.",
+				type: t.string().optional()
+			},
+			trace: {
+				...traceOption,
+				description: "Add each one's name, tier, and version, the interface's cardinality and accepted versions, and the ones left out with why."
+			}
+		},
+		async run(args) {
+			const accept = parseAccept(args.accept);
+			try {
+				const home = homedir();
+				const found = referenceImplementations(args.id, await layersFor(args, home), {
+					accept,
+					display: (path) => collapseHome(home, path)
+				});
+				const rows = found.implementations.map(({ pin, description, unsupported, name, tier, version }) => compact(args.trace ? {
+					pin,
+					description,
+					unsupported,
+					name,
+					tier,
+					version
+				} : {
+					pin,
+					description,
+					unsupported
+				}));
+				const report = { implementations: rows.length ? rows : `0 implementations of ${args.id}` };
+				if (args.trace) Object.assign(report, compact({
+					interface: found.interface,
+					cardinality: found.cardinality,
+					accept: found.accept,
+					excluded: found.excluded,
+					warnings: found.warnings
+				}));
+				return result(report);
+			} catch (error) {
+				return fail(error, "Implementation lookup failed.");
+			}
+		}
+	});
+}
+function checkCommand(layersFor) {
+	return command({
+		name: "check",
+		description: "Check interface documents and their implementations, each composed as `show` composes it. With no names, checks every one found. Exits 1 on any failure.",
+		arguments: [{
+			name: "names",
+			description: "Reference names, without the `.md` extension; `<plugin>/<name>` builds that plugin’s own stack.",
+			type: t.array(t.string()).optional()
+		}],
+		options: {
+			root: rootOption,
+			trace: {
+				...traceOption,
+				description: "Add every entry checked, with its kind and unsupported sections."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const entries = checkReferences(await layersFor(args, home), {
+					names: args.names ?? [],
+					display: (path) => collapseHome(home, path)
+				});
+				const failing = entries.filter((entry) => entry.status !== "passed");
+				const strip = (failures) => failures.map(({ check, message }) => ({
+					check,
+					message
+				}));
+				const report = compact({
+					failed: failing.map(({ name, loadedBy, failures }) => compact({
+						name,
+						loadedBy,
+						failures: strip(failures)
+					})),
+					passed: entries.length - failing.length,
+					references: args.trace ? entries.map(({ name, loadedBy, kind, status, failures, unsupported }) => compact({
+						name,
+						loadedBy,
+						kind,
+						status,
+						failures: strip(failures),
+						unsupported
+					})) : void 0
+				});
+				const answer = result(report);
+				if (!failing.length) return answer;
+				if (format === "text") process.stderr.write(`error: interface-check: ${failing.length} of ${entries.length} references fail their check.\n`);
+				return answerThenFail(answer, format);
+			} catch (error) {
+				return fail(error, "Reference check failed.");
+			}
+		}
+	});
+}
+const scopeOption = {
+	description: "Tier to write: project (default), `.agents/references/` at the root, or user, `~/.agents/references/`.",
+	type: t.string().optional()
+};
+const pluginOption = {
+	description: "A plugin's source folder in this repository: acts on its `references/<name>.md`.",
+	type: t.string().optional()
+};
+const skillOption = {
+	description: "A skill's source folder in this repository: acts on its `references/<name>.default.md`.",
+	type: t.string().optional()
+};
+function createCommand(layersFor) {
+	return command({
+		name: "create",
+		description: "Start a contribution in the project or user tier, or in a plugin's or a skill's source folder, from a template or an interface. Never overwrites a file with a body.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			scope: scopeOption,
+			plugin: pluginOption,
+			default: skillOption,
+			merge: {
+				description: "How it applies over what is below: replace, patch (default), combine, or remove. remove writes no body.",
+				type: t.string().optional()
+			},
+			template: {
+				description: "File whose text is written as it is, frontmatter included. Defaults to a built-in template of top-level `##` sections.",
+				type: t.string().optional()
+			},
+			implements: {
+				description: "Interface id to implement: the interface's sections become `##` headings, each stubbed `**Unsupported.**`, with `merge: replace`. Not with --template.",
+				type: t.string().optional()
+			},
+			"dry-run": {
+				description: "Print the target path and the exact content, and write nothing.",
+				type: t.boolean().optional()
+			},
+			trace: {
+				...traceOption,
+				description: "After the write, add the trace, in which the new file applies."
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const root = resolve(args.root ?? process.cwd());
+				const display = (path) => collapseHome(home, path);
+				const created = createContribution(await layersFor({
+					root,
+					default: args.default
+				}, home), {
+					root,
+					home,
+					name: args.name,
+					scope: args.scope,
+					plugin: args.plugin,
+					default: args.default,
+					merge: args.merge,
+					template: args.template,
+					implements: args.implements,
+					dryRun: args["dry-run"]
+				}, { display });
+				const report = compact({
+					path: display(created.path),
+					hint: created.dryRun ? "Nothing was written. Run again without --dry-run to write it." : `Run \`show ${created.name}\` for the composed document.`,
+					content: created.dryRun ? created.content : void 0,
+					hints: created.hints,
+					trace: args.trace && created.after ? displayTrace(created.after.trace, home) : void 0
+				});
+				if (format !== "text") return result(report);
+				for (const hint of created.hints) process.stderr.write(`hint: ${hint}\n`);
+				if (args.trace && created.after) process.stderr.write(traceText(created.after, home));
+				return document(created.dryRun ? `${report.path}\n\n${created.content}` : `${report.path}\n\n${report.hint}\n`);
+			} catch (error) {
+				return fail(error, "Reference creation failed.");
+			}
+		}
+	});
+}
+function selectCommand(layersFor) {
+	return command({
+		name: "select",
+		description: "Choose what a name builds on: write an `extends` listing the options, bottom first, in the project or user file. Its body and other keys are kept.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}, {
+			name: "options",
+			description: "Bottom first: each a plugin holding the name (or `<plugin>/<name>`), or `default`.",
+			type: t.array(t.string()).optional()
+		}],
+		options: {
+			root: rootOption,
+			scope: scopeOption,
+			clear: {
+				description: "Remove the selection; a file left with nothing in it is deleted.",
+				type: t.boolean().optional()
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const root = resolve(args.root ?? process.cwd());
+				const display = (path) => collapseHome(home, path);
+				const selected = selectContribution(await layersFor({ root }, home), {
+					root,
+					home,
+					name: args.name,
+					options: args.options ?? [],
+					scope: args.scope,
+					clear: args.clear
+				}, { display });
+				const report = compact({
+					path: display(selected.path),
+					extends: selected.extends,
+					deleted: selected.deleted || void 0,
+					status: selected.after.status,
+					stack: selected.after.trace.stack,
+					answer: describeAnswer(selected.after, display)
+				});
+				if (format !== "text") return result(report);
+				writeWarnings(selected.after.warnings);
+				const what = args.clear ? selected.deleted ? "selection cleared; the file was left empty and deleted" : "selection cleared" : `extends: [${selected.extends.join(", ")}]`;
+				return document(`${report.path}\n\n${what}. ${report.answer}\n`);
+			} catch (error) {
+				return fail(error, "Reference selection failed.");
+			}
+		}
+	});
+}
+function deleteReport(deleted, home) {
+	const selection = deleted.selection ? `the selection extends: [${deleted.selection.join(", ")}] went with it; run \`reference select ${deleted.name} <option>...\` to restore it` : void 0;
+	return compact({
+		path: collapseHome(home, deleted.path),
+		dryRun: deleted.dryRun || void 0,
+		status: deleted.after.status,
+		stack: deleted.after.trace.stack,
+		answer: describeAnswer(deleted.after, (path) => collapseHome(home, path)),
+		selection,
+		options: deleted.after.options
+	});
+}
+function deleteCommand(layersFor) {
+	return command({
+		name: "delete",
+		description: "Delete a project or user contribution, or one in a plugin's or a skill's source folder, and report what answers the name afterwards. Never deletes an installed or managed one.",
+		arguments: [{
+			name: "name",
+			description: "Reference name, without the `.md` extension.",
+			type: t.string()
+		}],
+		options: {
+			root: rootOption,
+			scope: {
+				...scopeOption,
+				description: "Tier to delete from: project (default) or user."
+			},
+			plugin: pluginOption,
+			default: skillOption,
+			"dry-run": {
+				description: "Print the file that would be deleted and what would answer the name then, and delete nothing.",
+				type: t.boolean().optional()
+			}
+		},
+		async run(args) {
+			const format = this.format;
+			try {
+				const home = homedir();
+				const root = resolve(args.root ?? process.cwd());
+				const deleted = deleteContribution(await layersFor({
+					root,
+					default: args.default
+				}, home), {
+					root,
+					home,
+					name: args.name,
+					scope: args.scope,
+					plugin: args.plugin,
+					default: args.default,
+					dryRun: args["dry-run"]
+				}, { display: (path) => collapseHome(home, path) });
+				const report = deleteReport(deleted, home);
+				if (format !== "text") return result(report);
+				const selection = report.selection ? ` Also, ${report.selection}.` : "";
+				return document(`${report.path}\n\n${deleted.dryRun ? "would delete" : "deleted"}. ${report.answer}${selection}\n`);
+			} catch (error) {
+				return fail(error, "Reference deletion failed.");
+			}
+		}
+	});
+}
+/** A factory, so each host CLI names itself as the plugin whose own references come first. */
+function createReferenceCommands({ plugin } = {}) {
+	const layersFor = layerSource(plugin);
+	return {
+		show: showCommand(layersFor),
+		list: listCommand(layersFor),
+		search: searchCommand(layersFor),
+		where: whereCommand(layersFor),
+		create: createCommand(layersFor),
+		select: selectCommand(layersFor),
+		delete: deleteCommand(layersFor),
+		check: checkCommand(layersFor),
+		implementations: implementationsCommand(layersFor)
+	};
+}
+function createReferenceCommand(options = {}) {
+	const { show, list, search, where, create, select, delete: remove, check, implementations } = createReferenceCommands(options);
+	return command({
+		name: "reference",
+		description: "Read reference documents by name, composed from the managed, project, user, plugin, and default tiers, and write, select, or delete a contribution.",
+		commands: [
+			show,
+			list,
+			search,
+			where,
+			create,
+			select,
+			remove,
+			implementations,
+			check
+		]
+	});
+}
+//#endregion
+export { createReferenceCommand, createReferenceCommands };