@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/schema-from-runs.ts

@@ -0,0 +1,128 @@
+/**
+ * ARV-175: `zond schema-from-runs` — mine 2xx response bodies from a
+ * persisted run and emit `patch.schema.json` (inferred JSON Schema per
+ * endpoint+status). Pairs with `refresh-api --merge-schema` (ARV-176).
+ */
+import { writeFile } from "node:fs/promises";
+import type { Command } from "commander";
+import { readOpenApiSpec, extractEndpoints } from "../../core/generator/index.ts";
+import { schemaFromRuns, type ResultRow } from "../../core/spec/schema-from-runs.ts";
+import { getResultsByRunId, getLatestRunId } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
+import { resolveApiCollection, globalJson } from "../resolve.ts";
+import { getApi } from "../util/api-context.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { parsePositiveInt } from "../argv.ts";
+
+export interface SchemaFromRunsCliOptions {
+  api?: string;
+  spec?: string;
+  db?: string;
+  run?: number;
+  minSamples?: number;
+  out?: string;
+  engine?: string;
+  json?: boolean;
+}
+
+export async function schemaFromRunsCommand(
+  opts: SchemaFromRunsCliOptions,
+  cmd: Command,
+): Promise<number> {
+  const json = opts.json === true || globalJson(cmd);
+  const label = "schema-from-runs";
+
+  // ARV-175 AC#2: only `builtin` is wired. quicktype/genson would each pull
+  // a large dependency tree, which contradicts zond's minimal-deps charter.
+  const engine = (opts.engine ?? "builtin").toLowerCase();
+  if (engine !== "builtin") {
+    const msg = `--engine "${opts.engine}" is not available. Only 'builtin' is wired (quicktype/genson would add heavy deps; see src/CLAUDE.md).`;
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  // Resolve spec: --spec wins, else --api / current-api collection.
+  let spec = opts.spec;
+  const apiFlag = opts.spec ? opts.api : getApi(cmd, opts as Record<string, unknown>);
+  if (!spec && apiFlag) {
+    const resolved = resolveApiCollection(apiFlag, opts.db);
+    if ("error" in resolved) {
+      if (json) printJson(jsonError(label, [resolved.error])); else printError(resolved.error);
+      return resolved.error.startsWith("Failed") ? 2 : 1;
+    }
+    if (resolved.spec) spec = resolved.spec;
+  }
+  if (!spec) {
+    const msg = "No spec: pass --spec <path> or --api <name> (or set a current API).";
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  getDb(opts.db);
+  const runId = opts.run ?? getLatestRunId();
+  if (runId == null) {
+    const msg = "No runs in the database. Run `zond run` / `zond checks run` first, then re-run schema-from-runs.";
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+
+  let doc;
+  try {
+    doc = await readOpenApiSpec(spec);
+  } catch (err) {
+    const msg = `Failed to read spec at "${spec}": ${(err as Error).message}`;
+    if (json) printJson(jsonError(label, [msg])); else printError(msg);
+    return 2;
+  }
+  const endpoints = extractEndpoints(doc);
+
+  const rows = getResultsByRunId(runId) as unknown as ResultRow[];
+  const minSamples = opts.minSamples ?? 2;
+  const result = schemaFromRuns({ results: rows, endpoints, minSamples });
+
+  const emitted = result.groups.filter((g) => g.emitted);
+  const skipped = result.groups.filter((g) => !g.emitted);
+  const out = opts.out ?? "patch.schema.json";
+
+  if (emitted.length > 0) {
+    await writeFile(out, JSON.stringify(result.patch, null, 2) + "\n", "utf-8");
+  }
+
+  if (json) {
+    printJson(jsonOk(label, {
+      run_id: runId,
+      out: emitted.length > 0 ? out : null,
+      min_samples: minSamples,
+      emitted: emitted.map((g) => ({ endpoint: g.endpoint, status: g.status, samples: g.samples })),
+      skipped: skipped.map((g) => ({ endpoint: g.endpoint, status: g.status, samples: g.samples, reason: g.reason })),
+    }));
+    return 0;
+  }
+
+  if (emitted.length === 0) {
+    printWarning(`No schemas emitted from run #${runId}: no (endpoint, status) group reached --min-samples ${minSamples}. ${skipped.length} group(s) had too few 2xx JSON samples.`);
+    return 0;
+  }
+  printSuccess(`Wrote ${emitted.length} response schema(s) from run #${runId} to ${out}`);
+  for (const g of emitted) console.log(`  ${g.endpoint} → ${g.status} (${g.samples} samples)`);
+  for (const g of skipped) printWarning(`skipped ${g.endpoint} → ${g.status}: ${g.reason} (${g.samples} sample(s))`);
+  console.log(`\nNext: zond refresh-api --api <name> --merge-schema ${out}`);
+  return 0;
+}
+
+export function registerSchemaFromRuns(program: Command): void {
+  program
+    .command("schema-from-runs")
+    .description("ARV-175: infer response JSON Schemas from a run's 2xx bodies → patch.schema.json (pairs with refresh-api --merge-schema). Revives response_schema_conformance on specs that declare no response schemas.")
+    .option("--api <name>", "Registered API (spec + DB lookup)")
+    .option("--spec <path>", "Explicit OpenAPI spec path (overrides --api)")
+    .option("--run <id>", "Run id to mine (default: latest)", parsePositiveInt("--run"))
+    .option("--min-samples <n>", "Minimum 2xx samples per endpoint+status to emit (default 2)", parsePositiveInt("--min-samples"))
+    .option("--out <path>", "Output path for patch.schema.json (default: patch.schema.json)")
+    .option("--engine <name>", "Schema engine. Only 'builtin' is wired (default).", "builtin")
+    .option("--db <path>", "SQLite path")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await schemaFromRunsCommand(opts, cmd);
+    });
+}

package/src/cli/commands/secrets.ts

@@ -0,0 +1,133 @@
+/**
+ * `zond secrets set <key> <value>` — write a raw secret into
+ * `apis/<name>/.secrets.yaml` (ARV-377). Before this, rotating an expired
+ * token meant hand-editing the gitignored file (or a python script), since
+ * `zond fixtures add` only writes `.env.yaml` and the iron rules forbid an
+ * agent reading `.secrets.yaml` directly.
+ *
+ * Two safety properties:
+ *   • the value is NEVER echoed back (stdout, stderr, or JSON envelope) —
+ *     only the key name and whether a Bearer prefix was stripped;
+ *   • a `.secrets.yaml.bak` backup is written before the file is touched,
+ *     mirroring `fixtures add --apply`.
+ *
+ * Bearer trap (ARV-367/AC3): `.secrets.yaml` holds the RAW token — zond's
+ * runner adds the scheme prefix itself (`Authorization: Bearer <token>`).
+ * A pasted `Bearer eyJ…` is therefore always a mistake, so we strip a
+ * leading `Bearer ` (case-insensitive) and warn once. `--literal` keeps the
+ * value verbatim for the rare case someone really means to store it.
+ */
+import type { Command } from "commander";
+import { join } from "node:path";
+import { copyFile } from "node:fs/promises";
+
+import { getApi, MISSING_API_MESSAGE } from "../util/api-context.ts";
+import { resolveApiCollection } from "../resolve.ts";
+import { upsertEnvLine } from "./discover.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+import { globalJson } from "../resolve.ts";
+
+interface SecretsSetOptions {
+  api?: string;
+  literal?: boolean;
+  json?: boolean;
+}
+
+const BEARER_PREFIX_RE = /^\s*Bearer\s+/i;
+
+/** Normalise a pasted secret value: strip a leading `Bearer ` prefix (unless
+ *  `literal`) so `.secrets.yaml` holds the raw token zond's runner expects.
+ *  Exported for unit tests. */
+export function normalizeSecretValue(raw: string, literal?: boolean): { value: string; bearerStripped: boolean } {
+  if (!literal && BEARER_PREFIX_RE.test(raw)) {
+    return { value: raw.replace(BEARER_PREFIX_RE, ""), bearerStripped: true };
+  }
+  return { value: raw, bearerStripped: false };
+}
+
+/** Upsert one `key: "value"` line into `.secrets.yaml`, backing up first.
+ *  Exported for unit tests. */
+export async function applySecretWrite(
+  secretsPath: string,
+  key: string,
+  value: string,
+): Promise<{ backup: string | null }> {
+  const file = Bun.file(secretsPath);
+  const exists = await file.exists();
+  let text = exists ? await file.text() : "";
+  let backup: string | null = `${secretsPath}.bak`;
+  if (exists) {
+    try { await copyFile(secretsPath, backup); } catch { backup = null; }
+  } else {
+    backup = null;
+  }
+  text = upsertEnvLine(text, key, value);
+  if (!text.endsWith("\n")) text += "\n";
+  await Bun.write(secretsPath, text);
+  return { backup };
+}
+
+async function setAction(key: string, valueParts: string[], cmd: Command): Promise<void> {
+  const opts = cmd.opts<SecretsSetOptions>();
+  const json = opts.json === true || globalJson(cmd);
+
+  const fail = (m: string, code = 2) => {
+    if (json) printJson(jsonError("secrets set", [m])); else printError(m);
+    process.exit(code);
+  };
+
+  const apiName = getApi(cmd, { api: opts.api } as Record<string, unknown>);
+  if (!apiName) return fail(MISSING_API_MESSAGE);
+  const col = resolveApiCollection(apiName, undefined);
+  if ("error" in col) return fail(col.error);
+  if (!col.baseDir) return fail(`API '${apiName}' has no base_dir registered.`);
+
+  const k = key.trim();
+  if (!k) return fail("Secret key must not be empty. Usage: zond secrets set <key> <value>");
+
+  // Join variadic value parts so an unquoted `Bearer eyJ…` paste (two argv
+  // tokens) still lands as one value instead of dropping the token.
+  const rawValue = valueParts.join(" ");
+  const { value, bearerStripped } = normalizeSecretValue(rawValue, opts.literal);
+  const warnings: string[] = [];
+  if (bearerStripped) {
+    warnings.push(
+      "Stripped a leading 'Bearer ' prefix — .secrets.yaml stores the raw token; zond adds the scheme prefix itself. Pass --literal to keep it verbatim.",
+    );
+  }
+
+  const secretsPath = join(col.baseDir, ".secrets.yaml");
+  const { backup } = await applySecretWrite(secretsPath, k, value);
+
+  // NEVER echo the value — key + metadata only.
+  if (json) {
+    printJson(jsonOk("secrets set", {
+      api: apiName,
+      secrets: secretsPath,
+      key: k,
+      bearer_stripped: bearerStripped,
+      backup,
+    }, warnings));
+  } else {
+    printSuccess(`Set secret '${k}' in ${secretsPath}` + (backup ? ` (backup: ${backup})` : ""));
+    process.stdout.write("  (value not echoed)\n");
+    for (const w of warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+  process.exit(0);
+}
+
+export function registerSecrets(program: Command): void {
+  const secrets = program
+    .command("secrets")
+    .description("Manage apis/<name>/.secrets.yaml (gitignored raw secret values, TASK-170). Values are never echoed back.");
+
+  secrets
+    .command("set <key> <value...>")
+    .description("Write a secret to .secrets.yaml (with .secrets.yaml.bak backup). Auto-strips a pasted 'Bearer ' prefix unless --literal. Never prints the value.")
+    .option("--api <name>", "Registered API (apis/<name>/.secrets.yaml). Falls back to ZOND_API / .zond/current-api.")
+    .option("--literal", "Store the value verbatim; do not strip a leading 'Bearer ' prefix.")
+    .action(async (key: string, value: string[], _opts, cmd: Command) => {
+      await setAction(key, value, cmd);
+    });
+}

package/src/cli/commands/session.ts

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import {
+  clearCurrentSession,
+  readCurrentSession,
+  sessionFilePath,
+  writeCurrentSession,
+  type SessionRecord,
+} from "../../core/context/session.ts";
+import { jsonError, jsonOk, printJson } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+import { listSessions, countSessions } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
+import { parsePositiveInt } from "../argv.ts";
+
+export interface SessionStartOptions {
+  label?: string;
+  id?: string;
+  json?: boolean;
+  /** ARV-155: replace the existing active session instead of erroring out
+   *  ("Session already active …"). Useful in ralph-loop iterations where a
+   *  previous turn left a stale `.zond/current-session` behind. */
+  force?: boolean;
+}
+
+export interface SessionEndOptions {
+  json?: boolean;
+}
+
+export interface SessionStatusOptions {
+  json?: boolean;
+}
+
+function isValidUuid(s: string): boolean {
+  // Permissive — accept any RFC4122-shaped UUID (v1-v8) and zero-UUID for tests.
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s);
+}
+
+export async function sessionStartCommand(opts: SessionStartOptions): Promise<number> {
+  const existing = readCurrentSession();
+  if (existing && !opts.force) {
+    const message =
+      `Session already active (${existing.id}). Run 'zond session end' first, or pass --force to replace it.`;
+    if (opts.json) printJson(jsonError("session", [message]));
+    else printError(message);
+    return 1;
+  }
+  if (existing && opts.force) {
+    clearCurrentSession();
+    if (!opts.json) {
+      process.stdout.write(`  Replaced active session ${existing.id}${existing.label ? ` (${existing.label})` : ""}.\n`);
+    }
+  }
+
+  let id = opts.id?.trim();
+  if (id && !isValidUuid(id)) {
+    const message = `Invalid --id: ${id} is not a UUID`;
+    if (opts.json) printJson(jsonError("session", [message]));
+    else printError(message);
+    return 1;
+  }
+  if (!id) id = randomUUID();
+
+  const record: SessionRecord = {
+    id,
+    label: opts.label?.trim() || undefined,
+    started_at: new Date().toISOString(),
+  };
+
+  let path: string;
+  try {
+    path = writeCurrentSession(record);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) printJson(jsonError("session", [message]));
+    else printError(message);
+    return 1;
+  }
+
+  if (opts.json) {
+    printJson(jsonOk("session", { action: "started", ...record, path }));
+  } else {
+    printSuccess(`Session ${record.id} started${record.label ? ` (${record.label})` : ""}`);
+    process.stdout.write(`  All subsequent 'zond run' calls in this workspace inherit this session_id.\n`);
+    process.stdout.write(`  Stored at ${path}. Run 'zond session end' to clear.\n`);
+  }
+  return 0;
+}
+
+export async function sessionEndCommand(opts: SessionEndOptions): Promise<number> {
+  const existing = readCurrentSession();
+  const path = sessionFilePath();
+  const removed = clearCurrentSession();
+
+  if (opts.json) {
+    printJson(jsonOk("session", {
+      action: "ended",
+      removed,
+      previous_id: existing?.id ?? null,
+      path,
+    }));
+    return 0;
+  }
+
+  if (!removed) {
+    process.stdout.write(`No active session (${path} not present).\n`);
+    return 0;
+  }
+  printSuccess(`Session ${existing?.id ?? "(unknown)"} ended`);
+  return 0;
+}
+
+export async function sessionStatusCommand(opts: SessionStatusOptions): Promise<number> {
+  const record = readCurrentSession();
+  const path = sessionFilePath();
+  const env = process.env.ZOND_SESSION_ID?.trim() || null;
+
+  if (opts.json) {
+    printJson(jsonOk("session", {
+      action: "status",
+      active: !!record,
+      session: record,
+      env_session_id: env,
+      path,
+    }));
+    return 0;
+  }
+
+  if (record) {
+    process.stdout.write(`session_id: ${record.id}\n`);
+    if (record.label) process.stdout.write(`label:      ${record.label}\n`);
+    process.stdout.write(`started_at: ${record.started_at}\n`);
+    process.stdout.write(`path:       ${path}\n`);
+    if (env && env !== record.id) {
+      process.stdout.write(`\nNote: ZOND_SESSION_ID is set to '${env}' and overrides the file.\n`);
+    }
+    return 0;
+  }
+
+  if (env) {
+    process.stdout.write(`No active session file. ZOND_SESSION_ID is set to '${env}' (env wins).\n`);
+    return 0;
+  }
+  process.stdout.write(
+    `No active session. Run 'zond session start' to group subsequent 'zond run' calls.\n`,
+  );
+  return 0;
+}
+
+// ARV-43: list past sessions surfaced from the runs table so users can
+// discover session_ids for `zond coverage --union session --session-id <id>`
+// without dropping into sqlite. Labels live only in .zond/current-session
+// (not persisted per run), so we only show what's stored in the DB.
+export interface SessionListOptions {
+  limit?: number;
+  json?: boolean;
+  dbPath?: string;
+}
+
+export async function sessionListCommand(opts: SessionListOptions): Promise<number> {
+  const limit = opts.limit ?? 20;
+  let sessions: ReturnType<typeof listSessions>;
+  let total: number;
+  try {
+    getDb(opts.dbPath);
+    sessions = listSessions(limit);
+    total = countSessions();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) printJson(jsonError("session", [message]));
+    else printError(message);
+    return 1;
+  }
+
+  if (opts.json) {
+    printJson(jsonOk("session", { action: "list", limit, total, sessions }));
+    return 0;
+  }
+
+  if (sessions.length === 0) {
+    process.stdout.write("No sessions recorded yet. Run 'zond session start' before 'zond run' to group runs.\n");
+    return 0;
+  }
+  process.stdout.write(`Showing ${sessions.length} of ${total} session(s):\n\n`);
+  process.stdout.write("session_id                            started_at            finished_at           runs   pass/fail/skip\n");
+  for (const s of sessions) {
+    const started = s.started_at ? s.started_at.replace("T", " ").slice(0, 19) : "—".padEnd(19);
+    const finished = s.finished_at ? s.finished_at.replace("T", " ").slice(0, 19) : "(open)".padEnd(19);
+    const runs = String(s.run_count).padStart(4);
+    const counts = `${s.passed}/${s.failed}/${s.skipped}`;
+    process.stdout.write(`${s.session_id}  ${started}   ${finished}   ${runs}   ${counts}\n`);
+  }
+  return 0;
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerSession(program: Command): void {
+  // Group multiple `zond run` calls under one session_id without juggling env
+  // vars. `start` writes a UUID to .zond/current-session; subsequent `run`
+  // calls auto-pick it up (priority: --session-id flag > ZOND_SESSION_ID env
+  // > current-session file).
+  const session = program.command("session").description("Manage run grouping (campaigns)");
+  session
+    .command("start")
+    .description("Begin a session — group all subsequent 'zond run' calls under one session_id (.zond/current-session)")
+    .option("--label <text>", "Optional human-readable label shown alongside the session in the UI")
+    .option("--id <uuid>", "Reuse a specific UUID instead of generating one (useful for CI)")
+    .option("--force", "Replace any already-active session instead of erroring out (ARV-155)")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await sessionStartCommand({
+        label: opts.label,
+        id: opts.id,
+        force: opts.force === true,
+        json: globalJson(cmd),
+      });
+    });
+  session
+    .command("end")
+    .description("End the current session — remove .zond/current-session")
+    .action(async (_opts, cmd: Command) => {
+      process.exitCode = await sessionEndCommand({ json: globalJson(cmd) });
+    });
+  session
+    .command("status")
+    .description("Show the active session (if any)")
+    .action(async (_opts, cmd: Command) => {
+      process.exitCode = await sessionStatusCommand({ json: globalJson(cmd) });
+    });
+  // ARV-43: complete the start/end/status/list quartet so coverage --union
+  // session --session-id <id> is discoverable without sqlite spelunking.
+  session
+    .command("list")
+    .description("List recent sessions (id, started_at, finished_at, run counts) so coverage --session-id is discoverable")
+    .option("--limit <n>", "Max sessions to print (default 20)", parsePositiveInt("--limit"))
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (opts, cmd: Command) => {
+      process.exitCode = await sessionListCommand({
+        limit: opts.limit,
+        dbPath: opts.db,
+        json: globalJson(cmd),
+      });
+    });
+}

