@oscharko-dev/keiko 0.1.5 → 0.1.7

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/investigate.js

@@ -0,0 +1,242 @@
+// `keiko investigate` — investigates a bounded bug report and proposes a minimal fix + a
+// regression test (ADR-0009 D14). Dry-run by default; --apply writes the fix and runs verification.
+// The text path prints the proposed diff (when present) plus clearly-labelled verified facts and
+// the UNVERIFIED model hypothesis; --json emits the full BugInvestigationReport. Failing output and
+// stack traces may be read from files (--output-file / --stack-file) to avoid huge argv. Evidence
+// files are read through the workspace boundary, never raw node:fs. The gateway ModelPort is built
+// from config (loadConfigFromFile); tests inject deps.model directly so no live gateway is needed.
+// Exit 0 on fix-applied/fix-proposed/investigation-only, 1 on
+// rejected/cancelled/failed/runtime, 2 on usage. Mirrors runGenTestsCli's structure.
+import { Gateway, loadConfigFromFile, ConfigInvalidError, GatewayError, assertConfiguredModel, selectConfiguredModel, redact, } from "@oscharko-dev/keiko-model-gateway";
+import { GatewayModelPort } from "@oscharko-dev/keiko-harness";
+import { detectWorkspace, readWorkspaceFile, WorkspaceError, } from "@oscharko-dev/keiko-workspace";
+import { investigateBug, renderBugMarkdownReport } from "@oscharko-dev/keiko-workflows";
+const USAGE = `Usage:
+  keiko investigate [--description TEXT] [--output TEXT | --output-file PATH]
+                    [--stack TEXT | --stack-file PATH] [--file PATH[,PATH]]
+                    [--apply] [--model MODEL_ID] [--config PATH] [--json] [--dir-root PATH]
+
+Investigates a bounded bug report and proposes a root-cause hypothesis with a
+minimal fix and a regression test, separating verified facts from model
+hypotheses. At least one evidence source is required (--description, --output[-file],
+--stack[-file], or --file). Dry-run by default (writes nothing); pass --apply to
+write the fix and run verification through the safe tool + verification layers.
+`;
+// Returns the value of a `--flag value` pair, undefined if absent, or null if present without a
+// value (a usage error) — identical contract to runGenTestsCli's flagValue.
+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 = [
+    "--description",
+    "--output",
+    "--output-file",
+    "--stack",
+    "--stack-file",
+    "--file",
+    "--model",
+    "--config",
+    "--dir-root",
+];
+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 parseFiles(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parts = raw
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    return parts.length === 0 ? undefined : parts;
+}
+function parseArgs(args) {
+    const values = readValueFlags(args);
+    if (values === null) {
+        return null;
+    }
+    return {
+        description: values["--description"],
+        output: values["--output"],
+        outputFile: values["--output-file"],
+        stack: values["--stack"],
+        stackFile: values["--stack-file"],
+        files: parseFiles(values["--file"]),
+        apply: args.includes("--apply"),
+        model: values["--model"],
+        config: values["--config"],
+        json: args.includes("--json"),
+        dirRoot: values["--dir-root"] ?? ".",
+    };
+}
+// At least one evidence source must be present, else there is nothing to investigate.
+function hasEvidenceFlag(parsed) {
+    return (parsed.description !== undefined ||
+        parsed.output !== undefined ||
+        parsed.outputFile !== undefined ||
+        parsed.stack !== undefined ||
+        parsed.stackFile !== undefined ||
+        parsed.files !== undefined);
+}
+// Resolves the failing output and stack trace, reading from files when the *-file flags are set.
+// The inline flag is used only when its file counterpart is absent. Throws on a read failure (the
+// CLI catch maps it to a runtime error).
+function resolveReport(parsed, readFile) {
+    const failingOutput = parsed.outputFile !== undefined ? readFile(parsed.outputFile) : parsed.output;
+    const stackTrace = parsed.stackFile !== undefined ? readFile(parsed.stackFile) : parsed.stack;
+    return {
+        ...(parsed.description === undefined ? {} : { description: parsed.description }),
+        ...(failingOutput === undefined ? {} : { failingOutput }),
+        ...(stackTrace === undefined ? {} : { stackTrace }),
+        ...(parsed.files === undefined ? {} : { targetFiles: parsed.files }),
+    };
+}
+function workspaceEvidenceReader(workspace) {
+    return (path) => readWorkspaceFile(workspace, path).text;
+}
+function buildModel(parsed, io, env) {
+    try {
+        const path = parsed.config ?? env.KEIKO_CONFIG_FILE;
+        if (path === undefined) {
+            throw new ConfigInvalidError("no config source; pass --config PATH or set KEIKO_CONFIG_FILE");
+        }
+        const config = loadConfigFromFile(path, env);
+        if (parsed.model !== undefined) {
+            assertConfiguredModel(config, parsed.model);
+        }
+        const modelId = parsed.model ??
+            selectConfiguredModel(config, {
+                kind: "chat",
+                toolCalling: true,
+                structuredOutput: true,
+            });
+        if (modelId === undefined) {
+            io.err("Error: no configured workflow-capable chat model is available.\n");
+            return 1;
+        }
+        return { port: new GatewayModelPort(new Gateway(config)), modelId };
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n` +
+                `Provide a gateway config with --config PATH or KEIKO_CONFIG_FILE.\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+function resolveConfiguredModelId(parsed, env) {
+    const path = parsed.config ?? env.KEIKO_CONFIG_FILE;
+    if (path === undefined) {
+        return parsed.model ?? "default";
+    }
+    const config = loadConfigFromFile(path, env);
+    if (parsed.model !== undefined) {
+        assertConfiguredModel(config, parsed.model);
+        return parsed.model;
+    }
+    return selectConfiguredModel(config, {
+        kind: "chat",
+        toolCalling: true,
+        structuredOutput: true,
+    });
+}
+function resolveModel(parsed, io, env, deps) {
+    if (deps.model !== undefined) {
+        try {
+            const modelId = resolveConfiguredModelId(parsed, env);
+            if (modelId === undefined) {
+                io.err("Error: no configured workflow-capable chat model is available.\n");
+                return 1;
+            }
+            return { port: deps.model, modelId };
+        }
+        catch (error) {
+            if (error instanceof GatewayError) {
+                io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n`);
+                return 1;
+            }
+            throw error;
+        }
+    }
+    return buildModel(parsed, io, env);
+}
+function printText(report, io) {
+    io.out(`${renderBugMarkdownReport(report)}\n`);
+    if (report.dryRunPreview !== undefined) {
+        io.out(`\n${report.dryRunPreview}\n`);
+    }
+    if (report.proposedDiff !== undefined) {
+        io.out(`\n--- proposed fix ---\n${report.proposedDiff}\n`);
+    }
+}
+function exitCodeFor(status) {
+    return status === "fix-applied" || status === "fix-proposed" || status === "investigation-only"
+        ? 0
+        : 1;
+}
+function emitReport(report, io, json) {
+    if (json) {
+        io.out(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        printText(report, io);
+    }
+    return exitCodeFor(report.status);
+}
+// Maps a boundary error to an exit code, or rethrows when it is not a recognised IO failure.
+function handleCliError(error, io) {
+    if (error instanceof WorkspaceError) {
+        io.err(`Error [${error.code}]: ${error.message}\n`);
+        return 1;
+    }
+    if (error instanceof Error && isFileReadError(error)) {
+        io.err(`Error: could not read an evidence file — ${redact(error.message)}\n`);
+        return 1;
+    }
+    throw error;
+}
+export async function runInvestigateCli(args, io, env = {}, deps = {}) {
+    const parsed = parseArgs(args);
+    if (parsed === null || !hasEvidenceFlag(parsed)) {
+        io.err(USAGE);
+        return 2;
+    }
+    const model = resolveModel(parsed, io, env, deps);
+    if (typeof model === "number") {
+        return model;
+    }
+    try {
+        const workspace = detectWorkspace(parsed.dirRoot);
+        const readFile = deps.readFile ?? workspaceEvidenceReader(workspace);
+        const report = await investigateBug({
+            workspaceRoot: workspace.root,
+            report: resolveReport(parsed, readFile),
+            apply: parsed.apply,
+            modelId: model.modelId,
+        }, { model: model.port });
+        return emitReport(report, io, parsed.json);
+    }
+    catch (error) {
+        return handleCliError(error, io);
+    }
+}
+// A Node fs read error carries a string `code` (e.g. ENOENT); narrow without `any`.
+function isFileReadError(error) {
+    const code = error.code;
+    return typeof code === "string" && code.length > 0;
+}

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/lifecycle.d.ts

@@ -0,0 +1,19 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+type LifecycleCommand = "start" | "stop" | "status" | "restart";
+type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) => ChildProcess;
+type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
+type SleepFn = (ms: number) => Promise<void>;
+type ProcessKiller = (pid: number, signal?: NodeJS.Signals | 0) => void;
+export interface LifecycleCliDeps {
+    readonly cwd?: string | undefined;
+    readonly spawnFn?: SpawnFn | undefined;
+    readonly fetchImpl?: FetchFn | undefined;
+    readonly sleep?: SleepFn | undefined;
+    readonly isProcessAlive?: ((pid: number) => boolean) | undefined;
+    readonly killProcess?: ProcessKiller | undefined;
+}
+export declare function runLifecycleCli(command: LifecycleCommand, args: readonly string[], io: CliIo, env: EnvSource, deps?: LifecycleCliDeps): Promise<number>;
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/lifecycle.ts"],"names":[],"mappings":"AASA,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAGnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,KAAK,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAChE,KAAK,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC;AAC9F,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AACxE,KAAK,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAC7C,KAAK,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,IAAI,CAAC;AAgDxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAClD;AAgXD,wBAAsB,eAAe,CACnC,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA6BjB"}

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/lifecycle.js

@@ -0,0 +1,337 @@
+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-version.js";
+import { DEFAULT_UI_PORT, UI_HOST } from "@oscharko-dev/keiko-server";
+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() {
+    // The root bin shim (`dist/cli/index.js`) surfaces `KEIKO_CLI_BIN_PATH` so
+    // re-exec'd children spawned by `keiko start` invoke the published bin rather
+    // than the cli package barrel (which is not executable). The
+    // import.meta.url fallback preserves the pre-extraction behaviour for callers
+    // that invoke runLifecycleCli without going through the bin shim.
+    const fromEnv = process.env.KEIKO_CLI_BIN_PATH;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv;
+    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/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/models.d.ts

@@ -0,0 +1,4 @@
+import { type EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+export declare function runModelsCli(args: readonly string[], io: CliIo, env: EnvSource): number;
+//# sourceMappingURL=models.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../../src/models.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAkDzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAevF"}

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/models.js

@@ -0,0 +1,62 @@
+// `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, loadConfigFromFile, GatewayError, } from "@oscharko-dev/keiko-model-gateway";
+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/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/run.d.ts

@@ -0,0 +1,8 @@
+import { type EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+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>;
+//# sourceMappingURL=run.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/packages/keiko-cli/src/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../../src/run.ts"],"names":[],"mappings":"AAmBA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAItC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAuBzC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC5C;AA8JD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,OAAY,GACjB,OAAO,CAAC,MAAM,CAAC,CA+BjB"}