@nikovirtala/adr 0.2.0 → 0.4.0

package/dist/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
-import { n as DECISION_STATUSES, t as adrKind } from "./kind-BcHjCHvi.js";
-import { C as initDecisionLog, S as unavailableReason, a as noteDecision, c as scopeDecision, d as withdrawDecision, f as adrChecks, g as showDecision, h as listDecisions, i as linkDecision, m as decisionsFor, n as deprecateDecision, o as proposeDecision, r as followScopeRenames, s as rejectDecision, t as acceptDecision, u as supersedeDecision, v as openDecisionLog, x as resolveDecision, y as readDecisions } from "./write-9IaqHRrY.js";
+import { A as changedSince, I as resolveDecision, M as numberingNote, N as openDecisionLog, O as runDecisionIndex, P as readDecisions, _ as withdrawDecision, c as followScopeRenames, d as proposeDecision, f as rejectDecision, h as supersedeDecision, i as showDecision, l as linkDecision, n as decisionsFor, o as acceptDecision, p as scopeDecision, r as listDecisions, s as deprecateDecision, t as searchDecisions, u as noteDecision } from "./search-CwIPlNGd.js";
+import { n as DECISION_STATUSES, t as adrKind } from "./kind-DjvA3dyA.js";
+import { a as installDecisionHooks, c as uninstallDecisionHooks, l as adrChecks, o as printDecisionHooks, r as addHookTrailers, s as runPreCommitHook, t as initDecisionLog } from "./init-YgW7g9Fx.js";
 import { createRequire } from "node:module";
