@crediolabs/policy-builder-cli 0.1.0

package/dist/bin/policy-builder.d.ts

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

package/dist/bin/policy-builder.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// apps/policy-builder-cli/bin/policy-builder.ts - subcommand router.
+//
+// Usage:
+//   policy-builder record --network <mainnet|testnet> --hash <tx>
+//                                 [--xdr <b64>] [--json] [--quiet] [--out <path>]
+//   policy-builder synthesize --mandate <path.json>
+//                              [--json] [--quiet] [--out <path>]
+//   policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
+//                              [--responses <path.json>]
+//                              [--json] [--quiet] [--out <path>]
+//
+// The router is hand-rolled (no commander / yargs dep). It splits argv into
+// `command + subcommand-flags + global-flags` and dispatches to the matching
+// command body. Bad args -> CliError -> non-zero exit (JSON envelope under
+// --json).
+import { runRecordCommand } from "../src/commands/record.js";
+import { runSynthesizeCommand } from "../src/commands/synthesize.js";
+import { emitCliError, parseFlags } from "../src/output.js";
+async function main() {
+    const argv = process.argv.slice(2);
+    const command = argv[0];
+    const subcommandArgs = argv.slice(1);
+    // Pull out --json/--quiet/--out first so they survive any position.
+    // We re-parse the subcommand args below so command bodies can use
+    // parsePairs cleanly (those strip the leading -- prefix).
+    const flags = parseFlags(subcommandArgs);
+    try {
+        switch (command) {
+            case 'record':
+                await runRecordCommand(subcommandArgs, flags);
+                return;
+            case 'synthesize':
+            case 'synth': {
+                await runSynthesizeCommand(subcommandArgs, flags);
+                return;
+            }
+            case 'help':
+            case '--help':
+            case '-h':
+            case undefined:
+                printHelp();
+                return;
+            default:
+                process.stderr.write(`unknown command: ${command}\n`);
+                printHelp();
+                process.exit(2);
+        }
+    }
+    catch (e) {
+        emitCliError(e, flags);
+    }
+}
+function printHelp() {
+    process.stdout.write(`policy-builder - OZ policy-synth CLI
+
+Usage:
+  policy-builder record     --network <mainnet|testnet> --hash <tx> | --xdr <b64>
+                            [--json] [--quiet] [--out <path>]
+  policy-builder synthesize --mandate <path.json>
+                            [--json] [--quiet] [--out <path>]
+  policy-builder synthesize --recorded-tx <path.json> --network <mainnet|testnet>
+                            [--responses <path.json>]
+                            [--json] [--quiet] [--out <path>]
+
+Flags:
+  --json     emit machine-readable JSON on stdout
+  --quiet    suppress progress / non-error output
+  --out      write artefact to file (JSON)
+`);
+}
+await main();

package/dist/src/commands/record.d.ts

@@ -0,0 +1,3 @@
+import type { RecordedTransaction } from '@crediolabs/policy-synth';
+import { type CliFlags } from '../output.ts';
+export declare function runRecordCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<RecordedTransaction>;

package/dist/src/commands/record.js