package/src/cli/commands/use.ts

@@ -23,7 +23,7 @@ export async function useCommand(opts: UseOptions): Promise<number> {
     } else if (removed) {
       printSuccess(`Cleared ${path}`);
     } else {
-      process.stdout.write(`No .zond-current file in ${process.cwd()}\n`);
+      process.stdout.write(`No .zond/current-api file in ${process.cwd()}\n`);
     }
     return 0;
   }
@@ -55,3 +55,20 @@ export async function useCommand(opts: UseOptions): Promise<number> {
   }
   return 0;
 }
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerUse(program: Command): void {
+  program
+    .command("use [api]")
+    .description("Set or show the current API for this workspace (.zond/current-api). TASK-290: resolution chain is per-cmd --api > global --api > ZOND_API env > this file.")
+    .option("--clear", "Remove .zond/current-api from the workspace")
+    .action(async (api: string | undefined, opts, cmd: Command) => {
+      process.exitCode = await useCommand({
+        api,
+        clear: opts.clear === true,
+        json: globalJson(cmd),
+      });
+    });
+}

package/src/cli/index.ts

@@ -1,12 +1,29 @@
 #!/usr/bin/env bun
 
+import { createHash } from "node:crypto";
 import { CommanderError } from "commander";
 import { buildProgram, preprocessArgv } from "./program.ts";
