buddy-agent-harness 0.15.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();
 }
@@ -2513,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");
@@ -2521,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";
@@ -2546,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 [
 		{
@@ -2573,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");
@@ -2581,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.`);
@@ -2602,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`);
@@ -2615,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, {
@@ -3580,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.",
@@ -3604,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,
@@ -3625,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) {
@@ -3850,14 +3923,92 @@ const referenceWhereCommand = command({
 		}
 	}
 });
+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,
-		referenceWhereCommand
+		referenceWhereCommand,
+		referenceCreateCommand
 	]
 });
 //#endregion