@claudexor/cli 3.0.4 → 3.1.1

package/dist/cli.js

@@ -7,21 +7,25 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { ArtifactStore } from "@claudexor/artifact-store";
 import { CLAUDEXOR_VERSION, noProjectRepoRoot, readTextSafe, userConfigDir } from "@claudexor/util";
 import { releaseCommand } from "./release-command.js";
-import { serveAcpBridge, serveBeltBridge, serveMcpBridge } from "./bridge-serve.js";
+import { serveBeltBridge, serveMcpBridge } from "./bridge-serve.js";
+import { dispatchAcpCommand } from "./acp-auth-command.js";
 import { initProjectConfig } from "@claudexor/config";
-import { DecisionRecord, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunTelemetry, StructuredOutputConformance, TaskContract, runOutcomeLabel, } from "@claudexor/schema";
+import { DecisionRecord, EFFORT_HINT_HELP, EffortHint, ExternalContextPolicy, ModeKind as ModeKindSchema, RoutingGoal, ControlThreadListResponse, RunTelemetry, StructuredOutputConformance, TaskContract, runOutcomeLabel, } from "@claudexor/schema";
 import { flagBool, flagStr, flagStringList, flagValues, parseArgs, requiredStringFlagError, } from "./args.js";
 import { print, printJson, printJsonLine, printUsageError, statusGlyph } from "./cli-io.js";
+import { controlProblemError, minIntError, renderCliFailure, usageError } from "./cli-error.js";
+import { handleHelpRequest } from "./command-help.js";
 import { pickResumableThread } from "./thread-select.js";
 import { KNOWN_FLAGS, VALUE_FLAGS, commandFlagScopeError, helpJson, renderHelp, } from "./command-registry.js";
 import { buildAgentCapabilityCatalog } from "./capabilities.js";
+import { aboutJson, renderAbout } from "./about-command.js";
 import { dispatchOpsCommand } from "./ops-commands.js";
 import { reviewCommand } from "./review-command.js";
 import { controlApiFetch, followRun } from "./live.js";
 import { retryCommand, runAgainCommand } from "./retry-command.js";
 import { assertCliRunParamsHaveNoInlineSecrets } from "./run-secret-scan.js";
 import { openLocalAttachment, resolveLocalAttachment, } from "./local-attachment.js";
-import { connectDaemonIfRunning, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, fetchCouncil, fetchOutcomeBanner, } from "./daemon-run.js";
+import { connectDaemonIfRunning, daemonOutcomeProblemFields, daemonOutcomeSummary, ensureDaemon, enqueueAndAwait, exitCodeForState, fetchApplyEligibility, fetchCouncil, fetchOutcomeBanner, fetchRunDetail, fetchRunOutcomeFacts, projectApplyEligibility, projectOutcomeBanner, projectRunOutcomeFacts, mergeDaemonRunOutcome, } from "./daemon-run.js";
 import { runPlanQuestionLoop } from "./plan-question-loop.js";
 import { resolveDecisionBody } from "./decision.js";
 import { primaryOutputForCli } from "./primary-output.js";