-import { printError } from "./output.ts";
 import { VERSION } from "./version.ts";
 
 export { VERSION };
 
+/**
+ * Anything that reaches this handler is an *unexpected* throw — command
+ * implementations are expected to catch their own usage/config errors and
+ * return exit 2 themselves. Tag these with `[zond:internal]` so operators
+ * can tell them apart from sandbox/SIGKILL/OOM (137/143). See ZOND.md →
+ * "Exit codes" for the full taxonomy.
+ */
+function reportInternalError(err: unknown): void {
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error && err.stack ? err.stack : message;
+  const stackHash = createHash("sha1").update(stack).digest("hex").slice(0, 8);
+  process.stderr.write(`[zond:internal] zond ${VERSION} — uncaught ${message} (stack ${stackHash})\n`);
+  if (err instanceof Error && err.stack) {
+    process.stderr.write(err.stack + "\n");
+  }
+}
+
 async function main(): Promise<void> {
   const program = buildProgram();
   try {
@@ -22,8 +39,8 @@ async function main(): Promise<void> {
       process.exitCode = 2;
       return;
     }
-    printError(err instanceof Error ? err.message : String(err));
-    process.exitCode = 2;
+    reportInternalError(err);
+    process.exitCode = 3;
   }
 }
 

package/src/cli/json-envelope.ts

