@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/src/cli/commands/task.js

@@ -0,0 +1,144 @@
+import { CliUsageError, usageLine } from "../usage.js";
+const COMMON = { json: "boolean" };
+const TASK_COMMAND_SPECS = {
+    add: {
+        arity: [0, 1], stdin: "document", flags: { ...COMMON, namespace: "value", state: "value", priority: "value", needs: "repeat", parent: "value", supersedes: "repeat", relates: "repeat", body: "value", note: "value" },
+        usage: `task add <TITLE> [--namespace <ns>] [--priority 0..3]
+  [--state open|in_progress|on_hold|done|drop]
+  [--note <text>]
+  [--needs <TaskId>]... [--parent <TaskId>]
+  [--supersedes <TaskId>]... [--relates <TaskId>]...
+  [--body <text>] [--json]
+task add [--namespace <ns>] [--json] -`,
+        purpose: "Create one Task from flags or a canonical stdin document.",
+    },
+    show: { arity: [1, 1], flags: COMMON, usage: "task show <TaskId> [--json]", purpose: "Read one Task and its relationships." },
+    ls: { arity: [0, 0], flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean" }, usage: "task ls [--closed | --all] [--world] [--json]", purpose: "List Tasks in the selected scope." },
+    ready: { arity: [0, 0], flags: { ...COMMON, world: "boolean" }, usage: "task ready [--world] [--json]", purpose: "List Tasks whose dependencies are satisfied." },
+    blocked: { arity: [0, 0], flags: { ...COMMON, world: "boolean" }, usage: "task blocked [--world] [--json]", purpose: "List Tasks blocked by dependencies." },
+    tree: { arity: [1, 1], flags: { ...COMMON, full: "boolean" }, usage: "task tree <TaskId> [--full] [--json]", purpose: "Read one Task dependency tree." },
+    doctor: { arity: [0, 0], flags: COMMON, usage: "task doctor [--json]", purpose: "Inspect Task authority without repairing it." },
+    update: {
+        arity: [1, 1], flags: { ...COMMON, title: "value", body: "value", append: "value", note: "value", priority: "value", needs: "repeat", "drop-needs": "repeat", parent: "value", "no-parent": "boolean", supersedes: "repeat", "drop-supersedes": "repeat", relates: "repeat", "drop-relates": "repeat" },
+        usage: `task update <TaskId> [--title <text>] [--body <text>|- | --append <text>|-]
+  [--note <text>|-]
+  [--priority 0..3] [--needs <TaskId>]... [--drop-needs <TaskId>]...
+  [--parent <TaskId> | --no-parent]
+  [--supersedes <TaskId>]... [--drop-supersedes <TaskId>]...
+  [--relates <TaskId>]... [--drop-relates <TaskId>]... [--json]`,
+        purpose: "Apply one or more patches to a Task.",
+    },
+    start: { arity: [1, 1], flags: COMMON, usage: "task start <TaskId> [--json]", purpose: "Move one open Task into progress." },
+    stop: { arity: [1, 1], flags: COMMON, usage: "task stop <TaskId> [--json]", purpose: "Return one in-progress Task to open." },
+    hold: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task hold <TaskId>... [--json]", purpose: "Put one or more Tasks on hold." },
+    resume: { arity: [1, 1], flags: COMMON, usage: "task resume <TaskId> [--json]", purpose: "Return one held Task to open." },
+    done: { arity: [1, Number.POSITIVE_INFINITY], flags: COMMON, usage: "task done <TaskId>... [--json]", purpose: "Mark one or more Tasks done." },
+    drop: { arity: [1, Number.POSITIVE_INFINITY], flags: { ...COMMON, note: "value" }, usage: "task drop <TaskId>... [--note <text>] [--json]", purpose: "Drop one or more Tasks." },
+    namespace: { arity: [0, 1], flags: COMMON, usage: "task namespace [<namespace>] [--json]", purpose: "Read or replace the current Task namespace." },
+    compose: { arity: [0, 0], stdin: "compose", flags: COMMON, usage: "task compose [--json] -", purpose: "Apply one atomic Task graph composition from stdin." },
+};
+export function isTaskAction(value) {
+    return value !== undefined && Object.hasOwn(TASK_COMMAND_SPECS, value);
+}
+export function renderTaskHelp(action) {
+    if (action !== undefined) {
+        const spec = TASK_COMMAND_SPECS[action];
+        return `${spec.purpose}\n\n${usageLine(spec.usage)}`;
+    }
+    return [
+        "usage: keiyaku task <command> ...",
+        "",
+        "commands:",
+        ...Object.values(TASK_COMMAND_SPECS).flatMap((spec) => spec.usage.split("\n").map((line) => `  ${line}`).concat(`    ${spec.purpose}`)),
+    ].join("\n");
+}
+export function renderTaskUsage(action) {
+    return usageLine(TASK_COMMAND_SPECS[action].usage);
+}
+function setFlag(flags, name, kind, value, fail) {
+    if (flags[name] !== undefined && kind !== "repeat")
+        fail(`duplicate option: --${name}`);
+    if (kind === "boolean") {
+        flags[name] = true;
+        return;
+    }
+    if (value === undefined)
+        fail(`--${name} requires a value`);
+    if (kind === "repeat") {
+        const current = flags[name];
+        flags[name] = [...(Array.isArray(current) ? current : []), value];
+    }
+    else
+        flags[name] = value;
+}
+function scanTaskOption(input, fail) {
+    const token = input.argv[input.index], name = token.slice(2), kind = input.spec.flags[name];
+    if (kind === undefined)
+        fail(`option ${token} is not valid for task ${input.action}`);
+    const next = kind === "boolean" ? undefined : input.argv[input.index + 1];
+    if (next === "-" && input.action === "update" && (name === "body" || name === "append" || name === "note")) {
+        if (input.index + 1 !== input.argv.length - 1 || input.stdin !== undefined)
+            fail("stdin update marker '-' must be final");
+        input.flags[name] = "";
+        return { index: input.index + 1, stdin: name };
+    }
+    if (kind !== "boolean" && (next === undefined || next.startsWith("--") || next === "-"))
+        fail(`--${name} requires a value`);
+    setFlag(input.flags, name, kind, next, fail);
+    return { index: input.index + (kind === "boolean" ? 0 : 1), ...(input.stdin === undefined ? {} : { stdin: input.stdin }) };
+}
+function scanTaskArgv(action, argv, fail) {
+    const spec = TASK_COMMAND_SPECS[action], positionals = [], flags = {};
+    let stdin;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "-") {
+            if (index !== argv.length - 1 || stdin !== undefined || spec.stdin === undefined)
+                fail("stdin marker '-' is not valid here");
+            stdin = spec.stdin;
+            continue;
+        }
+        if (!token.startsWith("--")) {
+            positionals.push(token);
+            continue;
+        }
+        const scanned = scanTaskOption({ action, spec, argv, index, flags, ...(stdin === undefined ? {} : { stdin }) }, fail);
+        index = scanned.index;
+        stdin = scanned.stdin;
+    }
+    return { positionals, flags, ...(stdin === undefined ? {} : { stdin }) };
+}
+function validateUpdate(scanned, fail) {
+    const flags = scanned.flags;
+    if (flags.body !== undefined && flags.append !== undefined)
+        fail("--body and --append are mutually exclusive");
+    if (flags.parent !== undefined && flags["no-parent"] === true)
+        fail("--parent and --no-parent are mutually exclusive");
+    if (Object.keys(flags).every((name) => name === "json"))
+        fail("task update requires at least one patch option");
+}
+function validateTaskScan(action, scanned, fail) {
+    const spec = TASK_COMMAND_SPECS[action], { positionals, flags, stdin } = scanned;
+    if (positionals.length < spec.arity[0] || positionals.length > spec.arity[1])
+        fail(`task ${action} has invalid positional arguments`);
+    if (action === "add" && (stdin === "document") === (positionals.length === 1))
+        fail("task add requires either TITLE or final '-' input");
+    if (action === "add" && stdin === "document" && Object.keys(flags).some((name) => name !== "json" && name !== "namespace"))
+        fail("task add document input owns its creation fields");
+    if (action === "compose" && stdin !== "compose")
+        fail("task compose requires final '-' input");
+    if (action === "ls" && flags.closed === true && flags.all === true)
+        fail("--closed and --all are mutually exclusive");
+    if (action === "update")
+        validateUpdate(scanned, fail);
+}
+export function parseTaskCommand(argv) {
+    const candidate = argv[0];
+    if (!isTaskAction(candidate))
+        throw new CliUsageError(`unknown task command: ${candidate ?? ""}`, renderTaskHelp());
+    const action = candidate;
+    const fail = (message) => { throw new CliUsageError(message, renderTaskUsage(action)); };
+    const scanned = scanTaskArgv(action, argv, fail);
+    validateTaskScan(action, scanned, fail);
+    return { command: "task", action, output: scanned.flags.json === true ? "json" : "text", ...scanned };
+}

