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

package/dist/commands/sync/index.js

@@ -0,0 +1,187 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { ApiClient } from "@zivis/mcp/api-client";
+import { detectProjectBinding, resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+import { readGitMetadata, deriveRepoFullNameFromRemote } from "../../internal/git-metadata.js";
+import { validateInventorySyncInput, syncApplicationInventory, } from "../../internal/inventory-sync.js";
+import { ensureZivisGitignore } from "../../internal/zivis-local-state.js";
+import { writeOutboxEntry, listOutboxEntries, removeOutboxEntry, recordOutboxRetryFailure, } from "../../internal/sync-outbox.js";
+import { completeDevXRunRemote } from "../../internal/devx-run.js";
+export function registerSyncCommands(program) {
+    program
+        .command("sync")
+        .description("push a locally-derived endpoint/feature/technology-stack inventory to your bound ZIVIS Application " +
+        "(the coding agent derives the inventory; this command reconciles it — see --file)")
+        .option("--file <path>", "JSON file with { endpoints?, features?, technologyStack? } (use - for stdin)")
+        .option("--flush", "retry pending outbox entries from a previous failed sync, instead of reading --file")
+        .option("--cwd <path>", "repo root (default: cwd)")
+        .option("--source <source>", "provenance source: cli or agent", "agent")
+        .option("--format <fmt>", "output format: human or json", "human")
+        .option("--dry-run", "validate/list and print what would be sent — no network calls")
+        .action(async (opts) => {
+        const exitCode = opts.flush ? await runFlush(opts) : await runSync(opts);
+        process.exit(exitCode);
+    });
+}
+async function runSync(opts) {
+    const rootDir = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+    const format = opts.format === "json" ? "json" : "human";
+    const source = opts.source === "cli" ? "cli" : "agent";
+    if (!opts.file) {
+        return fail(format, "--file is required (or pass --flush to retry queued entries)");
+    }
+    if (opts.source && opts.source !== "cli" && opts.source !== "agent") {
+        return fail(format, `--source must be "cli" or "agent" (got: ${opts.source})`);
+    }
+    let raw;
+    try {
+        raw = opts.file === "-" ? await readStdin() : await fs.readFile(path.resolve(rootDir, opts.file), "utf-8");
+    }
+    catch (err) {
+        return fail(format, `Could not read ${opts.file}: ${err instanceof Error ? err.message : err}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return fail(format, `Invalid JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    const validated = validateInventorySyncInput(parsed);
+    if (!validated.ok) {
+        return fail(format, `Invalid inventory input:\n  - ${validated.errors.join("\n  - ")}`);
+    }
+    const binding = detectProjectBinding(rootDir);
+    const applicationId = binding?.binding.applicationId;
+    if (!applicationId) {
+        return fail(format, "No Application bound for this repo. Run `zivis init` first (see .zivis/project.json).");
+    }
+    const gitMeta = await readGitMetadata(rootDir);
+    const repoFullName = deriveRepoFullNameFromRemote(gitMeta.remoteUrl);
+    const provenance = {
+        gitCommitSha: gitMeta.commitSha ?? null,
+        repoFullName: repoFullName ?? null,
+        defaultBranch: gitMeta.branch ?? null,
+        source,
+    };
+    if (opts.dryRun) {
+        process.stdout.write(JSON.stringify({ applicationId, provenance, input: validated.value }, null, 2) + "\n");
+        if (format === "human") {
+            process.stderr.write("\n[zivis sync] --dry-run: nothing was sent.\n");
+        }
+        return 0;
+    }
+    ensureZivisGitignore(rootDir);
+    const config = resolveConfigFromBinding(rootDir);
+    const client = new ApiClient(config);
+    let summary;
+    try {
+        summary = await syncApplicationInventory({ client, applicationId, input: validated.value, provenance });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const outboxPath = writeOutboxEntry(rootDir, { applicationId, input: validated.value, provenance, error: message });
+        return fail(format, `Sync failed: ${message}\nQueued for retry: ${outboxPath}\nRun \`zivis sync --flush\` once the issue is resolved.`);
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify({ applicationId, summary }, null, 2) + "\n");
+        return 0;
+    }
+    renderHumanSummary(summary);
+    return 0;
+}
+async function runFlush(opts) {
+    const rootDir = opts.cwd ? path.resolve(opts.cwd) : process.cwd();
+    const format = opts.format === "json" ? "json" : "human";
+    const pending = listOutboxEntries(rootDir);
+    if (pending.length === 0) {
+        if (format === "json")
+            process.stdout.write(JSON.stringify({ pending: 0 }, null, 2) + "\n");
+        else
+            process.stdout.write("\nNo pending outbox entries.\n");
+        return 0;
+    }
+    if (opts.dryRun) {
+        const preview = pending.map((p) => ({
+            file: p.filePath,
+            kind: p.entry.kind,
+            queuedAt: p.entry.queuedAt,
+            attempts: p.entry.attempts,
+            lastError: p.entry.lastError,
+            ...(p.entry.kind === "devx-run-complete"
+                ? { runId: p.entry.runId, result: p.entry.result }
+                : { applicationId: p.entry.applicationId, input: p.entry.input }),
+        }));
+        process.stdout.write(JSON.stringify(preview, null, 2) + "\n");
+        if (format === "human")
+            process.stderr.write(`\n[zivis sync --flush] --dry-run: ${pending.length} pending, nothing sent.\n`);
+        return 0;
+    }
+    const config = resolveConfigFromBinding(rootDir);
+    const client = new ApiClient(config);
+    let succeeded = 0;
+    let failed = 0;
+    for (const { filePath, entry } of pending) {
+        try {
+            if (entry.kind === "devx-run-complete") {
+                await completeDevXRunRemote(client, { runId: entry.runId, contractVersion: entry.contractVersion, result: entry.result });
+            }
+            else {
+                await syncApplicationInventory({
+                    client,
+                    applicationId: entry.applicationId,
+                    input: entry.input,
+                    provenance: entry.provenance,
+                });
+            }
+            removeOutboxEntry(filePath);
+            succeeded++;
+        }
+        catch (err) {
+            recordOutboxRetryFailure(filePath, entry, err instanceof Error ? err.message : String(err));
+            failed++;
+        }
+    }
+    if (format === "json") {
+        process.stdout.write(JSON.stringify({ succeeded, failed, remaining: failed }, null, 2) + "\n");
+    }
+    else {
+        process.stdout.write(`\nFlushed outbox: ${succeeded} succeeded, ${failed} still failing (left queued).\n`);
+    }
+    return failed > 0 ? 1 : 0;
+}
+function renderHumanSummary(summary) {
+    let out = "\nZIVIS inventory sync:\n\n";
+    if (summary.technologyStack) {
+        out += `  Technology stack: ${summary.technologyStack.count} entries\n`;
+    }
+    if (summary.endpoints) {
+        const e = summary.endpoints;
+        out += `  Endpoints:  +${e.created} new, ${e.updated} updated, ${e.deprecated} deprecated (${e.total} total reported)\n`;
+    }
+    if (summary.features) {
+        const f = summary.features;
+        out += `  Features:   +${f.created} new, ${f.updated} updated, ${f.deprecated} deprecated\n`;
+    }
+    if (summary.repo) {
+        out += `  Repository: ${summary.repo.repoFullName} (${summary.repo.created ? "linked" : "revision updated"})\n`;
+    }
+    process.stdout.write(out + "\n");
+}
+function fail(format, message) {
+    if (format === "json") {
+        process.stdout.write(JSON.stringify({ error: message }, null, 2) + "\n");
+    }
+    else {
+        process.stderr.write(`\n${message}\n`);
+    }
+    return 1;
+}
+async function readStdin() {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    for await (const chunk of process.stdin) {
+        data += chunk;
+    }
+    return data;
+}

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

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

package/dist/commands/test/index.js

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ApiClient } from "@zivis/mcp/api-client";
+import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+import { requireApplicationId } from "@zivis/mcp/resolve-application-id";
+import { renderSecurityContext } from "../../internal/security-context.js";
+import { startTestRun, listTestScopes } from "../../internal/test-scope.js";
+import { HttpPackRegistryClient, LocalPackRegistryClient, registryDirOverride } from "../../internal/packs/registry-client.js";
+import { PackUnavailableError, PackIntegrityError, UnknownScopeError } from "../../internal/packs/types.js";
+import { jsonEnvelope, printJson, EXIT, exitCodeForError, errorMessage, failCommand } from "../../internal/cli-output.js";
+class UsageError extends Error {
+}
+function buildRegistryClient(apiClient) {
+    const override = registryDirOverride();
+    if (override)
+        return new LocalPackRegistryClient(override);
+    return new HttpPackRegistryClient(apiClient);
+}
+function exitCodeForTestError(err) {
+    if (err instanceof UnknownScopeError || err instanceof PackIntegrityError)
+        return EXIT.INVALID_OR_INDETERMINATE;
+    if (err instanceof PackUnavailableError)
+        return EXIT.CLOUD_UNAVAILABLE;
+    return exitCodeForError(err);
+}
+function getCliVersion() {
+    try {
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../../../package.json"), "utf-8"));
+        return pkg.version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function registerTestCommand(program) {
+    program
+        .command("test [scope]")
+        .description("run a Zivis-guided AppSec review — full/adaptive by default, or targeted at a stable scope")
+        .option("--list", "list available scopes from the verified AppSec methodology pack")
+        .option("--app <id>", "Application id (defaults to the bound Application)")
+        .option("--json", "emit JSON only on stdout")
+        .action(async (scope, opts) => {
+        const json = !!opts.json;
+        const cwd = process.cwd();
+        const config = resolveConfigFromBinding(cwd);
+        const apiClient = new ApiClient(config);
+        const registryClient = buildRegistryClient(apiClient);
+        const cliVersion = getCliVersion();
+        if (opts.list) {
+            try {
+                const listing = await listTestScopes(registryClient, cliVersion);
+                if (json) {
+                    printJson(jsonEnvelope("test", { list: true, methodology: { pack: listing.pack, version: listing.version }, scopes: listing.scopes }));
+                }
+                else {
+                    printListHuman(listing);
+                }
+                process.exit(EXIT.OK);
+            }
+            catch (err) {
+                failCommand("test", err, json);
+            }
+            return;
+        }
+        try {
+            const resolvedApp = requireApplicationId(opts.app, cwd);
+            if (!resolvedApp.ok) {
+                throw new UsageError(resolvedApp.message);
+            }
+            const { envelope, resolvedScope, contextOutcome } = await startTestRun({ apiClient, registryClient }, { applicationId: resolvedApp.id, scopeId: scope, cwd, cliVersion });
+            const output = jsonEnvelope("test", { ...envelope });
+            if (json) {
+                printJson(output);
+            }
+            else {
+                printRunHuman(envelope, resolvedScope, contextOutcome);
+            }
+            process.exit(EXIT.OK);
+        }
+        catch (err) {
+            const code = err instanceof UsageError ? EXIT.INVALID_OR_INDETERMINATE : exitCodeForTestError(err);
+            const message = errorMessage(err);
+            if (json) {
+                printJson(jsonEnvelope("test", { result: "error", scope: scope ?? null, error: message }));
+            }
+            else {
+                console.error(`zivis test: ${message}`);
+                if (err instanceof UnknownScopeError) {
+                    console.error(`Run \`zivis test --list\` for descriptions.`);
+                }
+            }
+            process.exit(code);
+        }
+    });
+}
+function printListHuman(listing) {
+    const lines = [`ZIVIS AppSec methodology — ${listing.pack} v${listing.version}`, ""];
+    const idWidth = Math.max(...listing.scopes.map((s) => s.id.length), "scope".length);
+    for (const s of listing.scopes) {
+        lines.push(`  ${s.id.padEnd(idWidth)}  ${s.label} — ${s.description}`);
+    }
+    lines.push("", "Run `zivis test <scope>` for a focused review, or `zivis test` for a full adaptive review.");
+    console.log(lines.join("\n"));
+}
+function printRunHuman(envelope, resolvedScope, contextOutcome) {
+    console.log(`zivis test: started run ${envelope.run_id}${resolvedScope ? ` (scope: ${resolvedScope.id})` : " (full adaptive review)"}`);
+    console.log(renderSecurityContext(contextOutcome, "human"));
+    console.log(`\nMethodology: ${envelope.methodology.path}`);
+    if (envelope.methodology.scope) {
+        console.log(`Focused scope guidance: ${envelope.methodology.scope.path}`);
+    }
+    console.log(`\nWhen finished: ${envelope.result_contract.complete_command}`);
+}

package/dist/commands/tm/index.js

@@ -4,6 +4,7 @@ import { ApiClient } from "@zivis/mcp/api-client";
 import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
 import { getEphemeralCreds } from "../../internal/target-auth/index.js";
 import { runExtractor } from "../../internal/extractor/index.js";
+import { ensureZivisGitignore } from "../../internal/zivis-local-state.js";
 function buildClient(opts) {
     const config = opts.session
         ? { ...resolveConfigFromBinding(process.cwd()), session: opts.session }
@@ -132,6 +133,9 @@ export function registerTmCommands(program) {
             return;
         }
         const absOut = path.isAbsolute(target) ? target : path.join(rootDir, target);
+        if (absOut.startsWith(path.join(rootDir, ".zivis") + path.sep)) {
+            ensureZivisGitignore(rootDir);
+        }
         await fs.mkdir(path.dirname(absOut), { recursive: true });
         await fs.writeFile(absOut, JSON.stringify(result, null, 2) + "\n", "utf8");
         console.log(`✓ Wrote ${absOut}`);

package/dist/index.js

@@ -14,6 +14,11 @@ import { registerInspectCommands } from "./commands/inspect/index.js";
 import { registerMcpCommands } from "./commands/mcp/index.js";
 import { registerCreditsCommands } from "./commands/credits/index.js";
 import { registerOpenCommands } from "./commands/open/index.js";
+import { registerSyncCommands } from "./commands/sync/index.js";
+import { registerAssuranceCommands } from "./commands/assurance/index.js";
+import { registerGateCommand } from "./commands/gate/index.js";
+import { registerRunCommands } from "./commands/run/index.js";
+import { registerTestCommand } from "./commands/test/index.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function getVersion() {
     try {
@@ -34,6 +39,7 @@ program
     .description("interactive setup: authenticate, pick org, and bind this repo (alias for `zivis auth init`)")
     .option("-s, --session <name>", "named session for multi-tenant")
     .option("--skip-mint-key", "skip MCP API key mint after successful OAuth")
+    .option("--application <name-or-id>", "select an existing Application by id or exact name (fails if not found — never creates one)")
     .action(async (opts) => {
     await authInitCommand(opts);
 });
@@ -47,6 +53,11 @@ registerInspectCommands(program);
 registerMcpCommands(program);
 registerCreditsCommands(program);
 registerOpenCommands(program);
+registerSyncCommands(program);
+registerAssuranceCommands(program);
+registerGateCommand(program);
+registerRunCommands(program);
+registerTestCommand(program);
 program.parseAsync(process.argv).catch((err) => {
     console.error(err instanceof Error ? err.message : err);
     process.exit(1);

package/dist/internal/application-binding.d.ts

@@ -0,0 +1,8 @@
+import type { ZivisConfig } from "@zivis/mcp/types";
+export interface EnsureApplicationBindingOpts {
+    config: ZivisConfig;
+    accessToken: string;
+    cwd: string;
+    explicitApplication?: string;
+}
+export declare function ensureApplicationBinding(opts: EnsureApplicationBindingOpts): Promise<void>;

package/dist/internal/application-binding.js

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline/promises";
+import * as child_process from "node:child_process";
+import { detectProjectBinding } from "@zivis/mcp/project-binding";
+async function apiFetch(config, accessToken, method, path, body) {
+    const response = await fetch(`${config.apiBaseUrl}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            "User-Agent": "@zivis/cli",
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!response.ok) {
+        const errorBody = (await response.json().catch(() => ({})));
+        throw new Error(errorBody.message || errorBody.error || `HTTP ${response.status}`);
+    }
+    return (await response.json());
+}
+async function fetchApplications(config, accessToken) {
+    const result = await apiFetch(config, accessToken, "GET", "/api/rt/applications?limit=100");
+    return result.applications;
+}
+async function createApplication(config, accessToken, name) {
+    const result = await apiFetch(config, accessToken, "POST", "/api/rt/applications", { name, placeholder: true });
+    return result.application;
+}
+function defaultApplicationName(cwd) {
+    try {
+        const remote = child_process
+            .execSync("git remote get-url origin 2>/dev/null", { cwd, encoding: "utf8" })
+            .trim();
+        const match = remote.match(/\/([^/]+?)(\.git)?$/);
+        if (match?.[1])
+            return match[1];
+    }
+    catch {
+    }
+    return path.basename(cwd);
+}
+async function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptForApplicationName(defaultName) {
+    const answer = await prompt(`Application name [${defaultName}]: `);
+    return answer || defaultName;
+}
+const NON_INTERACTIVE_HELP = "Pass --application <name-or-id> to select an existing one non-interactively " +
+    "(it will not create one), or set applicationId manually in .zivis/project.json.";
+export async function ensureApplicationBinding(opts) {
+    const { config, accessToken, cwd, explicitApplication } = opts;
+    const detected = detectProjectBinding(cwd);
+    if (!detected)
+        return;
+    if (detected.binding.applicationId) {
+        console.log(`✓ Application binding verified: ${detected.binding.applicationName ?? detected.binding.applicationId}`);
+        return;
+    }
+    let apps;
+    try {
+        apps = await fetchApplications(config, accessToken);
+    }
+    catch (err) {
+        console.log(`  WARNING: Could not list applications: ${err instanceof Error ? err.message : err}`);
+        console.log("  Skipping application binding — set applicationId manually in .zivis/project.json.");
+        return;
+    }
+    const interactive = process.stderr.isTTY === true && process.stdin.isTTY === true;
+    let selected;
+    if (explicitApplication) {
+        const byId = apps.find((a) => a.id === explicitApplication);
+        const byName = byId
+            ? []
+            : apps.filter((a) => a.name.toLowerCase() === explicitApplication.toLowerCase());
+        if (byId) {
+            selected = byId;
+            console.log(`\nUsing existing application: ${selected.name}`);
+        }
+        else if (byName.length > 1) {
+            console.log(`\n  AMBIGUOUS: ${byName.length} applications named "${explicitApplication}" found — ` +
+                `refusing to guess which one you mean.`);
+            for (const a of byName)
+                console.log(`    ${a.id}  ${a.name}`);
+            console.log("  Use the Application ID instead of the name, or run `zivis init` interactively.");
+            return;
+        }
+        else if (byName.length === 1) {
+            selected = byName[0];
+            console.log(`\nUsing existing application: ${selected.name}`);
+        }
+        else {
+            console.log(`\n  NOT FOUND: no application matches id or name "${explicitApplication}".`);
+            console.log("  --application selects an EXISTING application — it does not create one.");
+            console.log("  Check the id/name (`zivis app list`), or run `zivis init` interactively to create a new one.");
+            return;
+        }
+    }
+    else if (apps.length === 0) {
+        if (!interactive) {
+            console.log("\n  WARNING: No applications found and no TTY to prompt — skipping application binding.");
+            console.log(`  ${NON_INTERACTIVE_HELP}`);
+            return;
+        }
+        console.log("\nNo applications found in this org — let's create one.");
+        const name = await promptForApplicationName(defaultApplicationName(cwd));
+        try {
+            selected = await createApplication(config, accessToken, name);
+        }
+        catch (err) {
+            console.log(`  WARNING: Could not create application: ${err instanceof Error ? err.message : err}`);
+            return;
+        }
+        console.log(`✓ Created application ${selected.name} (${selected.id})`);
+    }
+    else if (!interactive) {
+        console.log(`\n  WARNING: ${apps.length} application(s) found and no TTY to prompt — skipping application binding.`);
+        console.log("  Never auto-selecting the sole application without explicit confirmation.");
+        console.log(`  ${NON_INTERACTIVE_HELP}`);
+        return;
+    }
+    else {
+        console.log("\nWhich application are you working on?");
+        apps.forEach((a, i) => console.log(`  ${i + 1}. ${a.name}`));
+        console.log(`  ${apps.length + 1}. Create a new application`);
+        const answer = await prompt(`\n> `);
+        const idx = parseInt(answer, 10) - 1;
+        if (idx === apps.length) {
+            const name = await promptForApplicationName(defaultApplicationName(cwd));
+            try {
+                selected = await createApplication(config, accessToken, name);
+            }
+            catch (err) {
+                console.log(`  WARNING: Could not create application: ${err instanceof Error ? err.message : err}`);
+                return;
+            }
+            console.log(`✓ Created application ${selected.name} (${selected.id})`);
+        }
+        else if (!Number.isNaN(idx) && idx >= 0 && idx < apps.length) {
+            selected = apps[idx];
+        }
+        else {
+            console.log("  Invalid selection — skipping application binding. Set applicationId manually in .zivis/project.json.");
+            return;
+        }
+    }
+    if (!selected)
+        return;
+    const current = detectProjectBinding(cwd);
+    if (!current)
+        return;
+    const updated = {
+        ...current.binding,
+        applicationId: selected.id,
+        applicationName: selected.name,
+    };
+    fs.writeFileSync(current.filePath, JSON.stringify(updated, null, 2) + "\n");
+    console.log(`✓ Repo bound to application: ${selected.name}`);
+    console.log(`  File: ${current.filePath}`);
+}

package/dist/internal/cli-output.d.ts

@@ -0,0 +1,16 @@
+export declare const SCHEMA_VERSION = "1";
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly POLICY_FAIL: 1;
+    readonly INVALID_OR_INDETERMINATE: 2;
+    readonly AUTH_FAILURE: 3;
+    readonly CLOUD_UNAVAILABLE: 4;
+};
+export declare function jsonEnvelope<T extends Record<string, unknown>>(command: string, data: T): {
+    schema_version: string;
+    command: string;
+} & T;
+export declare function printJson(value: unknown): void;
+export declare function exitCodeForError(err: unknown): number;
+export declare function errorMessage(err: unknown): string;
+export declare function failCommand(command: string, err: unknown, json: boolean): never;

package/dist/internal/cli-output.js

@@ -0,0 +1,39 @@
+import { ApiError } from "@zivis/mcp/api-client";
+export const SCHEMA_VERSION = "1";
+export const EXIT = {
+    OK: 0,
+    POLICY_FAIL: 1,
+    INVALID_OR_INDETERMINATE: 2,
+    AUTH_FAILURE: 3,
+    CLOUD_UNAVAILABLE: 4,
+};
+export function jsonEnvelope(command, data) {
+    return { schema_version: SCHEMA_VERSION, command, ...data };
+}
+export function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+export function exitCodeForError(err) {
+    if (err instanceof ApiError) {
+        if (err.code === "NETWORK_ERROR")
+            return EXIT.CLOUD_UNAVAILABLE;
+        if (err.code === "AUTH_REQUIRED" || err.status === 401 || err.status === 403)
+            return EXIT.AUTH_FAILURE;
+        return EXIT.INVALID_OR_INDETERMINATE;
+    }
+    return EXIT.INVALID_OR_INDETERMINATE;
+}
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function failCommand(command, err, json) {
+    const code = exitCodeForError(err);
+    const message = errorMessage(err);
+    if (json) {
+        printJson(jsonEnvelope(command, { result: "error", error: message }));
+    }
+    else {
+        console.error(`zivis ${command}: ${message}`);
+    }
+    process.exit(code);
+}

package/dist/internal/devx-run.d.ts

@@ -0,0 +1,47 @@
+export declare const DEVX_RUN_CONTRACT_VERSION = "1";
+export interface DevXRunApi {
+    post<T>(path: string, body: unknown): Promise<T>;
+}
+export interface DevXRunPackProvenance {
+    packId: string;
+    packType: string;
+    version: string;
+}
+export interface StartDevXRunParams {
+    applicationId: string;
+    runType: string;
+    requestedIntent?: unknown;
+    pack?: DevXRunPackProvenance;
+    cwd?: string;
+}
+export interface StartedDevXRun {
+    runId: string;
+    contractVersion: string;
+    applicationId: string;
+    startedAt: string;
+}
+export declare function startDevXRun(client: DevXRunApi, params: StartDevXRunParams): Promise<StartedDevXRun>;
+export interface DevXRunWire {
+    id: string;
+    applicationId: string;
+    status: "pending" | "completed" | "cancelled";
+    contractVersion: string;
+    startedAt: string;
+    completedAt: string | null;
+    cancelledAt: string | null;
+    cancelReason: string | null;
+}
+export interface DevXRunOutcome {
+    outcome: "completed" | "cancelled" | "idempotent-replay";
+    run: DevXRunWire;
+}
+export declare function isRetryableDevXRunError(err: unknown): boolean;
+export declare function completeDevXRunRemote(client: DevXRunApi, params: {
+    runId: string;
+    contractVersion: string;
+    result: unknown;
+}): Promise<DevXRunOutcome>;
+export declare function cancelDevXRunRemote(client: DevXRunApi, params: {
+    runId: string;
+    reason?: string | null;
+}): Promise<DevXRunOutcome>;

package/dist/internal/devx-run.js

@@ -0,0 +1,36 @@
+import { ApiError } from "@zivis/mcp/api-client";
+import { readGitMetadata } from "./git.js";
+export const DEVX_RUN_CONTRACT_VERSION = "1";
+export async function startDevXRun(client, params) {
+    const git = await readGitMetadata(params.cwd ?? process.cwd());
+    const response = await client.post(`/api/rt/applications/${params.applicationId}/runs`, {
+        runType: params.runType,
+        contractVersion: DEVX_RUN_CONTRACT_VERSION,
+        gitSha: git.commitSha ?? null,
+        gitDirty: git.dirty ?? null,
+        packId: params.pack?.packId ?? null,
+        packType: params.pack?.packType ?? null,
+        packVersion: params.pack?.version ?? null,
+        requestedIntent: params.requestedIntent,
+    });
+    return {
+        runId: response.id,
+        contractVersion: response.contractVersion,
+        applicationId: response.applicationId,
+        startedAt: response.startedAt,
+    };
+}
+export function isRetryableDevXRunError(err) {
+    return err instanceof ApiError && (err.code === "NETWORK_ERROR" || err.status >= 500);
+}
+export async function completeDevXRunRemote(client, params) {
+    return client.post(`/api/devx-runs/${params.runId}/complete`, {
+        contractVersion: params.contractVersion,
+        result: params.result,
+    });
+}
+export async function cancelDevXRunRemote(client, params) {
+    return client.post(`/api/devx-runs/${params.runId}/cancel`, {
+        reason: params.reason ?? null,
+    });
+}