@@ -1,19 +1,108 @@
+/**
+ * Single source of truth for `--json` output across all CLI commands.
+ *
+ * Every `--json` response carries the same envelope:
+ *
+ *   { ok, command, data, warnings, errors, exit_code? }
+ *
+ * Commands construct the payload (`data`) and ask one of the helpers
+ * below to render it. Don't `console.log(JSON.stringify(...))` ad-hoc
+ * for `--json` paths — go through `printJson` / `writeEnvelope` so the
+ * shape stays uniform (TASK-73, TASK-74, closed by TASK-184).
+ *
+ * TASK-296: errors[] is a list of `{code, message, details?}` so an
+ * agent can route on `code` without parsing the human message. Helpers
+ * accept either a bare `string` (auto-wrapped with code `unknown_error`)
+ * or a structured `ZondError` to keep call sites short.
+ */
+
+// TASK-295: types are derived from the zod schemas in `./json-schemas.ts`
+// so the published JSON Schema (docs/json-schema/) and the runtime types
+// can never drift. Edit the enum/object there, run `bun run schemas`,
+// commit the regenerated docs.
+import type { z } from "zod";
+import {
+  ZondErrorCodeSchema,
+  ZondErrorSchema,
+} from "./json-schemas.ts";
+
+export type ZondErrorCode = z.infer<typeof ZondErrorCodeSchema>;
+export type ZondError = z.infer<typeof ZondErrorSchema>;
+
 export interface JsonEnvelope<T = unknown> {
   ok: boolean;
   command: string;
   data: T;
   warnings: string[];
-  errors: string[];
+  errors: ZondError[];
+  /** Exit code the process will return. Present on error envelopes so a
+   *  caller can read the taxonomy class without re-parsing $? from a shell
+   *  (see ZOND.md → "Exit codes"). */
+  exit_code?: number;
+}
+
+/** Accept either a bare string (auto-coded `unknown_error`) or a fully-
+ *  structured `ZondError`. Lets us migrate ~100 call sites incrementally
+ *  without breaking the schema. */
+export type ErrorInput = string | ZondError;
+
+function normalizeErrors(errs: readonly ErrorInput[]): ZondError[] {
+  return errs.map(e =>
+    typeof e === "string" ? { code: "unknown_error" as const, message: e } : e,
+  );
 }
 
 export function jsonOk<T>(command: string, data: T, warnings?: string[]): JsonEnvelope<T> {
   return { ok: true, command, data, warnings: warnings ?? [], errors: [] };
 }
 
