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

package/dist/cli.js

@@ -0,0 +1,1032 @@
+// src/cli.ts
+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 } from "./documentation.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverNornProject, findNornProject, inspectNornWorkflow, loadNornProject, NORN_PROJECT_FILE_NAME } from "./plugin-loader.js";
+import { NornEngine } from "./internal/engine.js";
+import { errorMessage, NornProjectLoadError, NornRunStoppedError } from "./internal/errors.js";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// src/cli.ts
+import { clearRunResumeRequest, readRunLaunchRequest, readRunResumeRequest, writeRunLaunchRequest, writeRunResumeRequest } from "./internal/launch-request.js";
+import { generateRunName } from "./internal/run-names.js";
+import { getRunLeaseOwner, NornRunLease } from "./internal/run-lease.js";
+import { NornRunStore } from "./internal/run-store.js";
+import { readRunMetrics } from "./internal/metrics.js";
+import { getRunInfo, listRuns, mergeInterruptedWorkflowParams, resolveRunRoot } from "./internal/run-state.js";
+import { NORN_BUILD_INFO } from "./build-info.js";
+var RUNS_ROOT = join(".norn", "runs");
+var RUN_WAIT_INTERVAL_MS = 1e3;
+var 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.";
+var COMMANDS = [
+  {
+    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());
+    }
+  }
+];
+var 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"
+];
+var HUMAN_COMMAND_SUMMARIES = {
+  "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."
+};
+async function main(args, documentationSource) {
+  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, documentationSource) {
+  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);
+}
+async function listCliCommands(args) {
+  assertKnownFlags("commands list", args, ["--all"]);
+  const shouldIncludeHidden = args.includes("--all");
+  writeJson({ commands: COMMANDS.filter((command) => shouldIncludeHidden || !command.hidden).map(cliCommandInfo) });
+}
+async function inspectCliCommand(args) {
+  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) {
+  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) {
+  return args.length === 1 && (args[0] === "--version" || args[0] === "-v");
+}
+function cliHelpPath(args) {
+  if (args[0] === "help") return args.slice(1);
+  if (!args.includes("--help") && !args.includes("-h")) return void 0;
+  return args.filter((arg) => arg !== "--help" && arg !== "-h");
+}
+function writeCliHelp(path) {
+  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, commands) {
+  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) {
+  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) {
+  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, lines) {
+  return ["", `${title}:`, ...lines.map((line) => `  ${line}`)];
+}
+function groupHelpUsage(path) {
+  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) {
+  return sortedCommandsByPathLength(COMMANDS).find((command) => startsWithPath(args, command.path));
+}
+function findExactCliCommand(path) {
+  return COMMANDS.find((command) => command.path.length === path.length && startsWithPath(command.path, path));
+}
+function sortedCommandsByPathLength(commands) {
+  return [...commands].sort((left, right) => right.path.length - left.path.length);
+}
+function sortedCommandsForHelp(commands) {
+  return [...commands].sort((left, right) => commandHelpOrder(left) - commandHelpOrder(right));
+}
+function commandHelpOrder(command) {
+  const index = HELP_COMMAND_ORDER.indexOf(command.id);
+  return index === -1 ? HELP_COMMAND_ORDER.length : index;
+}
+function commandHumanSummary(command) {
+  return HUMAN_COMMAND_SUMMARIES[command.id] ?? command.description;
+}
+function visibleCommands() {
+  return COMMANDS.filter((command) => !command.hidden);
+}
+function startsWithPath(value, path) {
+  return path.every((segment, index) => value[index] === segment);
+}
+async function resolveCliDocumentation(source) {
+  return resolveNornDocumentation({
+    source,
+    build: { ...NORN_BUILD_INFO, version: await readPackageVersion() },
+    cacheRoot: resolveDocumentationCacheRoot({ platform: process.platform, home: homedir(), environment: process.env })
+  });
+}
+async function versionInfo() {
+  return { version: await readPackageVersion(), build: NORN_BUILD_INFO };
+}
+async function readPackageVersion() {
+  try {
+    const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    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) {
+  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, currentVersion, reason) {
+  return {
+    supported: false,
+    kind: build.kind,
+    currentVersion,
+    buildVersion: build.version,
+    reason
+  };
+}
+async function upgradeGithubReleaseBinary(build, currentVersion, dryRun) {
+  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, 493);
+    await rename(tempPath, plan.targetPath);
+  } catch (error) {
+    await rm(tempPath, { force: true });
+    throw error;
+  }
+  return { ...plan, status: "completed", checksum: actualChecksum };
+}
+function githubReleaseBinaryUpgradePlan(build, currentVersion, dryRun) {
+  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, assetName) {
+  return `https://github.com/${build.repository}/releases/download/${build.releaseTag}/${assetName}`;
+}
+async function downloadReleaseAsset(url) {
+  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) {
+  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, checksumAssetName) {
+  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, args, index, label) {
+  const value = args[index];
+  if (!value) throw new Error(`Missing ${label} for ${command}`);
+  return value;
+}
+function assertNoExtraArgs(command, args) {
+  if (args.length > 0) throw new Error(`${command} does not accept CLI arguments: ${args.join(" ")}`);
+}
+function assertKnownFlags(command, args, flags) {
+  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) {
+  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) {
+  writeJson(await inspectNornWorkflow({ cwd: process.cwd(), workflowId }));
+}
+function workflowListEntrypointsOnly(args) {
+  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() {
+  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)}
+`, "utf8");
+  await ensureGitignoreExcludesRunState(projectRoot);
+  writeJson({ project: { path: projectPath, root: projectRoot, runsRoot: resolve(projectRoot, RUNS_ROOT) } });
+}
+async function listCurrentProjectRuns() {
+  const project = await findNornProject(process.cwd());
+  return listRuns(project.projectRoot);
+}
+async function inspectProject() {
+  const { project, isComplete, diagnostics } = await discoverNornProject(process.cwd());
+  writeJson({ project, isComplete, diagnostics });
+}
+async function inspectSeerMode() {
+  const project = await findNornProject(process.cwd());
+  writeJson({ seerMode: project.seerMode ?? null });
+}
+async function startRun(workflowId, args) {
+  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 = (/* @__PURE__ */ 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, args) {
+  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;
+  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: (/* @__PURE__ */ 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, params) {
+  if (runInfo.status === "interrupted") {
+    if (params === void 0) 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 !== void 0) throw new Error(`Pending-resume workflows do not accept params: ${runInfo.name}`);
+    return void 0;
+  }
+  throw new Error(`Run must be rolled back before resuming: ${runInfo.name}`);
+}
+async function waitRun(run) {
+  const project = await findNornProject(process.cwd());
+  writeJson({ run: await waitForInactiveRun(project.projectRoot, run) });
+}
+async function waitForInactiveRun(projectRoot, run) {
+  let runRoot;
+  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, run) {
+  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) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function ensureGitignoreExcludesRunState(projectRoot) {
+  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}
+`, "utf8");
+}
+async function executeRun(runId) {
+  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) {
+  const lease = await NornRunLease.acquire(input.runRoot);
+  try {
+    await clearRunResumeRequest({ ...input, lease });
+  } finally {
+    await lease.release();
+  }
+}
+async function rollbackRun(run, args) {
+  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) {
+  const project = await findNornProject(process.cwd());
+  return readRunInspection(await resolveRunRoot(project.projectRoot, run));
+}
+async function readRunInspection(runRoot) {
+  return getRunInfo(runRoot);
+}
+async function signalRun(run, signal) {
+  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) {
+  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, signal) {
+  const owner = await getRunLeaseOwner(runRoot);
+  if (!owner) return;
+  sendSignal(owner.processGroupId, owner.pid, signal);
+  await delay(signal === "SIGKILL" ? 250 : 1e3);
+}
+async function writeRunLogs(run, options) {
+  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)}
+`);
+    written = events.length;
+    if (!options.follow) return;
+    const info = await getRunInfo(runRoot);
+    if (info.status !== "running" && written >= events.length) return;
+    await delay(1e3);
+  }
+}
+async function startDetachedExecuteRun(runId, projectRoot) {
+  const child = spawn(process.execPath, detachedExecuteRunArgs(runId), {
+    cwd: projectRoot,
+    detached: true,
+    stdio: "ignore"
+  });
+  await new Promise((resolveSpawn, reject) => {
+    child.once("spawn", resolveSpawn);
+    child.once("error", reject);
+  });
+  child.unref();
+}
+function detachedExecuteRunArgs(runId) {
+  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) {
+  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) {
+  try {
+    return await readRunLaunchRequest(runRoot);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function readRunEvents(runRoot) {
+  try {
+    const manifest = JSON.parse(await readFile(join(runRoot, "current", "manifest.json"), "utf8"));
+    return manifest.events ?? [];
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+async function readStdinJson() {
+  const text = await readStdin();
+  const trimmed = text.trim();
+  return trimmed.length === 0 ? void 0 : JSON.parse(trimmed);
+}
+async function readStdin() {
+  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) {
+  if (value === void 0) return {};
+  const input = parseStructuredInputObject("runs start", value);
+  assertStructuredInputKeys("runs start", input, ["params", "config"]);
+  return { params: input.params, config: input.config };
+}
+function parseResumeRunInput(value) {
+  if (value === void 0) return {};
+  const input = parseStructuredInputObject("runs resume", value);
+  assertStructuredInputKeys("runs resume", input, ["params"]);
+  return { params: input.params };
+}
+function parseStructuredInputObject(command, value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${command} reads a JSON object from stdin`);
+  return value;
+}
+function assertStructuredInputKeys(command, input, allowedKeys) {
+  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, args) {
+  if (args.length > 0) throw new Error(`${command} reads structured input from stdin, not CLI arguments: ${args.join(" ")}`);
+}
+function sendSignal(processGroupId, pid, signal) {
+  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) {
+  return isNodeError(error) && (error.code === "ESRCH" || error.code === "EPERM");
+}
+function writeJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+function errorCode(error) {
+  if (error instanceof NornProjectLoadError) return error.code;
+  if (error instanceof SyntaxError) return "INVALID_JSON";
+  return "NORN_ERROR";
+}
+export {
+  main
+};