@@ -0,0 +1,42 @@
+// apps/policy-builder-cli/src/commands/record.ts
+//
+// `policy-builder record` subcommand. Thin wrapper around the core
+// `recordTransaction` - no business logic, just argv -> RecordInput + the
+// canonical CLI envelope.
+import { runRecordTransaction } from '@crediolabs/policy-builder-mcp';
+import { CliError, formatToolResponse, parsePairs } from "../output.js";
+export async function runRecordCommand(argv, flags) {
+    const pairs = parsePairs(argv);
+    const network = pairs.network;
+    if (!network) {
+        throw new CliError({
+            code: 'CLI_MISSING_ARG',
+            message: 'record: --network <mainnet|testnet> is required',
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    if (!pairs.hash && !pairs.xdr) {
+        throw new CliError({
+            code: 'CLI_MISSING_ARG',
+            message: 'record: exactly one of --hash <tx> or --xdr <b64> is required',
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    if (pairs.hash && pairs.xdr) {
+        throw new CliError({
+            code: 'CLI_MISSING_ARG',
+            message: 'record: provide exactly one of --hash or --xdr, not both',
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    const args = { network };
+    if (pairs.hash)
+        args.hash = pairs.hash;
+    if (pairs.xdr)
+        args.xdr = pairs.xdr;
+    const res = await runRecordTransaction(args);
+    return formatToolResponse(res, flags, 'record');
+}

package/dist/src/commands/synthesize.d.ts

@@ -0,0 +1,3 @@
+import type { ProposedPolicy } from '@crediolabs/policy-synth';
+import { type CliFlags } from '../output.ts';
+export declare function runSynthesizeCommand(argv: ReadonlyArray<string>, flags: CliFlags): Promise<ProposedPolicy>;

package/dist/src/commands/synthesize.js

@@ -0,0 +1,46 @@
+// apps/policy-builder-cli/src/commands/synthesize.ts
+//
+// `policy-builder synthesize` subcommand. Dispatches to ONE of the two
+// front-ends (mandate / recording) based on which file flag is supplied:
+//   --mandate <path.json>     -> synthesizeFromMandate
+//   --recorded-tx <path.json> -> synthesizeFromRecording
+//
+// The CLI mirrors the MCP tool's discriminated union: one subcommand, two
+// front-ends, mutually exclusive.
+import { runSynthesizePolicy } from '@crediolabs/policy-builder-mcp';
+import { CliError, formatToolResponse, parsePairs, readJsonFile } from "../output.js";
+export async function runSynthesizeCommand(argv, flags) {
+    const pairs = parsePairs(argv);
+    const hasMandate = Boolean(pairs.mandate);
+    const hasRecorded = Boolean(pairs['recorded-tx']);
+    if (hasMandate === hasRecorded) {
+        throw new CliError({
+            code: 'CLI_MISSING_ARG',
+            message: 'synthesize: exactly one of --mandate <path> or --recorded-tx <path> is required',
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    if (hasMandate) {
+        const mandate = readJsonFile(pairs.mandate);
+        const res = await runSynthesizePolicy({ source: 'mandate', mandate });
+        return formatToolResponse(res, flags, 'synthesize(mandate)');
+    }
+    // hasRecorded
+    const recordedTx = readJsonFile(pairs['recorded-tx']);
+    const network = pairs.network;
+    if (!network) {
+        throw new CliError({
+            code: 'CLI_MISSING_ARG',
+            message: 'synthesize: --network <mainnet|testnet> is required with --recorded-tx',
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    const args = { source: 'recording', recordedTx, network };
+    if (pairs.responses) {
+        args.userResponses = readJsonFile(pairs.responses);
+    }
+    const res = await runSynthesizePolicy(args);
+    return formatToolResponse(res, flags, 'synthesize(recording)');
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { runRecordCommand } from './commands/record.ts';
+export { runSynthesizeCommand } from './commands/synthesize.ts';
+export { formatToolResponse, readJsonFile, writeJsonFile } from './output.ts';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+// apps/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
+export { runRecordCommand } from "./commands/record.js";
+export { runSynthesizeCommand } from "./commands/synthesize.js";
+export { formatToolResponse, readJsonFile, writeJsonFile } from "./output.js";

package/dist/src/output.d.ts

@@ -0,0 +1,49 @@
+import type { ErrorCode, ToolError, ToolResponse } from '@crediolabs/policy-synth';
+/** CLI flags (the only ones shipped in T1). */
+export interface CliFlags {
+    json: boolean;
+    quiet: boolean;
+    out: string | null;
+}
+/** Parse the argv tail for the known flags. Unrecognised flags are ignored
+ *  (the caller enforces per-subcommand required flags separately). */
+export declare function parseFlags(argv: ReadonlyArray<string>): CliFlags;
+/** Resolve `--value <v>` style pairs after the subcommand name. Returns
+ *  an object keyed by the option name (without `--`). Throws on missing
+ *  value or duplicate keys. */
+export declare function parsePairs(argv: ReadonlyArray<string>): Record<string, string>;
+/** Read a JSON file, parse it, and return the value. Throws with a CLI-
+ *  friendly error if the file is missing or malformed. */
+export declare function readJsonFile(path: string): unknown;
+/** Write a JSON-serialisable value to disk. Pretty-prints by default so the
+ *  artefact is human-readable; CI scripts that need compact JSON can pipe
+ *  through `jq` instead. */
+export declare function writeJsonFile(path: string, value: unknown): void;
+/** Wraps a core ToolResponse for the CLI:
+ *    - always prints something useful (JSON or a short summary)
+ *    - exits non-zero on ToolError so CI scripts can gate on `$?`
+ *    - writes the `{ ok, data }` envelope to --out when present (matches
+ *      the --json stdout shape so CI scripts get a single canonical payload)
+ *
+ *  Throws CliError so the router can map it to a process exit code + a
+ *  structured JSON envelope under --json. */
+export declare function formatToolResponse<T>(res: ToolResponse<T>, flags: CliFlags, outLabel?: string): T;
+/** CLI-specific error codes, distinct from the core's ErrorCode union. They
+ *  cover failures that arise around the core call (bad argv, missing or
+ *  malformed input files) and never collide with a core code. */
+export type CliErrorCode = 'CLI_MISSING_ARG' | 'CLI_FILE_NOT_FOUND' | 'CLI_INVALID_JSON' | 'CLI_INTERNAL';
+/** A ToolError whose `code` may be a core ErrorCode OR a CLI-local code. The
+ *  CLI wraps both core failures and its own argv / IO failures in this shape;
+ *  a core ToolError is assignable here since ErrorCode is a subset. */
+export type CliToolError = Omit<ToolError, 'code'> & {
+    code: ErrorCode | CliErrorCode;
+};
+/** CLI-local error class wrapping a (core or CLI) ToolError so the router can
+ *  map it to a non-zero exit. The error is preserved verbatim for --json. */
+export declare class CliError extends Error {
+    readonly toolError: CliToolError;
+    constructor(err: CliToolError);
+}
+/** Pretty-print a CliError to stderr and exit non-zero. Used by the router
+ *  when the catch fires. */
+export declare function emitCliError(e: unknown, flags: CliFlags): never;

package/dist/src/output.js

@@ -0,0 +1,137 @@
+// apps/policy-builder-cli/src/output.ts
+//
+// Output helpers for the CLI: formatToolResponse for the `--json` flag and
+// file I/O for `--out`. The CLI is intentionally tiny - no commander / yargs
+// dependency; the router is a hand-rolled argv parser.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** Parse the argv tail for the known flags. Unrecognised flags are ignored
+ *  (the caller enforces per-subcommand required flags separately). */
+export function parseFlags(argv) {
+    let json = false;
+    let quiet = false;
+    let out = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--json')
+            json = true;
+        else if (a === '--quiet')
+            quiet = true;
+        else if (a === '--out' && argv[i + 1]) {
+            out = argv[i + 1];
+            i++;
+        }
+        else if (a?.startsWith('--out=')) {
+            out = a.slice('--out='.length);
+        }
+    }
+    return { json, quiet, out };
+}
+/** Resolve `--value <v>` style pairs after the subcommand name. Returns
+ *  an object keyed by the option name (without `--`). Throws on missing
+ *  value or duplicate keys. */
+export function parsePairs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a?.startsWith('--') && a.includes('=')) {
+            const eq = a.indexOf('=');
+            const key = a.slice(2, eq);
+            const val = a.slice(eq + 1);
+            if (key && val !== undefined)
+                out[key] = val;
+        }
+        else if (a?.startsWith('--') && argv[i + 1] && !argv[i + 1]?.startsWith('--')) {
+            const key = a.slice(2);
+            const val = argv[i + 1];
+            out[key] = val;
+            i++;
+        }
+    }
+    return out;
+}
+/** Read a JSON file, parse it, and return the value. Throws with a CLI-
+ *  friendly error if the file is missing or malformed. */
+export function readJsonFile(path) {
+    const abs = resolve(path);
+    if (!existsSync(abs)) {
+        throw new CliError({
+            code: 'CLI_FILE_NOT_FOUND',
+            message: `file not found: ${path}`,
+            severity: 'error',
+            retryable: false,
+        });
+    }
+    const raw = readFileSync(abs, 'utf8');
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new CliError({
+            code: 'CLI_INVALID_JSON',
+            message: `invalid JSON in ${path}: ${e.message}`,
+            severity: 'error',
+            retryable: false,
+        });
+    }
+}
+/** Write a JSON-serialisable value to disk. Pretty-prints by default so the
+ *  artefact is human-readable; CI scripts that need compact JSON can pipe
+ *  through `jq` instead. */
+export function writeJsonFile(path, value) {
+    const abs = resolve(path);
+    writeFileSync(abs, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+/** Wraps a core ToolResponse for the CLI:
+ *    - always prints something useful (JSON or a short summary)
+ *    - exits non-zero on ToolError so CI scripts can gate on `$?`
+ *    - writes the `{ ok, data }` envelope to --out when present (matches
+ *      the --json stdout shape so CI scripts get a single canonical payload)
+ *
+ *  Throws CliError so the router can map it to a process exit code + a
+ *  structured JSON envelope under --json. */
+export function formatToolResponse(res, flags, outLabel = 'result') {
+    if (res.ok) {
+        const envelope = { ok: true, data: res.data };
+        if (flags.out)
+            writeJsonFile(flags.out, envelope);
+        if (flags.json) {
+            // newline-terminated JSON so it pipes cleanly
+            process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else if (!flags.quiet) {
+            process.stdout.write(`${outLabel}: ok\n`);
+        }
+        return res.data;
+    }
+    throw new CliError(res.error);
+}
+/** CLI-local error class wrapping a (core or CLI) ToolError so the router can
+ *  map it to a non-zero exit. The error is preserved verbatim for --json. */
+export class CliError extends Error {
+    toolError;
+    constructor(err) {
+        super(err.message);
+        this.toolError = err;
+    }
+}
+/** Pretty-print a CliError to stderr and exit non-zero. Used by the router
+ *  when the catch fires. */
+export function emitCliError(e, flags) {
+    if (e instanceof CliError) {
+        if (flags.json) {
+            process.stdout.write(`${JSON.stringify({ ok: false, error: e.toolError })}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${e.toolError.code} - ${e.toolError.message}\n`);
+        }
+        process.exit(1);
+    }
+    if (flags.json) {
+        process.stdout.write(`${JSON.stringify({ ok: false, error: { code: 'CLI_INTERNAL', message: e.message, severity: 'fatal', retryable: false } })}\n`);
+    }
+    else {
+        process.stderr.write(`internal error: ${e.message}\n`);
+    }
+    process.exit(2);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crediolabs/policy-builder-cli",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "CLI wrapper around the OZ policy-synth core (record + synthesize) for solo-dev and CI workflows.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "policy-builder": "./dist/bin/policy-builder.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@crediolabs/policy-builder-mcp": "^0.1.0",
+    "@crediolabs/policy-synth": "^0.1.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.5",
+    "@types/node": "^26.1.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/commands/record.ts

@@ -0,0 +1,46 @@
+// apps/policy-builder-cli/src/commands/record.ts
+//
+// `policy-builder record` subcommand. Thin wrapper around the core
+// `recordTransaction` - no business logic, just argv -> RecordInput + the
+// canonical CLI envelope.
+
+import { runRecordTransaction } from '@crediolabs/policy-builder-mcp'
+import type { RecordedTransaction } from '@crediolabs/policy-synth'
+import { CliError, type CliFlags, formatToolResponse, parsePairs } from '../output.ts'
+
+export async function runRecordCommand(
+  argv: ReadonlyArray<string>,
+  flags: CliFlags
+): Promise<RecordedTransaction> {
+  const pairs = parsePairs(argv)
+  const network = pairs.network
+  if (!network) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: 'record: --network <mainnet|testnet> is required',
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  if (!pairs.hash && !pairs.xdr) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: 'record: exactly one of --hash <tx> or --xdr <b64> is required',
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  if (pairs.hash && pairs.xdr) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: 'record: provide exactly one of --hash or --xdr, not both',
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  const args: Record<string, unknown> = { network }
+  if (pairs.hash) args.hash = pairs.hash
+  if (pairs.xdr) args.xdr = pairs.xdr
+  const res = await runRecordTransaction(args)
+  return formatToolResponse(res, flags, 'record')
+}

package/src/commands/synthesize.ts

@@ -0,0 +1,54 @@
+// apps/policy-builder-cli/src/commands/synthesize.ts
+//
+// `policy-builder synthesize` subcommand. Dispatches to ONE of the two
+// front-ends (mandate / recording) based on which file flag is supplied:
+//   --mandate <path.json>     -> synthesizeFromMandate
+//   --recorded-tx <path.json> -> synthesizeFromRecording
+//
+// The CLI mirrors the MCP tool's discriminated union: one subcommand, two
+// front-ends, mutually exclusive.
+
+import { runSynthesizePolicy } from '@crediolabs/policy-builder-mcp'
+import type { ProposedPolicy } from '@crediolabs/policy-synth'
+import { CliError, type CliFlags, formatToolResponse, parsePairs, readJsonFile } from '../output.ts'
+
+export async function runSynthesizeCommand(
+  argv: ReadonlyArray<string>,
+  flags: CliFlags
+): Promise<ProposedPolicy> {
+  const pairs = parsePairs(argv)
+  const hasMandate = Boolean(pairs.mandate)
+  const hasRecorded = Boolean(pairs['recorded-tx'])
+  if (hasMandate === hasRecorded) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: 'synthesize: exactly one of --mandate <path> or --recorded-tx <path> is required',
+      severity: 'error',
+      retryable: false,
+    })
+  }
+
+  if (hasMandate) {
+    const mandate = readJsonFile(pairs.mandate as string) as Record<string, unknown>
+    const res = await runSynthesizePolicy({ source: 'mandate', mandate })
+    return formatToolResponse(res, flags, 'synthesize(mandate)')
+  }
+
+  // hasRecorded
+  const recordedTx = readJsonFile(pairs['recorded-tx'] as string) as Record<string, unknown>
+  const network = pairs.network
+  if (!network) {
+    throw new CliError({
+      code: 'CLI_MISSING_ARG',
+      message: 'synthesize: --network <mainnet|testnet> is required with --recorded-tx',
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  const args: Record<string, unknown> = { source: 'recording', recordedTx, network }
+  if (pairs.responses) {
+    args.userResponses = readJsonFile(pairs.responses)
+  }
+  const res = await runSynthesizePolicy(args)
+  return formatToolResponse(res, flags, 'synthesize(recording)')
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+// apps/policy-builder-cli/src/index.ts - public re-exports for the CLI package.
+
+export { runRecordCommand } from './commands/record.ts'
+export { runSynthesizeCommand } from './commands/synthesize.ts'
+export { formatToolResponse, readJsonFile, writeJsonFile } from './output.ts'

package/src/output.ts

@@ -0,0 +1,163 @@
+// apps/policy-builder-cli/src/output.ts
+//
+// Output helpers for the CLI: formatToolResponse for the `--json` flag and
+// file I/O for `--out`. The CLI is intentionally tiny - no commander / yargs
+// dependency; the router is a hand-rolled argv parser.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { ErrorCode, ToolError, ToolResponse } from '@crediolabs/policy-synth'
+
+/** CLI flags (the only ones shipped in T1). */
+export interface CliFlags {
+  json: boolean
+  quiet: boolean
+  out: string | null
+}
+
+/** Parse the argv tail for the known flags. Unrecognised flags are ignored
+ *  (the caller enforces per-subcommand required flags separately). */
+export function parseFlags(argv: ReadonlyArray<string>): CliFlags {
+  let json = false
+  let quiet = false
+  let out: string | null = null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') json = true
+    else if (a === '--quiet') quiet = true
+    else if (a === '--out' && argv[i + 1]) {
+      out = argv[i + 1] as string
+      i++
+    } else if (a?.startsWith('--out=')) {
+      out = a.slice('--out='.length)
+    }
+  }
+  return { json, quiet, out }
+}
+
+/** Resolve `--value <v>` style pairs after the subcommand name. Returns
+ *  an object keyed by the option name (without `--`). Throws on missing
+ *  value or duplicate keys. */
+export function parsePairs(argv: ReadonlyArray<string>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a?.startsWith('--') && a.includes('=')) {
+      const eq = a.indexOf('=')
+      const key = a.slice(2, eq)
+      const val = a.slice(eq + 1)
+      if (key && val !== undefined) out[key] = val
+    } else if (a?.startsWith('--') && argv[i + 1] && !argv[i + 1]?.startsWith('--')) {
+      const key = a.slice(2)
+      const val = argv[i + 1] as string
+      out[key] = val
+      i++
+    }
+  }
+  return out
+}
+
+/** Read a JSON file, parse it, and return the value. Throws with a CLI-
+ *  friendly error if the file is missing or malformed. */
+export function readJsonFile(path: string): unknown {
+  const abs = resolve(path)
+  if (!existsSync(abs)) {
+    throw new CliError({
+      code: 'CLI_FILE_NOT_FOUND',
+      message: `file not found: ${path}`,
+      severity: 'error',
+      retryable: false,
+    })
+  }
+  const raw = readFileSync(abs, 'utf8')
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    throw new CliError({
+      code: 'CLI_INVALID_JSON',
+      message: `invalid JSON in ${path}: ${(e as Error).message}`,
+      severity: 'error',
+      retryable: false,
+    })
+  }
+}
+
+/** Write a JSON-serialisable value to disk. Pretty-prints by default so the
+ *  artefact is human-readable; CI scripts that need compact JSON can pipe
+ *  through `jq` instead. */
+export function writeJsonFile(path: string, value: unknown): void {
+  const abs = resolve(path)
+  writeFileSync(abs, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}
+
+/** Wraps a core ToolResponse for the CLI:
+ *    - always prints something useful (JSON or a short summary)
+ *    - exits non-zero on ToolError so CI scripts can gate on `$?`
+ *    - writes the `{ ok, data }` envelope to --out when present (matches
+ *      the --json stdout shape so CI scripts get a single canonical payload)
+ *
+ *  Throws CliError so the router can map it to a process exit code + a
+ *  structured JSON envelope under --json. */
+export function formatToolResponse<T>(
+  res: ToolResponse<T>,
+  flags: CliFlags,
+  outLabel = 'result'
+): T {
+  if (res.ok) {
+    const envelope = { ok: true as const, data: res.data }
+    if (flags.out) writeJsonFile(flags.out, envelope)
+    if (flags.json) {
+      // newline-terminated JSON so it pipes cleanly
+      process.stdout.write(`${JSON.stringify(envelope)}\n`)
+    } else if (!flags.quiet) {
+      process.stdout.write(`${outLabel}: ok\n`)
+    }
+    return res.data
+  }
+  throw new CliError(res.error)
+}
+
+/** CLI-specific error codes, distinct from the core's ErrorCode union. They
+ *  cover failures that arise around the core call (bad argv, missing or
+ *  malformed input files) and never collide with a core code. */
+export type CliErrorCode =
+  | 'CLI_MISSING_ARG'
+  | 'CLI_FILE_NOT_FOUND'
+  | 'CLI_INVALID_JSON'
+  | 'CLI_INTERNAL'
+
+/** A ToolError whose `code` may be a core ErrorCode OR a CLI-local code. The
+ *  CLI wraps both core failures and its own argv / IO failures in this shape;
+ *  a core ToolError is assignable here since ErrorCode is a subset. */
+export type CliToolError = Omit<ToolError, 'code'> & { code: ErrorCode | CliErrorCode }
+
+/** CLI-local error class wrapping a (core or CLI) ToolError so the router can
+ *  map it to a non-zero exit. The error is preserved verbatim for --json. */
+export class CliError extends Error {
+  readonly toolError: CliToolError
+  constructor(err: CliToolError) {
+    super(err.message)
+    this.toolError = err
+  }
+}
+
+/** Pretty-print a CliError to stderr and exit non-zero. Used by the router
+ *  when the catch fires. */
+export function emitCliError(e: unknown, flags: CliFlags): never {
+  if (e instanceof CliError) {
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, error: e.toolError })}\n`)
+    } else {
+      process.stderr.write(`error: ${e.toolError.code} - ${e.toolError.message}\n`)
+    }
+    process.exit(1)
+  }
+  if (flags.json) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: false, error: { code: 'CLI_INTERNAL', message: (e as Error).message, severity: 'fatal', retryable: false } })}\n`
+    )
+  } else {
+    process.stderr.write(`internal error: ${(e as Error).message}\n`)
+  }
+  process.exit(2)
+}