buddy-agent-harness 0.14.0 → 0.16.0

package/dist/index.mjs

@@ -2088,6 +2088,11 @@ function stripMergeComments(body) {
 	const inFence = fenceTracker();
 	return body.split("\n").filter((line) => inFence(line) || !mergeCommentPattern.test(line)).join("\n");
 }
+/** Each heading with a single `#` outside a code fence, as written. */
+function titleHeadings(body) {
+	const inFence = fenceTracker();
+	return body.split("\n").filter((line) => !inFence(line) && headingPattern.exec(line)?.[1] === "#");
+}
 function sectionKey(title) {
 	return title.trim().replace(/\s+/g, " ").toLowerCase();
 }
@@ -2264,6 +2269,7 @@ function pluginLabel(layer) {
 function layerName(layer) {
 	return layer.tier === "plugin" ? `plugin ${pluginLabel(layer)}` : layer.tier;
 }
+/** The layers a name is resolved through, in the order `resolveReference` traces them. */
 function layersFor$2(ref, layers) {
 	const plugin = ref.plugin;
 	if (plugin === void 0) return [...layers];
@@ -2512,6 +2518,7 @@ function searchReferences(query, layers, options = {}) {
 }
 //#endregion
 //#region src/governance-overrides/governance-overrides.ts
+/** @deprecated Use `managedReferencesDir`. Removed in the next major version. */
 function managedGovernancesDir(platform, programData) {
 	if (platform === "darwin") return "/Library/Application Support/BuddyAgentHarness/governances";
 	if (platform === "win32") return join(programData || "C:\\ProgramData", "BuddyAgentHarness", "governances");
@@ -2520,6 +2527,8 @@ function managedGovernancesDir(platform, programData) {
 /**
 * Still read below the layer above, so a machine already using it keeps working; reported as
 * deprecated so an admin knows to move it.
+*
+* @deprecated Use `managedReferencesDir`. Removed in the next major version.
 */
 function deprecatedManagedGovernancesDir(platform, programData) {
 	if (platform === "darwin") return "/Library/Application Support/UniPlugin/governances";
@@ -2545,6 +2554,7 @@ function packageGovernancesDir(from = fileURLToPath(import.meta.url)) {
 		dir = parent;
 	}
 }
+/** @deprecated Use `referenceLayers`. Removed in the next major version. */
 function governanceLayers({ root, home, platform, programData }) {
 	return [
 		{
@@ -2572,6 +2582,8 @@ function governanceLayers({ root, home, platform, programData }) {
 /**
 * Filters by scope rather than slicing the list, so a layer added later can't quietly become an
 * override by position.
+*
+* @deprecated Use `referenceLayers`. Removed in the next major version.
 */
 function overrideLayers(layers) {
 	return layers.filter((layer) => layer.scope !== "package");
@@ -2580,6 +2592,8 @@ const namePattern = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/i;
 /**
 * Rejects rather than sanitizes — silently answering a different question is how untrusted input
 * reads a file outside the layer.
+*
+* @deprecated Use `parseReferenceName`. Removed in the next major version.
 */
 function parseGovernanceName(value) {
 	if (value.endsWith(".md")) throw new Error(`"${value}" names a file. Ask for the governance by name, without the .md extension.`);
@@ -2601,7 +2615,11 @@ function documentNames(dir) {
 		return [];
 	}
 }
-/** The first layer that holds the name wins; the rest are not read. */
+/**
+* The first layer that holds the name wins; the rest are not read.
+*
+* @deprecated Use `resolveReference`. Removed in the next major version.
+*/
 function resolveGovernance(name, layers) {
 	for (const { scope, dir } of layers) {
 		const path = join(dir, `${name}.md`);
@@ -2614,7 +2632,11 @@ function resolveGovernance(name, layers) {
 		};
 	}
 }
-/** Every name any layer holds, each reported at the layer that would win, sorted by name. */
+/**
+* Every name any layer holds, each reported at the layer that would win, sorted by name.
+*
+* @deprecated Use `listReferences`. Removed in the next major version.
+*/
 function listGovernances(layers) {
 	const found = /* @__PURE__ */ new Map();
 	for (const { scope, dir } of layers) for (const name of documentNames(dir)) if (!found.has(name)) found.set(name, {
@@ -3579,12 +3601,61 @@ const governanceShowCommand = command({
 		}
 	}
 });
+/** @deprecated Use `referenceCommand`. Removed in the next major version. */
 const governanceCommand = command({
 	name: "governance",
 	description: "Deprecated: use `reference`. Read the governance documents the project, user, and machine-wide override layers hold. Read-only.",
 	commands: [governanceListCommand, governanceShowCommand]
 });
 //#endregion
+//#region src/references/create-reference.ts
+/** No `#` title: `merge-sections` 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.
+`;
+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
+	};
+}
+/** Adds one line and changes nothing else, so the result still reads as the template it came from. */
+function withMergeSections(content) {
+	const match = frontmatterPattern.exec(content);
+	if (!match) return `---\nmerge: merge-sections\n---\n\n${content}`;
+	const open = match[0].indexOf("\n") + 1;
+	const newline = match[0][open - 2] === "\r" ? "\r\n" : "\n";
+	const end = open + match[1].length;
+	return `${content.slice(0, end)}${newline}merge: merge-sections${content.slice(end)}`;
+}
+function templateWarnings({ metadata, body }) {
+	const warnings = titleHeadings(body).map((heading) => `"${heading.trim()}" is a heading with one hash; merge-sections matches by heading path, so an override would replace or duplicate the whole document. Use top-level ## sections.`);
+	if (typeof metadata["description"] !== "string" || !metadata["description"].trim()) warnings.push("the reference has no `description` in its frontmatter; `list` and `search` show it blank.");
+	return warnings;
+}
+//#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. Defaults to the current directory.",
@@ -3603,6 +3674,12 @@ function fail(error, fallback) {
 	process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
 	return exitCodes.error;
 }
+function traceOf(resolved, home) {
+	return resolved.trace.map(({ description: _, ...step }) => ({
+		...step,
+		path: collapseHome(home, step.path)
+	}));
+}
 function showEntry(resolved, home, suggestions, trace) {
 	const entry = {
 		name: resolved.name,
@@ -3624,10 +3701,7 @@ function showEntry(resolved, home, suggestions, trace) {
 	if (resolved.status === "missing") entry.suggestions = suggestions;
 	if (resolved.status === "ambiguous") entry.plugins = resolved.plugins;
 	entry.warnings = resolved.warnings;
-	if (trace) entry.trace = resolved.trace.map(({ description: _, ...step }) => ({
-		...step,
-		path: collapseHome(home, step.path)
-	}));
+	if (trace) entry.trace = traceOf(resolved, home);
 	return entry;
 }
 function missReason(entry) {
@@ -3761,13 +3835,180 @@ const referenceSearchCommand = command({
 		}
 	}
 });
+/** Managed is left out: writing there needs an admin, and most of it cannot be read locally. */
+const slotScopes = {
+	project: "everyone working in this repository",
+	user: "only you, in every repository",
+	plugin: "read-only; override it with the project or user file"
+};
+const callerScope = "read-only; the calling skill's own copy, read only when no layer holds the name";
+const mergeNote = "The default, first-wins, makes the override replace the whole document. Set `merge: merge-sections` in its frontmatter to keep the sections it does not redefine.";
+function slotStatus(outcome) {
+	if (outcome === "missing") return "empty";
+	return outcome.startsWith("shadowed") ? "shadowed" : outcome;
+}
+/** Where Load reads the caller's copy when no layer holds the name, in the order it tries them. */
+function callerCopy(caller, name) {
+	return [join(caller, "references", `${name}.md`), join(caller, "references", "governances", `${name}.md`)].find((path) => existsSync(path));
+}
+function callerStatus(resolved) {
+	if (resolved.status === "missing") return "used";
+	return resolved.status === "ambiguous" ? "not read — the name is ambiguous" : "shadowed";
+}
+const referenceWhereCommand = command({
+	name: "where",
+	description: "List the project and user files an override of a reference can be written to, highest precedence first, with the copy each overrides and who it applies to.",
+	arguments: [{
+		name: "name",
+		description: "Reference name, without the `.md` extension; `<plugin>/<name>` picks one plugin.",
+		type: z.string()
+	}],
+	options: {
+		root: rootOption,
+		caller: {
+			description: "Folder of the skill that loads the reference, so its own copy is reported as the reference skill's Load mode reads it.",
+			type: z.optional(z.string())
+		},
+		format: listFormatOption
+	},
+	async run(args) {
+		try {
+			const format = parseFormat(args.format);
+			const name = parseReferenceName(args.name);
+			const home = homedir();
+			const layers = await layersFor(args, home);
+			const root = resolve(args.root ?? process.cwd());
+			const display = (path) => collapseHome(home, path);
+			const resolved = resolveReference(name, layers, { display });
+			const traced = layersFor$2(name, layers);
+			const slots = [];
+			for (const [index, step] of resolved.trace.entries()) {
+				const layer = traced[index];
+				const scope = slotScopes[step.tier];
+				if (!scope || (layer.status || step.tier === "plugin") && !step.found) continue;
+				const path = step.found ? step.path : join(layer.dir, `${name.name}.md`);
+				slots.push({
+					layer: step.tier === "plugin" ? `plugin ${step.plugin}` : step.tier,
+					path: step.tier === "project" ? relative(root, path) : display(path),
+					status: slotStatus(step.outcome),
+					scope
+				});
+			}
+			const copy = args.caller === void 0 ? void 0 : callerCopy(resolve(args.caller), name.name);
+			if (copy) slots.push({
+				layer: "caller",
+				path: display(copy),
+				status: callerStatus(resolved),
+				scope: callerScope
+			});
+			const report = {
+				name: name.name,
+				root: display(root),
+				slots,
+				merge: mergeNote
+			};
+			if (resolved.status === "ambiguous") report.plugins = resolved.plugins;
+			if (resolved.warnings.length) report.warnings = resolved.warnings;
+			writeResult(report, format);
+			if (resolved.status !== "ambiguous") return exitCodes.success;
+			process.stderr.write(`error: ${missReason({
+				name: name.raw,
+				status: "ambiguous",
+				plugins: resolved.plugins,
+				warnings: []
+			})}\n`);
+			return exitCodes.error;
+		} catch (error) {
+			return fail(error, "Reference placement lookup failed.");
+		}
+	}
+});
+function parseScope(value) {
+	if (value !== "project" && value !== "user") throw new Error("--scope must be project or user.");
+	return value;
+}
+const referenceCreateCommand = command({
+	name: "create",
+	description: "Start a new reference in the project or user tier from a template, marked merge-sections when it overrides a copy below. Never overwrites.",
+	arguments: [{
+		name: "name",
+		description: "Reference name, without the `.md` extension.",
+		type: z.string()
+	}],
+	options: {
+		root: rootOption,
+		template: {
+			description: "File whose text is written as it is, frontmatter included. Defaults to a built-in template of top-level `##` sections with no `#` title.",
+			type: z.optional(z.string())
+		},
+		scope: {
+			description: "Tier to write: project (default), `.agents/references/` at the root, or user, `~/.agents/references/`.",
+			type: z.optional(z.string()),
+			default: "project"
+		},
+		"dry-run": {
+			description: "Print the target path and the exact content, and write nothing.",
+			type: z.optional(z.boolean())
+		},
+		format: {
+			description: "Output format: text (default) writes the path, then the content or the trace; toon and json return an object.",
+			type: z.optional(z.string()),
+			default: "text"
+		}
+	},
+	async run(args) {
+		try {
+			const format = parseFormat(args.format);
+			const name = parseReferenceName(args.name);
+			if (name.plugin !== void 0) throw new Error(`an override is written under the bare name, which every tier resolves; ask for "${name.name}".`);
+			const scope = parseScope(args.scope);
+			const template = readTemplate(args.template === void 0 ? void 0 : resolve(args.template));
+			const home = homedir();
+			const dir = scope === "project" ? projectReferencesDir(resolve(args.root ?? process.cwd())) : join(home, ".agents", "references");
+			const target = join(dir, `${name.name}.md`);
+			const display = (path) => collapseHome(home, path);
+			const layers = await layersFor(args, home);
+			const { trace } = resolveReference(name, layers, { display });
+			const at = layers.findIndex((layer) => layer.dir === dir);
+			if (trace[at]?.found) throw new Error(`${display(trace[at].path)} already holds "${name.name}"; change it with the reference skill's Update mode.`);
+			const shadow = trace.slice(0, at).find((step) => step.found && step.merge === "first-wins");
+			if (shadow) throw new Error(`the ${shadow.tier} copy ${display(shadow.path)} is first-wins, so nothing would read a new ${scope} file; change that copy instead.`);
+			const content = trace.slice(at + 1).some((step) => step.found) && template.metadata["merge"] === void 0 ? withMergeSections(template.content) : template.content;
+			const warnings = templateWarnings(template);
+			const report = {
+				name: name.name,
+				scope,
+				path: display(target),
+				dryRun: Boolean(args["dry-run"]),
+				content,
+				warnings
+			};
+			if (!report.dryRun) {
+				mkdirSync(dir, { recursive: true });
+				writeFileSync(target, content, { flag: "wx" });
+				report.trace = traceOf(resolveReference(name, layers, { display }), home);
+			}
+			if (format !== "text") writeResult(report, format);
+			else {
+				for (const warning of warnings) process.stderr.write(`warning: ${warning}\n`);
+				if (report.trace) process.stdout.write(`${report.path}\n\n${renderText({ trace: report.trace })}\n`);
+				else writeDocument(`${report.path}\n\n${content}`);
+			}
+			return exitCodes.success;
+		} catch (error) {
+			return fail(error, "Reference creation failed.");
+		}
+	}
+});
 const referenceCommand = command({
 	name: "reference",
-	description: "Read on-demand reference documents by name, layered across the managed, project, user, and plugin tiers. Read-only.",
+	description: "Read on-demand reference documents by name, layered across the managed, project, user, and plugin tiers, and start a new one in the project or user tier.",
 	commands: [
 		referenceShowCommand,
 		referenceListCommand,
-		referenceSearchCommand
+		referenceSearchCommand,
+		referenceWhereCommand,
+		referenceCreateCommand
 	]
 });
 //#endregion
@@ -4638,12 +4879,26 @@ const mcpCommand = command({
 //#endregion
 //#region src/cli.ts
 const version = typeof __PACKAGE_VERSION__ !== "undefined" ? __PACKAGE_VERSION__ : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** Exported for `scripts/generate-llms-txt.ts`, which lists the CLI from it; `app()` must stay built from it. */
+const rootCommand = {
+	name: "buddy-agent-harness",
+	description: "Initialize agent harness skill compatibility in consumer repositories.",
+	commands: [
+		initCommand,
+		doctorCommand,
+		mcpCommand,
+		depPluginsCommand,
+		referenceCommand,
+		governanceCommand
+	]
+};
 function app() {
-	return cli({
-		name: "buddy-agent-harness",
+	const [first, ...rest] = rootCommand.commands;
+	return rest.reduce((builder, command) => builder.command(command), cli({
+		name: rootCommand.name,
 		version,
-		description: "Initialize agent harness skill compatibility in consumer repositories."
-	}).command(initCommand).command(doctorCommand).command(mcpCommand).command(depPluginsCommand).command(referenceCommand).command(governanceCommand);
+		description: rootCommand.description
+	}).command(first));
 }
 /**
 * The application boundary: argv in, exit code out — returned rather than written, so a caller that