@oscharko-dev/keiko 0.1.0-beta.0

package/dist/audit/types.js

@@ -0,0 +1,8 @@
+// All Evidence* interfaces, the retention/redaction config, the injectable deps, and the frozen
+// EVIDENCE_SCHEMA_VERSION / DEFAULT_RETENTION tables (ADR-0010 D2/D6/D10). No runtime logic beyond
+// the two frozen tables. Everything here is plain-JSON, deeply readonly, and JSON-serializable:
+// timestamps are epoch-ms numbers sourced from events/RunResult, never Date objects.
+// The schema discriminant — distinct from the harness event `schemaVersion`. A breaking change
+// produces "2" as a NEW union member rather than mutating "1" (ADR-0010 D2).
+export const EVIDENCE_SCHEMA_VERSION = "1";
+export const DEFAULT_RETENTION = { maxRuns: 50 };

package/dist/audit/workflow-evidence.d.ts

@@ -0,0 +1,27 @@
+import { type EvidenceReport } from "./report.js";
+import { type EvidenceManifest } from "./types.js";
+import type { EvidenceStore } from "./store.js";
+import type { EnvSource } from "../gateway/index.js";
+export type WorkflowRunKind = "unit-tests" | "bug-investigation";
+export type WorkflowTerminalStatus = "completed" | "cancelled" | "failed";
+export interface EvidencePersistContext {
+    readonly store: EvidenceStore;
+    readonly env: EnvSource;
+    readonly additionalSecrets?: readonly string[] | undefined;
+}
+export interface WorkflowRunIdentity {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly modelId: string;
+    readonly kind: WorkflowRunKind;
+    readonly status: WorkflowTerminalStatus;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly workspaceRoot?: string | undefined;
+}
+export interface WorkflowEventLike {
+    readonly type: string;
+}
+export declare function foldWorkflowUsage(events: readonly WorkflowEventLike[]): EvidenceManifest["usageTotals"];
+export declare function buildWorkflowManifest(identity: WorkflowRunIdentity, events: readonly WorkflowEventLike[], report: unknown): EvidenceManifest;
+export declare function persistWorkflowEvidence(identity: WorkflowRunIdentity, report: unknown, events: readonly WorkflowEventLike[], ctx: EvidencePersistContext): EvidenceReport;

package/dist/audit/workflow-evidence.js