-export function jsonError(command: string, errors: string[], warnings?: string[]): JsonEnvelope<null> {
-  return { ok: false, command, data: null, warnings: warnings ?? [], errors };
+export function jsonError(
+  command: string,
+  errors: readonly ErrorInput[],
+  warnings?: string[],
+  exitCode = 2,
+): JsonEnvelope<null> {
+  return {
+    ok: false,
+    command,
+    data: null,
+    warnings: warnings ?? [],
+    errors: normalizeErrors(errors),
+    exit_code: exitCode,
+  };
 }
 
 export function printJson(envelope: JsonEnvelope): void {
   process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
 }
+
+/** Convenience constructor: `zerr("env_missing", "base_url not set", { var: "base_url" })`. */
+export function zerr(code: ZondErrorCode, message: string, details?: Record<string, unknown>): ZondError {
+  return details ? { code, message, details } : { code, message };
+}
+
+/** Discriminated-union result an action can hand back to {@link writeEnvelope}. */
+export type EnvelopeResult<T> =
+  | { ok: true; data: T; warnings?: string[] }
+  | { ok: false; errors: readonly ErrorInput[]; warnings?: string[]; exitCode?: number };
+
+/**
+ * Render a typed `EnvelopeResult` to stdout as a JSON envelope and return
+ * the process exit code (0 on ok, `result.exitCode ?? 2` on error). This
+ * is the recommended wrapper for new commands — it lets the handler
+ * focus on producing a payload and surfaces the right exit code in one
+ * call:
+ *
+ *     const result = await doWork();
+ *     if (options.json) return writeEnvelope("my-cmd", result);
+ *     // …human path…
+ */
+export function writeEnvelope<T>(command: string, result: EnvelopeResult<T>): number {
+  if (result.ok) {
+    printJson(jsonOk(command, result.data, result.warnings));
+    return 0;
+  }
+  const exit = result.exitCode ?? 2;
+  printJson(jsonError(command, result.errors, result.warnings, exit));
+  return exit;
+}