-import { UsageError, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
+import { UsageError, exitCode, findingsReport, formatText, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
 import { spawn } from "node:child_process";
 // src/cli/open.ts
@@ -27,6 +30,8 @@ async function displayAfterWrite(log) {
 	const read = await readDecisions(log);
 	return { display: (id) => read.projection.views.get(id)?.display ?? id };
 }
+/** `notes` with `note` appended when there is one. */
+const notesWith = (notes, note) => note === null ? notes : [...notes, note];
 // src/cli/text.ts
 /** A table: each column padded to its widest value, trailing spaces removed. */
 function columns(rows) {
@@ -39,6 +44,21 @@ function columns(rows) {
 /** `adr list`: one row per decision, `→ <effective>` when it differs from the decision. */
 function listText(doc, display) {
 	if (doc.decisions.length === 0) return "No decisions.";
+	return listRows(doc, display).join("\n");
+}
+/**
+* `adr list --since <rev>` (design 2b D7): a heading, then each row followed by the event types
+* added since `rev`; nothing at all when no decision changed, so the post-merge hook stays quiet.
+*/
+function sinceText(doc, since, display) {
+	if (doc.decisions.length === 0) return "";
+	const rows = listRows(doc, display);
+	return [`Changed since ${since.rev} (${since.commit.slice(0, 7)}):`, ...doc.decisions.flatMap((v, i) => {
+		const types = [...new Set(since.events.filter((e) => e.subject === v.id).map((e) => e.type))];
+		return [rows[i] ?? "", `  [new: ${types.join(", ")}]`];
+	})].join("\n");
+}
+function listRows(doc, display) {
 	return columns(doc.decisions.map((v) => {
 		const arrow = v.effective === null ? "→ (cycle)" : v.effective === v.id ? "" : `→ ${display(v.effective)}`;
 		return [
@@ -48,7 +68,7 @@ function listText(doc, display) {
 			v.title,
 			arrow
 		];
-	}));
+	})).split("\n");
 }
 /** `ADR-0003 (m2x7p4d2)`, or the id alone when it has no number. */
 function named(id, display) {
@@ -132,7 +152,7 @@ function unfilledWarning(doc) {
 function findingLines(findings) {
 	return findings.map((f) => `  ${f.file === null ? "" : `${f.file}: `}${f.message} [${f.rule}]`);
 }
-const short = (sha) => sha.slice(0, 7);
+const short$1 = (sha) => sha.slice(0, 7);
 /**
 * `adr scope --follow-renames`: one `<named>: <old globs> → <new globs>` line per changed
 * decision (`affected`), whether or not a decision was given.
@@ -158,7 +178,8 @@ const VERBS = {
 	deprecate: "deprecated",
 	note: "noted",
 	link: "linked",
-	scope: "scoped"
+	scope: "scoped",
+	update: "updated"
 };
 /**
 * The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
@@ -178,7 +199,7 @@ function writeText(doc, display, o) {
 	if (o.followRenames !== void 0) return followRenamesText(doc, display, o.followRenames);
 	const v = doc.decision;
 	if (v === null) return "";
-	const committed = doc.commit === null ? null : `Committed ${short(doc.commit)}`;
+	const committed = doc.commit === null ? null : `Committed ${short$1(doc.commit)}`;
 	const recorded = committed === null ? "Staged; commit to record it." : `${committed}.`;
 	switch (doc.command) {
 		case "new": return [
@@ -225,6 +246,9 @@ function writeText(doc, display, o) {
 				recorded
 			].join("\n");
 		}
+		case "update":
+			if (doc.written.length === 0) return `Draft of ${named(v.id, display)} unchanged`;
+			return [`Updated the draft of ${named(v.id, display)}: ${v.title}`, recorded].join("\n");
 	}
 }
 /**
@@ -280,15 +304,39 @@ function forText(doc, display, keyword) {
 	}
 	return lines.join("\n");
 }
+/**
+* `adr search`: one padded row per result with its excerpt (or which field matched) under it, and
+* an inactive result's warning; then the count.
+*/
+function searchText(doc) {
+	const quoted = JSON.stringify(doc.query);
+	if (doc.results.length === 0) return `No ${doc.include_inactive ? "" : "active "}decisions match ${quoted}.`;
+	const rows = columns(doc.results.map((r) => [
+		r.decision.number === null ? r.decision.id : `${r.decision.display} (${r.decision.id})`,
+		r.decision.status,
+		r.decision.title
+	])).split("\n");
+	const lines = [];
+	doc.results.forEach((r, i) => {
+		lines.push(rows[i] ?? "");
+		if (r.header.warning !== null) lines.push(`  ${r.header.warning}`);
+		const where = r.matched.filter((f) => f === "id" || f === "title").join(" and ");
+		lines.push(r.excerpt === null ? `  (${where} match)` : `  ${r.excerpt}`);
+	});
+	const n = doc.total;
+	lines.push(`${n === 1 ? "1 decision matches" : `${n} decisions match`} ${quoted}.`);
+	return lines.join("\n");
+}
 /** `adr init`: what was written and kept, then the next step; or that nothing was needed. */
 function initText(doc) {
 	if (doc.written.length === 0) return `Already initialized: ${doc.root} (kept ${doc.kept.join(", ")})`;
+	const skill = doc.skill !== null && doc.written.includes(doc.skill);
 	return [
-		`Initialized ${doc.root}`,
+		doc.written.every((p) => p === doc.skill || p === "AGENTS.md") ? "Set up the adr agent skill" : `Initialized ${doc.root}`,
 		...doc.written.map((p) => `  ${p}`),
 		...doc.kept.map((p) => `Kept ${p}`),
-		...doc.commit === null ? [] : [`Committed ${short(doc.commit)}.`],
-		"Next: adr new \"<title>\""
+		...doc.commit === null ? [] : [`Committed ${short$1(doc.commit)}.`],
+		skill ? "Next: adr mcp, from your MCP client's config" : "Next: adr new \"<title>\""
 	].join("\n");
 }
 // src/cli/accept.ts
@@ -366,12 +414,12 @@ const acceptCommand = {
 	}
 };
 // src/cli/deprecate.ts
-const USAGE$4 = "deprecate <decision> --reason <text> [--commit | --no-commit] [-m <message>]";
+const USAGE$5 = "deprecate <decision> --reason <text> [--commit | --no-commit] [-m <message>]";
 /** `adr deprecate` (design §6.5): an accepted decision no longer in force. */
 const deprecateCommand = {
 	name: "deprecate",
 	summary: "deprecate an accepted decision",
-	usage: USAGE$4,
+	usage: USAGE$5,
 	options: {
 		reason: { type: "string" },
 		...COMMIT_OPTIONS
@@ -384,7 +432,7 @@ const deprecateCommand = {
 	ref: "reject",
 	async run({ io, flags, values, positionals }) {
 		const input = positionals[0] ?? "";
-		if (typeof values.reason !== "string" || values.reason.trim() === "") throw new UsageError(`missing --reason <text>; usage: adr ${USAGE$4}`);
+		if (typeof values.reason !== "string" || values.reason.trim() === "") throw new UsageError(`missing --reason <text>; usage: adr ${USAGE$5}`);
 		const reason = typeof values.reason === "string" ? values.reason.trim() : null;
 		const log = await openForCli(io, flags);
 		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
@@ -435,21 +483,121 @@ const forCommand = {
 			exit: 0,
 			json: doc,
 			text: forText(doc, display, read.adr.anchorKeyword),
-			notes: doc.notes
+			notes: notesWith(doc.notes, numberingNote(read, { unavailable: false }))
 		};
 	}
 };
-// src/cli/init.ts
-/** `adr init [--template <name>]… [--commit | --no-commit] [-m <message>]` (design §6.2). */
-const initCommand = {
-	name: "init",
-	summary: "set up a decision log: a config file and starter templates",
-	usage: "init [--template <name>]… [--commit | --no-commit] [-m <message>]",
+// src/cli/hooks.ts
+const USAGE$4 = "hooks install | uninstall | print --manager lefthook|husky|pre-commit | run pre-commit | trailers <message-file>";
+const MANAGERS = [
+	"lefthook",
+	"husky",
+	"pre-commit"
+];
+const outcome = (doc, text, notes) => ({
+	exit: 0,
+	json: doc,
+	text,
+	notes
+});
+/**
+* `adr hooks install | uninstall | print --manager … | run pre-commit | trailers <message-file>`
+* (design 2b D4, D8, §4.3): adr's git hooks through ledger's shims, shared with other ark tools.
+*/
+const hooksCommand = {
+	name: "hooks",
+	summary: "install, remove or print adr's git hooks, and run their steps",
+	usage: USAGE$4,
+	options: { manager: { type: "string" } },
+	positionals: {
+		min: 1,
+		max: 2,
+		names: ["action", "argument"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [action = "", argument] = positionals;
+		const manager = values.manager;
+		if (manager !== void 0 && action !== "print") throw new UsageError(`--manager goes with hooks print only; usage: adr ${USAGE$4}`);
+		const noArgument = () => {
+			if (argument !== void 0) throw new UsageError(`unexpected argument ${JSON.stringify(argument)}; usage: adr ${USAGE$4}`);
+		};
+		switch (action) {
+			case "install": {
+				noArgument();
+				const log = await openForCli(io, flags);
+				const doc = await installDecisionHooks(log);
+				const lines = [...[...doc.written, ...doc.unchanged].map((p) => `${doc.written.includes(p) ? "wrote" : "unchanged"} ${p}`).sort((a, b) => order(a) - order(b)), `adr hooks: ${doc.registrations.map((r) => r.hook).join(", ")}`];
+				return outcome(doc, lines.join("\n"), log.notes);
+			}
+			case "uninstall": {
+				noArgument();
+				const log = await openForCli(io, flags);
+				const doc = await uninstallDecisionHooks(log);
+				const text = doc.written.length === 0 ? "adr hooks were not installed" : doc.written.map((p) => `removed adr from ${p}`).join("\n");
+				return outcome(doc, text, log.notes);
+			}
+			case "print": {
+				noArgument();
+				if (manager === void 0) throw new UsageError("hooks print needs --manager lefthook, husky or pre-commit");
+				if (!MANAGERS.includes(manager)) throw new UsageError(`unknown hook manager ${JSON.stringify(manager)}; use lefthook, husky or pre-commit`);
+				const log = await openForCli(io, flags);
+				const doc = printDecisionHooks(log, manager);
+				return outcome(doc, doc.snippet ?? "", log.notes);
+			}
+			case "run": {
+				if (argument !== "pre-commit") throw new UsageError("adr hooks run supports pre-commit");
+				const worktree = await openForCli(io, flags);
+				const index = await openForCli(io, flags, { reader: "index" });
+				const r = await runPreCommitHook({
+					worktree,
+					index,
+					env: io.env
+				});
+				return {
+					exit: r.exit,
+					json: findingsReport(r.findings, { failOn: r.failOn }),
+					text: r.findings.length === 0 ? "" : formatText(r.findings),
+					notes: r.notes
+				};
+			}
+			case "trailers": {
+				if (argument === void 0) throw new UsageError(`missing argument <message-file>; usage: adr ${USAGE$4}`);
+				const log = await openForCli(io, flags);
+				const doc = await addHookTrailers(log, resolve(io.cwd, argument));
+				return outcome(doc, "", log.notes);
+			}
+			default: throw new UsageError(`unknown hooks action ${JSON.stringify(action)}; use install, uninstall, print, run or trailers`);
+		}
+	}
+};
+/** A shim line's rank in hook order, for the install text. */
+function order(line) {
+	return [
+		"pre-commit",
+		"commit-msg",
+		"pre-push",
+		"post-merge"
+	].findIndex((h) => line.endsWith(`/${h}`));
+}
+// src/cli/index-command.ts
+const short = (sha) => sha.slice(0, 7);
+/** The text of `adr index` (design 2b §4.5). */
+function indexText({ doc, refreshed }) {
+	const { path } = doc;
+	if (doc.check) return doc.findings.length === 0 ? `${path} is up to date` : formatText(doc.findings);
+	if (doc.commit !== null) return [`Committed ${path} as ${short(doc.commit)}`, ...refreshed ? [`Wrote ${path} with uncommitted log changes`] : []].join("\n");
+	if (refreshed) return `${path} is up to date in HEAD; wrote the work tree's copy, which includes uncommitted log changes`;
+	if (doc.fresh) return `${path} is up to date`;
+	return doc.written.length > 0 ? `Wrote ${path}` : `Staged ${path}`;
+}
+/** `adr index [--check] [--commit | --no-commit] [-m <message>]` (design 2b §4.5). */
+const indexCommand = {
+	name: "index",
+	summary: "regenerate the decision index (index.md), or check that it is current",
+	usage: "index [--check] [--commit | --no-commit] [-m <message>]",
 	options: {
-		template: {
-			type: "string",
-			multiple: true
-		},
+		check: { type: "boolean" },
 		...COMMIT_OPTIONS
 	},
 	positionals: {
@@ -457,22 +605,87 @@ const initCommand = {
 		max: 0,
 		names: []
 	},
-	ref: "reject",
+	ref: "read",
 	async run({ io, flags, values }) {
-		const templates = Array.isArray(values.template) ? values.template : void 0;
+		const check = values.check === true;
+		if (check && (values.commit === true || typeof values.message === "string")) throw new UsageError("--check writes nothing; drop --commit and --message");
+		if (!check && flags.ref !== null) throw new UsageError("adr index writes the work tree; use --ref only with --check");
 		const log = await openForCli(io, flags);
-		const doc = await initDecisionLog(log, {
-			...templates === void 0 ? {} : { templates },
-			...commitChoice(values, { autoCommit: log.adr.autoCommit })
+		const run = await runDecisionIndex(log, {
+			check,
+			...check ? {} : commitChoice(values, { autoCommit: log.adr.autoCommit })
 		});
 		return {
-			exit: 0,
-			json: doc,
-			text: initText(doc),
-			notes: doc.notes
+			exit: check ? exitCode(run.doc.findings, { failOn: log.adr.failOn }) : 0,
+			json: run.doc,
+			text: indexText(run),
+			notes: run.doc.notes
 		};
 	}
 };
+// src/cli/init.ts
+const DEFAULT_SKILL_DIR = ".claude/skills/adr";
+const MAX_DIR = 1024;
+/** `--skill-dir` as a repo-relative directory inside the work tree and outside `.git`. */
+async function skillDir(root, cwd, given) {
+	const dir = given.trim();
+	const bad = () => new UsageError("--skill-dir must be a directory inside the repository");
+	if (dir === "" || dir.length > MAX_DIR || dir.includes("\0")) throw bad();
+	const base = await realpath(cwd).catch(() => cwd);
+	const rel = relative(root, resolve(base, dir));
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw bad();
+	const segments = rel.split(sep).filter((s) => s !== "");
+	if (segments[0] === ".git") throw bad();
+	return segments.join("/");
+}
+/**
+* `adr init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit]
+* [-m <message>]` (design §6.2, phase 3 §9).
+*/
+function initCommand(version) {
+	return {
+		name: "init",
+		summary: "set up a decision log: a config file and starter templates",
+		usage: "init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit] [-m <message>]",
+		options: {
+			template: {
+				type: "string",
+				multiple: true
+			},
+			skill: { type: "boolean" },
+			"skill-dir": { type: "string" },
+			...COMMIT_OPTIONS
+		},
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags, values }) {
+			const templates = Array.isArray(values.template) ? values.template : void 0;
+			const given = typeof values["skill-dir"] === "string" ? values["skill-dir"] : null;
+			if (given !== null && values.skill !== true) throw new UsageError("--skill-dir needs --skill");
+			const log = await openForCli(io, flags);
+			const root = log.git.root ?? io.cwd;
+			const dir = values.skill !== true ? null : given === null ? DEFAULT_SKILL_DIR : await skillDir(root, io.cwd, given);
+			const doc = await initDecisionLog(log, {
+				...templates === void 0 ? {} : { templates },
+				...dir === null ? {} : { skill: {
+					dir,
+					version
+				} },
+				...commitChoice(values, { autoCommit: log.adr.autoCommit })
+			});
+			return {
+				exit: 0,
+				json: doc,
+				text: initText(doc),
+				notes: doc.notes
+			};
+		}
+	};
+}
 // src/cli/link.ts
 /** `adr link <decision> <target> [--rel <rel>]` (design §6.7): a typed link, in any state. */
 const linkCommand = {
@@ -524,15 +737,25 @@ function statuses(values) {
 		return s;
 	});
 }
-/** `adr list [--status <status>]…` (design §5.6). */
+/** `--since`'s revision: non-empty and not an option. */
+function sinceRev(values) {
+	const v = values.since;
+	if (typeof v !== "string") return null;
+	if (v.trim() === "" || v.startsWith("-")) throw new UsageError("--since must be a revision");
+	return v;
+}
+/** `adr list [--status <status>]… [--since <rev>]` (design §5.6, 2b D7). */
 const listCommand = {
 	name: "list",
 	summary: "list decisions with their computed status",
-	usage: "list [--status <status>]…",
-	options: { status: {
-		type: "string",
-		multiple: true
-	} },
+	usage: "list [--status <status>]… [--since <rev>]",
+	options: {
+		status: {
+			type: "string",
+			multiple: true
+		},
+		since: { type: "string" }
+	},
 	positionals: {
 		min: 0,
 		max: 0,
@@ -541,10 +764,17 @@ const listCommand = {
 	ref: "read",
 	async run({ io, flags, values }) {
 		const status = statuses(values);
-		const read = await readDecisions(await openForCli(io, flags));
-		const doc = listDecisions(read, { status });
+		const rev = sinceRev(values);
+		const log = await openForCli(io, flags);
+		const since = rev === null ? null : await changedSince(log, rev);
+		const read = await readDecisions(log);
+		const doc = listDecisions(read, {
+			status,
+			since
+		});
 		const notes = [...doc.notes];
-		if (!read.numbering.available && doc.decisions.length > 0) notes.push(`numbers are unavailable (${unavailableReason(read.numbering)}); decisions display by id`);
+		const numbering = numberingNote(read, { unavailable: true });
+		if (numbering !== null && doc.decisions.length > 0) notes.push(numbering);
 		if (doc.findings.length > 0) notes.push(`the decision log has ${plural(doc.findings.length, "problem", "problems")}; run adr verify`);
 		if (doc.unreadable.length > 0) notes.push(`${plural(doc.unreadable.length, "decision uses", "decisions use")} a newer format; upgrade adr`);
 		if (doc.unfoldable.length > 0) notes.push(`${plural(doc.unfoldable.length, "decision", "decisions")} can't be read; run adr verify`);
@@ -552,11 +782,47 @@ const listCommand = {
 		return {
 			exit: 0,
 			json: doc,
-			text: listText(doc, display),
+			text: doc.since === null ? listText(doc, display) : sinceText(doc, doc.since, display),
 			notes
 		};
 	}
 };
+// src/cli/mcp.ts
+/**
+* `adr mcp` (design §7.1): the MCP server over stdio. Loaded with a dynamic import, so no other
+* command loads the MCP SDK.
+*/
+function mcpCommand(version) {
+	return {
+		name: "mcp",
+		summary: "start the MCP server over stdio",
+		usage: "mcp",
+		options: {},
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags }) {
+			if (flags.json) throw new UsageError("adr mcp speaks JSON-RPC on stdout; it takes no --json");
+			if (io.interactive) io.stderr.write("adr: adr mcp speaks MCP on stdin and stdout; start it from an MCP client\n");
+			const { serveAdrMcp } = await import("./server-CXCO5zfp.js");
+			await serveAdrMcp({
+				cwd: io.cwd,
+				root: flags.root,
+				env: io.env,
+				version,
+				stderr: io.stderr
+			});
+			return {
+				exit: 0,
+				json: null,
+				text: ""
+			};
+		}
+	};
+}
 // src/cli/editor.ts
 /**
 * The user's editor as an `edit` callback (design §5.7), or `null` when neither `VISUAL` nor
@@ -895,6 +1161,38 @@ const scopeCommand = {
 		};
 	}
 };
+// src/cli/search.ts
+/** `adr search <query>… [--all]` (design §8.2): words are joined, and every one must match. */
+const searchCommand = {
+	name: "search",
+	summary: "search decisions' ids, titles, bodies and notes",
+	usage: "search <query>… [--all]",
+	options: { all: { type: "boolean" } },
+	positionals: {
+		min: 1,
+		max: 20,
+		names: ["query"]
+	},
+	ref: "read",
+	async run({ io, flags, values, positionals }) {
+		const read = await readDecisions(await openForCli(io, flags));
+		const doc = searchDecisions(read, {
+			query: positionals.join(" "),
+			includeInactive: values.all === true
+		});
+		const notes = [...notesWith(doc.notes, numberingNote(read, { unavailable: false }))];
+		if (doc.inactive_omitted > 0) {
+			const k = doc.inactive_omitted;
+			notes.push(`${k === 1 ? "1 inactive decision also matches" : `${k} inactive decisions also match`}; add --all to see them`);
+		}
+		return {
+			exit: 0,
+			json: doc,
+			text: searchText(doc),
+			notes
+		};
+	}
+};
 // src/cli/show.ts
 /** `adr show <decision> [--history]` (design §5.6). */
 const showCommand = {
@@ -917,7 +1215,7 @@ const showCommand = {
 			exit: 0,
 			json: doc,
 			text: showText(doc, display),
-			notes: doc.notes
+			notes: notesWith(doc.notes, numberingNote(read, { unavailable: false }))
 		};
 	}
 };
@@ -1032,7 +1330,7 @@ function adrCli(version) {
 		version,
 		summary: "Architecture decision records kept as event logs in git.",
 		commands: [
-			initCommand,
+			initCommand(version),
 			newCommand,
 			acceptCommand,
 			rejectCommand,
@@ -1042,10 +1340,14 @@ function adrCli(version) {
 			noteCommand,
 			linkCommand,
 			scopeCommand,
+			indexCommand,
+			hooksCommand,
 			forCommand,
 			listCommand,
 			showCommand,
-			verify
+			searchCommand,
+			verify,
+			mcpCommand(version)
 		]
 	};
 }