@@ -119,7 +123,7 @@ function effortHint(args) {
         return undefined;
     const parsed = EffortHint.safeParse(v);
     if (!parsed.success)
-        throw new Error(`invalid --effort '${v}' (expected low|medium|high|xhigh|max)`);
+        throw new Error(`invalid --effort '${v}' (expected a ${EFFORT_HINT_HELP})`);
     return parsed.data;
 }
 function synthesisMode(args) {
@@ -288,7 +292,12 @@ async function orchestrate(args, mode, json, forced = {}) {
         const maxUsd = floatFlag(args, "max-usd");
         paidBudget = maxUsd === undefined ? undefined : { kind: "finite", maxUsd };
         nFlag = intFlag(args, "n");
+        // Structured min-value validation (GH #28): `--n 0` is a usage field error, not a Zod dump.
+        if (nFlag !== undefined && nFlag < 1)
+            throw minIntError("n", 1);
         attemptsFlag = intFlag(args, "attempts");
+        if (attemptsFlag !== undefined && attemptsFlag < 1)
+            throw minIntError("attempts", 1);
         delegate = flagBool(args, "delegate") ? true : undefined;
         council = flagBool(args, "council") ? true : undefined;
         resolvedSynthesis = synthesisMode(args);
@@ -322,7 +331,8 @@ async function orchestrate(args, mode, json, forced = {}) {
         }
     }
     catch (err) {
-        return printUsageError(json, `claudexor: ${err instanceof Error ? err.message : String(err)}`);
+        // Projector: typed field errors / domain codes survive; a plain flag-parse Error is usage (exit 2).
+        return renderCliFailure(json, err, { defaultCategory: "usage", messagePrefix: "claudexor:" });
     }
     let tests;
     try {
@@ -350,7 +360,8 @@ async function orchestrate(args, mode, json, forced = {}) {
         });
     }
     catch (err) {
-        return printUsageError(json, `claudexor: ${err instanceof Error ? err.message : String(err)}`);
+        // Preserves the typed `inline_secret_rejected` code (never echoing the token).
+        return renderCliFailure(json, err, { defaultCategory: "usage", messagePrefix: "claudexor:" });
     }
     if (delegate && mode !== "agent") {
         return printUsageError(json, `claudexor: --delegate is an agent strategy (got mode '${mode}')`);
@@ -405,15 +416,13 @@ async function daemonRun(args, json, p) {
         ({ client, addr } = await ensureDaemon());
     }
     catch (err) {
-        if (json)
-            printJson({
-                ok: false,
-                exitCode: 1,
-                error: `claudexor: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        else
-            process.stderr.write(`claudexor: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
+        // D-7 projector: one failure envelope with message/code (never a legacy
+        // partial {ok,exitCode,error}). --json-stream stays valid NDJSON via the
+        // compact-line stream option.
+        return renderCliFailure(json || jsonStream, err, {
+            messagePrefix: "claudexor:",
+            stream: jsonStream,
+        });
     }
     // Thread continuation (W13/D10): --thread <id> targets a thread explicitly;
     // --resume picks the most recently updated one. When a threadId is present
@@ -435,28 +444,17 @@ async function daemonRun(args, json, p) {
             // another project's threads.
             const newest = pickResumableThread(list.threads, process.cwd());
             if (!newest) {
-                // Stay valid on the active output surface: NDJSON stream keeps compact
+                // D-7 projector on the active surface: NDJSON stream keeps compact
                 // lines; --json prints its one object; text goes to stderr.
-                const message = "claudexor: --resume found no threads to continue in this project";
-                if (jsonStream)
-                    printJsonLine({ ok: false, exitCode: 1, error: message });
-                else if (json)
-                    printJson({ ok: false, exitCode: 1, error: message });
-                else
-                    process.stderr.write(`${message}\n`);
-                return 1;
+                return renderCliFailure(json || jsonStream, new Error("--resume found no threads to continue in this project"), { messagePrefix: "claudexor:", stream: jsonStream });
             }
             threadId = newest.id;
         }
         catch (err) {
-            const message = `claudexor: --resume could not list threads: ${err instanceof Error ? err.message : String(err)}`;
-            if (jsonStream)
-                printJsonLine({ ok: false, exitCode: 1, error: message });
-            else if (json)
-                printJson({ ok: false, exitCode: 1, error: message });
-            else
-                process.stderr.write(`${message}\n`);
-            return 1;
+            // Flatten any cause (transport error, a malformed-threads Zod parse) into a
+            // single operational message so the exit code stays 1 and no raw Zod field
+            // dump leaks; the projector owns the envelope on every surface.
+            return renderCliFailure(json || jsonStream, new Error(`--resume could not list threads: ${err instanceof Error ? err.message : String(err)}`), { messagePrefix: "claudexor:", stream: jsonStream });
         }
     }
     let attachmentRefs;
@@ -466,15 +464,9 @@ async function daemonRun(args, json, p) {
             : undefined;
     }
     catch (err) {
-        if (json)
-            printJson({
-                ok: false,
-                exitCode: 1,
-                error: `claudexor: attachment upload failed: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        else
-            process.stderr.write(`claudexor: attachment upload failed: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
+        // D-7 projector: message/code envelope, NDJSON-safe. (Previously this branch
+        // ignored --json-stream and fell through to a stderr line.)
+        return renderCliFailure(json || jsonStream, new Error(`attachment upload failed: ${err instanceof Error ? err.message : String(err)}`), { messagePrefix: "claudexor:", stream: jsonStream });
     }
     const body = {
         prompt: p.prompt,
@@ -528,6 +520,7 @@ async function daemonRun(args, json, p) {
                     jobId: started.jobId,
                     mode: p.mode,
                     ...(started.error ? { error: started.error } : {}),
+                    ...daemonOutcomeProblemFields(started),
                 });
                 return exitCodeForState(started.status);
             }
@@ -542,17 +535,13 @@ async function daemonRun(args, json, p) {
             // per event via print(JSON.stringify(ev)).
             await followRun(started.runId, true);
             const final = started.jobId ? await client.status(started.jobId) : null;
-            const status = final?.state ?? started.status;
-            const out = {
-                runId: started.runId,
-                runDir: final?.runDir ?? started.runDir,
-                status: status,
-                jobId: started.jobId,
-                error: final?.error ?? started.error,
-            };
+            const out = mergeDaemonRunOutcome(started, final);
+            const status = out.status;
             const reason = daemonOutcomeSummary({ ...started, status, error: out.error });
-            const applyEligibility = await fetchApplyEligibility(addr, started.runId);
-            const outcomeBanner = await fetchOutcomeBanner(addr, started.runId);
+            // ONE GET /runs/:id feeds all three terminal projections (INV-120/122).
+            const detail = await fetchRunDetail(addr, out.runId);
+            const applyEligibility = projectApplyEligibility(detail);
+            const outcomeBanner = projectOutcomeBanner(detail);
             printJsonLine({
                 frame: "run.terminal",
                 runId: out.runId,
@@ -561,11 +550,12 @@ async function daemonRun(args, json, p) {
                 jobId: out.jobId,
                 mode: p.mode,
                 ...(out.error ? { error: out.error } : {}),
+                ...daemonOutcomeProblemFields(out),
                 ...(reason ? { summary: reason } : {}),
                 ...(outcomeBanner ? { outcomeBanner } : {}),
                 ...(applyEligibility ? { applyEligibility } : {}),
             });
-            return exitCodeForState(status);
+            return exitCodeForState(status, projectRunOutcomeFacts(detail));
         }
         if (json) {
             // Pure machine surface: await the terminal outcome and print one JSON object.
@@ -574,9 +564,11 @@ async function daemonRun(args, json, p) {
             const reason = daemonOutcomeSummary(out);
             // ADD-ONLY key (bench contract keeps {runId,runDir,status}): the derived
             // apply-gate verdict, so machine callers act on truth instead of
-            // re-implying eligibility from status.
-            const applyEligibility = await fetchApplyEligibility(addr, out.runId);
-            const outcomeBanner = await fetchOutcomeBanner(addr, out.runId);
+            // re-implying eligibility from status. ONE GET /runs/:id feeds all three
+            // terminal projections (INV-120/122).
+            const detail = await fetchRunDetail(addr, out.runId);
+            const applyEligibility = projectApplyEligibility(detail);
+            const outcomeBanner = projectOutcomeBanner(detail);
             printJson({
                 runId: out.runId,
                 runDir: out.runDir,
@@ -584,11 +576,12 @@ async function daemonRun(args, json, p) {
                 jobId: out.jobId,
                 mode: p.mode,
                 ...(out.error ? { error: out.error } : {}),
+                ...daemonOutcomeProblemFields(out),
                 ...(reason ? { summary: reason } : {}),
                 ...(outcomeBanner ? { outcomeBanner } : {}),
                 ...(applyEligibility ? { applyEligibility } : {}),
             });
-            return exitCodeForState(out.status);
+            return exitCodeForState(out.status, projectRunOutcomeFacts(detail));
         }
         // Text mode: enqueue, then live-stream the run through the shared follow
         // pipeline (replay + push + interactive TTY question answering), then print
@@ -652,18 +645,15 @@ async function daemonRun(args, json, p) {
                 print(`  inspect with: claudexor inspect ${effectiveRunId}`);
             }
         }
-        return exitCodeForState(status);
+        return exitCodeForState(status, await fetchRunOutcomeFacts(addr, effectiveRunId));
     }
     catch (err) {
-        if (json)
-            printJson({
-                ok: false,
-                exitCode: 1,
-                error: `claudexor: ${err instanceof Error ? err.message : String(err)}`,
-            });
-        else
-            process.stderr.write(`claudexor: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
+        // D-7 projector: a typed control problem (code/retryable/context) survives
+        // intact; --json-stream stays valid NDJSON via the compact-line stream option.
+        return renderCliFailure(json || jsonStream, err, {
+            messagePrefix: "claudexor:",
+            stream: jsonStream,
+        });
     }
 }
 /**
@@ -692,19 +682,9 @@ async function decisionCommand(args, json) {
         const text = await res.text();
         const data = text ? JSON.parse(text) : {};
         if (!res.ok) {
-            // A typed decision rejection (e.g. revert refused: tree diverged) carries
-            // its reason in `message`; transport/gate failures use `error`. Surface
-            // whichever is present so the concrete reason is never lost behind "HTTP 409".
-            const msg = typeof data["error"] === "string"
-                ? data["error"]
-                : typeof data["message"] === "string"
-                    ? data["message"]
-                    : `decision failed (HTTP ${res.status})`;
-            if (json)
-                printJson({ accepted: false, status: "rejected", message: msg });
-            else
-                process.stderr.write(`claudexor decision: ${msg}\n`);
-            return 1;
+            // A typed decision rejection (revert_refused: tree diverged) rides through
+            // the projector with its code/retryable/bounded git-stderr context intact.
+            return renderCliFailure(json, controlProblemError(res.status, data, `decision failed (HTTP ${res.status})`), { messagePrefix: "claudexor decision:" });
         }
         if (json) {
             printJson(data);
@@ -720,8 +700,7 @@ async function decisionCommand(args, json) {
         return data["accepted"] === true ? 0 : 1;
     }
     catch (err) {
-        process.stderr.write(`claudexor decision: ${err instanceof Error ? err.message : String(err)}\n`);
-        return 1;
+        return renderCliFailure(json, err, { messagePrefix: "claudexor decision:" });
     }
 }
 /**
@@ -818,19 +797,12 @@ function listCliArtifacts(root) {
 // KNOWN_FLAGS / VALUE_FLAGS (imported above) and the per-command scope check
 // are projections of the command registry. Unknown flags FAIL LOUDLY: `--harnes
 // codex` must never silently run all harnesses.
-async function main() {
-    const args = parseArgs(process.argv.slice(2));
-    // --version / --help are standard CLI affordances, not unknown flags.
-    if (flagBool(args, "version")) {
-        process.stdout.write(`${CLI_VERSION}\n`);
-        return 0;
-    }
-    if (flagBool(args, "help")) {
-        process.stdout.write(HELP);
-        return 0;
-    }
-    const json = flagBool(args, "json");
+async function dispatch(args, json) {
     const cmd = args._[0] ?? "help";
+    // `--help` resolves the COMMAND first (QA-057): scoped usage for a known verb,
+    // global help for a bare/`help` verb, a usage error (exit 2) for a typo.
+    if (flagBool(args, "help"))
+        return handleHelpRequest(cmd, args._.length, json, CLI_VERSION);
     const unknownFlags = Object.keys(args.flags).filter((f) => !KNOWN_FLAGS.has(f));
     if (unknownFlags.length > 0) {
         const error = `claudexor: unknown flag(s): ${unknownFlags.map((f) => `--${f}`).join(", ")} (see \`claudexor help\`)`;
@@ -921,9 +893,7 @@ async function main() {
             return printUsageError(json, "usage: claudexor mcp serve");
         }
         case "acp": {
-            if (args._[1] === "serve")
-                return serveAcpBridge();
-            return printUsageError(json, "usage: claudexor acp serve");
+            return dispatchAcpCommand(args, json);
         }
         case "follow": {
             const runId = args._[1];
@@ -947,11 +917,8 @@ async function main() {
             // store, or a daemon-tracked run that started in another project.
             const resolved = await resolveRunStore(runId);
             if (!resolved) {
-                if (json)
-                    printJson({ runId, error: `no such run ${runId}` });
-                else
-                    print(`no such run ${runId}`);
-                return 1;
+                // D-7 projector: canonical envelope, run id as a per-command extra.
+                return renderCliFailure(json, new Error(`no such run ${runId}`), { extras: { runId } });
             }
             const store = resolved.store;
             const paths = store.runPaths(runId);
@@ -1090,11 +1057,10 @@ async function main() {
             }
             const rawMode = flagStr(args, "mode") ?? "apply";
             if (!["apply", "commit", "branch", "pr"].includes(rawMode)) {
-                if (json)
-                    printJson({ runId, error: `unsupported apply mode: ${rawMode}` });
-                else
-                    print(`unsupported apply mode: ${rawMode}`);
-                return 2;
+                // D-7 projector: a usage failure (exit 2) with the run id as extra.
+                return renderCliFailure(json, usageError(`unsupported apply mode: ${rawMode}`), {
+                    extras: { runId },
+                });
             }
             const { addr } = await ensureDaemon();
             const dryRun = flagBool(args, "dry-run");
@@ -1116,9 +1082,14 @@ async function main() {
             else if (!response.ok)
                 print(String(result["message"] ?? result["error"] ?? text));
             else if (dryRun)
-                print(result["ok"] === true ? "patch applies cleanly" : "patch does not apply");
+                print(result["alreadyApplied"] === true
+                    ? "already applied; nothing would change"
+                    : result["ok"] === true
+                        ? "patch applies cleanly"
+                        : "patch does not apply");
             else
                 print(`${String(result["mode"] ?? rawMode)}: applied=${String(result["applied"] ?? false)}` +
+                    (result["alreadyApplied"] === true ? " (already applied; no files changed)" : "") +
                     (typeof result["commit"] === "string"
                         ? ` commit=${result["commit"].slice(0, 8)}`
                         : "") +
@@ -1214,6 +1185,15 @@ async function main() {
             }
             return 0;
         }
+        case "about":
+            // Product identity (version + author + license + owner links, D-11).
+            // `--json` is a small stable envelope; the Swift About panel and the
+            // packed npm-manifest assertion consume the same facts.
+            if (json)
+                printJson(aboutJson(CLI_VERSION));
+            else
+                print(renderAbout(CLI_VERSION));
+            return 0;
         case "help":
             // `help --json` is the machine-readable command catalog (agents parse
             // it instead of scraping the text help).
@@ -1225,23 +1205,37 @@ async function main() {
         default:
             // Unknown command is an ERROR (exit 2), not a silent help print with
             // exit 0 — scripts must not mistake a typo'd verb for success. --json
-            // callers get the machine envelope on stdout (stdout purity contract).
+            // callers get the ONE projector envelope (with message/code shape, no
+            // longer a partial {ok,exitCode,error}); text mode prints the full help.
             if (json) {
-                printJson({
-                    ok: false,
-                    exitCode: 2,
-                    error: `claudexor: unknown command '${cmd}' (see \`claudexor help --json\`)`,
-                });
-                return 2;
+                return renderCliFailure(true, usageError(`claudexor: unknown command '${cmd}' (see \`claudexor help --json\`)`), {});
             }
             process.stderr.write(`claudexor: unknown command '${cmd}'\n\n${HELP}\n`);
             return 2;
     }
 }
+// The ONE top-level result/error projector (D-7, GH #28): any throw from any
+// command path is rendered by renderCliFailure (see cli-error.ts) into exactly
+// one JSON envelope or one stderr line, via the central category->exit-code
+// table. Commands that already print and return a code are unaffected.
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (flagBool(args, "version")) {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        return 0;
+    }
+    const json = flagBool(args, "json");
+    try {
+        return await dispatch(args, json);
+    }
+    catch (err) {
+        return renderCliFailure(json, err);
+    }
+}
 main()
     .then((code) => process.exit(code))
     .catch((err) => {
-    process.stderr.write(`claudexor: ${err instanceof Error ? err.message : String(err)}\n`);
-    process.exit(1);
+    // Last-resort projector: still emit ONE envelope if the parse threw before json was known.
+    process.exit(renderCliFailure(process.argv.includes("--json"), err));
 });
 //# sourceMappingURL=cli.js.map