@vimhead.dev/norn-cli 0.1.0-tip.0

package/assets/packages/cli/src/cli.ts

@@ -0,0 +1,1135 @@
+import { spawn } from "node:child_process";
+import { main as runPi } from "@earendil-works/pi-coding-agent";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { renderNornDocumentationIntro, resolveDocumentationCacheRoot, resolveNornDocumentation, type NornDocumentationSource } from "./documentation.ts";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverNornProject, findNornProject, inspectNornWorkflow, loadNornProject, NORN_PROJECT_FILE_NAME } from "./plugin-loader.ts";
+import { type NornAnyWorkflowDeclaration, type DeletedNornRunInfo, type NornRunInfo } from "@vimhead.dev/norn";
+import { NornEngine } from "./internal/engine.ts";
+import { errorMessage, NornProjectLoadError, NornRunStoppedError } from "./internal/errors.ts";
+import { isNodeError } from "@vimhead.dev/norn-core/errors";
+import { clearRunResumeRequest, readRunLaunchRequest, readRunResumeRequest, writeRunLaunchRequest, writeRunResumeRequest, type NornRunResumeRequest } from "./internal/launch-request.ts";
+import { generateRunName } from "./internal/run-names.ts";
+import { getRunLeaseOwner, NornRunLease } from "./internal/run-lease.ts";
+import { NornRunStore } from "./internal/run-store.ts";
+import { readRunMetrics } from "./internal/metrics.ts";
+import { getRunInfo, listRuns, mergeInterruptedWorkflowParams, resolveRunRoot } from "./internal/run-state.ts";
+import { NORN_BUILD_INFO, type NornBuildInfo, type NornGithubReleaseBinaryBuildInfo } from "./build-info.ts";
+
+const RUNS_ROOT = join(".norn", "runs");
+const RUN_WAIT_INTERVAL_MS = 1000;
+const CLI_DESCRIPTION = "Norn is a harness-agnostic runtime for agent-driven and code-driven workflows, built primarily for agents. Build workflows with the Norn SDK; use this JSON-native CLI to discover workflows, start or resume runs, inspect evidence, and manage the installed runtime.";
+
+const COMMANDS: readonly CliCommand[] = [
+	{
+		id: "pi",
+		path: ["pi"],
+		description: "Run Norn's bundled Pi CLI for interactive authentication, provider packages, model configuration, or direct Pi use. No Norn project is required.",
+		usage: "norn pi [pi arguments...]",
+		arguments: ["pi arguments: forwarded unchanged; use norn pi --help for Pi's CLI contract"],
+		output: "Pi's native terminal, text, JSON, or RPC output and exit status; not wrapped in Norn JSON.",
+		examples: ["norn pi", "norn pi install npm:pi-cursor-sdk", "norn pi --list-models cursor", "norn pi --help"],
+		execute: args => runPi([...args]),
+	},
+	{
+		id: "commands.list",
+		path: ["commands", "list"],
+		description: "Use when an agent or human needs machine-readable Norn CLI command metadata.",
+		usage: "norn commands list [--all]",
+		options: ["--all: include hidden internal commands"],
+		output: "JSON object with command metadata under commands.",
+		examples: ["norn commands list", "norn commands list --all"],
+		execute: listCliCommands,
+	},
+	{
+		id: "commands.inspect",
+		path: ["commands", "inspect"],
+		description: "Use when an agent or human needs the usage contract for one Norn CLI command.",
+		usage: "norn commands inspect <command-id>",
+		arguments: ["command-id: command metadata id such as runs.start"],
+		output: "JSON object with one command metadata object under command.",
+		examples: ["norn commands inspect runs.start"],
+		execute: inspectCliCommand,
+	},
+	{
+		id: "help",
+		path: ["help"],
+		description: "Use when reading JSON help for all Norn commands, one command group, or one command.",
+		usage: "norn help [command-or-group]",
+		arguments: ["command-or-group: optional command path such as runs or runs start"],
+		output: "JSON object with help metadata under help.",
+		examples: ["norn help", "norn help runs", "norn help runs start", "norn --help"],
+		execute: (args) => writeCliHelp(args),
+	},
+	{
+		id: "docs.inspect",
+		path: ["docs", "inspect"],
+		description: "Resolve version-matched local documentation and examples. Standalone binaries extract bundled assets into a verified build-specific cache; no project or network is required.",
+		usage: "norn docs inspect",
+		output: "JSON object under documentation with storage, version, commit, assetDigest, and absolute paths. NORN_DOCS_CACHE_DIR overrides the binary cache directory.",
+		examples: ["norn docs inspect"],
+		execute: async (args, documentationSource) => {
+			assertNoExtraArgs("docs inspect", args);
+			writeJson({ documentation: await resolveCliDocumentation(documentationSource) });
+		},
+	},
+	{
+		id: "docs.intro",
+		path: ["docs", "intro"],
+		description: "Produce a compact introduction to Norn authoring with this runtime's invocation and matching local documentation pointers. Does not load a project, list workflows, or deliver context to agents.",
+		usage: "norn docs intro",
+		output: "JSON object with introduction text under intro. Uses the same asset resolution and NORN_DOCS_CACHE_DIR override as docs inspect.",
+		examples: ["norn docs intro"],
+		execute: async (args, documentationSource) => {
+			assertNoExtraArgs("docs intro", args);
+			writeJson({ intro: renderNornDocumentationIntro({
+				documentation: await resolveCliDocumentation(documentationSource),
+				invocation: documentationSource.kind === "embedded"
+					? [process.execPath]
+					: [process.execPath, fileURLToPath(new URL("../bin/norn.mjs", import.meta.url))],
+			}) });
+		},
+	},
+	{
+		id: "project.init",
+		path: ["project", "init"],
+		description: "Use when creating a self-contained Norn project config and local run state directory in the current directory.",
+		usage: "norn project init",
+		output: "JSON object with initialized project metadata under project.",
+		examples: ["norn project init"],
+		execute: async (args) => {
+			assertNoExtraArgs("project init", args);
+			await initProject();
+		},
+	},
+	{
+		id: "project.inspect",
+		path: ["project", "inspect"],
+		description: "Use when discovering the active Norn project, plugins, workflow sources, and Seer mode.",
+		usage: "norn project inspect",
+		output: "JSON object with project metadata under project, isComplete, and plugin diagnostics. Incomplete discovery does not permit execution.",
+		examples: ["norn project inspect"],
+		execute: async (args) => {
+			assertNoExtraArgs("project inspect", args);
+			await inspectProject();
+		},
+	},
+	{
+		id: "seer.inspect",
+		path: ["seer", "inspect"],
+		description: "Use when checking the current project's resolved Seer mode before agent execution.",
+		usage: "norn seer inspect",
+		output: "JSON object with resolved Seer mode under seerMode.",
+		examples: ["norn seer inspect"],
+		execute: async (args) => {
+			assertNoExtraArgs("seer inspect", args);
+			await inspectSeerMode();
+		},
+	},
+	{
+		id: "workflows.list",
+		path: ["workflows", "list"],
+		description: "Use when selecting a Norn workflow for a user task; defaults to entrypoint workflows.",
+		usage: "norn workflows list [--entrypoints|--all]",
+		options: ["--entrypoints: list entrypoint workflows", "--all: include internal workflow steps"],
+		output: "JSON object with workflow summaries under workflows, isComplete, and plugin diagnostics. Successful discovery can be incomplete; start/resume remain strict.",
+		examples: ["norn workflows list", "norn workflows list --all"],
+		execute: listWorkflows,
+	},
+	{
+		id: "workflows.inspect",
+		path: ["workflows", "inspect"],
+		description: "Use when reading a workflow's instructions, params schema, gate contract, and source plugin before starting or editing it.",
+		usage: "norn workflows inspect <workflow-id>",
+		arguments: ["workflow-id: fully qualified workflow id"],
+		output: "JSON object with workflow details, isComplete, and plugin diagnostics. workflow is null if unavailable in an incomplete catalog or its schema cannot be inspected; an unknown id in a complete catalog is an error.",
+		examples: ["norn workflows inspect example.plan"],
+		execute: async (args) => {
+			const workflowId = requiredArg("workflows inspect", args, 0, "workflow id");
+			assertNoExtraArgs("workflows inspect", args.slice(1));
+			await inspectWorkflow(workflowId);
+		},
+	},
+	{
+		id: "runs.start",
+		path: ["runs", "start"],
+		description: "Use when starting a Norn workflow run after the workflow id and params are known.",
+		usage: "norn runs start <workflow-id>",
+		arguments: ["workflow-id: fully qualified workflow id to start"],
+		stdin: "Optional JSON object: {\"params\":{...},\"config\":{\"pluginId\":{...}}}.",
+		output: "JSON object with started run info under run.",
+		examples: ["printf '{\"params\":{\"task\":\"Add tests\"}}' | norn runs start example.plan"],
+		execute: async (args) => {
+			const workflowId = requiredArg("runs start", args, 0, "workflow id");
+			await startRun(workflowId, args.slice(1));
+		},
+	},
+	{
+		id: "runs.resume",
+		path: ["runs", "resume"],
+		description: "Use when resuming an interrupted gate or a checkpoint restored for retry.",
+		usage: "norn runs resume <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		stdin: "Optional JSON object: {\"params\":{...}}. Interrupted runs require a patch containing only editable gate fields; pending-resume runs do not accept params.",
+		output: "JSON object with resumed run info under run.",
+		examples: ["printf '{\"params\":{\"decision\":\"accept\"}}' | norn runs resume quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs resume", args, 0, "run");
+			await resumeRun(run, args.slice(1));
+		},
+	},
+	{
+		id: "runs.wait",
+		path: ["runs", "wait"],
+		description: "Use when waiting for a Norn run to finish, fail, interrupt, or become unhealthy.",
+		usage: "norn runs wait <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with final or current run info under run.",
+		examples: ["norn runs wait quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs wait", args, 0, "run");
+			assertNoExtraArgs("runs wait", args.slice(1));
+			await waitRun(run);
+		},
+	},
+	{
+		id: "runs.list",
+		path: ["runs", "list"],
+		description: "Use when listing known Norn runs in the current project.",
+		usage: "norn runs list",
+		output: "JSON object with run summaries under runs.",
+		examples: ["norn runs list"],
+		execute: async (args) => {
+			assertNoExtraArgs("runs list", args);
+			writeJson({ runs: await listCurrentProjectRuns() });
+		},
+	},
+	{
+		id: "runs.inspect",
+		path: ["runs", "inspect"],
+		description: "Use when reading status, health, current workflow, interruption, and outcome details for one Norn run.",
+		usage: "norn runs inspect <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with run details under run.",
+		examples: ["norn runs inspect quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs inspect", args, 0, "run");
+			assertNoExtraArgs("runs inspect", args.slice(1));
+			writeJson({ run: await inspectRun(run) });
+		},
+	},
+	{
+		id: "runs.checkpoints",
+		path: ["runs", "checkpoints"],
+		description: "Use when finding rollback points before retrying or repairing a Norn run.",
+		usage: "norn runs checkpoints <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with checkpoints under checkpoints.",
+		examples: ["norn runs checkpoints quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs checkpoints", args, 0, "run");
+			assertNoExtraArgs("runs checkpoints", args.slice(1));
+			const project = await findNornProject(process.cwd());
+			const runRoot = await resolveRunRoot(project.projectRoot, run);
+			writeJson({ checkpoints: await (await NornRunStore.open(runRoot)).listCheckpoints() });
+		},
+	},
+	{
+		id: "runs.metrics",
+		path: ["runs", "metrics"],
+		description: "Use when measuring workflow, agent, command, token, and cost totals for a Norn run.",
+		usage: "norn runs metrics <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with metrics under metrics.",
+		examples: ["norn runs metrics quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs metrics", args, 0, "run");
+			assertNoExtraArgs("runs metrics", args.slice(1));
+			const project = await findNornProject(process.cwd());
+			const runRoot = await resolveRunRoot(project.projectRoot, run);
+			writeJson({ metrics: await readRunMetrics(runRoot) });
+		},
+	},
+	{
+		id: "runs.logs",
+		path: ["runs", "logs"],
+		description: "Use when streaming or reading chronological JSON events for a Norn run.",
+		usage: "norn runs logs <run> [--follow]",
+		arguments: ["run: run id, generated name, or run path"],
+		options: ["--follow: continue streaming until the run stops"],
+		output: "JSON Lines stream of run events.",
+		examples: ["norn runs logs quiet-river-lantern", "norn runs logs quiet-river-lantern --follow"],
+		execute: async (args) => {
+			const run = requiredArg("runs logs", args, 0, "run");
+			const logArgs = args.slice(1);
+			assertKnownFlags("runs logs", logArgs, ["--follow"]);
+			await writeRunLogs(run, { follow: logArgs.includes("--follow") });
+		},
+	},
+	{
+		id: "runs.rollback",
+		path: ["runs", "rollback"],
+		description: "Use when restoring a failed or stopped run to a checkpoint and marking it pending resume.",
+		usage: "norn runs rollback <run> <checkpoint-id>",
+		arguments: ["run: run id, generated name, or run path", "checkpoint-id: checkpoint id from runs.checkpoints"],
+		output: "JSON object with rolled-back run info under run.",
+		examples: ["norn runs rollback quiet-river-lantern checkpoint-1"],
+		execute: async (args) => {
+			const run = requiredArg("runs rollback", args, 0, "run");
+			await rollbackRun(run, args.slice(1));
+		},
+	},
+	{
+		id: "runs.stop",
+		path: ["runs", "stop"],
+		description: "Use when stopping a running Norn execution while preserving its dirty state for inspection or rollback.",
+		usage: "norn runs stop <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with updated run info under run.",
+		examples: ["norn runs stop quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs stop", args, 0, "run");
+			assertNoExtraArgs("runs stop", args.slice(1));
+			await signalRun(run, "SIGTERM");
+		},
+	},
+	{
+		id: "runs.kill",
+		path: ["runs", "kill"],
+		description: "Use when force-stopping a Norn execution process that did not stop politely.",
+		usage: "norn runs kill <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with updated run info under run.",
+		examples: ["norn runs kill quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs kill", args, 0, "run");
+			assertNoExtraArgs("runs kill", args.slice(1));
+			await signalRun(run, "SIGKILL");
+		},
+	},
+	{
+		id: "runs.delete",
+		path: ["runs", "delete"],
+		description: "Use when deleting an inactive Norn run directory after evidence is no longer needed.",
+		usage: "norn runs delete <run>",
+		arguments: ["run: run id, generated name, or run path"],
+		output: "JSON object with deleted run identity under deleted.",
+		examples: ["norn runs delete quiet-river-lantern"],
+		execute: async (args) => {
+			const run = requiredArg("runs delete", args, 0, "run");
+			assertNoExtraArgs("runs delete", args.slice(1));
+			writeJson({ deleted: await deleteRun(run) });
+		},
+	},
+	{
+		id: "execute-run",
+		path: ["execute-run"],
+		description: "Use internally when executing a previously launched detached run request.",
+		usage: "norn execute-run <run-id>",
+		arguments: ["run-id: internal run id"],
+		output: "No stable stdout contract; execution state is persisted in the run directory.",
+		hidden: true,
+		examples: ["norn execute-run 00000000-0000-0000-0000-000000000000"],
+		execute: async (args) => {
+			const runId = requiredArg("execute-run", args, 0, "run id");
+			assertNoExtraArgs("execute-run", args.slice(1));
+			await executeRun(runId);
+		},
+	},
+	{
+		id: "upgrade",
+		path: ["upgrade"],
+		description: "Use when upgrading this Norn CLI installation according to explicit build metadata.",
+		usage: "norn upgrade [--dry-run]",
+		options: ["--dry-run: report the upgrade plan without changing files or running installers"],
+		output: "JSON object with upgrade status, plan, or unsupported reason under upgrade.",
+		examples: ["norn upgrade --dry-run", "norn upgrade"],
+		execute: upgradeNorn,
+	},
+	{
+		id: "version",
+		path: ["version"],
+		description: "Use when checking the installed Norn CLI version and explicit build metadata.",
+		usage: "norn version",
+		output: "JSON object with package version under version and build metadata under build.",
+		examples: ["norn version", "norn --version"],
+		execute: async (args) => {
+			assertNoExtraArgs("version", args);
+			writeJson(await versionInfo());
+		},
+	},
+];
+
+const HELP_COMMAND_ORDER = [
+	"commands.list",
+	"commands.inspect",
+	"docs.inspect",
+	"docs.intro",
+	"workflows.list",
+	"workflows.inspect",
+	"runs.start",
+	"runs.resume",
+	"runs.wait",
+	"runs.list",
+	"runs.inspect",
+	"runs.logs",
+	"runs.checkpoints",
+	"runs.rollback",
+	"runs.metrics",
+	"runs.stop",
+	"runs.kill",
+	"runs.delete",
+	"project.init",
+	"project.inspect",
+	"seer.inspect",
+	"pi",
+	"upgrade",
+	"version",
+	"help",
+];
+
+const HUMAN_COMMAND_SUMMARIES: Readonly<Record<string, string>> = {
+	"commands.list": "List machine-readable command metadata.",
+	"commands.inspect": "Inspect one command's machine-readable contract.",
+	"docs.inspect": "Locate matching documentation and examples offline.",
+	"docs.intro": "Produce a compact authoring introduction with local documentation pointers.",
+	"workflows.list": "List Norn workflows.",
+	"workflows.inspect": "Inspect a workflow schema and source.",
+	"runs.start": "Start a workflow run.",
+	"runs.resume": "Resume an interrupted gate or a restored checkpoint.",
+	"runs.wait": "Wait for a run to stop running.",
+	"runs.list": "List known runs.",
+	"runs.inspect": "Inspect a run.",
+	"runs.logs": "Read run event logs.",
+	"runs.checkpoints": "List run rollback checkpoints.",
+	"runs.rollback": "Restore a run checkpoint for a manual resume.",
+	"runs.metrics": "Inspect run metrics.",
+	"runs.stop": "Stop a running run.",
+	"runs.kill": "Force-stop a running run.",
+	"runs.delete": "Delete an inactive run.",
+	"project.init": "Create a Norn project in the current directory.",
+	"project.inspect": "Inspect the Norn project.",
+	"seer.inspect": "Inspect resolved Seer mode.",
+	pi: "Run bundled Pi for authentication, providers, and model setup.",
+	upgrade: "Upgrade the installed Norn CLI.",
+	version: "Print version/build info.",
+	help: "Show concise command help.",
+};
+
+export async function main(args: readonly string[], documentationSource: NornDocumentationSource): Promise<void> {
+	if (args[0] === "pi") {
+		await runPi([...args.slice(1)]);
+		return;
+	}
+	try {
+		await runCommand(args, documentationSource);
+	} catch (error) {
+		writeJson({ error: {
+			code: errorCode(error), message: errorMessage(error),
+			...(error instanceof NornProjectLoadError ? { isComplete: error.isComplete, diagnostics: error.diagnostics } : {}),
+		} });
+		process.exitCode = 1;
+	}
+}
+
+async function runCommand(args: readonly string[], documentationSource: NornDocumentationSource): Promise<void> {
+	if (args.length === 0) {
+		writeCliHelp([]);
+		return;
+	}
+	if (isVersionRequest(args)) {
+		writeJson(await versionInfo());
+		return;
+	}
+	const helpPath = cliHelpPath(args);
+	if (helpPath) {
+		writeCliHelp(helpPath);
+		return;
+	}
+	const command = findCliCommand(args);
+	if (!command) throw new Error(`Unknown norn command: ${args.join(" ")}`);
+	await command.execute(args.slice(command.path.length), documentationSource);
+}
+
+type CliCommand = {
+	readonly id: string;
+	readonly path: readonly string[];
+	readonly description: string;
+	readonly usage: string;
+	readonly arguments?: readonly string[];
+	readonly options?: readonly string[];
+	readonly stdin?: string;
+	readonly output: string;
+	readonly examples: readonly string[];
+	readonly hidden?: true;
+	readonly execute: (args: readonly string[], documentationSource: NornDocumentationSource) => Promise<void> | void;
+};
+
+type CliCommandInfo = Omit<CliCommand, "execute">;
+
+async function listCliCommands(args: readonly string[]): Promise<void> {
+	assertKnownFlags("commands list", args, ["--all"]);
+	const shouldIncludeHidden = args.includes("--all");
+	writeJson({ commands: COMMANDS.filter((command) => shouldIncludeHidden || !command.hidden).map(cliCommandInfo) });
+}
+
+async function inspectCliCommand(args: readonly string[]): Promise<void> {
+	const commandId = requiredArg("commands inspect", args, 0, "command id");
+	assertNoExtraArgs("commands inspect", args.slice(1));
+	const command = COMMANDS.find((candidate) => candidate.id === commandId);
+	if (!command) throw new Error(`Unknown norn command id: ${commandId}`);
+	writeJson({ command: cliCommandInfo(command) });
+}
+
+function cliCommandInfo(command: CliCommand): CliCommandInfo {
+	return {
+		id: command.id,
+		path: command.path,
+		description: command.description,
+		usage: command.usage,
+		arguments: command.arguments,
+		options: command.options,
+		stdin: command.stdin,
+		output: command.output,
+		examples: command.examples,
+		hidden: command.hidden,
+	};
+}
+
+function isVersionRequest(args: readonly string[]): boolean {
+	return args.length === 1 && (args[0] === "--version" || args[0] === "-v");
+}
+
+function cliHelpPath(args: readonly string[]): readonly string[] | undefined {
+	if (args[0] === "help") return args.slice(1);
+	if (!args.includes("--help") && !args.includes("-h")) return undefined;
+	return args.filter((arg) => arg !== "--help" && arg !== "-h");
+}
+
+function writeCliHelp(path: readonly string[]): void {
+	const command = findExactCliCommand(path);
+	if (command) {
+		process.stdout.write(renderCommandHelp(command));
+		return;
+	}
+	const groupCommands = sortedCommandsForHelp(visibleCommands().filter((candidate) => path.length === 0 || startsWithPath(candidate.path, path)));
+	if (groupCommands.length === 0) throw new Error(`Unknown norn help topic: ${path.join(" ")}`);
+	process.stdout.write(renderGroupHelp(path, groupCommands));
+}
+
+function renderGroupHelp(path: readonly string[], commands: readonly CliCommand[]): string {
+	return [
+		"Norn",
+		"",
+		CLI_DESCRIPTION,
+		"",
+		"Usage:",
+		...groupHelpUsage(path).map((line) => `  ${line}`),
+		"",
+		"Commands:",
+		renderCommandSummary(commands),
+		"",
+		"Machine-readable metadata:",
+		"  norn commands list",
+		"  norn commands inspect <command-id>",
+		"",
+	].join("\n");
+}
+
+function renderCommandHelp(command: CliCommand): string {
+	return [
+		commandHumanSummary(command),
+		"",
+		"Usage:",
+		`  ${command.usage}`,
+		"",
+		"Description:",
+		`  ${command.description}`,
+		...(command.arguments ? helpSection("Arguments", command.arguments) : []),
+		...(command.options ? helpSection("Options", command.options) : []),
+		...(command.stdin ? ["", "Stdin:", `  ${command.stdin}`] : []),
+		"",
+		"Output:",
+		`  ${command.output}`,
+		...helpSection("Examples", command.examples),
+		"",
+	].join("\n");
+}
+
+function renderCommandSummary(commands: readonly CliCommand[]): string {
+	const commandNames = commands.map((command) => command.path.join(" "));
+	const width = Math.max(...commandNames.map((name) => name.length));
+	return commands.map((command, index) => `  ${commandNames[index].padEnd(width)}  ${commandHumanSummary(command)}`).join("\n");
+}
+
+function helpSection(title: string, lines: readonly string[]): readonly string[] {
+	return ["", `${title}:`, ...lines.map((line) => `  ${line}`)];
+}
+
+function groupHelpUsage(path: readonly string[]): readonly string[] {
+	if (path.length === 0) return ["norn <command> [args]", "norn help <command>", "norn --version"];
+	const prefix = `norn ${path.join(" ")}`;
+	return [`${prefix} <command> [args]`, `norn help ${path.join(" ")} <command>`, "norn --version"];
+}
+
+function findCliCommand(args: readonly string[]): CliCommand | undefined {
+	return sortedCommandsByPathLength(COMMANDS).find((command) => startsWithPath(args, command.path));
+}
+
+function findExactCliCommand(path: readonly string[]): CliCommand | undefined {
+	return COMMANDS.find((command) => command.path.length === path.length && startsWithPath(command.path, path));
+}
+
+function sortedCommandsByPathLength(commands: readonly CliCommand[]): readonly CliCommand[] {
+	return [...commands].sort((left, right) => right.path.length - left.path.length);
+}
+
+function sortedCommandsForHelp(commands: readonly CliCommand[]): readonly CliCommand[] {
+	return [...commands].sort((left, right) => commandHelpOrder(left) - commandHelpOrder(right));
+}
+
+function commandHelpOrder(command: CliCommand): number {
+	const index = HELP_COMMAND_ORDER.indexOf(command.id);
+	return index === -1 ? HELP_COMMAND_ORDER.length : index;
+}
+
+function commandHumanSummary(command: CliCommand): string {
+	return HUMAN_COMMAND_SUMMARIES[command.id] ?? command.description;
+}
+
+function visibleCommands(): readonly CliCommand[] {
+	return COMMANDS.filter((command) => !command.hidden);
+}
+
+function startsWithPath(value: readonly string[], path: readonly string[]): boolean {
+	return path.every((segment, index) => value[index] === segment);
+}
+
+async function resolveCliDocumentation(source: NornDocumentationSource) {
+	return resolveNornDocumentation({
+		source,
+		build: { ...NORN_BUILD_INFO, version: await readPackageVersion() },
+		cacheRoot: resolveDocumentationCacheRoot({ platform: process.platform, home: homedir(), environment: process.env }),
+	});
+}
+
+async function versionInfo(): Promise<{ readonly version: string; readonly build: NornBuildInfo }> {
+	return { version: await readPackageVersion(), build: NORN_BUILD_INFO };
+}
+
+async function readPackageVersion(): Promise<string> {
+	try {
+		const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown };
+		if (typeof packageJson.version !== "string") throw new Error("Invalid Norn package version");
+		return packageJson.version;
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return NORN_BUILD_INFO.version;
+		throw error;
+	}
+}
+
+async function upgradeNorn(args: readonly string[]): Promise<void> {
+	assertKnownFlags("upgrade", args, ["--dry-run"]);
+	const dryRun = args.includes("--dry-run");
+	const currentVersion = await readPackageVersion();
+	const build = NORN_BUILD_INFO;
+	if (build.kind !== "github-release-binary") {
+		writeJson({ upgrade: unsupportedUpgrade(build, currentVersion, build.upgrade.reason) });
+		return;
+	}
+	writeJson({ upgrade: await upgradeGithubReleaseBinary(build, currentVersion, dryRun) });
+}
+
+function unsupportedUpgrade(build: NornBuildInfo, currentVersion: string, reason: string): Record<string, unknown> {
+	return {
+		supported: false,
+		kind: build.kind,
+		currentVersion,
+		buildVersion: build.version,
+		reason,
+	};
+}
+
+async function upgradeGithubReleaseBinary(build: NornGithubReleaseBinaryBuildInfo, currentVersion: string, dryRun: boolean): Promise<Record<string, unknown>> {
+	const plan = githubReleaseBinaryUpgradePlan(build, currentVersion, dryRun);
+	if (dryRun) return { ...plan, status: "planned" };
+	if (process.platform === "win32") return unsupportedUpgrade(build, currentVersion, "Replacing a running Windows executable is not supported yet.");
+	const binary = await downloadReleaseAsset(plan.downloadUrl);
+	const checksumText = await downloadReleaseText(plan.checksumUrl);
+	const expectedChecksum = parseSha256Checksum(checksumText, build.checksumAssetName);
+	const actualChecksum = createHash("sha256").update(Buffer.from(binary)).digest("hex");
+	if (actualChecksum !== expectedChecksum) throw new Error(`Downloaded Norn binary checksum mismatch: expected ${expectedChecksum}, got ${actualChecksum}`);
+	const tempPath = join(dirname(plan.targetPath), `.norn-upgrade-${process.pid}-${build.assetName}`);
+	try {
+		await writeFile(tempPath, binary);
+		await chmod(tempPath, 0o755);
+		await rename(tempPath, plan.targetPath);
+	} catch (error) {
+		await rm(tempPath, { force: true });
+		throw error;
+	}
+	return { ...plan, status: "completed", checksum: actualChecksum };
+}
+
+function githubReleaseBinaryUpgradePlan(build: NornGithubReleaseBinaryBuildInfo, currentVersion: string, dryRun: boolean): {
+	readonly supported: true;
+	readonly kind: "github-release-binary";
+	readonly dryRun: boolean;
+	readonly currentVersion: string;
+	readonly buildVersion: string;
+	readonly repository: string;
+	readonly releaseTag: string;
+	readonly assetName: string;
+	readonly checksumAssetName: string;
+	readonly downloadUrl: string;
+	readonly checksumUrl: string;
+	readonly targetPath: string;
+} {
+	return {
+		supported: true,
+		kind: build.kind,
+		dryRun,
+		currentVersion,
+		buildVersion: build.version,
+		repository: build.repository,
+		releaseTag: build.releaseTag,
+		assetName: build.assetName,
+		checksumAssetName: build.checksumAssetName,
+		downloadUrl: githubReleaseDownloadUrl(build, build.assetName),
+		checksumUrl: githubReleaseDownloadUrl(build, build.checksumAssetName),
+		targetPath: process.execPath,
+	};
+}
+
+function githubReleaseDownloadUrl(build: NornGithubReleaseBinaryBuildInfo, assetName: string): string {
+	return `https://github.com/${build.repository}/releases/download/${build.releaseTag}/${assetName}`;
+}
+
+async function downloadReleaseAsset(url: string): Promise<Uint8Array> {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download Norn release asset: ${url} returned ${response.status}`);
+	return new Uint8Array(await response.arrayBuffer());
+}
+
+async function downloadReleaseText(url: string): Promise<string> {
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to download Norn release metadata: ${url} returned ${response.status}`);
+	return response.text();
+}
+
+function parseSha256Checksum(text: string, checksumAssetName: string): string {
+	const checksum = text.trim().split(/\s+/)[0] ?? "";
+	if (!/^[a-f0-9]{64}$/i.test(checksum)) throw new Error(`Invalid Norn checksum asset: ${checksumAssetName}`);
+	return checksum.toLowerCase();
+}
+
+function requiredArg(command: string, args: readonly string[], index: number, label: string): string {
+	const value = args[index];
+	if (!value) throw new Error(`Missing ${label} for ${command}`);
+	return value;
+}
+
+function assertNoExtraArgs(command: string, args: readonly string[]): void {
+	if (args.length > 0) throw new Error(`${command} does not accept CLI arguments: ${args.join(" ")}`);
+}
+
+function assertKnownFlags(command: string, args: readonly string[], flags: readonly string[]): void {
+	const allowedFlags = new Set(flags);
+	const unsupportedFlags = args.filter((arg) => !allowedFlags.has(arg));
+	if (unsupportedFlags.length > 0) throw new Error(`${command} has unsupported flags or arguments: ${unsupportedFlags.join(" ")}`);
+}
+
+async function listWorkflows(args: readonly string[]): Promise<void> {
+	assertKnownFlags("workflows list", args, ["--entrypoints", "--all"]);
+	const entrypointsOnly = workflowListEntrypointsOnly(args);
+	const { workflows, isComplete, diagnostics } = await discoverNornProject(process.cwd());
+	writeJson({ workflows: entrypointsOnly ? workflows.filter(workflow => workflow.isEntrypoint) : workflows, isComplete, diagnostics });
+}
+
+async function inspectWorkflow(workflowId: string): Promise<void> {
+	writeJson(await inspectNornWorkflow({ cwd: process.cwd(), workflowId }));
+}
+
+function workflowListEntrypointsOnly(args: readonly string[]): boolean {
+	const entrypoints = args.includes("--entrypoints");
+	const all = args.includes("--all");
+	if (entrypoints && all) throw new Error("Use either --entrypoints or --all, not both");
+	return !all;
+}
+
+async function initProject(): Promise<void> {
+	const projectRoot = process.cwd();
+	const projectPath = resolve(projectRoot, NORN_PROJECT_FILE_NAME);
+	if (await isFile(projectPath)) throw new Error(`Norn project already exists: ${projectPath}`);
+	await mkdir(resolve(projectRoot, RUNS_ROOT), { recursive: true });
+	await writeFile(projectPath, `${JSON.stringify({ version: 1, plugins: [], includes: [], config: {} }, null, 2)}\n`, "utf8");
+	await ensureGitignoreExcludesRunState(projectRoot);
+	writeJson({ project: { path: projectPath, root: projectRoot, runsRoot: resolve(projectRoot, RUNS_ROOT) } });
+}
+
+async function listCurrentProjectRuns(): Promise<NornRunInfo[]> {
+	const project = await findNornProject(process.cwd());
+	return listRuns(project.projectRoot);
+}
+
+async function inspectProject(): Promise<void> {
+	const { project, isComplete, diagnostics } = await discoverNornProject(process.cwd());
+	writeJson({ project, isComplete, diagnostics });
+}
+
+async function inspectSeerMode(): Promise<void> {
+	const project = await findNornProject(process.cwd());
+	writeJson({ seerMode: project.seerMode ?? null });
+}
+
+async function startRun(workflowId: string, args: readonly string[]): Promise<void> {
+	assertNoStructuredInputArgs("runs start", args);
+	const project = await loadNornProject(process.cwd());
+	const workflow = project.registry.workflowById(workflowId);
+	if (!workflow) throw new Error(`Unknown workflow: ${workflowId}`);
+	const input = parseStartRunInput(await readStdinJson());
+	const params = workflow.params.parse(input.params ?? {});
+	const configOverride = input.config;
+	const id = randomUUID();
+	const name = generateRunName(new Set((await listRuns(project.projectRoot)).map((run) => run.name)));
+	const runRoot = resolve(project.projectRoot, RUNS_ROOT, id);
+	await mkdir(runRoot, { recursive: true });
+	const createdAt = new Date().toISOString();
+	await writeRunLaunchRequest(runRoot, { version: 1, type: "run", id, name, workflowId, params, configOverride, createdAt });
+	await startDetachedExecuteRun(id, project.projectRoot);
+	writeJson({ run: startedRunInfo({ id, name, workflow, runRoot, createdAt }) });
+}
+
+async function resumeRun(run: string, args: readonly string[]): Promise<void> {
+	assertNoStructuredInputArgs("runs resume", args);
+	const project = await loadNornProject(process.cwd());
+	const runRoot = await resolveRunRoot(project.projectRoot, run);
+	const input = parseResumeRunInput(await readStdinJson());
+	const lease = await NornRunLease.acquire(runRoot);
+	let request: NornRunResumeRequest;
+	try {
+		const runInfo = await getRunInfo(runRoot);
+		const params = await parseResumeParams(runInfo, input.params);
+		request = { version: 1, type: "resume", id: runInfo.id, requestId: randomUUID(), params, createdAt: new Date().toISOString() };
+		await writeRunResumeRequest(runRoot, request);
+	} finally {
+		await lease.release();
+	}
+	try {
+		await startDetachedExecuteRun(request.id, project.projectRoot);
+	} catch (error) {
+		await removeResumeRequest({ runRoot, request });
+		throw error;
+	}
+	writeJson({ run: await getRunInfo(runRoot) });
+}
+
+async function parseResumeParams(runInfo: NornRunInfo, params: unknown): Promise<unknown> {
+	if (runInfo.status === "interrupted") {
+		if (params === undefined) throw new Error(`Interrupted workflow resume requires params: ${runInfo.name}`);
+		if (!runInfo.currentWorkflowId) throw new Error(`Run has no current workflow: ${runInfo.name}`);
+		const project = await loadNornProject(process.cwd());
+		const workflow = project.registry.workflowById(runInfo.currentWorkflowId);
+		if (!workflow) throw new Error(`Unknown workflow for resumed run: ${runInfo.currentWorkflowId}`);
+		workflow.params.parse(mergeInterruptedWorkflowParams(runInfo.interruption?.params, params, runInfo.interruption?.fields));
+		return params;
+	}
+	if (runInfo.status === "pendingResume") {
+		if (params !== undefined) throw new Error(`Pending-resume workflows do not accept params: ${runInfo.name}`);
+		return undefined;
+	}
+	throw new Error(`Run must be rolled back before resuming: ${runInfo.name}`);
+}
+
+async function waitRun(run: string): Promise<void> {
+	const project = await findNornProject(process.cwd());
+	writeJson({ run: await waitForInactiveRun(project.projectRoot, run) });
+}
+
+async function waitForInactiveRun(projectRoot: string, run: string): Promise<NornRunInfo> {
+	let runRoot: string | undefined;
+	while (true) {
+		runRoot ??= await resolveWaitableRunRoot(projectRoot, run);
+		try {
+			const runInfo = await readRunInspection(runRoot);
+			if (runInfo.status !== "running" || runInfo.health === "unhealthy") return runInfo;
+		} catch (error) {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		}
+		await delay(RUN_WAIT_INTERVAL_MS);
+	}
+}
+
+async function resolveWaitableRunRoot(sessionCwd: string, run: string): Promise<string> {
+	try {
+		return await resolveRunRoot(sessionCwd, run);
+	} catch (error) {
+		for (const candidate of [resolve(sessionCwd, run), resolve(sessionCwd, RUNS_ROOT, run)]) {
+			if (await isDirectory(candidate)) return candidate;
+		}
+		throw error;
+	}
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function isFile(path: string): Promise<boolean> {
+	try {
+		return (await stat(path)).isFile();
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+
+async function ensureGitignoreExcludesRunState(projectRoot: string): Promise<void> {
+	const gitignorePath = resolve(projectRoot, ".gitignore");
+	const runStatePattern = ".norn/runs/";
+	let currentText = "";
+	try {
+		currentText = await readFile(gitignorePath, "utf8");
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+	}
+	if (currentText.split(/\r?\n/).includes(runStatePattern)) return;
+	const separator = currentText.length === 0 || currentText.endsWith("\n") ? "" : "\n";
+	await writeFile(gitignorePath, `${currentText}${separator}${runStatePattern}\n`, "utf8");
+}
+
+async function executeRun(runId: string): Promise<void> {
+	const abortController = new AbortController();
+	process.once("SIGTERM", () => abortController.abort(new NornRunStoppedError()));
+	process.once("SIGINT", () => abortController.abort(new NornRunStoppedError()));
+	const location = await findNornProject(process.cwd());
+	const runRoot = resolve(location.projectRoot, RUNS_ROOT, runId);
+	const request = await readOptionalRunLaunchRequest(runRoot) ?? await readRunResumeRequest(runRoot);
+	try {
+		const project = await loadNornProject(process.cwd());
+		const engine = new NornEngine({ cwd: project.projectRoot, signal: abortController.signal, gateMode: "pause", config: project.projectConfig });
+		for (const plugin of project.plugins) engine.registerPlugin(plugin);
+		if (request.type === "run") {
+			const workflow = project.registry.workflowById(request.workflowId);
+			if (!workflow) throw new Error(`Unknown workflow: ${request.workflowId}`);
+			await engine.runWorkflow(workflow, request.params, { id: request.id, name: request.name, configOverride: request.configOverride });
+		} else {
+			await engine.resumeRequestedWorkflow({ runRoot, request });
+		}
+	} finally {
+		if (request.type === "run") await rm(join(runRoot, "launch-request.json"), { force: true });
+		else await removeResumeRequest({ runRoot, request });
+	}
+}
+
+async function removeResumeRequest(input: { readonly runRoot: string; readonly request: NornRunResumeRequest }): Promise<void> {
+	const lease = await NornRunLease.acquire(input.runRoot);
+	try {
+		await clearRunResumeRequest({ ...input, lease });
+	} finally {
+		await lease.release();
+	}
+}
+
+async function rollbackRun(run: string, args: readonly string[]): Promise<void> {
+	const checkpointId = requiredArg("runs rollback", args, 0, "checkpoint id");
+	assertNoExtraArgs("runs rollback", args.slice(1));
+	const project = await findNornProject(process.cwd());
+	const runRoot = await resolveRunRoot(project.projectRoot, run);
+	const engine = new NornEngine({ cwd: project.projectRoot, gateMode: "pause" });
+	writeJson({ run: await engine.rollbackRun(runRoot, checkpointId) });
+}
+
+async function inspectRun(run: string): Promise<NornRunInfo> {
+	const project = await findNornProject(process.cwd());
+	return readRunInspection(await resolveRunRoot(project.projectRoot, run));
+}
+
+async function readRunInspection(runRoot: string): Promise<NornRunInfo> {
+	return getRunInfo(runRoot);
+}
+
+async function signalRun(run: string, signal: NodeJS.Signals): Promise<void> {
+	const project = await findNornProject(process.cwd());
+	const runRoot = await resolveRunRoot(project.projectRoot, run);
+	await terminateRun(runRoot, signal);
+	writeJson({ run: await getRunInfo(runRoot) });
+}
+
+async function deleteRun(run: string): Promise<DeletedNornRunInfo> {
+	const project = await findNornProject(process.cwd());
+	const runRoot = await resolveRunRoot(project.projectRoot, run);
+	const runInfo = await getRunInfo(runRoot);
+	if (runInfo.status === "running") throw new Error(`Stop run before deleting it: ${runInfo.name}`);
+	await rm(runRoot, { recursive: true, force: true });
+	return { id: runInfo.id, name: runInfo.name, path: runInfo.path };
+}
+
+async function terminateRun(runRoot: string, signal: NodeJS.Signals): Promise<void> {
+	const owner = await getRunLeaseOwner(runRoot);
+	if (!owner) return;
+	sendSignal(owner.processGroupId, owner.pid, signal);
+	await delay(signal === "SIGKILL" ? 250 : 1000);
+}
+
+async function writeRunLogs(run: string, options: { readonly follow: boolean }): Promise<void> {
+	const project = await findNornProject(process.cwd());
+	const runRoot = await resolveRunRoot(project.projectRoot, run);
+	let written = 0;
+	while (true) {
+		const events = await readRunEvents(runRoot);
+		for (const event of events.slice(written)) process.stdout.write(`${JSON.stringify(event)}\n`);
+		written = events.length;
+		if (!options.follow) return;
+		const info = await getRunInfo(runRoot);
+		if (info.status !== "running" && written >= events.length) return;
+		await delay(1000);
+	}
+}
+
+async function startDetachedExecuteRun(runId: string, projectRoot: string): Promise<void> {
+	const child = spawn(process.execPath, detachedExecuteRunArgs(runId), {
+		cwd: projectRoot,
+		detached: true,
+		stdio: "ignore",
+	});
+	await new Promise<void>((resolveSpawn, reject) => {
+		child.once("spawn", resolveSpawn);
+		child.once("error", reject);
+	});
+	child.unref();
+}
+
+function detachedExecuteRunArgs(runId: string): readonly string[] {
+	if (NORN_BUILD_INFO.kind === "github-release-binary") return ["execute-run", runId];
+	const scriptPath = process.argv[1];
+	return scriptPath && isAbsolute(scriptPath) && /\.(?:c?m?js|ts)$/.test(scriptPath) ? [scriptPath, "execute-run", runId] : ["execute-run", runId];
+}
+
+function startedRunInfo(input: {
+	readonly id: string;
+	readonly name: string;
+	readonly workflow: NornAnyWorkflowDeclaration;
+	readonly runRoot: string;
+	readonly createdAt: string;
+}): NornRunInfo {
+	return {
+		version: 1,
+		id: input.id,
+		name: input.name,
+		path: input.runRoot,
+		entrypointWorkflowId: input.workflow.id,
+		currentWorkflowId: input.workflow.id,
+		status: "running",
+		health: "healthy",
+		startedAt: input.createdAt,
+		updatedAt: input.createdAt,
+	};
+}
+
+async function readOptionalRunLaunchRequest(runRoot: string) {
+	try {
+		return await readRunLaunchRequest(runRoot);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+async function readRunEvents(runRoot: string): Promise<readonly Record<string, unknown>[]> {
+	try {
+		const manifest = JSON.parse(await readFile(join(runRoot, "current", "manifest.json"), "utf8")) as { events?: readonly Record<string, unknown>[] };
+		return manifest.events ?? [];
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+async function readStdinJson(): Promise<unknown | undefined> {
+	const text = await readStdin();
+	const trimmed = text.trim();
+	return trimmed.length === 0 ? undefined : JSON.parse(trimmed);
+}
+
+async function readStdin(): Promise<string> {
+	if (process.stdin.isTTY) return "";
+	return new Promise((resolvePromise, reject) => {
+		let text = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => {
+			text += chunk;
+		});
+		process.stdin.on("error", reject);
+		process.stdin.on("end", () => resolvePromise(text));
+		process.stdin.resume();
+	});
+}
+
+function parseStartRunInput(value: unknown): { readonly params?: unknown; readonly config?: unknown } {
+	if (value === undefined) return {};
+	const input = parseStructuredInputObject("runs start", value);
+	assertStructuredInputKeys("runs start", input, ["params", "config"]);
+	return { params: input.params, config: input.config };
+}
+
+function parseResumeRunInput(value: unknown): { readonly params?: unknown } {
+	if (value === undefined) return {};
+	const input = parseStructuredInputObject("runs resume", value);
+	assertStructuredInputKeys("runs resume", input, ["params"]);
+	return { params: input.params };
+}
+
+function parseStructuredInputObject(command: string, value: unknown): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${command} reads a JSON object from stdin`);
+	return value as Record<string, unknown>;
+}
+
+function assertStructuredInputKeys(command: string, input: Record<string, unknown>, allowedKeys: readonly string[]): void {
+	const allowed = new Set(allowedKeys);
+	const unexpected = Object.keys(input).filter((key) => !allowed.has(key));
+	if (unexpected.length > 0) throw new Error(`${command} stdin JSON has unsupported keys: ${unexpected.join(", ")}`);
+}
+
+function assertNoStructuredInputArgs(command: string, args: readonly string[]): void {
+	if (args.length > 0) throw new Error(`${command} reads structured input from stdin, not CLI arguments: ${args.join(" ")}`);
+}
+
+function sendSignal(processGroupId: number, pid: number, signal: NodeJS.Signals): void {
+	try {
+		if (processGroupId > 0 && process.platform !== "win32") {
+			process.kill(-processGroupId, signal);
+			return;
+		}
+	} catch (error) {
+		if (!isIgnorableSignalError(error)) throw error;
+	}
+	try {
+		process.kill(pid, signal);
+	} catch (error) {
+		if (!isIgnorableSignalError(error)) throw error;
+	}
+}
+
+function isIgnorableSignalError(error: unknown): boolean {
+	return isNodeError(error) && (error.code === "ESRCH" || error.code === "EPERM");
+}
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function errorCode(error: unknown): string {
+	if (error instanceof NornProjectLoadError) return error.code;
+	if (error instanceof SyntaxError) return "INVALID_JSON";
+	return "NORN_ERROR";
+}