@oscharko-dev/keiko 0.1.5 → 0.1.7

package/dist/cli/lifecycle.js

@@ -1,329 +0,0 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
-import { spawn } from "node:child_process";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { SDK_VERSION } from "../sdk/index.js";
-import { DEFAULT_UI_PORT, UI_HOST } from "../ui/index.js";
-const ALLOWED_HOSTS = new Set(["127.0.0.1", "localhost"]);
-const LIFECYCLE_FLAG_SETTERS = {
-    "--port": (raw, value) => {
-        raw.portRaw = value;
-    },
-    "--host": (raw, value) => {
-        raw.hostRaw = value;
-    },
-    "--state-dir": (raw, value) => {
-        raw.stateDirRaw = value;
-    },
-    "--start-timeout": (raw, value) => {
-        raw.startTimeoutRaw = value;
-    },
-    "--stop-timeout": (raw, value) => {
-        raw.stopTimeoutRaw = value;
-    },
-};
-const USAGE = `Usage:
-  keiko start [--port PORT] [--host 127.0.0.1|localhost] [--state-dir PATH]
-  keiko stop [--state-dir PATH]
-  keiko restart [--port PORT] [--host 127.0.0.1|localhost] [--state-dir PATH]
-  keiko status [--port PORT] [--host 127.0.0.1|localhost] [--state-dir PATH]
-
-Manages the local Keiko UI process. Runtime state is written to .keiko/ by default.
-`;
-function readFlagValue(args, index) {
-    const value = args[index + 1];
-    return value === undefined || value.startsWith("--") ? null : value;
-}
-function parsePort(raw) {
-    if (!/^\d{1,5}$/.test(raw))
-        return null;
-    const port = Number(raw);
-    return port >= 1 && port <= 65535 ? port : null;
-}
-function parsePositiveSeconds(raw) {
-    if (!/^[1-9]\d*$/.test(raw))
-        return null;
-    return Number(raw) * 1000;
-}
-function optionOrEnv(value, envValue, fallback) {
-    return value ?? envValue ?? fallback;
-}
-function resolveStateDir(cwd, value) {
-    return isAbsolute(value) ? value : resolve(cwd, value);
-}
-function isLifecycleFlag(arg) {
-    return Object.prototype.hasOwnProperty.call(LIFECYCLE_FLAG_SETTERS, arg);
-}
-function collectLifecycleOptions(args) {
-    const raw = {};
-    for (let i = 0; i < args.length; i += 1) {
-        const arg = args[i];
-        if (arg === undefined)
-            return null;
-        if (arg === "--help" || arg === "-h") {
-            return "help";
-        }
-        if (!isLifecycleFlag(arg))
-            return null;
-        const value = readFlagValue(args, i);
-        if (value === null)
-            return null;
-        LIFECYCLE_FLAG_SETTERS[arg](raw, value);
-        i += 1;
-    }
-    return raw;
-}
-function buildLifecycleOptions(raw, cwd, env) {
-    const port = parsePort(optionOrEnv(raw.portRaw, env.KEIKO_UI_PORT, String(DEFAULT_UI_PORT)));
-    const host = optionOrEnv(raw.hostRaw, env.KEIKO_UI_HOST, UI_HOST);
-    const startTimeoutMs = parsePositiveSeconds(optionOrEnv(raw.startTimeoutRaw, env.KEIKO_START_TIMEOUT_SECS, "20"));
-    const stopTimeoutMs = parsePositiveSeconds(optionOrEnv(raw.stopTimeoutRaw, env.KEIKO_STOP_TIMEOUT_SECS, "10"));
-    if (port === null ||
-        !ALLOWED_HOSTS.has(host) ||
-        startTimeoutMs === null ||
-        stopTimeoutMs === null) {
-        return null;
-    }
-    return {
-        port,
-        host,
-        stateDir: resolveStateDir(cwd, optionOrEnv(raw.stateDirRaw, env.KEIKO_STATE_DIR, ".keiko")),
-        startTimeoutMs,
-        stopTimeoutMs,
-    };
-}
-function parseLifecycleArgs(args, cwd, env) {
-    const raw = collectLifecycleOptions(args);
-    if (raw === "help" || raw === null)
-        return raw;
-    return buildLifecycleOptions(raw, cwd, env);
-}
-function pidFile(options) {
-    return join(options.stateDir, "ui.pid");
-}
-function logFile(options) {
-    return join(options.stateDir, "ui.log");
-}
-function healthUrl(options) {
-    return `http://${options.host}:${String(options.port)}/api/health`;
-}
-function healthVersion(payload) {
-    if (typeof payload !== "object" || payload === null)
-        return undefined;
-    const version = payload.version;
-    return typeof version === "string" ? version : undefined;
-}
-async function probeHealth(options, fetchImpl) {
-    try {
-        const response = await fetchImpl(healthUrl(options), {
-            signal: AbortSignal.timeout(1_000),
-        });
-        if (!response.ok) {
-            return { reachable: false, version: undefined };
-        }
-        let body;
-        try {
-            body = await response.json();
-        }
-        catch {
-            return { reachable: true, version: undefined };
-        }
-        return { reachable: true, version: healthVersion(body) };
-    }
-    catch {
-        return { reachable: false, version: undefined };
-    }
-}
-function readPid(path) {
-    if (!existsSync(path))
-        return undefined;
-    const raw = readFileSync(path, "utf8").trim();
-    if (!/^[1-9]\d*$/.test(raw))
-        return undefined;
-    return Number(raw);
-}
-function defaultIsProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM";
-    }
-}
-function runningPid(options, isAlive) {
-    const path = pidFile(options);
-    const pid = readPid(path);
-    if (pid === undefined) {
-        rmSync(path, { force: true });
-        return undefined;
-    }
-    if (!isAlive(pid)) {
-        rmSync(path, { force: true });
-        return undefined;
-    }
-    return pid;
-}
-function childEnv(env) {
-    const next = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (!Object.prototype.hasOwnProperty.call(env, key) && value !== undefined) {
-            next[key] = value;
-        }
-    }
-    for (const [key, value] of Object.entries(env)) {
-        if (value !== undefined) {
-            next[key] = value;
-        }
-    }
-    return next;
-}
-function cliEntryPath() {
-    return join(dirname(fileURLToPath(import.meta.url)), "index.js");
-}
-function spawnUiProcess(options, env, deps, cwd) {
-    mkdirSync(options.stateDir, { recursive: true, mode: 0o700 });
-    const logPath = logFile(options);
-    const fd = openSync(logPath, "a", 0o600);
-    try {
-        return {
-            child: deps.spawnFn(process.execPath, [cliEntryPath(), "ui", "--port", String(options.port), "--host", options.host], {
-                cwd,
-                detached: true,
-                env: childEnv(env),
-                stdio: ["ignore", fd, fd],
-            }),
-            logPath,
-        };
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-async function waitForHealth(options, pid, deps) {
-    const deadline = Date.now() + options.startTimeoutMs;
-    while (Date.now() <= deadline) {
-        if (!deps.isProcessAlive(pid))
-            return false;
-        try {
-            const response = await deps.fetchImpl(healthUrl(options), {
-                signal: AbortSignal.timeout(1_000),
-            });
-            if (response.ok) {
-                return true;
-            }
-        }
-        catch {
-            // Startup is still in progress.
-        }
-        await deps.sleep(500);
-    }
-    return false;
-}
-async function cmdStart(options, io, env, deps, cwd) {
-    const running = runningPid(options, deps.isProcessAlive);
-    if (running !== undefined) {
-        const health = await probeHealth(options, deps.fetchImpl);
-        if (health.version === SDK_VERSION) {
-            io.out(`Keiko UI already running on ${healthUrl(options).replace("/api/health", "")} (pid ${String(running)}).\n`);
-            return 0;
-        }
-        const reason = !health.reachable
-            ? "health check is unreachable"
-            : health.version === undefined
-                ? "health check did not return the current Keiko version"
-                : `running version ${health.version} differs from installed version ${SDK_VERSION}`;
-        io.out(`Keiko UI process is stale (${reason}); restarting pid ${String(running)}.\n`);
-        const stopped = await cmdStop(options, io, deps);
-        if (stopped !== 0)
-            return stopped;
-    }
-    const { child, logPath } = spawnUiProcess(options, env, deps, cwd);
-    if (child.pid === undefined) {
-        io.err("keiko start: failed to spawn the UI process.\n");
-        return 1;
-    }
-    child.unref();
-    writeFileSync(pidFile(options), `${String(child.pid)}\n`, { encoding: "utf8", mode: 0o600 });
-    io.out(`Starting Keiko UI on ${healthUrl(options).replace("/api/health", "")} ...\n`);
-    const healthy = await waitForHealth(options, child.pid, deps);
-    if (healthy) {
-        io.out(`Keiko UI running on ${healthUrl(options).replace("/api/health", "")} (pid ${String(child.pid)}).\n`);
-        io.out(`Logs: ${logPath}\n`);
-        return 0;
-    }
-    deps.killProcess(child.pid, "SIGTERM");
-    rmSync(pidFile(options), { force: true });
-    io.err(`keiko start: UI did not become healthy. Logs: ${logPath}\n`);
-    return 1;
-}
-async function cmdStop(options, io, deps) {
-    const pid = runningPid(options, deps.isProcessAlive);
-    if (pid === undefined) {
-        io.out("Keiko UI is not running.\n");
-        return 0;
-    }
-    io.out(`Stopping Keiko UI (pid ${String(pid)}) ...\n`);
-    deps.killProcess(pid, "SIGTERM");
-    const deadline = Date.now() + options.stopTimeoutMs;
-    while (Date.now() <= deadline) {
-        if (!deps.isProcessAlive(pid)) {
-            rmSync(pidFile(options), { force: true });
-            io.out("Keiko UI stopped.\n");
-            return 0;
-        }
-        await deps.sleep(500);
-    }
-    io.err("keiko stop: UI did not exit gracefully; sending SIGKILL.\n");
-    deps.killProcess(pid, "SIGKILL");
-    await deps.sleep(500);
-    if (deps.isProcessAlive(pid)) {
-        io.err(`keiko stop: failed to stop pid ${String(pid)}.\n`);
-        return 1;
-    }
-    rmSync(pidFile(options), { force: true });
-    io.out("Keiko UI stopped (forced).\n");
-    return 0;
-}
-function cmdStatus(options, io, isAlive) {
-    const pid = runningPid(options, isAlive);
-    if (pid === undefined) {
-        io.out("Keiko UI is not running.\n");
-        return 0;
-    }
-    io.out(`Keiko UI is running on ${healthUrl(options).replace("/api/health", "")} (pid ${String(pid)}).\n`);
-    return 0;
-}
-async function cmdRestart(options, io, env, deps, cwd) {
-    const stopped = await cmdStop(options, io, deps);
-    if (stopped !== 0)
-        return stopped;
-    return cmdStart(options, io, env, deps, cwd);
-}
-export async function runLifecycleCli(command, args, io, env, deps = {}) {
-    const cwd = deps.cwd ?? process.cwd();
-    const options = parseLifecycleArgs(args, cwd, env);
-    if (options === "help") {
-        io.out(USAGE);
-        return 0;
-    }
-    if (options === null) {
-        io.err(USAGE);
-        return 2;
-    }
-    const fullDeps = {
-        spawnFn: deps.spawnFn ?? spawn,
-        fetchImpl: deps.fetchImpl ?? fetch,
-        sleep: deps.sleep ??
-            ((ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms))),
-        isProcessAlive: deps.isProcessAlive ?? defaultIsProcessAlive,
-        killProcess: deps.killProcess ?? process.kill.bind(process),
-    };
-    const handlers = {
-        start: () => cmdStart(options, io, env, fullDeps, cwd),
-        stop: () => cmdStop(options, io, fullDeps),
-        status: () => Promise.resolve(cmdStatus(options, io, fullDeps.isProcessAlive)),
-        restart: () => cmdRestart(options, io, env, fullDeps, cwd),
-    };
-    return handlers[command]();
-}

package/dist/cli/models.d.ts

@@ -1,3 +0,0 @@
-import { type EnvSource } from "../gateway/config.js";
-import type { CliIo } from "./runner.js";
-export declare function runModelsCli(args: readonly string[], io: CliIo, env: EnvSource): number;

package/dist/cli/models.js

@@ -1,64 +0,0 @@
-// `keiko models` CLI handler. Synchronous by design: `list` reads built-in
-// capability metadata; `validate` reads a config file with readFileSync and runs
-// the hand-rolled validator. Neither path needs a live async Gateway, so the
-// existing `process.exit(runCli(...))` shim stays synchronous. No credential value
-// is ever written to stdout or stderr.
-import { listCapabilities } from "../gateway/capabilities.js";
-import { loadConfigFromFile } from "../gateway/config.js";
-import { GatewayError } from "../gateway/errors.js";
-import { resolveConfigPathFromArgs } from "./gateway-config.js";
-const USAGE = `Usage:
-  keiko models list                      List registered model capabilities.
-  keiko models validate [--config PATH]  Validate gateway configuration.
-`;
-function formatUseCases(useCases) {
-    return useCases.map((useCase) => useCase.toLowerCase().replace(/\s+/g, "-")).join(",");
-}
-function listModels(io) {
-    io.out("ID\tKIND\tCOST\tLATENCY\tTOOLS\tSTRUCT\tUSE-CASES\n");
-    for (const cap of listCapabilities()) {
-        const tools = cap.toolCalling ? "yes" : "no";
-        const struct = cap.structuredOutput ? "yes" : "no";
-        io.out(`${cap.id}\t${cap.kind}\t${cap.costClass}\t${cap.latencyClass}\t${tools}\t${struct}\t${formatUseCases(cap.preferredUseCases)}\n`);
-    }
-    return 0;
-}
-function validateConfig(args, io, env) {
-    const resolution = resolveConfigPathFromArgs(args, env);
-    if (resolution.kind === "missing-value") {
-        io.err("Error: --config requires a path argument.\n");
-        return 2;
-    }
-    if (resolution.kind === "not-configured") {
-        io.err("Error [GATEWAY_CONFIG_INVALID]: no config source; pass --config PATH or set KEIKO_CONFIG_FILE.\n");
-        return 1;
-    }
-    try {
-        const config = loadConfigFromFile(resolution.path, env);
-        io.out(`Gateway config valid. ${String(config.providers.length)} model providers configured.\n`);
-        return 0;
-    }
-    catch (error) {
-        if (error instanceof GatewayError) {
-            io.err(`Error [${error.code}]: ${error.message}\n`);
-            return 1;
-        }
-        throw error;
-    }
-}
-export function runModelsCli(args, io, env) {
-    const sub = args[0];
-    if (sub === "list") {
-        return listModels(io);
-    }
-    if (sub === "validate") {
-        return validateConfig(args.slice(1), io, env);
-    }
-    if (sub === undefined) {
-        io.err(USAGE);
-        return 2;
-    }
-    io.err(`keiko models: unknown sub-command: ${sub}\n`);
-    io.err(USAGE);
-    return 2;
-}

package/dist/cli/run.d.ts

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

package/dist/cli/run.js

@@ -1,187 +0,0 @@
-// `keiko run` — the dry-run task command. It builds an AgentSession wired to deterministic mocked
-// model/tool fixtures (no provider call, no real tools) and renders the HarnessEvent stream to
-// CliIo. Since ADR-0010 it ALSO writes a redacted evidence manifest by default (evidence is the
-// product value): a tee EventSink forwards every event to BOTH a MemoryEventSink (which retains raw
-// content to assemble the replay manifest) and the existing CliEventSink (whose summarisers never
-// print sensitive fields). After the run resolves, the audit layer builds + redacts + persists the
-// manifest and the EvidenceReport is printed. Writing is on by default; --no-evidence disables it,
-// --evidence-dir relocates it. Tests inject an in-memory EvidenceStore via deps so no write ever
-// touches the repository tree.
-import { DryRunToolPort } from "../harness/adapters.js";
-import { createSession, HARNESS_VERSION } from "../harness/session.js";
-import { CliEventSink, MemoryEventSink } from "../harness/sinks.js";
-import { DEFAULT_LIMITS } from "../harness/types.js";
-import { persistEvidence } from "../audit/persist.js";
-import { renderEvidenceReport } from "../audit/report.js";
-import { createNodeEvidenceStore, resolveEvidenceDir } from "../audit/store.js";
-import { AuditError } from "../audit/errors.js";
-import { redact } from "../gateway/redaction.js";
-const TASK_TYPES = new Set([
-    "generate-unit-tests",
-    "investigate-bug",
-    "explain-plan",
-]);
-const USAGE = `Usage:
-  keiko run explain-plan --file PATH [--question TEXT]
-  keiko run generate-unit-tests --file PATH [--function NAME]
-  keiko run investigate-bug --description TEXT [--file PATH]
-
-  Evidence flags (a redacted manifest is written by default):
-    --no-evidence            Do not write an evidence manifest.
-    --evidence-dir PATH      Write evidence under PATH (default $KEIKO_EVIDENCE_DIR or ./.keiko/evidence).
-    --include-reasoning      Include redacted reasoning entries in the manifest.
-    --include-diff           Include the redacted proposed diff in the manifest.
-
-All tasks run in dry-run mode: a patch is proposed as an event, never written to disk.
-`;
-function flag(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 parseEvidenceFlags(args) {
-    return {
-        write: !args.includes("--no-evidence"),
-        evidenceDirFlag: flag(args, "--evidence-dir"),
-        includeReasoning: args.includes("--include-reasoning"),
-        includeDiff: args.includes("--include-diff"),
-    };
-}
-// A deterministic, dependency-free canned final response. It never requests tools, so the dry-run
-// path is reproducible regardless of task type.
-function cannedResponse() {
-    return {
-        modelId: "mock-model",
-        content: "--- a/file\n+++ b/file\n+// dry-run proposed change\n",
-        finishReason: "stop",
-        toolCalls: [],
-        structuredOutput: null,
-        usage: {
-            requestId: "dry-run",
-            promptTokens: 0,
-            completionTokens: 0,
-            latencyMs: 1,
-            costClass: "low",
-        },
-    };
-}
-function parseTask(taskType, args) {
-    const file = flag(args, "--file");
-    if (taskType === "explain-plan") {
-        if (file === undefined) {
-            return null;
-        }
-        return { taskType, input: { filePath: file, question: flag(args, "--question") } };
-    }
-    if (taskType === "generate-unit-tests") {
-        if (file === undefined) {
-            return null;
-        }
-        return { taskType, input: { filePath: file, targetFunction: flag(args, "--function") } };
-    }
-    const description = flag(args, "--description");
-    if (description === undefined) {
-        return null;
-    }
-    return { taskType, input: { description, filePaths: file === undefined ? undefined : [file] } };
-}
-// Forwards each event to every wrapped sink. retainsRawContent is true so the harness emits raw
-// SENSITIVE fields — required for the MemoryEventSink's faithful replay manifest. The CliEventSink
-// summarisers never print those fields, and the audit layer redacts before anything is persisted.
-function teeSink(sinks) {
-    return {
-        retainsRawContent: true,
-        emit: (event) => {
-            for (const sink of sinks) {
-                sink.emit(event);
-            }
-        },
-    };
-}
-function seedFor(task, result) {
-    return {
-        runId: result.runId,
-        fingerprint: result.fingerprint,
-        harnessVersion: HARNESS_VERSION,
-        taskType: task.taskType,
-        taskInput: task,
-        limits: DEFAULT_LIMITS,
-        modelId: "mock-model",
-        workingDirectory: ".",
-        dryRun: true,
-        startedAt: new Date(result.startedAt).toISOString(),
-    };
-}
-// Persists the evidence manifest. This is a system boundary (filesystem write), so try/catch is
-// correct here (CLAUDE.md): on any failure — typed AuditError or otherwise — print a REDACTED
-// message and return exit 1 rather than rejecting out of runAgentCli as an unhandled rejection (C3).
-// Returns undefined on success so the caller falls through to the run-outcome exit code.
-function writeEvidence(result, memory, task, ctx, io) {
-    try {
-        const manifest = memory.collectManifest(seedFor(task, result));
-        const store = ctx.deps.store ??
-            createNodeEvidenceStore(resolveEvidenceDir(ctx.flags.evidenceDirFlag, ctx.env));
-        const out = persistEvidence({
-            result,
-            manifest,
-            options: {
-                includeReasoning: ctx.flags.includeReasoning,
-                includeDiff: ctx.flags.includeDiff,
-            },
-        }, { store, env: ctx.env });
-        io.out(renderEvidenceReport(out.report));
-        return undefined;
-    }
-    catch (error) {
-        const detail = error instanceof AuditError ? error.message : redact(String(error));
-        io.err(`keiko run: failed to write evidence: ${detail}\n`);
-        return 1;
-    }
-}
-function outcomeToExitCode(result, io) {
-    if (result.outcome === "completed") {
-        io.out(`run ${result.runId} completed (fingerprint ${result.fingerprint})\n`);
-        return 0;
-    }
-    if (result.outcome === "cancelled") {
-        io.err(`run ${result.runId} cancelled\n`);
-        return 1;
-    }
-    const category = result.failure?.category ?? "HARNESS_INTERNAL";
-    io.err(`run ${result.runId} ${result.outcome} [${category}]: ${result.failure?.message ?? ""}\n`);
-    return 1;
-}
-export async function runAgentCli(args, io, env = {}, deps = {}) {
-    const taskType = args[0];
-    if (taskType === undefined || !TASK_TYPES.has(taskType)) {
-        io.err(taskType === undefined ? USAGE : `keiko run: unknown task type: ${taskType}\n${USAGE}`);
-        return 2;
-    }
-    const task = parseTask(taskType, args.slice(1));
-    if (task === null) {
-        io.err(`keiko run: missing required argument for ${taskType}.\n${USAGE}`);
-        return 2;
-    }
-    const flags = parseEvidenceFlags(args);
-    const response = cannedResponse();
-    const memory = new MemoryEventSink();
-    const config = { model: "mock-model", workingDirectory: ".", dryRun: true };
-    const session = createSession(task, config, {
-        model: {
-            call: (request) => Promise.resolve({ ...response, modelId: request.modelId }),
-        },
-        tools: new DryRunToolPort(),
-        sink: teeSink([memory, new CliEventSink(io)]),
-    });
-    const result = await session.result;
-    if (flags.write) {
-        const evidenceFailure = writeEvidence(result, memory, task, { flags, env, deps }, io);
-        if (evidenceFailure !== undefined) {
-            return evidenceFailure;
-        }
-    }
-    return outcomeToExitCode(result, io);
-}

package/dist/cli/runner.d.ts

@@ -1,6 +0,0 @@
-import type { EnvSource } from "../gateway/config.js";
-export interface CliIo {
-    readonly out: (text: string) => void;
-    readonly err: (text: string) => void;
-}
-export declare function runCli(args: readonly string[], io: CliIo, env?: EnvSource): number | Promise<number>;

package/dist/cli/runner.js

@@ -1,76 +0,0 @@
-import { runModelsCli } from "./models.js";
-import { runAgentCli } from "./run.js";
-import { runContextCli } from "./context.js";
-import { runVerifyCli } from "./verify.js";
-import { runGenTestsCli } from "./gen-tests.js";
-import { runInvestigateCli } from "./investigate.js";
-import { runEvidenceCli } from "./evidence.js";
-import { runEvaluateCli } from "./evaluate.js";
-import { runInitCli } from "./init.js";
-import { runLifecycleCli } from "./lifecycle.js";
-import { runUiCli } from "./ui.js";
-import { SDK_VERSION } from "../sdk/index.js";
-const HELP_TEXT = `keiko ${SDK_VERSION}
-Enterprise model-agnostic developer-assist coding agent.
-
-Usage:
-  keiko [--help | -h]      Print this help and exit.
-  keiko [--version | -v]   Print the version and exit.
-  keiko init [OPTIONS]     Add local package.json start/stop scripts.
-  keiko start|stop|status|restart Manage the local Keiko UI process.
-  keiko models list        List registered model capabilities.
-  keiko models validate    Validate gateway configuration.
-  keiko run <task>         Run a bounded dry-run task through the agent harness.
-  keiko context [OPTIONS]  Print a redacted workspace context summary (dry-run).
-  keiko verify [OPTIONS]   Run the project's gates and print a redacted evidence summary.
-  keiko gen-tests [OPTIONS] Generate a reviewable unit-test patch (dry-run by default).
-  keiko investigate [OPTIONS] Investigate a bug and propose a fix + regression test (dry-run by default).
-  keiko evidence <list|show> Inspect redacted evidence manifests written by \`keiko run\`.
-  keiko evaluate [OPTIONS]     Run the evaluation harness (offline by default; --live for live model).
-  keiko ui [OPTIONS]       Launch the local UI on 127.0.0.1 and print its URL.
-
-Exit codes:
-  0  Success
-  1  Runtime error
-  2  Usage error
-`;
-const COMMAND_HANDLERS = {
-    models: runModelsCli,
-    run: runAgentCli,
-    context: (rest, io) => runContextCli(rest, io),
-    verify: (rest, io) => runVerifyCli(rest, io),
-    "gen-tests": runGenTestsCli,
-    investigate: runInvestigateCli,
-    evidence: (rest, io, env) => runEvidenceCli(rest, io, { env }),
-    evaluate: (rest, io, env) => runEvaluateCli(rest, io, env, {}),
-    init: runInitCli,
-    start: (rest, io, env) => runLifecycleCli("start", rest, io, env),
-    stop: (rest, io, env) => runLifecycleCli("stop", rest, io, env),
-    status: (rest, io, env) => runLifecycleCli("status", rest, io, env),
-    restart: (rest, io, env) => runLifecycleCli("restart", rest, io, env),
-    ui: runUiCli,
-};
-// Dispatches named subcommands; returns undefined when the name is not recognised.
-function dispatchCommand(name, rest, io, env) {
-    return COMMAND_HANDLERS[name]?.(rest, io, env);
-}
-// Returns a number for synchronous commands; the async `run` command returns a Promise.
-// The process shim in index.ts awaits the union before calling process.exit.
-export function runCli(args, io, env = {}) {
-    const first = args[0];
-    if (first === undefined || first === "--help" || first === "-h") {
-        io.out(HELP_TEXT);
-        return 0;
-    }
-    if (first === "--version" || first === "-v") {
-        io.out(`keiko ${SDK_VERSION}\n`);
-        return 0;
-    }
-    const result = dispatchCommand(first, args.slice(1), io, env);
-    if (result !== undefined) {
-        return result;
-    }
-    io.err(`keiko: unknown ${first.startsWith("-") ? "option" : "command"}: ${first}\n`);
-    io.err("Run `keiko --help` for usage.\n");
-    return 2;
-}