@zivis/cli 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/commands/gate/index.js

@@ -0,0 +1,171 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { ApiClient, ApiError } from "@zivis/mcp/api-client";
+import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+import { requireApplicationId } from "@zivis/mcp/resolve-application-id";
+import { getCurrentGitSha } from "../../internal/git.js";
+import { parsePolicyFile, PolicyValidationError } from "../../internal/gate-policy.js";
+import { evaluateGate } from "../../internal/gate-evaluate.js";
+import { jsonEnvelope, printJson, EXIT, exitCodeForError, errorMessage } from "../../internal/cli-output.js";
+const DEFAULT_POLICY_PATH = ".zivis/policy.yaml";
+export function registerGateCommand(program) {
+    program
+        .command("gate [name]")
+        .description("evaluate a committed release/ship policy deterministically against current Zivis state")
+        .option("--file <path>", `policy file path (default: ${DEFAULT_POLICY_PATH})`)
+        .option("--app <id>", "Application id (defaults to the bound Application)")
+        .option("--model <zamId>", "ad-hoc form: assurance model key")
+        .option("--category <categoryId>", "ad-hoc form: category id to threshold")
+        .option("--min-score <0..1>", "ad-hoc form: minimum normalized score_raw")
+        .option("--min-coverage <0..1>", "ad-hoc form: minimum coverage")
+        .option("-s, --session <name>", "named session")
+        .option("--json", "emit JSON only on stdout")
+        .action(async (name, opts) => {
+        const json = !!opts.json;
+        try {
+            const { gateName, policy, policyHash } = await resolvePolicy(name, opts);
+            const config = opts.session
+                ? { ...resolveConfigFromBinding(process.cwd()), session: opts.session }
+                : resolveConfigFromBinding(process.cwd());
+            const client = new ApiClient(config);
+            const resolvedApp = requireApplicationId(opts.app, process.cwd());
+            if (!resolvedApp.ok) {
+                throw new PolicyValidationError(resolvedApp.message);
+            }
+            const applicationId = resolvedApp.id;
+            const [currentGitSha, statusResult] = await Promise.all([
+                getCurrentGitSha(process.cwd()),
+                fetchStatus(client, applicationId, policy),
+            ]);
+            let mark = null;
+            let markLookupFailed = false;
+            let markId = null;
+            let assessorVersion = null;
+            if (policy.provenance) {
+                try {
+                    const query = new URLSearchParams({ applicationId, model: policy.model });
+                    const raw = await client.get(`/api/zat/marks/latest?${query.toString()}`);
+                    markId = raw.mark_id ?? null;
+                    const methodology = raw.methodology;
+                    assessorVersion = methodology?.assessor_version ?? null;
+                    mark = {
+                        basis: raw.framework?.basis,
+                        expired: !!raw.expired,
+                        revoked: !!raw.revoked,
+                        signature: { verified: !!raw.signature?.verified },
+                    };
+                }
+                catch (err) {
+                    if (!(err instanceof ApiError && err.status === 404)) {
+                        markLookupFailed = true;
+                    }
+                }
+            }
+            const evaluation = evaluateGate({
+                policy,
+                status: statusResult,
+                mark,
+                markLookupFailed,
+                currentGitSha,
+                now: new Date(),
+            });
+            const output = jsonEnvelope("gate", {
+                gate: gateName,
+                result: evaluation.result,
+                application_id: applicationId,
+                git_sha: currentGitSha ?? null,
+                policy_hash: policyHash,
+                evaluated_at: new Date().toISOString(),
+                scoring_profile: policy.scoring_profile ?? null,
+                checks: evaluation.checks,
+                provenance: {
+                    source: policy.source,
+                    latest_mark_id: markId,
+                    basis: mark?.basis ?? null,
+                    assessor_version: assessorVersion,
+                    last_evaluated_sha: statusResult?.lastEvaluatedGitSha ?? null,
+                },
+            });
+            if (json) {
+                printJson(output);
+            }
+            else {
+                printHuman(gateName, evaluation, output);
+            }
+            process.exit(evaluation.result === "pass" ? EXIT.OK : evaluation.result === "fail" ? EXIT.POLICY_FAIL : EXIT.INVALID_OR_INDETERMINATE);
+        }
+        catch (err) {
+            const code = err instanceof PolicyValidationError ? EXIT.INVALID_OR_INDETERMINATE : exitCodeForError(err);
+            const message = errorMessage(err);
+            if (json) {
+                printJson(jsonEnvelope("gate", { gate: name ?? null, result: "indeterminate", error: message }));
+            }
+            else {
+                console.error(`zivis gate: ${message}`);
+            }
+            process.exit(code);
+        }
+    });
+}
+async function resolvePolicy(name, opts) {
+    const isAdHoc = !!(opts.model && opts.category && opts.minScore !== undefined);
+    if (isAdHoc) {
+        const minScore = Number(opts.minScore);
+        if (Number.isNaN(minScore) || minScore < 0 || minScore > 1) {
+            throw new PolicyValidationError("--min-score must be a number between 0.0 and 1.0.");
+        }
+        const policy = {
+            source: "current",
+            model: opts.model,
+            assurance: { categories: [{ id: opts.category, min_score_raw: minScore }] },
+        };
+        if (opts.minCoverage !== undefined) {
+            const minCoverage = Number(opts.minCoverage);
+            if (Number.isNaN(minCoverage) || minCoverage < 0 || minCoverage > 1) {
+                throw new PolicyValidationError("--min-coverage must be a number between 0.0 and 1.0.");
+            }
+            policy.assurance.categories[0].min_coverage = minCoverage;
+        }
+        return { gateName: "ad-hoc", policy, policyHash: "sha256:" + crypto.createHash("sha256").update(JSON.stringify(policy)).digest("hex") };
+    }
+    if (!name) {
+        throw new PolicyValidationError("A gate name is required (e.g. `zivis gate ship`), or pass --model/--category/--min-score for the ad-hoc debugging form.");
+    }
+    const filePath = path.resolve(process.cwd(), opts.file ?? DEFAULT_POLICY_PATH);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        throw new PolicyValidationError(`Policy file not found: ${filePath}`);
+    }
+    const parsed = parsePolicyFile(raw);
+    const policy = parsed.gates[name];
+    if (!policy) {
+        const available = Object.keys(parsed.gates).join(", ") || "(none defined)";
+        throw new PolicyValidationError(`Gate '${name}' is not defined in ${filePath}. Available gates: ${available}`);
+    }
+    const policyHash = "sha256:" + crypto.createHash("sha256").update(raw).digest("hex");
+    return { gateName: name, policy, policyHash };
+}
+async function fetchStatus(client, applicationId, policy) {
+    const query = new URLSearchParams({ applicationId, model: policy.model });
+    try {
+        return await client.get(`/api/assurance/status?${query.toString()}`);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+function printHuman(gateName, evaluation, _full) {
+    const symbol = evaluation.result === "pass" ? "✓" : evaluation.result === "fail" ? "✗" : "?";
+    console.log(`Gate '${gateName}': ${symbol} ${evaluation.result.toUpperCase()}`);
+    for (const c of evaluation.checks) {
+        const label = c.category_id ? `${c.type}[${c.category_id}]` : c.type;
+        const mark = c.result === "pass" ? "✓" : c.result === "fail" ? "✗" : "?";
+        console.log(`  ${mark} ${label}: actual=${JSON.stringify(c.actual)} required=${JSON.stringify(c.required)}`);
+    }
+}

package/dist/commands/inspect/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInspectCommands(program: Command): void;

package/dist/commands/inspect/index.js

@@ -0,0 +1,136 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { detectProjectBinding } from "@zivis/mcp/project-binding";
+import { runExtractor } from "../../internal/extractor/index.js";
+import { buildRepoGraphArtifact } from "../../internal/extractor/graph-builder.js";
+const execAsync = promisify(exec);
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+export function registerInspectCommands(program) {
+    program
+        .command("inspect")
+        .description("build a local repo graph artifact (services, endpoints, external deps) — local-only, no network")
+        .option("--root <dir>", "repo root to inspect (default: cwd)")
+        .option("--out <file>", "write artifact JSON to a file (default: <user-cache>/repos/<repo-id>/inspect/runs/<run-id>.json; '-' for stdout)")
+        .option("--privacy-audit", "print exactly what would be sent without writing to cache or sending — never makes network calls")
+        .option("--lang <list>", "comma-separated subset of adapters: typescript,go,python")
+        .option("--ignore <pattern>", "extra ignore pattern (repeatable)", collect, [])
+        .option("--application <id>", "set provenance.application_id (default: from .zivis/project.json if present)")
+        .option("--repo-id <id>", "override repo identifier (default: hash of git remote, fallback to hash of root path)")
+        .option("--commit <sha>", "override commit SHA (default: from `git rev-parse HEAD`)")
+        .option("--branch <name>", "override branch (default: from `git rev-parse --abbrev-ref HEAD`)")
+        .action(async (opts) => {
+        const rootDir = path.resolve(opts.root ?? process.cwd());
+        const cliPkg = await readCliPackage();
+        const langs = opts.lang
+            ? String(opts.lang).split(",").map((s) => s.trim()).filter(Boolean)
+            : undefined;
+        const result = await runExtractor({
+            rootDir,
+            languages: langs,
+            extraIgnores: opts.ignore,
+            extractorVersion: cliPkg.version,
+        });
+        const gitMeta = await readGitMetadata(rootDir);
+        const applicationId = opts.application ?? detectProjectBinding(rootDir)?.binding.applicationId;
+        const repoId = opts.repoId ?? deriveRepoId(gitMeta.remoteUrl, rootDir);
+        const commitSha = opts.commit ?? gitMeta.commitSha;
+        const branch = opts.branch ?? gitMeta.branch;
+        const artifact = buildRepoGraphArtifact(result, {
+            applicationId,
+            repoId,
+            commitSha,
+            branch,
+            analysisMode: "local",
+        });
+        if (opts.privacyAudit) {
+            process.stdout.write(JSON.stringify(artifact, null, 2) + "\n");
+            printSummary(artifact, "PRIVACY AUDIT — nothing was written or sent");
+            return;
+        }
+        if (opts.out === "-") {
+            process.stdout.write(JSON.stringify(artifact, null, 2) + "\n");
+            printSummary(artifact);
+            return;
+        }
+        const outPath = opts.out
+            ? path.isAbsolute(opts.out)
+                ? opts.out
+                : path.join(rootDir, opts.out)
+            : defaultCacheOutPath(repoId, commitSha, artifact.extracted_at);
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, JSON.stringify(artifact, null, 2) + "\n");
+        printSummary(artifact, `wrote ${outPath}`);
+    });
+}
+async function readCliPackage() {
+    const here = path.dirname(new URL(import.meta.url).pathname);
+    const pkgPath = path.join(here, "../../../package.json");
+    const raw = await fs.readFile(pkgPath, "utf8");
+    return JSON.parse(raw);
+}
+async function readGitMetadata(rootDir) {
+    const out = {};
+    out.remoteUrl = await tryGit(rootDir, "remote get-url origin");
+    out.commitSha = await tryGit(rootDir, "rev-parse HEAD");
+    out.branch = await tryGit(rootDir, "rev-parse --abbrev-ref HEAD");
+    return out;
+}
+async function tryGit(cwd, args) {
+    try {
+        const { stdout } = await execAsync(`git ${args}`, { cwd });
+        const value = stdout.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deriveRepoId(remoteUrl, rootDir) {
+    if (remoteUrl) {
+        return "remote-" + sha256Short(remoteUrl);
+    }
+    return "path-" + sha256Short(rootDir);
+}
+function sha256Short(value) {
+    return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function userCacheRoot() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "zivis");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return path.join(localAppData, "zivis", "Cache");
+    }
+    const xdg = process.env.XDG_CACHE_HOME;
+    return path.join(xdg ?? path.join(home, ".cache"), "zivis");
+}
+function defaultCacheOutPath(repoId, commitSha, extractedAt) {
+    const runId = formatRunId(commitSha, extractedAt);
+    return path.join(userCacheRoot(), "repos", repoId, "inspect", "runs", `${runId}.json`);
+}
+function formatRunId(commitSha, extractedAt) {
+    const compactTs = extractedAt.replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    if (!commitSha)
+        return `nogit-${compactTs}`;
+    return `${commitSha.slice(0, 7)}-${compactTs}`;
+}
+function printSummary(artifact, suffix) {
+    const services = artifact.nodes.filter((n) => n.type === "service").length;
+    const endpoints = artifact.nodes.filter((n) => n.type === "endpoint").length;
+    const deps = artifact.nodes.filter((n) => n.type === "external_dependency").length;
+    const exposes = artifact.edges.filter((e) => e.type === "exposes").length;
+    const dependsOn = artifact.edges.filter((e) => e.type === "depends_on").length;
+    const langs = artifact.scope.languages?.join(",") ?? "(none)";
+    process.stderr.write(`\n[zivis inspect] ${artifact.scope.files_scanned} files scanned in ${artifact.scope.duration_ms}ms (langs: ${langs})\n` +
+        `  ${artifact.nodes.length} nodes  (${services} services, ${endpoints} endpoints, ${deps} external deps)\n` +
+        `  ${artifact.edges.length} edges  (${exposes} exposes, ${dependsOn} depends_on)\n` +
+        (suffix ? `  ${suffix}\n` : ""));
+}

package/dist/commands/mcp/index.js

@@ -1,6 +1,8 @@
+import * as path from "node:path";
+import * as readline from "node:readline/promises";
 import { startServer } from "@zivis/mcp/server";
 import { DEFAULT_CONFIG } from "@zivis/mcp/types";
-import { setupCursor, setupVsCodeCopilot, setupVsCodeClaude, setupClaudeCodeCli, setupCline, setupWindsurf, printClaudeCodeManual, } from "../../internal/ide-setup.js";
+import { setupCursorWorkspace, setupVsCodeCopilot, setupVsCodeClaude, setupClaudeCodeCli, setupCline, setupWindsurf, printClaudeCodeManual, writeGuidance, removeGuidance, } from "../../internal/ide-setup.js";
 const KNOWN_CLIENTS = [
     "cursor",
     "claude-code",
@@ -10,50 +12,84 @@ const KNOWN_CLIENTS = [
     "vscode-copilot",
     "vscode-claude",
 ];
+function toGuidanceClient(client) {
+    switch (client) {
+        case "cursor": return "cursor";
+        case "claude-code-cli": return "claude-code-cli";
+        case "vscode-copilot": return "vscode-copilot";
+        case "vscode-claude": return "vscode-claude";
+        case "cline": return "cline";
+        case "windsurf": return "windsurf";
+        default: return null;
+    }
+}
+async function promptYesNo(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer !== "n" && answer !== "no";
+    }
+    finally {
+        rl.close();
+    }
+}
 export function registerMcpCommands(program) {
     const mcp = program.command("mcp").description("MCP server for IDE integration");
     mcp
         .command("serve")
         .description("start the stdio MCP server (called by your IDE, not directly)")
-        .action(async () => {
-        await startServer(DEFAULT_CONFIG);
+        .option("-w, --workspace <path>", "workspace root for project binding detection (auto-set by IDE config, do not pass manually)")
+        .action(async (opts) => {
+        const config = { ...DEFAULT_CONFIG };
+        if (opts.workspace) {
+            config.workspacePath = path.resolve(opts.workspace);
+        }
+        await startServer(config);
     });
     mcp
         .command("install")
-        .description("write MCP config for a supported IDE client")
+        .description("write MCP config for a supported IDE client (run from your project root)")
         .option("--client <name>", `target client (${KNOWN_CLIENTS.join(" | ")})`)
-        .option("-s, --session <name>", "include ZIVIS_SESSION env var")
+        .option("--package <name>", "which ZIVIS MCP package to register: 'builder' (default, @zivis/mcp-builder, citizen-dev surface) or 'appsec' (@zivis/mcp, DevSecOps surface)", "builder")
+        .option("--with-guidance", "also write IDE guidance files so the AI knows when to suggest security checks (no prompt). Only applies to the appsec package; builder ships its own cadence block via zivis_setup.")
+        .option("--no-guidance", "skip writing IDE guidance files (no prompt)")
         .action(async (opts) => {
         const client = opts.client?.toLowerCase();
-        const session = opts.session;
+        const pkgArg = opts.package?.toLowerCase() ?? "builder";
         if (!client) {
             console.error("Specify a client with --client <name>:");
             for (const c of KNOWN_CLIENTS)
                 console.error(`  zivis mcp install --client ${c}`);
             process.exit(1);
         }
+        if (pkgArg !== "appsec" && pkgArg !== "builder") {
+            console.error(`Unknown --package value: ${pkgArg}`);
+            console.error("Supported: appsec, builder");
+            process.exit(1);
+        }
+        const pkg = pkgArg;
         try {
             switch (client) {
                 case "cursor":
-                    await setupCursor(session);
+                    await setupCursorWorkspace(pkg);
                     break;
                 case "claude-code":
-                    printClaudeCodeManual(session);
+                    printClaudeCodeManual(pkg);
                     break;
                 case "claude-code-cli":
-                    await setupClaudeCodeCli(session);
+                    await setupClaudeCodeCli(pkg);
                     break;
                 case "cline":
-                    await setupCline(session);
+                    await setupCline(pkg);
                     break;
                 case "windsurf":
-                    await setupWindsurf(session);
+                    await setupWindsurf(pkg);
                     break;
                 case "vscode-copilot":
-                    await setupVsCodeCopilot(session);
+                    await setupVsCodeCopilot(pkg);
                     break;
                 case "vscode-claude":
-                    await setupVsCodeClaude(session);
+                    await setupVsCodeClaude(pkg);
                     break;
                 default:
                     console.error(`Unknown client: ${client}`);
@@ -65,6 +101,69 @@ export function registerMcpCommands(program) {
             console.error("Install failed:", err instanceof Error ? err.message : err);
             process.exit(1);
         }
+        if (client === "claude-code")
+            return;
+        if (pkg === "builder")
+            return;
+        const guidanceClient = toGuidanceClient(client);
+        if (!guidanceClient)
+            return;
+        let shouldWrite;
+        if (opts.withGuidance) {
+            shouldWrite = true;
+        }
+        else if (opts.guidance === false) {
+            shouldWrite = false;
+        }
+        else {
+            console.log("");
+            shouldWrite = await promptYesNo("Write ZIVIS guidance files so your IDE knows when to suggest security checks?\n" +
+                "(Adds a rule/instruction file to the project. You can edit or remove it anytime.) [Y/n] ");
+        }
+        if (shouldWrite) {
+            try {
+                const files = writeGuidance({ cwd: process.cwd(), client: guidanceClient });
+                if (files.length > 0) {
+                    console.log(`✓ Wrote guidance files:`);
+                    for (const f of files)
+                        console.log(`  ${f}`);
+                }
+            }
+            catch (err) {
+                console.warn(`  Warning: Could not write guidance files: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+    });
+    mcp
+        .command("uninstall")
+        .description("remove ONLY the ZIVIS-managed guidance block/files for a client (run from your project root)")
+        .option("--client <name>", `target client (${KNOWN_CLIENTS.join(" | ")})`)
+        .action(async (opts) => {
+        const client = opts.client?.toLowerCase();
+        if (!client) {
+            console.error("Specify a client with --client <name>:");
+            for (const c of KNOWN_CLIENTS)
+                console.error(`  zivis mcp uninstall --client ${c}`);
+            process.exit(1);
+        }
+        const guidanceClient = toGuidanceClient(client);
+        if (!guidanceClient) {
+            console.log(`Nothing to remove for "${client}" — no guidance files are written for this client.`);
+            return;
+        }
+        try {
+            const removed = removeGuidance({ cwd: process.cwd(), client: guidanceClient });
+            if (removed.length === 0) {
+                console.log("No ZIVIS-managed guidance found — nothing to remove.");
+                return;
+            }
+            console.log(`✓ Removed ZIVIS guidance:`);
+            for (const f of removed)
+                console.log(`  ${f}`);
+        }
+        catch (err) {
+            console.error("Uninstall failed:", err instanceof Error ? err.message : err);
+            process.exit(1);
+        }
     });
 }
-//# sourceMappingURL=index.js.map

package/dist/commands/open/index.d.ts

@@ -1,10 +1,2 @@
-/**
- * `zivis open` — Build and (by default) launch a vscode:// or cursor:// deep link
- * that opens a ZIVIS artifact in the ZIVIS Code IDE extension. Use `--ide cursor`
- * for Cursor. With --print, emit the URI to stdout for piping/sharing.
- *
- * Mirrors the URI shape emitted by the `zivis_open_in_ide` MCP tool and the
- * web app's buildIdeLink() helper. See docs/platform/integrations/IDE-DEEP-LINKS.md.
- */
 import type { Command } from "commander";
 export declare function registerOpenCommands(program: Command): void;

package/dist/commands/open/index.js

@@ -1,11 +1,3 @@
-/**
- * `zivis open` — Build and (by default) launch a vscode:// or cursor:// deep link
- * that opens a ZIVIS artifact in the ZIVIS Code IDE extension. Use `--ide cursor`
- * for Cursor. With --print, emit the URI to stdout for piping/sharing.
- *
- * Mirrors the URI shape emitted by the `zivis_open_in_ide` MCP tool and the
- * web app's buildIdeLink() helper. See docs/platform/integrations/IDE-DEEP-LINKS.md.
- */
 const KINDS = ["diagram", "document", "threat-model"];
 export function registerOpenCommands(program) {
     program
@@ -47,11 +39,8 @@ export function registerOpenCommands(program) {
             console.log(uri);
             return;
         }
-        // Lazy-import `open` so --print stays dependency-free in environments
-        // (e.g. headless CI) where launching a URL handler would fail or hang.
         const { default: open } = await import("open");
         await open(uri);
         console.log(uri);
     });
 }
-//# sourceMappingURL=index.js.map

package/dist/commands/run/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerRunCommands(program: Command): void;

package/dist/commands/run/index.js

@@ -0,0 +1,111 @@
+import * as fs from "node:fs/promises";
+import { ApiClient } from "@zivis/mcp/api-client";
+import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+import { DEVX_RUN_CONTRACT_VERSION, completeDevXRunRemote, cancelDevXRunRemote, isRetryableDevXRunError, } from "../../internal/devx-run.js";
+import { writeDevXRunCompleteOutboxEntry } from "../../internal/sync-outbox.js";
+import { jsonEnvelope, printJson, EXIT, errorMessage, failCommand } from "../../internal/cli-output.js";
+async function readInput(inputArg) {
+    const raw = inputArg === "-" ? await readStdin() : await fs.readFile(inputArg, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--input is not valid JSON: ${errorMessage(err)}`);
+    }
+}
+async function readStdin() {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    for await (const chunk of process.stdin) {
+        data += chunk;
+    }
+    return data;
+}
+export function registerRunCommands(program) {
+    const run = program.command("run").description("resolve a DevX run started by a run producer (e.g. `zivis test`)");
+    run
+        .command("complete <runId>")
+        .description("complete a pending run with its result envelope")
+        .requiredOption("--input <path>", "path to a JSON result file, or '-' for stdin")
+        .option("--json", "emit JSON only on stdout")
+        .action(async (runId, opts) => {
+        const json = !!opts.json;
+        let result;
+        try {
+            result = await readInput(opts.input);
+        }
+        catch (err) {
+            failCommand("run complete", err, json);
+        }
+        const config = resolveConfigFromBinding(process.cwd());
+        const client = new ApiClient(config);
+        try {
+            const response = await completeDevXRunRemote(client, {
+                runId,
+                contractVersion: DEVX_RUN_CONTRACT_VERSION,
+                result,
+            });
+            const output = jsonEnvelope("run complete", {
+                run_id: runId,
+                outcome: response.outcome,
+                status: response.run.status,
+                completed_at: response.run.completedAt,
+            });
+            if (json) {
+                printJson(output);
+            }
+            else {
+                console.log(`zivis run complete: ${response.outcome} (run ${runId} is now ${response.run.status})`);
+            }
+            process.exit(EXIT.OK);
+        }
+        catch (err) {
+            if (isRetryableDevXRunError(err)) {
+                const message = errorMessage(err);
+                const outboxPath = writeDevXRunCompleteOutboxEntry(process.cwd(), {
+                    runId,
+                    contractVersion: DEVX_RUN_CONTRACT_VERSION,
+                    result,
+                    error: message,
+                });
+                if (json) {
+                    printJson(jsonEnvelope("run complete", { run_id: runId, outcome: "queued", queued_at: outboxPath, error: message }));
+                }
+                else {
+                    console.error(`zivis run complete: Cloud unreachable (${message})\nQueued for retry: ${outboxPath}\nRun \`zivis sync --flush\` once the issue is resolved.`);
+                }
+                process.exit(EXIT.CLOUD_UNAVAILABLE);
+            }
+            failCommand("run complete", err, json);
+        }
+    });
+    run
+        .command("cancel <runId>")
+        .description("cancel a pending run")
+        .option("--reason <text>", "optional human-readable cancellation reason")
+        .option("--json", "emit JSON only on stdout")
+        .action(async (runId, opts) => {
+        const json = !!opts.json;
+        const config = resolveConfigFromBinding(process.cwd());
+        const client = new ApiClient(config);
+        try {
+            const response = await cancelDevXRunRemote(client, { runId, reason: opts.reason ?? null });
+            const output = jsonEnvelope("run cancel", {
+                run_id: runId,
+                outcome: response.outcome,
+                status: response.run.status,
+                cancelled_at: response.run.cancelledAt,
+            });
+            if (json) {
+                printJson(output);
+            }
+            else {
+                console.log(`zivis run cancel: ${response.outcome} (run ${runId} is now ${response.run.status})`);
+            }
+            process.exit(EXIT.OK);
+        }
+        catch (err) {
+            failCommand("run cancel", err, json);
+        }
+    });
+}