@@ -0,0 +1,145 @@
+// Shared workflow→EvidenceManifest mapping (ADR-0010 + ADR-0011 AC5 + ADR-0012 D9/C2). This is the
+// PURE, surface-agnostic core that folds a terminated workflow run (its typed report + buffered
+// events) into a redacted, versioned EvidenceManifest and writes it through the #10 EvidenceStore.
+//
+// It was extracted from src/ui/evidence.ts so BOTH the UI BFF and the evaluation harness build the
+// manifest from one implementation. The dependency direction is preserved: this module lives in the
+// audit layer and imports only audit + harness + gateway primitives. It defines its own narrow
+// `WorkflowRunKind` / `WorkflowTerminalStatus` so it never depends on src/ui types. The UI
+// re-exports it (behaviour-preserving); the evaluation runner imports it directly.
+//
+import { buildEvidenceReport } from "./report.js";
+import { resolveCostClass } from "./aggregate.js";
+import { createAuditRedactor, deepRedactStrings } from "./redaction.js";
+import { EVIDENCE_SCHEMA_VERSION } from "./types.js";
+import { HARNESS_VERSION } from "../harness/index.js";
+const KIND_TO_TASK_TYPE = {
+    "unit-tests": "generate-unit-tests",
+    "bug-investigation": "investigate-bug",
+};
+// Folds the buffered `workflow:model:call:completed` events into usage totals. The workflow event
+// carries token/latency fields at the TOP level (not under `usage` like the harness event), so this
+// sums the four dimensions directly rather than reusing the audit `aggregateUsage` fold.
+export function foldWorkflowUsage(events) {
+    let promptTokens = 0;
+    let completionTokens = 0;
+    let requestCount = 0;
+    let totalLatencyMs = 0;
+    for (const event of events) {
+        if (event.type !== "workflow:model:call:completed" &&
+            event.type !== "bug:model:call:completed") {
+            continue;
+        }
+        const record = event;
+        promptTokens += numberOf(record.promptTokens);
+        completionTokens += numberOf(record.completionTokens);
+        totalLatencyMs += numberOf(record.latencyMs);
+        requestCount += 1;
+    }
+    return { promptTokens, completionTokens, requestCount, totalLatencyMs };
+}
+function numberOf(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+export function buildWorkflowManifest(identity, events, report) {
+    return {
+        evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
+        run: {
+            runId: identity.runId,
+            fingerprint: identity.fingerprint,
+            harnessVersion: HARNESS_VERSION,
+            taskType: KIND_TO_TASK_TYPE[identity.kind],
+            outcome: identity.status,
+            startedAt: identity.startedAt,
+            finishedAt: identity.finishedAt,
+            durationMs: Math.max(0, identity.finishedAt - identity.startedAt),
+        },
+        model: { modelId: identity.modelId, costClass: resolveCostClass(identity.modelId) },
+        usageTotals: foldWorkflowUsage(events),
+        ...(contextOf(identity.workspaceRoot) === undefined
+            ? {}
+            : { context: contextOf(identity.workspaceRoot) }),
+        stateTransitions: [],
+        toolCalls: [],
+        commandExecutions: [],
+        verification: verificationOf(report),
+        patch: patchOf(report),
+        failure: undefined,
+    };
+}
+function contextOf(workspaceRoot) {
+    if (workspaceRoot === undefined) {
+        return undefined;
+    }
+    return {
+        workspaceRoot,
+        totalCandidates: 0,
+        usedBytes: 0,
+        budgetBytes: 0,
+        droppedForBudget: 0,
+        entries: [],
+    };
+}
+// Builds, redacts, writes the workflow manifest through the store, and returns the structured
+// EvidenceReport. Errors intentionally surface to the caller so UI/evaluation paths cannot silently
+// claim a terminal run without a durable evidence artifact.
+export function persistWorkflowEvidence(identity, report, events, ctx) {
+    const manifest = buildWorkflowManifest(identity, events, report);
+    const redactor = createAuditRedactor({ additionalSecrets: ctx.additionalSecrets ?? [] }, ctx.env);
+    const redacted = deepRedactStrings(manifest, redactor);
+    const location = ctx.store.put(redacted.run.runId, JSON.stringify(redacted));
+    return buildEvidenceReport(redacted, location);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Extracts the verification audit summary from a workflow report when present. The summary is already
+// the audit shape; the deep redact in persist re-scrubs every string leaf for defense in depth.
+function verificationOf(report) {
+    if (!isRecord(report)) {
+        return undefined;
+    }
+    const summary = report.verificationSummary ?? verifiedVerificationOf(report);
+    return isRecord(summary) ? summary : undefined;
+}
+function verifiedVerificationOf(report) {
+    const verified = report.verified;
+    return isRecord(verified) ? verified.verification : undefined;
+}
+// Builds patch metadata (counts/bytes only, never the raw diff) from a workflow report. unit-tests
+// reports carry `addedTestFiles`; bug-investigation reports carry `changedFiles`.
+function patchOf(report) {
+    if (!isRecord(report)) {
+        return undefined;
+    }
+    const proposedDiff = report.proposedDiff;
+    const proposed = typeof proposedDiff === "string" && proposedDiff.length > 0;
+    const changedFiles = changedFileCount(report);
+    if (!proposed && changedFiles === 0) {
+        return undefined;
+    }
+    return {
+        proposed,
+        applied: patchApplied(report),
+        targetFileCount: changedFiles,
+        patchBytes: typeof proposedDiff === "string" ? Buffer.byteLength(proposedDiff, "utf8") : 0,
+        changedFiles,
+        created: 0,
+        deleted: 0,
+    };
+}
+function patchApplied(report) {
+    if (report.status === "completed" || report.status === "fix-applied") {
+        return true;
+    }
+    const verified = report.verified;
+    return isRecord(verified) && verified.patchApplied === true;
+}
+function changedFileCount(report) {
+    const added = report.addedTestFiles;
+    if (Array.isArray(added)) {
+        return added.length;
+    }
+    const changed = report.changedFiles;
+    return Array.isArray(changed) ? changed.length : 0;
+}

package/dist/cli/context.d.ts

@@ -0,0 +1,2 @@
+import type { CliIo } from "./runner.js";
+export declare function runContextCli(args: readonly string[], io: CliIo): number;

package/dist/cli/context.js

@@ -0,0 +1,102 @@
+// `keiko context` — a DRY-RUN-BY-CONSTRUCTION repository-context summary. It detects a
+// workspace, builds a redacted structured summary (and a context pack when --task/--budget is
+// given), and prints a human table or JSON. It NEVER constructs an agent session and NEVER
+// calls a model: there is no import of the harness/gateway run path in this file.
+import { detectWorkspace } from "../workspace/detect.js";
+import { discoverWithStats } from "../workspace/discovery.js";
+import { buildContextPackFromFiles } from "../workspace/contextPack.js";
+import { buildWorkspaceSummary } from "../workspace/summary.js";
+import { WorkspaceError } from "../workspace/errors.js";
+import { DEFAULT_CONTEXT_REQUEST } from "../workspace/types.js";
+const USAGE = `Usage:
+  keiko context [--dir PATH] [--task TEXT] [--budget BYTES] [--json]
+
+Detects the workspace, prints a redacted context summary, and (with --task or
+--budget) a deterministic context pack. Dry-run by construction: no model is called.
+`;
+// Returns the value of a `--flag value` pair, `undefined` if absent, or `null` if the flag is
+// present but missing its value (a usage error).
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1) {
+        return undefined;
+    }
+    const value = args[i + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+function parseArgs(args) {
+    const dirRaw = flagValue(args, "--dir");
+    const taskRaw = flagValue(args, "--task");
+    const budgetRaw = flagValue(args, "--budget");
+    if (dirRaw === null || taskRaw === null || budgetRaw === null) {
+        return null;
+    }
+    if (budgetRaw !== undefined && !/^[1-9][0-9]*$/.test(budgetRaw)) {
+        return null;
+    }
+    const budget = budgetRaw === undefined ? undefined : Number.parseInt(budgetRaw, 10);
+    if (budget !== undefined && !Number.isSafeInteger(budget)) {
+        return null;
+    }
+    return { dir: dirRaw ?? ".", task: taskRaw, budget, json: args.includes("--json") };
+}
+function buildSummary(parsed) {
+    const workspace = detectWorkspace(parsed.dir);
+    const { files, stats } = discoverWithStats(workspace, DEFAULT_CONTEXT_REQUEST.discovery);
+    const wantsPack = parsed.task !== undefined || parsed.budget !== undefined;
+    if (!wantsPack) {
+        return buildWorkspaceSummary(workspace, undefined, stats);
+    }
+    const pack = buildContextPackFromFiles(workspace, {
+        ...DEFAULT_CONTEXT_REQUEST,
+        task: parsed.task,
+        budgetBytes: parsed.budget ?? DEFAULT_CONTEXT_REQUEST.budgetBytes,
+    }, files);
+    return buildWorkspaceSummary(workspace, pack, stats);
+}
+function renderContext(summary, io) {
+    const context = summary.context;
+    if (context === undefined) {
+        return;
+    }
+    io.out(`Context:   used=${String(context.usedBytes)}/${String(context.budgetBytes)} bytes, dropped=${String(context.droppedForBudget)}\n`);
+    io.out("PATH\tREASON\tSIZE\tEXCERPT-BYTES\tTRUNCATED\n");
+    for (const entry of context.entries) {
+        io.out(`${entry.path}\t${entry.selectionReason}\t${String(entry.sizeBytes)}\t${String(entry.excerptBytes)}\t${entry.truncated ? "yes" : "no"}\n`);
+    }
+}
+function renderText(summary, io) {
+    io.out(`Workspace: ${summary.root}\n`);
+    io.out(`Name:      ${summary.name ?? "(none)"}\n`);
+    io.out(`Version:   ${summary.version ?? "(none)"}\n`);
+    io.out(`Framework: ${summary.testFramework}\n`);
+    io.out(`Sources:   ${summary.sourceDirs.join(", ") || "(none)"}\n`);
+    io.out(`Tests:     ${summary.testDirs.join(", ") || "(none)"}\n`);
+    io.out(`Languages: ${summary.languages.join(", ")}\n`);
+    io.out(`Counts:    discovered=${String(summary.counts.discovered)} denied=${String(summary.counts.denied)} ignored=${String(summary.counts.ignored)}\n`);
+    renderContext(summary, io);
+}
+export function runContextCli(args, io) {
+    const parsed = parseArgs(args);
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    try {
+        const summary = buildSummary(parsed);
+        if (parsed.json) {
+            io.out(`${JSON.stringify(summary, null, 2)}\n`);
+        }
+        else {
+            renderText(summary, io);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceError) {
+            io.err(`Error [${error.code}]: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}

package/dist/cli/evaluate.d.ts

@@ -0,0 +1,7 @@
+import type { EnvSource } from "../gateway/config.js";
+import { type EvalRunnerDeps } from "../evaluations/index.js";
+import type { CliIo } from "./runner.js";
+export interface EvaluateDeps {
+    readonly runner?: EvalRunnerDeps | undefined;
+}
+export declare function runEvaluateCli(args: readonly string[], io: CliIo, env?: EnvSource, deps?: EvaluateDeps): Promise<number>;

package/dist/cli/evaluate.js

@@ -0,0 +1,207 @@
+// `keiko evaluate` — runs the evaluation harness (ADR-0012 D10). Offline (default, deterministic, no
+// network) replays each fixture's scripted transcript; --live builds a GatewayModelPort and fails
+// CLOSED (exit 1, names the required env vars) when no config/credentials resolve — it NEVER silently
+// falls back to offline. Dry-run-safe by construction: fixtures choose their own apply mode. Mirrors
+// runGenTestsCli structurally (injected CliIo + deps, testable without process.*). Exit 0 when all
+// applicable dimensions pass AND surface parity passes; 1 on dimension/parity failure or runtime
+// error; 2 on usage error (unknown flag, mutual exclusion, unknown suite/fixture name).
+import { writeFileSync } from "node:fs";
+import { GatewayError } from "../gateway/errors.js";
+import { redact } from "../gateway/redaction.js";
+import { createAuditRedactor, deepRedactStrings } from "../audit/index.js";
+import { fixtureByName, fixturesForSuite, isSuiteName, renderEvalSummary, runEvaluationSuite, } from "../evaluations/index.js";
+const USAGE = `Usage:
+  keiko evaluate [--suite <unit-tests|bug-investigation|all>] [--fixture <name>]
+                 [--live] [--model <id>] [--config PATH] [--json] [--output <path>]
+
+Runs the evaluation harness against the built-in fixtures. Offline by default
+(deterministic, no network); pass --live to evaluate against a configured model.
+--suite and --fixture are mutually exclusive.
+`;
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1) {
+        return undefined;
+    }
+    const value = args[i + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+const VALUE_FLAGS = ["--suite", "--fixture", "--model", "--config", "--output"];
+const BOOLEAN_FLAGS = ["--live", "--json"];
+function readValueFlags(args) {
+    const values = {};
+    for (const flag of VALUE_FLAGS) {
+        const value = flagValue(args, flag);
+        if (value === null) {
+            return null;
+        }
+        values[flag] = value;
+    }
+    return values;
+}
+function isValueFlag(value) {
+    return VALUE_FLAGS.includes(value);
+}
+function isBooleanFlag(value) {
+    return BOOLEAN_FLAGS.includes(value);
+}
+function findUsageError(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        if (isValueFlag(arg)) {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return `missing value for ${arg}`;
+            }
+            i += 1;
+            continue;
+        }
+        if (isBooleanFlag(arg)) {
+            continue;
+        }
+        return arg.startsWith("--") ? `unknown flag ${arg}` : `unexpected argument ${arg}`;
+    }
+    return undefined;
+}
+function parseArgs(args) {
+    const values = readValueFlags(args);
+    if (values === null) {
+        return null;
+    }
+    return {
+        suite: values["--suite"],
+        fixture: values["--fixture"],
+        live: args.includes("--live"),
+        model: values["--model"],
+        config: values["--config"],
+        json: args.includes("--json"),
+        output: values["--output"],
+    };
+}
+// Resolves the fixture set from --suite / --fixture, enforcing mutual exclusion and name validity.
+function selectFixtures(parsed) {
+    if (parsed.suite !== undefined && parsed.fixture !== undefined) {
+        return { usageError: "Error: --suite and --fixture are mutually exclusive.\n" };
+    }
+    if (parsed.fixture !== undefined) {
+        const fixture = fixtureByName(parsed.fixture);
+        return fixture === undefined
+            ? { usageError: `Error: unknown fixture "${parsed.fixture}".\n` }
+            : { fixtures: [fixture] };
+    }
+    const suite = parsed.suite ?? "all";
+    if (!isSuiteName(suite)) {
+        return { usageError: `Error: unknown suite "${suite}".\n` };
+    }
+    return { fixtures: fixturesForSuite(suite) };
+}
+// In live mode, deep-redact the scorecard before serialization so that any model content that
+// leaked into workflow report fields (e.g. fixture reasons) is scrubbed by the same audit
+// redactor applied at evidence-persist time. Offline scorecard is static harness text — safe as-is.
+function redactedScorecard(scorecard, live, env) {
+    if (!live) {
+        return scorecard;
+    }
+    const redactFn = createAuditRedactor({ additionalSecrets: keikoApiKeySecrets(env) }, env);
+    return deepRedactStrings(scorecard, redactFn);
+}
+function isKeikoApiKeyEnvName(name) {
+    return (name === "KEIKO_DEFAULT_API_KEY" ||
+        (name.startsWith("KEIKO_MODEL_") && name.endsWith("_API_KEY")));
+}
+function keikoApiKeySecrets(env) {
+    const secrets = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (value !== undefined && isKeikoApiKeyEnvName(name)) {
+            secrets.push(value);
+        }
+    }
+    return secrets;
+}
+function writeScorecard(path, output) {
+    writeFileSync(path, `${JSON.stringify(output, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+}
+function emit(scorecard, parsed, io, env) {
+    const output = redactedScorecard(scorecard, parsed.live, env);
+    if (parsed.output !== undefined) {
+        writeScorecard(parsed.output, output);
+    }
+    if (parsed.json) {
+        io.out(`${JSON.stringify(output, null, 2)}\n`);
+        return;
+    }
+    io.out(`${renderEvalSummary(scorecard)}\n`);
+}
+// Exit 0 only when every scored dimension passed (zero failures) AND surface parity passed.
+function exitCodeFor(scorecard) {
+    if (!scorecard.surfaceParity.allPassed) {
+        return 1;
+    }
+    return scorecard.dimensions.some((d) => d.failCount > 0) ? 1 : 0;
+}
+export async function runEvaluateCli(args, io, env = {}, deps = {}) {
+    if (args.includes("--help")) {
+        io.out(USAGE);
+        return 0;
+    }
+    const usageError = findUsageError(args);
+    if (usageError !== undefined) {
+        io.err(`Error: ${usageError}.\n${USAGE}`);
+        return 2;
+    }
+    const parsed = parseArgs(args);
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    const selection = selectFixtures(parsed);
+    if ("usageError" in selection) {
+        io.err(selection.usageError);
+        return 2;
+    }
+    return runSuite(parsed, selection.fixtures, io, env, deps);
+}
+async function runSuite(parsed, fixtures, io, env, deps) {
+    try {
+        const scorecard = await runEvaluationSuite({
+            mode: parsed.live ? "live" : "offline",
+            fixtures,
+            ...(parsed.model === undefined ? {} : { modelIdOverride: parsed.model }),
+            ...(parsed.config === undefined ? {} : { configPath: parsed.config }),
+        }, 
+        // Provide Date.now as the default wall-clock so a real `keiko evaluate` prints the actual
+        // current time. Tests override this via deps.runner.now for deterministic evaluatedAt.
+        { env, now: Date.now, ...deps.runner });
+        emit(scorecard, parsed, io, env);
+        return exitCodeFor(scorecard);
+    }
+    catch (error) {
+        if (isOutputAlreadyExistsError(error)) {
+            io.err(`Error: output file already exists: ${parsed.output ?? "<unknown>"}\n`);
+            return 1;
+        }
+        return handleRunError(error, parsed, io);
+    }
+}
+function isOutputAlreadyExistsError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "EEXIST");
+}
+// Live-mode fail-closed: a GatewayError (incl. ConfigInvalidError) means no resolvable config or
+// credentials. Name the required env vars and exit 1 — never fall back to offline silently.
+function handleRunError(error, parsed, io) {
+    if (error instanceof GatewayError) {
+        io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n` +
+            (parsed.live
+                ? "Live evaluation requires a configured provider. Pass --config PATH or set " +
+                    "KEIKO_CONFIG_FILE.\n"
+                : ""));
+        return 1;
+    }
+    throw error;
+}

package/dist/cli/evidence.d.ts

@@ -0,0 +1,8 @@
+import { type EvidenceStore } from "../audit/store.js";
+import type { EnvSource } from "../gateway/config.js";
+import type { CliIo } from "./runner.js";
+export interface EvidenceCliDeps {
+    readonly store?: EvidenceStore | undefined;
+    readonly env?: EnvSource | undefined;
+}
+export declare function runEvidenceCli(args: readonly string[], io: CliIo, deps?: EvidenceCliDeps): number;

package/dist/cli/evidence.js

@@ -0,0 +1,88 @@
+// `keiko evidence` — inspects previously written evidence manifests (ADR-0010 D9). `list` prints the
+// EvidenceListEntry[] (text or --json); `show <runId>` prints one EvidenceReport / full manifest
+// (--json). It reads ONLY the contained base dir via the EvidenceStore (default $KEIKO_EVIDENCE_DIR
+// or ./.keiko/evidence, overridable with --evidence-dir). Because manifests are redacted by
+// construction there is no un-redaction path. Exit 0 on success, 1 on a missing runId / read error,
+// 2 on usage (unknown or missing subcommand, invalid runId). Tests inject an in-memory store via deps
+// so no disk is touched.
+import { buildEvidenceReport, renderEvidenceReport } from "../audit/report.js";
+import { listEvidence, loadEvidence } from "../audit/index-api.js";
+import { createNodeEvidenceStore, resolveEvidenceDir } from "../audit/store.js";
+import { AuditError, InvalidRunIdError } from "../audit/errors.js";
+const USAGE = `Usage:
+  keiko evidence list [--evidence-dir PATH] [--json]
+  keiko evidence show <runId> [--evidence-dir PATH] [--json]
+
+Lists or shows redacted evidence manifests written by \`keiko run\`. Reads only the
+evidence base dir (default $KEIKO_EVIDENCE_DIR or ./.keiko/evidence; override with --evidence-dir).
+`;
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1) {
+        return undefined;
+    }
+    const value = args[i + 1];
+    return value === undefined || value.startsWith("--") ? undefined : value;
+}
+function resolveStore(args, deps) {
+    if (deps.store !== undefined) {
+        return deps.store;
+    }
+    return createNodeEvidenceStore(resolveEvidenceDir(flagValue(args, "--evidence-dir"), deps.env));
+}
+function renderListText(entries) {
+    if (entries.length === 0) {
+        return "No evidence manifests found.\n";
+    }
+    const rows = entries.map((e) => `${e.runId}  ${e.taskType}  ${e.outcome}  started=${String(e.startedAt)} finished=${String(e.finishedAt)}`);
+    return `${rows.join("\n")}\n`;
+}
+function runList(store, json, io) {
+    const entries = listEvidence(store);
+    io.out(json ? `${JSON.stringify(entries, null, 2)}\n` : renderListText(entries));
+    return 0;
+}
+function runShow(store, runId, json, io) {
+    const manifest = loadEvidence(store, runId);
+    if (manifest === undefined) {
+        io.err(`keiko evidence: no manifest for runId: ${runId}\n`);
+        return 1;
+    }
+    if (json) {
+        io.out(`${JSON.stringify(manifest, null, 2)}\n`);
+        return 0;
+    }
+    io.out(renderEvidenceReport(buildEvidenceReport(manifest, store.location?.(runId) ?? `${runId}.json`)));
+    return 0;
+}
+// Maps a thrown AuditError to an exit code: an invalid runId is a usage error (2), any other
+// audit/read failure is a runtime error (1). Messages are already redacted at construction.
+function exitForAuditError(error, io) {
+    io.err(`keiko evidence: ${error.message}\n`);
+    return error instanceof InvalidRunIdError ? 2 : 1;
+}
+export function runEvidenceCli(args, io, deps = {}) {
+    const sub = args[0];
+    const json = args.includes("--json");
+    try {
+        if (sub === "list") {
+            return runList(resolveStore(args, deps), json, io);
+        }
+        if (sub === "show") {
+            const runId = args[1];
+            if (runId === undefined || runId.startsWith("--")) {
+                io.err(`keiko evidence: show requires a <runId>.\n${USAGE}`);
+                return 2;
+            }
+            return runShow(resolveStore(args, deps), runId, json, io);
+        }
+        io.err(sub === undefined ? USAGE : `keiko evidence: unknown subcommand: ${sub}\n${USAGE}`);
+        return 2;
+    }
+    catch (error) {
+        if (error instanceof AuditError) {
+            return exitForAuditError(error, io);
+        }
+        throw error;
+    }
+}

package/dist/cli/gateway-config.d.ts

@@ -0,0 +1,10 @@
+import type { EnvSource } from "../gateway/index.js";
+export type ConfigPathResolution = {
+    readonly kind: "path";
+    readonly path: string;
+} | {
+    readonly kind: "missing-value";
+} | {
+    readonly kind: "not-configured";
+};
+export declare function resolveConfigPathFromArgs(args: readonly string[], env: EnvSource): ConfigPathResolution;

package/dist/cli/gateway-config.js

@@ -0,0 +1,12 @@
+export function resolveConfigPathFromArgs(args, env) {
+    const flagIndex = args.indexOf("--config");
+    if (flagIndex !== -1) {
+        const value = args[flagIndex + 1];
+        return value === undefined || value.startsWith("--")
+            ? { kind: "missing-value" }
+            : { kind: "path", path: value };
+    }
+    return env.KEIKO_CONFIG_FILE === undefined
+        ? { kind: "not-configured" }
+        : { kind: "path", path: env.KEIKO_CONFIG_FILE };
+}

package/dist/cli/gen-tests.d.ts

@@ -0,0 +1,7 @@
+import { type EnvSource } from "../gateway/config.js";
+import type { ModelPort } from "../harness/ports.js";
+import type { CliIo } from "./runner.js";
+export interface GenTestsDeps {
+    readonly model?: ModelPort | undefined;
+}
+export declare function runGenTestsCli(args: readonly string[], io: CliIo, env?: EnvSource, deps?: GenTestsDeps): Promise<number>;