@nikovirtala/adr 0.0.0 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,1057 @@
+#!/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 { createRequire } from "node:module";
+import { UsageError, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
+import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
+import { spawn } from "node:child_process";
+// src/cli/open.ts
+/**
+* The decision log a command works on: `--root` and `--ref` from the globals, git run with the
+* CLI's environment.
+*/
+function openForCli(io, flags, o = {}) {
+	return openDecisionLog({
+		cwd: io.cwd,
+		root: flags.root,
+		ref: flags.ref,
+		...o.reader === void 0 ? {} : { reader: o.reader },
+		gitOptions: { env: io.env }
+	});
+}
+/**
+* How other decisions display in a write's text, read again from the work tree, like the write
+* result's own views: a commit on the main ref has numbered the decisions it accepted.
+*/
+async function displayAfterWrite(log) {
+	const read = await readDecisions(log);
+	return { display: (id) => read.projection.views.get(id)?.display ?? id };
+}
+// src/cli/text.ts
+/** A table: each column padded to its widest value, trailing spaces removed. */
+function columns(rows) {
+	const widths = [];
+	for (const row of rows) row.forEach((cell, i) => {
+		widths[i] = Math.max(widths[i] ?? 0, cell.length);
+	});
+	return rows.map((row) => row.map((cell, i) => i === row.length - 1 ? cell : cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd()).join("\n");
+}
+/** `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 columns(doc.decisions.map((v) => {
+		const arrow = v.effective === null ? "→ (cycle)" : v.effective === v.id ? "" : `→ ${display(v.effective)}`;
+		return [
+			v.number === null ? "-" : v.display,
+			v.id,
+			v.status,
+			v.title,
+			arrow
+		];
+	}));
+}
+/** `ADR-0003 (m2x7p4d2)`, or the id alone when it has no number. */
+function named(id, display) {
+	const shown = display(id);
+	return shown === id ? id : `${shown} (${id})`;
+}
+const day = (at) => (at ?? "").slice(0, 10);
+const list = (ids, display) => ids.length === 0 ? "none" : ids.map((id) => named(id, display)).join(", ");
+function bodyLine(v) {
+	if (v.body_path === null) return "missing";
+	if (v.body_intact === null) return v.body_path;
+	return `${v.body_path} (${v.body_intact ? "intact" : "changed after acceptance"})`;
+}
+function actorText(e) {
+	const a = e.actor;
+	return a.kind === "agent" ? `${a.name} (agent ${a.agent} for ${a.on_behalf_of})` : a.name;
+}
+/** The second line of an event in `show --history`: its reason, else a summary of its data. */
+function eventDetail(e) {
+	if (typeof e.reason === "string") return `reason: ${e.reason}`;
+	const entries = Object.entries(e.data);
+	if (entries.length === 0) return null;
+	return entries.map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`).join(", ");
+}
+function historyLines(events) {
+	const width = Math.max(...events.map((e) => e.type.length));
+	return events.flatMap((e) => {
+		const detail = eventDetail(e);
+		return [`  ${e.at}  ${e.type.padEnd(width)}  ${actorText(e)}`, ...detail === null ? [] : [`    ${detail}`]];
+	});
+}
+const SECTION_FINDING = /^(?:required )?section (.+?) (is missing|is empty|still contains its guidance text)$/;
+const REASONS = {
+	"is missing": "missing",
+	"is empty": "empty",
+	"still contains its guidance text": "guidance text left"
+};
+/** The section findings of a draft lint as headings and reasons, and the other findings. */
+function sectionGaps(findings) {
+	const headings = [];
+	const reasons = [];
+	const other = [];
+	for (const f of findings) {
+		const m = SECTION_FINDING.exec(f.message);
+		if (m === null) {
+			other.push(f);
+			continue;
+		}
+		const [, heading = "", what = ""] = m;
+		const reason = REASONS[what] ?? what;
+		if (!headings.includes(heading)) headings.push(heading);
+		if (!reasons.includes(reason)) reasons.push(reason);
+	}
+	return {
+		headings,
+		reasons,
+		other
+	};
+}
+/**
+* The draft lint of `new` as advice: `Fill in N sections before accepting: A, B (why)` for the
+* section findings, and one line per other finding.
+*/
+function draftAdvice(findings) {
+	const { headings, reasons, other } = sectionGaps(findings);
+	const n = headings.length;
+	return [...n === 0 ? [] : [`Fill in ${n === 1 ? "1 section" : `${n} sections`} before accepting: ${headings.join(", ")} (${reasons.join(", ")})`], ...other.map((f) => `Draft: ${f.message} [${f.rule}]`)];
+}
+/**
+* The stderr warning of `new` when the draft it wrote has unfilled sections (design §7.2), or
+* `null` when there are none.
+*/
+function unfilledWarning(doc) {
+	if (doc.command !== "new" || !doc.ok || doc.written.length === 0) return null;
+	const { headings, reasons } = sectionGaps(doc.findings);
+	const n = headings.length;
+	const path = doc.findings.find((f) => f.file !== null)?.file ?? doc.decision?.body_path ?? null;
+	if (n === 0 || path === null) return null;
+	return `${path}: fill in ${n === 1 ? "1 required section" : `${n} required sections`} before committing or accepting: ${headings.join(", ")} (${reasons.join(", ")}); adr verify reports this until then`;
+}
+function findingLines(findings) {
+	return findings.map((f) => `  ${f.file === null ? "" : `${f.file}: `}${f.message} [${f.rule}]`);
+}
+const short = (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.
+*/
+function followRenamesText(doc, display, o) {
+	if (!o.renamed) return "No staged renames.";
+	if (doc.affected.length === 0) return "No scope globs follow the staged renames.";
+	return [...doc.affected.map((v) => {
+		const before = o.before.get(v.id) ?? [];
+		const old = before.filter((g) => !v.applies_to.includes(g));
+		const now = v.applies_to.filter((g) => !before.includes(g));
+		const change = old.length === 0 ? `+ ${now.join(", ")}` : `${old.join(", ")} → ${now.join(", ")}`;
+		return `${named(v.id, display)}: ${change}`;
+	}), "Staged; commit the scoped events with the renames."].join("\n");
+}
+/** The past participle of each write command, for `Not <verb>: …`. */
+const VERBS = {
+	new: "proposed",
+	accept: "accepted",
+	supersede: "superseded",
+	reject: "rejected",
+	withdraw: "withdrawn",
+	deprecate: "deprecated",
+	note: "noted",
+	link: "linked",
+	scope: "scoped"
+};
+/**
+* The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
+* about; `number` is the decision's number in the write result, if it has one now; `reason` is
+* the reason a lifecycle exit recorded.
+*/
+function writeText(doc, display, o) {
+	const verb = VERBS[doc.command];
+	if (!doc.ok) {
+		const unfilled = doc.command === "new" && sectionGaps(doc.findings).headings.length > 0;
+		return [
+			`Not ${verb}: ${o.subject}`,
+			...findingLines(doc.findings),
+			...unfilled ? ["Fill them in with --section <id>=<markdown>, or run without --commit and edit the draft."] : []
+		].join("\n");
+	}
+	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 recorded = committed === null ? "Staged; commit to record it." : `${committed}.`;
+	switch (doc.command) {
+		case "new": return [
+			`Proposed ${v.id}: ${v.title}`,
+			...doc.written.map((p) => `  ${p}`),
+			...draftAdvice(doc.findings),
+			...committed === null ? [] : [`${committed}.`],
+			o.actor?.kind === "agent" && o.acceptRequiresHuman === true ? `Next: ask a human to review and accept it (adr accept ${v.id})` : `Next: adr accept ${v.id}`
+		].join("\n");
+		case "accept": return [
+			`Accepted ${v.id}: ${v.title}`,
+			...doc.affected.map((a) => `Superseded ${named(a.id, display)}: ${a.title}`),
+			...o.copied === void 0 || o.copied === null ? [] : [`Copied scope from ${o.copied.displays.join(", ")}: ${o.copied.globs.join(", ")}`],
+			committed === null ? "Staged; commit to record it." : o.number === null ? `${committed}. The number is assigned when this commit lands on main.` : `${committed} as ${o.number}.`
+		].join("\n");
+		case "supersede": return [
+			`Superseded ${named(v.id, display)}: ${v.title}`,
+			`  by ${named(v.superseded_by ?? "", display)}`,
+			recorded
+		].join("\n");
+		case "reject":
+		case "withdraw":
+		case "deprecate": return [
+			`${verb.charAt(0).toUpperCase()}${verb.slice(1)} ${named(v.id, display)}: ${v.title}`,
+			...o.reason === void 0 || o.reason === null ? [] : [`  reason: ${o.reason}`],
+			recorded
+		].join("\n");
+		case "note": return [`Noted on ${named(v.id, display)}: ${v.title}`, recorded].join("\n");
+		case "link": {
+			const link = doc.written.length === 0 ? void 0 : v.links.at(-1);
+			if (link === void 0) return `Links of ${named(v.id, display)} unchanged`;
+			return [`Linked ${named(v.id, display)} ${link.rel} ${named(link.to, display)}`, recorded].join("\n");
+		}
+		case "scope": {
+			const before = new Set(o.scopeBefore ?? []);
+			const after = new Set(v.applies_to);
+			const globs = v.applies_to.length === 0 ? "no globs" : v.applies_to.join(", ");
+			if (doc.written.length === 0) return `Scope of ${named(v.id, display)} unchanged: ${globs}`;
+			return [
+				`Scope of ${named(v.id, display)}: ${v.title}`,
+				...v.applies_to.filter((g) => !before.has(g)).map((g) => `  + ${g}`),
+				...[...before].filter((g) => !after.has(g)).map((g) => `  - ${g}`),
+				`  = ${globs}`,
+				recorded
+			].join("\n");
+		}
+	}
+}
+/**
+* "Applies to" without globs: nothing is recorded, which isn't "governs nothing" (design §7.3),
+* with the command that adds globs while the decision can still take them.
+*/
+function noGlobs(v, display) {
+	return adrKind.machine.allowed(v.status, "scoped") ? `no globs recorded; add them with adr scope ${display(v.id)} --add <glob>` : "no globs recorded";
+}
+/** `adr show`: the state header, the decision's fields and its body. */
+function showText(doc, display) {
+	const v = doc.decision;
+	const supersedes = v.supersedes.length === 0 && v.declared_supersedes.length > 0 ? `none (declared: ${list(v.declared_supersedes, display)})` : list(v.supersedes, display);
+	const fields = [
+		["Title", v.title],
+		["Status", `${v.status} (${day(v.status_at)})`],
+		["Effective", v.effective === null ? "none (supersession cycle)" : named(v.effective, display)],
+		["Chain", v.chain.map(display).join(" → ")],
+		["Supersedes", supersedes],
+		["Applies to", v.applies_to.length === 0 ? noGlobs(v, display) : v.applies_to.join(", ")],
+		["Body", bodyLine(v)]
+	];
+	if (doc.events === null) fields.push(["History", v.history.join(" · ")]);
+	const width = Math.max(...fields.map(([k]) => k.length)) + 2;
+	const lines = fields.map(([k, value]) => `${`${k}:`.padEnd(width)}${value}`);
+	if (doc.events !== null) lines.push("History:", ...historyLines(doc.events));
+	const body = doc.body === null ? "" : `\n${doc.body.endsWith("\n") ? doc.body : `${doc.body}\n`}`;
+	return `${renderStateHeader(doc.header)}\n${lines.join("\n")}\n${body}`;
+}
+/**
+* `adr for`: per path, one row per decision (named, status, title, how it matched), its warning
+* below it when it isn't in force, then the anchors that name no decision of this log.
+*/
+function forText(doc, display, keyword) {
+	const lines = [];
+	for (const p of doc.paths) {
+		lines.push(p.tracked ? p.path : `${p.path} (not tracked)`);
+		if (p.decisions.length === 0 && p.unresolved.length === 0) lines.push("  no decisions");
+		const rows = columns(p.decisions.map((d) => [
+			named(d.id, display),
+			d.status,
+			d.title,
+			d.via.map((v) => v.type === "glob" ? `glob ${v.glob}` : `anchor line ${v.line}`).join(", ")
+		])).split("\n");
+		p.decisions.forEach((d, i) => {
+			lines.push(`  ${rows[i] ?? ""}`);
+			if (d.warning !== null) lines.push(`    ${d.warning}`);
+		});
+		for (const u of p.unresolved) {
+			const why = u.reason === "other-log" ? "in another log" : "not in this log";
+			lines.push(`  unresolved: ${keyword}:${u.ref} (line ${u.line}, ${why})`);
+		}
+	}
+	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(", ")})`;
+	return [
+		`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>\""
+	].join("\n");
+}
+// src/cli/accept.ts
+const MAX_LISTED = 5;
+/** `Copy the scope of ADR-0002 (src/a/**, src/b/**) to k3f9q8a1? [y/N] ` (design §6.10). */
+function question(id, offer) {
+	const shown = offer.globs.slice(0, MAX_LISTED).join(", ");
+	const more = offer.globs.length - MAX_LISTED;
+	const globs = more > 0 ? `${shown} and ${more} more` : shown;
+	const ds = offer.displays;
+	return `Copy the scope of ${ds.length === 1 ? ds[0] : `${ds.slice(0, -1).join(", ")} and ${ds.at(-1)}`} (${ds.length === 1 ? globs : `${offer.globs.length} globs: ${globs}`}) to ${id}? [y/N] `;
+}
+/**
+* The flags decide; without them a person at a terminal is asked, and everyone else (scripts,
+* hooks, CI, `--json`) gets the note with the `adr scope` command (design §6.10, D-e). `seen`
+* receives the offer that was copied, for the text.
+*/
+function copyChoice(io, json, value, seen) {
+	const copy = async (offer) => {
+		seen(offer);
+		return true;
+	};
+	if (value === true) return copy;
+	if (value === false) return "skip";
+	if (json || !io.interactive) return "suggest";
+	return async (offer) => {
+		const yes = await confirm(io, question(offer.id, offer), { json });
+		if (yes) seen(offer);
+		return yes;
+	};
+}
+/** `adr accept <decision> [--copy-scope | --no-copy-scope] …` (design §5.6, §6.10). */
+const acceptCommand = {
+	name: "accept",
+	summary: "accept a proposed decision, superseding the decisions it declares",
+	usage: "accept <decision> [--copy-scope | --no-copy-scope] [--commit | --no-commit] [-m <message>]",
+	options: {
+		"copy-scope": { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		const log = await openForCli(io, flags);
+		const { actor, notes: attribution } = await resolveAttribution(log.git, { env: io.env });
+		const seen = { offer: null };
+		const copyScope = copyChoice(io, flags.json, values["copy-scope"], (offer) => {
+			seen.offer = offer;
+		});
+		const doc = await acceptDecision(log, {
+			id: input,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes: attribution,
+			copyScope
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: v === null || doc.commit === null || v.number === null ? null : v.display,
+				copied: doc.ok ? seen.offer : null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/deprecate.ts
+const USAGE$4 = "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,
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	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}`);
+		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 });
+		const doc = await deprecateDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/for.ts
+/** `adr for <path>… [--ref <ref>]` (design §6.9): the decisions that govern each file. */
+const forCommand = {
+	name: "for",
+	summary: "list the decisions that govern files, by scope glob and code anchor",
+	usage: "for <path>…",
+	options: {},
+	positionals: {
+		min: 1,
+		max: 100,
+		names: ["path"]
+	},
+	ref: "read",
+	async run({ io, flags, positionals }) {
+		const log = await openForCli(io, flags);
+		const read = await readDecisions(log);
+		const doc = await decisionsFor(read, log, {
+			paths: positionals,
+			cwd: io.cwd
+		});
+		const display = (id) => read.projection.views.get(id)?.display ?? id;
+		return {
+			exit: 0,
+			json: doc,
+			text: forText(doc, display, read.adr.anchorKeyword),
+			notes: doc.notes
+		};
+	}
+};
+// 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>]",
+	options: {
+		template: {
+			type: "string",
+			multiple: true
+		},
+		...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 log = await openForCli(io, flags);
+		const doc = await initDecisionLog(log, {
+			...templates === void 0 ? {} : { templates },
+			...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 = {
+	name: "link",
+	summary: "link a decision to another one, here or in a configured source",
+	usage: "link <decision> <target> [--rel relates-to|refines|depends-on] [--commit | --no-commit] [-m <message>]",
+	options: {
+		rel: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 2,
+		max: 2,
+		names: ["decision", "target"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [input = "", to = ""] = positionals;
+		const rel = typeof values.rel === "string" ? values.rel : "relates-to";
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await linkDecision(log, {
+			id: input,
+			to,
+			rel,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/list.ts
+const plural = (n, one, many) => n === 1 ? `1 ${one}` : `${n} ${many}`;
+function statuses(values) {
+	return (Array.isArray(values.status) ? values.status : []).map((s) => {
+		if (!DECISION_STATUSES.includes(s)) throw new UsageError(`unknown status ${JSON.stringify(s)}; use one of ${DECISION_STATUSES.join(", ")}`);
+		return s;
+	});
+}
+/** `adr list [--status <status>]…` (design §5.6). */
+const listCommand = {
+	name: "list",
+	summary: "list decisions with their computed status",
+	usage: "list [--status <status>]…",
+	options: { status: {
+		type: "string",
+		multiple: true
+	} },
+	positionals: {
+		min: 0,
+		max: 0,
+		names: []
+	},
+	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 notes = [...doc.notes];
+		if (!read.numbering.available && doc.decisions.length > 0) notes.push(`numbers are unavailable (${unavailableReason(read.numbering)}); decisions display by id`);
+		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`);
+		const display = (id) => read.projection.views.get(id)?.display ?? id;
+		return {
+			exit: 0,
+			json: doc,
+			text: listText(doc, display),
+			notes
+		};
+	}
+};
+// src/cli/editor.ts
+/**
+* The user's editor as an `edit` callback (design §5.7), or `null` when neither `VISUAL` nor
+* `EDITOR` is set. The editor string is run by `sh -c` the way git runs `core.editor`, with the
+* path as the positional parameter `$1`, never interpolated. When stdout isn't a TTY (piped
+* `--json`, say), the editor's stdout goes to stderr so the CLI's stdout stays one document.
+* The callback never throws: a spawn error or a non-zero exit becomes the note.
+*/
+function editorFor(env, o) {
+	const editor = [env.VISUAL, env.EDITOR].map((v) => v?.trim() ?? "").find((v) => v !== "");
+	if (editor === void 0) return null;
+	return (absPath) => new Promise((resolve) => {
+		const fail = (e) => resolve(`could not start the editor: ${e instanceof Error ? e.message : String(e)}`);
+		try {
+			const child = spawn("sh", [
+				"-c",
+				`${editor} "$1"`,
+				"sh",
+				absPath
+			], {
+				env,
+				stdio: o.stdoutIsTTY ? "inherit" : [
+					"inherit",
+					2,
+					"inherit"
+				]
+			});
+			child.on("error", fail);
+			child.on("close", (code, signal) => {
+				if (code === 0) resolve(null);
+				else resolve(`the editor ${code === null ? `was killed by ${signal ?? "a signal"}` : `exited with status ${code}`}; the draft is staged as rendered`);
+			});
+		} catch (e) {
+			fail(e);
+		}
+	});
+}
+// src/cli/new.ts
+const strings$1 = (v) => Array.isArray(v) ? v : [];
+/** `--section <id>=<markdown>` values, split at the first `=`; each id at most once. */
+function sections(values) {
+	const out = {};
+	for (const value of values) {
+		const at = value.indexOf("=");
+		const id = at < 0 ? "" : value.slice(0, at).trim();
+		if (id === "") throw new UsageError(`--section needs <id>=<markdown>, not ${JSON.stringify(value)}`);
+		if (Object.hasOwn(out, id)) throw new UsageError(`--section ${id} is given twice`);
+		out[id] = value.slice(at + 1);
+	}
+	return out;
+}
+/**
+* `adr new <title> …` (design §5.6). The editor runs with `--edit`, or without `--no-edit` when
+* the terminal is interactive and an editor is set.
+*/
+const newCommand = {
+	name: "new",
+	summary: "propose a decision from a template and stage it",
+	usage: "new <title> [--template <name>] [--supersedes <decision>]… [--section <id>=<markdown>]… [--edit | --no-edit] [--commit | --no-commit] [-m <message>]",
+	options: {
+		template: { type: "string" },
+		supersedes: {
+			type: "string",
+			multiple: true
+		},
+		section: {
+			type: "string",
+			multiple: true
+		},
+		edit: { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["title"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const title = positionals[0] ?? "";
+		const given = sections(strings$1(values.section));
+		const log = await openForCli(io, flags);
+		const { actor, notes: attribution } = await resolveAttribution(log.git, { env: io.env });
+		const { commit: requested, message } = commitChoice(values, { autoCommit: log.adr.autoCommit });
+		const notes = [];
+		const editor = editorFor(io.env, { stdoutIsTTY: io.stdoutIsTTY });
+		const wantsEdit = values.edit === true || values.edit === void 0 && io.interactive;
+		if (values.edit === true && editor === null) notes.push("no editor: set VISUAL or EDITOR");
+		const edit = wantsEdit && editor !== null ? async (abs) => {
+			const note = await editor(abs);
+			if (note !== null) notes.push(note);
+			return note;
+		} : void 0;
+		const doc = await proposeDecision(log, {
+			title,
+			sections: given,
+			supersedes: strings$1(values.supersedes),
+			actor,
+			...typeof values.template === "string" ? { template: values.template } : {}
+		}, {
+			commit: requested,
+			message,
+			notes: attribution,
+			...edit === void 0 ? {} : { edit },
+			onNote: (note) => notes.push(requested ? `not committed: ${note}` : note)
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		const unfilled = unfilledWarning(doc);
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: title.trim(),
+				number: v === null || v.number === null ? null : v.display,
+				actor,
+				acceptRequiresHuman: log.adr.acceptRequiresHuman
+			}),
+			notes: [
+				...doc.notes,
+				...notes,
+				...unfilled === null ? [] : [unfilled]
+			]
+		};
+	}
+};
+// src/cli/note.ts
+/** `adr note <decision> <text>` (design §6.6): a note on a decision in any state. */
+const noteCommand = {
+	name: "note",
+	summary: "add a note to a decision, in any state",
+	usage: "note <decision> <text> [--commit | --no-commit] [-m <message>]",
+	options: { ...COMMIT_OPTIONS },
+	positionals: {
+		min: 2,
+		max: 2,
+		names: ["decision", "text"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const [input = "", text = ""] = positionals;
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await noteDecision(log, {
+			id: input,
+			text,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/reject.ts
+const USAGE$3 = "reject <decision> --reason <text> [--commit | --no-commit] [-m <message>]";
+/** `adr reject` (design §6.3): a proposal that won't be adopted. */
+const rejectCommand = {
+	name: "reject",
+	summary: "reject a proposed decision",
+	usage: USAGE$3,
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	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$3}`);
+		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 });
+		const doc = await rejectDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/scope.ts
+const USAGE$2 = "scope <decision> ([--set <glob>]… | --clear | [--add <glob>]… [--remove <glob>]…) [--commit | --no-commit] [-m <message>] | scope [<decision>] --follow-renames";
+/** The flag names `applySetOp` uses in its messages (design §3.2). */
+const NAMES = {
+	set: "--set",
+	add: "--add",
+	remove: "--remove",
+	clear: "--clear"
+};
+const strings = (v) => Array.isArray(v) ? v : [];
+/** `--set`/`--clear`/`--add`/`--remove` as a set operation; `--clear` is `{ set: [] }`. */
+function setOp(values) {
+	const set = strings(values.set);
+	const add = strings(values.add);
+	const remove = strings(values.remove);
+	if (values.clear === true) {
+		if (set.length > 0 || add.length > 0 || remove.length > 0) throw new UsageError("--clear can't be combined with --set, --add or --remove");
+		return { set: [] };
+	}
+	return {
+		...set.length > 0 ? { set } : {},
+		add,
+		remove
+	};
+}
+/**
+* `--follow-renames` alone: no set operation, no commit and no message, all refused before
+* `commitChoice` so the answer doesn't depend on `auto_commit` (design §6.8).
+*/
+function checkFollowRenames(values) {
+	if ([
+		"set",
+		"add",
+		"remove"
+	].some((k) => strings(values[k]).length > 0) || values.clear === true) throw new UsageError("--follow-renames can't be combined with --set, --clear, --add or --remove");
+	if (values.commit === true) throw new UsageError("--follow-renames stages its events for the commit that contains the renames; commit them together");
+	if (typeof values.message === "string") throw new UsageError("--follow-renames never commits, so it takes no --message");
+}
+/**
+* `adr scope <decision> --set|--clear|--add|--remove …` (design §6.8): the globs of the code a
+* decision governs, written as one whole-set `scoped` event. `adr scope [<decision>]
+* --follow-renames` rewrites them after staged renames and stages the events, never committing.
+*/
+const scopeCommand = {
+	name: "scope",
+	summary: "set, add or remove the globs of the code a decision governs",
+	usage: USAGE$2,
+	options: {
+		set: {
+			type: "string",
+			multiple: true
+		},
+		add: {
+			type: "string",
+			multiple: true
+		},
+		remove: {
+			type: "string",
+			multiple: true
+		},
+		clear: { type: "boolean" },
+		"follow-renames": { type: "boolean" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 0,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0];
+		if (values["follow-renames"] === true) {
+			checkFollowRenames(values);
+			const log = await openForCli(io, flags);
+			const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+			const read = await readDecisions(log);
+			const before = new Map([...read.projection.views].map(([id, v]) => [id, v.applies_to]));
+			const renamed = (await stagedRenames(log.git)).length > 0;
+			const doc = await followScopeRenames(log, {
+				...input === void 0 ? {} : { id: input },
+				actor
+			}, { notes });
+			const { display } = await displayAfterWrite(log);
+			const v = doc.decision;
+			return {
+				exit: doc.ok ? 0 : 1,
+				json: doc,
+				text: writeText(doc, display, {
+					subject: v === null ? (input ?? "").trim() : `${display(v.id)}: ${v.title}`,
+					number: null,
+					followRenames: {
+						before,
+						renamed
+					}
+				}),
+				notes: doc.notes
+			};
+		}
+		const op = setOp(values);
+		if (input === void 0) throw new UsageError(`missing argument <decision>; usage: adr ${USAGE$2}`);
+		const log = await openForCli(io, flags);
+		const { actor, notes } = await resolveAttribution(log.git, { env: io.env });
+		const choice = commitChoice(values, { autoCommit: log.adr.autoCommit });
+		const read = await readDecisions(log);
+		const before = read.projection.views.get(resolveDecision(read, input))?.applies_to ?? [];
+		const doc = await scopeDecision(log, {
+			id: input,
+			op,
+			actor,
+			names: NAMES
+		}, {
+			...choice,
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null,
+				scopeBefore: before
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/show.ts
+/** `adr show <decision> [--history]` (design §5.6). */
+const showCommand = {
+	name: "show",
+	summary: "show a decision with its state header, chain, history and body",
+	usage: "show <decision> [--history]",
+	options: { history: { type: "boolean" } },
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "read",
+	async run({ io, flags, values, positionals }) {
+		const read = await readDecisions(await openForCli(io, flags));
+		const id = resolveDecision(read, positionals[0] ?? "");
+		const doc = await showDecision(read, id, { history: values.history === true });
+		const display = (s) => read.projection.views.get(s)?.display ?? s;
+		return {
+			exit: 0,
+			json: doc,
+			text: showText(doc, display),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/supersede.ts
+const USAGE$1 = "supersede <decision> --by <decision> [--reason <text>] [--commit | --no-commit] [-m <message>]";
+/** `adr supersede <decision> --by <decision> …` (design §5.6). */
+const supersedeCommand = {
+	name: "supersede",
+	summary: "mark an accepted decision as superseded by another accepted one",
+	usage: USAGE$1,
+	options: {
+		by: { type: "string" },
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.by !== "string") throw new UsageError(`missing --by <decision>; usage: adr ${USAGE$1}`);
+		const log = await openForCli(io, flags);
+		const { actor, notes: attribution } = await resolveAttribution(log.git, { env: io.env });
+		const doc = await supersedeDecision(log, {
+			id: input,
+			by: values.by,
+			actor,
+			...typeof values.reason === "string" ? { reason: values.reason } : {}
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes: attribution
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null
+			}),
+			notes: doc.notes
+		};
+	}
+};
+/** `adr withdraw` (design §6.4): a proposal its author takes back. */
+const withdrawCommand = {
+	name: "withdraw",
+	summary: "withdraw a proposed decision",
+	usage: "withdraw <decision> [--reason <text>] [--commit | --no-commit] [-m <message>]",
+	options: {
+		reason: { type: "string" },
+		...COMMIT_OPTIONS
+	},
+	positionals: {
+		min: 1,
+		max: 1,
+		names: ["decision"]
+	},
+	ref: "reject",
+	async run({ io, flags, values, positionals }) {
+		const input = positionals[0] ?? "";
+		if (typeof values.reason === "string" && values.reason.trim() === "") throw new UsageError("--reason must not be empty");
+		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 });
+		const doc = await withdrawDecision(log, {
+			id: input,
+			reason,
+			actor
+		}, {
+			...commitChoice(values, { autoCommit: log.adr.autoCommit }),
+			notes
+		});
+		const { display } = await displayAfterWrite(log);
+		const v = doc.decision;
+		return {
+			exit: doc.ok ? 0 : 1,
+			json: doc,
+			text: writeText(doc, display, {
+				subject: v === null ? input.trim() : `${display(v.id)}: ${v.title}`,
+				number: null,
+				reason
+			}),
+			notes: doc.notes
+		};
+	}
+};
+// src/cli/commands.ts
+/**
+* ledger's shared `verify`: the log as the mode reads it (the index for `--staged`, else the
+* `--ref` tree or the work tree), every phase-1 check, and `[verify] fail_on`.
+*/
+const verify = verifyCommand({ async open({ io, flags, mode }) {
+	const log = await openForCli(io, flags, { reader: mode.type === "staged" ? "index" : "worktree" });
+	return {
+		git: log.git,
+		kind: adrKind,
+		layout: log.layout,
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode)),
+		failOn: log.adr.failOn,
+		notes: log.notes
+	};
+} });
+/** The `adr` tool: its commands, for ledger's `runCli`. */
+function adrCli(version) {
+	return {
+		name: "adr",
+		version,
+		summary: "Architecture decision records kept as event logs in git.",
+		commands: [
+			initCommand,
+			newCommand,
+			acceptCommand,
+			rejectCommand,
+			withdrawCommand,
+			deprecateCommand,
+			supersedeCommand,
+			noteCommand,
+			linkCommand,
+			scopeCommand,
+			forCommand,
+			listCommand,
+			showCommand,
+			verify
+		]
+	};
+}
+// src/cli.ts
+const { version } = createRequire(import.meta.url)("../package.json");
+process.exitCode = await runCli(adrCli(version), processIO());
+export {};
+
+//# sourceMappingURL=cli.js.map