package/build/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/src/cli/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./main.js";
+process.exitCode = await main();

package/build/src/cli/invoke.d.ts

@@ -0,0 +1,17 @@
+import { type Settings } from "../index.js";
+import { type AkumaInvocationResult } from "./commands/akuma-invoke.js";
+import { type InstallInvocationResult } from "./commands/install.js";
+import { type TaskInvocationResult } from "./commands/task-invoke.js";
+import { type ParsedExecution } from "./parse.js";
+import type { InvocationResult } from "./result.js";
+export type { AcceptedFact, DiffUnavailable, InvocationResult, Lag } from "./result.js";
+type InvokeRuntime = Readonly<{
+    cwd?: string;
+    environment?: NodeJS.ProcessEnv;
+    readStdin?: () => string;
+}>;
+export type SettingsInvocationResult = Readonly<{
+    kind: "settings";
+    value: Settings;
+}>;
+export declare function invoke(invocation: ParsedExecution, runtime?: InvokeRuntime): Promise<InvocationResult | TaskInvocationResult | AkumaInvocationResult | SettingsInvocationResult | InstallInvocationResult>;

package/build/src/cli/invoke.js

@@ -0,0 +1,265 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { gatesFrom, Keiyaku, NoGitWorldError, Repo, settings, SettingsError, worktreeHooksFrom } from "../index.js";
+import { kanshi, selectKanshi } from "../kanshi/index.js";
+import { resolveActor } from "./actor.js";
+import { resultFromMutationCall } from "./accepted.js";
+import { amendFromCommand } from "./commands/amend.js";
+import { invokeAkuma, invokeAkumaStatus } from "./commands/akuma-invoke.js";
+import { isParsedAkumaCommand } from "./commands/akuma.js";
+import { bindFromCommand } from "./commands/bind.js";
+import { installHarnesses } from "./commands/install.js";
+import { invokeTask } from "./commands/task-invoke.js";
+import { CliUsageError, renderCommandUsage } from "./parse.js";
+import { contractFromInput, resolveContextualContract, resolveKanshiContract } from "./selectors.js";
+function settingsAt(root, environment) {
+    const home = environment.KEIYAKU_HOME?.trim();
+    return settings({ root, ...(home === undefined || home.length === 0 ? {} : { home }) });
+}
+function selectedGates(value, name) {
+    try {
+        return gatesFrom({ settings: value, ...(name === undefined ? {} : { name }) });
+    }
+    catch (error) {
+        if (error instanceof SettingsError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+}
+function selectedHooks(value) {
+    try {
+        return worktreeHooksFrom({ settings: value });
+    }
+    catch (error) {
+        if (error instanceof SettingsError)
+            throw new CliUsageError(error.message);
+        throw error;
+    }
+}
+function actorFromEdge(actor, environment) {
+    let resolved;
+    try {
+        resolved = resolveActor({ env: environment, ...(actor === undefined ? {} : { actor }) });
+    }
+    catch (error) {
+        throw new CliUsageError(error instanceof Error ? error.message : String(error));
+    }
+    return resolved;
+}
+function repoAt(coordinate) {
+    return coordinate === undefined ? Repo.at() : Repo.at({ path: coordinate });
+}
+async function selectContract(repo, selector, scope) {
+    if (selector !== undefined && !selector.startsWith("@"))
+        return contractFromInput(repo, selector);
+    const id = resolveContextualContract(await Keiyaku.list({ repo }), selector, scope);
+    return contractFromInput(repo, id);
+}
+async function invokeBind(parsed, repo, edge, configuration, hooks) {
+    const markdown = edge.readStdin();
+    const gates = selectedGates(configuration, parsed.gates);
+    const actor = actorFromEdge(parsed.actor, edge.environment);
+    return resultFromMutationCall("bind", () => bindFromCommand({
+        command: parsed,
+        repo,
+        markdown,
+        gates,
+        ...(actor === undefined ? {} : { actor }),
+        hooks,
+    }), {
+        project: (result) => {
+            const bound = result.facts.find((fact) => fact.kind === "bind");
+            if (bound === undefined || bound.kind !== "bind")
+                throw new Error("accepted bind is missing its bind fact");
+            return { target: bound.data.coordinates.target ?? null };
+        },
+    });
+}
+function unavailableDiff(delivery) {
+    return {
+        reason: "git-unavailable",
+        snapshotId: delivery.snapshotId,
+        changeId: delivery.changeId,
+    };
+}
+async function invokeDeliver(parsed, seat) {
+    return resultFromMutationCall("deliver", () => seat.contract.deliver({
+        ...(seat.actor === undefined ? {} : { actor: seat.actor }),
+        ...(parsed.message === undefined ? {} : { message: parsed.message }),
+        hooks: seat.hooks,
+    }), {
+        coordinate: seat.id,
+        project: (result) => ({
+            obligations: {
+                ...(result.value.verification === undefined ? {} : { verification: result.value.verification }),
+                ...(result.value.placement === undefined ? {} : { placement: result.value.placement }),
+                ...(result.value.leak === undefined ? {} : { leak: result.value.leak }),
+            },
+        }),
+    });
+}
+async function invokeReview(parsed, seat, readStdin) {
+    const summary = parsed.summaryFromStdin === true ? readStdin() : parsed.summary;
+    return resultFromMutationCall("review", () => seat.contract.review({
+        verdict: parsed.verdict,
+        ...(seat.actor === undefined ? {} : { actor: seat.actor }),
+        ...(summary === undefined ? {} : { summary }),
+        hooks: seat.hooks,
+    }), {
+        coordinate: seat.id,
+        project: (result) => ({
+            obligations: result.value.placement === undefined ? {} : { placement: result.value.placement },
+        }),
+    });
+}
+async function invokeAudit(parsed, seat) {
+    const delivery = parsed.showDiffBody ? await seat.contract.delivery() : null;
+    return resultFromMutationCall("audit", () => seat.contract.audit({ ...(seat.actor === undefined ? {} : { actor: seat.actor }), hooks: seat.hooks }), {
+        coordinate: seat.id,
+        project: async (result) => {
+            let renderedDiff;
+            if (parsed.showDiffBody && delivery !== null) {
+                const diff = await delivery.diff();
+                renderedDiff = diff === null ? unavailableDiff(delivery) : diff;
+            }
+            return {
+                report: result.value,
+                ...(renderedDiff === undefined ? {} : { diff: renderedDiff }),
+            };
+        },
+    });
+}
+async function invokeExisting({ parsed, repo, edge, scope, configuration, hooks }) {
+    const { id, contract } = await selectContract(repo, parsed.contract, scope);
+    const actor = actorFromEdge(parsed.actor, edge.environment);
+    const seat = { contract, id, ...(actor === undefined ? {} : { actor }), hooks };
+    switch (parsed.command) {
+        case "amend": {
+            const markdown = edge.readStdin();
+            const gates = parsed.gates === undefined
+                ? undefined
+                : selectedGates(configuration, parsed.gates);
+            return resultFromMutationCall("amend", () => amendFromCommand({ command: parsed, repo, contract, markdown, gates, ...(actor === undefined ? {} : { actor }), hooks }), { coordinate: id });
+        }
+        case "deliver":
+            return invokeDeliver(parsed, seat);
+        case "review":
+            return invokeReview(parsed, seat, edge.readStdin);
+        case "arc": {
+            const markdown = edge.readStdin();
+            return resultFromMutationCall("arc", () => contract.arc({
+                markdown,
+                ...(actor === undefined ? {} : { actor }),
+                hooks,
+            }), { coordinate: id });
+        }
+        case "abandon":
+            return resultFromMutationCall("abandon", () => contract.abandon({
+                ...(actor === undefined ? {} : { actor }),
+                ...(parsed.note === undefined ? {} : { note: parsed.note }),
+                hooks,
+            }), { coordinate: id });
+        case "audit":
+            return invokeAudit(parsed, seat);
+        default:
+            return parsed;
+    }
+}
+async function invokeAkumaCommand(parsed, path, configuration, edge) {
+    if (parsed.command === "call" && parsed.contract !== undefined) {
+        const selected = contractFromInput(repoAt(path), parsed.contract);
+        return await invokeAkuma(parsed, {
+            path,
+            settings: configuration,
+            contract: selected.contract,
+            readStdin: edge.readStdin,
+        });
+    }
+    if (parsed.command === "fork") {
+        let repo;
+        try {
+            repo = repoAt(path);
+        }
+        catch (error) {
+            if (!(error instanceof NoGitWorldError))
+                throw error;
+        }
+        return await invokeAkuma(parsed, {
+            path,
+            settings: configuration,
+            ...(repo === undefined ? {} : { repo }),
+            readStdin: edge.readStdin,
+        });
+    }
+    return await invokeAkuma(parsed, { path, settings: configuration, readStdin: edge.readStdin });
+}
+async function invokeParsed(invocation, runtime) {
+    const coordinate = invocation.cwd ?? runtime.cwd;
+    const edge = {
+        environment: runtime.environment ?? process.env,
+        readStdin: runtime.readStdin ?? (() => readFileSync(0, "utf8")),
+    };
+    const parsed = invocation.command;
+    if (parsed.command === "settings") {
+        return { kind: "settings", value: settingsAt(resolve(coordinate ?? "."), edge.environment) };
+    }
+    if (parsed.command === "task") {
+        try {
+            return await invokeTask(parsed, { ...(coordinate === undefined ? {} : { path: coordinate }), readStdin: edge.readStdin });
+        }
+        catch (error) {
+            if (error instanceof TypeError)
+                throw new CliUsageError(error.message);
+            throw error;
+        }
+    }
+    if (isParsedAkumaCommand(parsed)) {
+        const path = resolve(coordinate ?? ".");
+        const configuration = settingsAt(path, edge.environment);
+        return await invokeAkumaCommand(parsed, path, configuration, edge);
+    }
+    if (parsed.command === "status") {
+        if (parsed.akuma === true) {
+            return invokeAkumaStatus(coordinate ?? ".", parsed.contract);
+        }
+        const report = await kanshi(coordinate === undefined ? {} : { path: coordinate });
+        if (parsed.contract === undefined)
+            return { kind: "status", report, selection: "world" };
+        const contract = resolveKanshiContract(report, parsed.contract);
+        return { kind: "status", report: selectKanshi({ report, contract }), selection: "contract" };
+    }
+    const repo = repoAt(coordinate);
+    const scope = coordinate ?? repo.root;
+    const configuration = settingsAt(repo.root, edge.environment);
+    const hooks = selectedHooks(configuration);
+    switch (parsed.command) {
+        case "reconcile": {
+            if (parsed.contract === undefined) {
+                return { kind: "observation", command: "reconcile", ...await repo.reconcile({ hooks, retryHooks: parsed.retryHooks }) };
+            }
+            const { contract } = await selectContract(repo, parsed.contract, scope);
+            return { kind: "observation", command: "reconcile", ...await contract.reconcile({ hooks, retryHooks: parsed.retryHooks }) };
+        }
+        case "bind":
+            return invokeBind(parsed, repo, edge, configuration, hooks);
+        default:
+            return invokeExisting({ parsed, repo, edge, scope, configuration, hooks });
+    }
+}
+async function invokeInstall(command, runtime) {
+    return installHarnesses(command.harnesses, runtime.environment ?? process.env);
+}
+export async function invoke(invocation, runtime = {}) {
+    try {
+        const command = invocation.command;
+        if (command.command === "install")
+            return await invokeInstall(command, runtime);
+        return await invokeParsed({ ...(invocation.cwd === undefined ? {} : { cwd: invocation.cwd }), command }, runtime);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError && error.projection === undefined) {
+            throw new CliUsageError(error.diagnostic, renderCommandUsage(invocation.command));
+        }
+        throw error;
+    }
+}

package/build/src/cli/main.d.ts

@@ -0,0 +1 @@
+export declare function main(argv?: readonly string[]): Promise<number>;

package/build/src/cli/main.js

@@ -0,0 +1,79 @@
+import { CliUsageError, parseArgv, renderContractHelp, renderRootHelp, } from "./parse.js";
+import { renderText } from "./render/text.js";
+import { renderTaskIncompleteDiagnostic, renderTaskText, taskExitCode } from "./render/task.js";
+import { akumaExitCode, renderAkumaJson, renderAkumaText } from "./render/akuma.js";
+import { isParsedAkumaCommand, renderAkumaHelp } from "./commands/akuma.js";
+import { installExitCode, renderInstallHelp, renderInstallText } from "./commands/install.js";
+import { renderTaskHelp } from "./commands/task.js";
+import { renderSettingsText, settingsJsonValue } from "./render/settings.js";
+function writeTask(command, result) {
+    if (command.output === "json")
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    else if (command.action === "compose" && typeof result === "object" && result !== null && "kind" in result && result.kind === "incomplete") {
+        const diagnostic = renderTaskIncompleteDiagnostic(result);
+        if (diagnostic.length > 0)
+            process.stderr.write(`${diagnostic}\n`);
+        process.stdout.write(result.draft);
+    }
+    else
+        process.stdout.write(`${renderTaskText(command, result)}\n`);
+    return taskExitCode(result);
+}
+function writeAkuma(command, result) {
+    const output = command.output === "json" ? renderAkumaJson(command, result) : renderAkumaText(command, result);
+    const rawLast = command.command === "history" && command.last && command.output === "text";
+    process.stdout.write(rawLast ? output : `${output}\n`);
+    return akumaExitCode(result);
+}
+function renderHelp(coordinate) {
+    switch (coordinate.kind) {
+        case "root": return renderRootHelp();
+        case "contract": return renderContractHelp(coordinate.command);
+        case "task": return renderTaskHelp(coordinate.action);
+        case "install": return renderInstallHelp();
+        case "akuma": return renderAkumaHelp(coordinate.action);
+    }
+}
+function writeResult(command, result) {
+    if (command.command === "install") {
+        const value = result;
+        process.stdout.write(`${command.output === "json" ? JSON.stringify(value) : renderInstallText(value)}\n`);
+        return installExitCode(value);
+    }
+    if (command.command === "task")
+        return writeTask(command, result);
+    if (command.command === "settings") {
+        const value = result.value;
+        process.stdout.write(`${command.output === "json" ? JSON.stringify(settingsJsonValue(value)) : renderSettingsText(value)}\n`);
+        return 0;
+    }
+    if (isParsedAkumaCommand(command)
+        || (typeof result === "object" && result !== null && "kind" in result && result.kind === "akuma")) {
+        return writeAkuma(command, result);
+    }
+    const contractResult = result;
+    const output = command.output === "json"
+        ? JSON.stringify(contractResult.kind === "status" ? contractResult.report : contractResult)
+        : renderText(contractResult, {
+            columns: process.stdout.isTTY === true && Number.isInteger(process.stdout.columns) ? process.stdout.columns : 80,
+            color: process.stdout.isTTY === true && process.env.NO_COLOR === undefined,
+        });
+    process.stdout.write(`${output}\n`);
+    return contractResult.kind === "refused" ? 1 : contractResult.kind === "retry" ? 2 : 0;
+}
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        const parsed = parseArgv(argv);
+        if ("help" in parsed) {
+            process.stdout.write(`${renderHelp(parsed.help)}\n`);
+            return 0;
+        }
+        const { invoke } = await import("./invoke.js");
+        const result = await invoke(parsed, { cwd: process.cwd() });
+        return writeResult(parsed.command, result);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return error instanceof CliUsageError ? 1 : 3;
+    }
+}