@oscharko-dev/keiko 0.2.0-beta.2 → 0.2.0-beta.4

package/node_modules/@oscharko-dev/keiko-cli/dist/evaluate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AASA,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAIzF,OAAO,EAML,KAAK,cAAc,EAGpB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAWzC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC9C;AA4ID,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CAqBjB"}
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AASA,OAAO,EAQL,KAAK,SAAS,EAGf,MAAM,mCAAmC,CAAC;AAI3C,OAAO,EAML,KAAK,cAAc,EAGpB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAWzC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC9C;AA4ID,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CAqBjB"}

package/node_modules/@oscharko-dev/keiko-cli/dist/evaluate.js

@@ -6,7 +6,7 @@
 // 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, redact } from "@oscharko-dev/keiko-model-gateway";
+import { ConfigInvalidError, GatewayError, assertConfiguredModel, findConfiguredCapability, listConfiguredCapabilities, loadConfigFromFile, redact, } from "@oscharko-dev/keiko-model-gateway";
 import { createAuditRedactor, deepRedactStrings } from "@oscharko-dev/keiko-evidence";
 import { keikoApiKeySecretValues } from "@oscharko-dev/keiko-security";
 import { parseRunRequest } from "@oscharko-dev/keiko-server";
@@ -156,10 +156,14 @@ export async function runEvaluateCli(args, io, env = {}, deps = {}) {
 }
 async function runSuite(parsed, fixtures, io, env, deps) {
     try {
+        const liveModelId = resolveLiveModelId(parsed, io, env);
+        if (typeof liveModelId === "number") {
+            return liveModelId;
+        }
         const scorecard = await runEvaluationSuite({
             mode: parsed.live ? "live" : "offline",
             fixtures,
-            ...(parsed.model === undefined ? {} : { modelIdOverride: parsed.model }),
+            ...(liveModelId === undefined ? {} : { modelIdOverride: liveModelId }),
             ...(parsed.config === undefined ? {} : { configPath: parsed.config }),
         }, 
         // Provide Date.now as the default wall-clock so a real `keiko evaluate` prints the actual
@@ -185,6 +189,61 @@ async function runSuite(parsed, fixtures, io, env, deps) {
         return handleRunError(error, parsed, io);
     }
 }
+function resolveLiveModelId(parsed, io, env) {
+    if (!parsed.live) {
+        return parsed.model;
+    }
+    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) {
+            assertLiveEvaluationModel(config, parsed.model);
+            return parsed.model;
+        }
+        const modelId = selectLiveEvaluationModel(config);
+        if (modelId === undefined) {
+            io.err("Error: no configured workflow-capable chat model is available.\n");
+            return 1;
+        }
+        return 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 isLiveEvaluationCapable(capability) {
+    return (capability?.kind === "chat" &&
+        capability.workflowEligible &&
+        capability.toolCalling &&
+        capability.structuredOutput);
+}
+const COST_RANK = { low: 0, medium: 1, high: 2 };
+function selectLiveEvaluationModel(config) {
+    let best;
+    for (const capability of listConfiguredCapabilities(config)) {
+        if (!isLiveEvaluationCapable(capability)) {
+            continue;
+        }
+        if (best === undefined || COST_RANK[capability.costClass] < COST_RANK[best.costClass]) {
+            best = capability;
+        }
+    }
+    return best?.id;
+}
+function assertLiveEvaluationModel(config, modelId) {
+    assertConfiguredModel(config, modelId);
+    if (!isLiveEvaluationCapable(findConfiguredCapability(config, modelId))) {
+        throw new ConfigInvalidError(`model '${modelId}' is not workflow-capable; live evaluation requires chat + tool-calling + structured-output`);
+    }
+}
 function isOutputAlreadyExistsError(error) {
     return (typeof error === "object" &&
         error !== null &&

package/node_modules/@oscharko-dev/keiko-cli/dist/evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAQA,OAAO,EAQL,KAAK,aAAa,EAGnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAWzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC;AA0DD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,IAAI,GAAE,eAAoB,GACzB,MAAM,CAuBR"}
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"AAQA,OAAO,EAQL,KAAK,aAAa,EAGnB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAWzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC;AAmID,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,IAAI,GAAE,eAAoB,GACzB,MAAM,CA2BR"}

package/node_modules/@oscharko-dev/keiko-cli/dist/evidence.js

@@ -13,19 +13,65 @@ const USAGE = `Usage:
 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;
+function parseSubcommand(value) {
+    return value === "list" || value === "show" ? value : undefined;
+}
+function parseFlags(args, startIndex) {
+    let json = false;
+    let evidenceDir;
+    let index = startIndex;
+    while (index < args.length) {
+        const arg = args[index];
+        if (arg === "--json") {
+            json = true;
+            index += 1;
+            continue;
+        }
+        if (arg !== "--evidence-dir") {
+            return { ok: false };
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return { ok: false };
+        }
+        evidenceDir = value;
+        index += 2;
     }
-    const value = args[i + 1];
-    return value === undefined || value.startsWith("--") ? undefined : value;
+    return { ok: true, json, evidenceDir };
 }
-function resolveStore(args, deps) {
+function invalidArgs(message) {
+    return { ok: false, error: message };
+}
+function resolveStore(evidenceDir, deps) {
     if (deps.store !== undefined) {
         return deps.store;
     }
-    return createNodeEvidenceStore(resolveEvidenceDir(flagValue(args, "--evidence-dir"), deps.env));
+    return createNodeEvidenceStore(resolveEvidenceDir(evidenceDir, deps.env));
+}
+function parseEvidenceArgs(args) {
+    const subcommand = parseSubcommand(args[0]);
+    if (subcommand === undefined) {
+        const sub = args[0];
+        return invalidArgs(sub === undefined ? USAGE : `keiko evidence: unknown subcommand: ${sub}\n${USAGE}`);
+    }
+    let index = 1;
+    let runId;
+    if (subcommand === "show") {
+        runId = args[index];
+        if (runId === undefined || runId.startsWith("--")) {
+            return invalidArgs(`keiko evidence: show requires a <runId>.\n${USAGE}`);
+        }
+        index += 1;
+    }
+    const flags = parseFlags(args, index);
+    if (!flags.ok) {
+        return invalidArgs(`keiko evidence: invalid arguments.\n${USAGE}`);
+    }
+    return {
+        ok: true,
+        error: "",
+        parsed: { subcommand, runId, evidenceDir: flags.evidenceDir, json: flags.json === true },
+    };
 }
 function renderListText(entries) {
     if (entries.length === 0) {
@@ -59,22 +105,20 @@ function exitForAuditError(error, io) {
     return error instanceof InvalidRunIdError ? 2 : 1;
 }
 export function runEvidenceCli(args, io, deps = {}) {
-    const sub = args[0];
-    const json = args.includes("--json");
+    const parsed = parseEvidenceArgs(args);
+    if (!parsed.ok || parsed.parsed === undefined) {
+        io.err(parsed.error);
+        return 2;
+    }
     try {
-        if (sub === "list") {
-            return runList(resolveStore(args, deps), json, io);
+        if (parsed.parsed.subcommand === "list") {
+            return runList(resolveStore(parsed.parsed.evidenceDir, deps), parsed.parsed.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);
+        if (parsed.parsed.runId === undefined) {
+            io.err(`keiko evidence: show requires a <runId>.\n${USAGE}`);
+            return 2;
         }
-        io.err(sub === undefined ? USAGE : `keiko evidence: unknown subcommand: ${sub}\n${USAGE}`);
-        return 2;
+        return runShow(resolveStore(parsed.parsed.evidenceDir, deps), parsed.parsed.runId, parsed.parsed.json, io);
     }
     catch (error) {
         if (error instanceof AuditError) {

package/node_modules/@oscharko-dev/keiko-cli/dist/launcher-platforms.js

@@ -7,7 +7,7 @@
 // any executable path or port that has not been validated by `validateExecPath` /
 // `validatePort`. The validators are deliberately strict allow-lists: a `keiko` executable
 // path that contains a space, a shell metacharacter, or any character outside
-// `[A-Za-z0-9_\-./\\:]` is rejected. Spaces in the bin location are a documented
+// `[A-Za-z0-9_@\-./\\:]` is rejected. Spaces in the bin location are a documented
 // unsupported edge case for this release (ADR-0024 D8 / spec §"Per-platform content rules").
 //
 // PLATFORMS:
@@ -23,7 +23,7 @@ import { posix as posixPath, win32 as win32Path } from "node:path";
 // `&`, `|`, `(`, `)`, `<`, `>`, `*`, `?`, `~`, `#`, `!`, `,`, `=`, `+`, control chars —
 // is rejected. The intent is defense-in-depth even though XDG `.desktop` and `.bat`
 // have their own quoting rules: no metacharacter ever reaches the file content.
-const EXEC_PATH_RE = /^[A-Za-z0-9_\-./\\:]+$/;
+const EXEC_PATH_RE = /^[A-Za-z0-9_@\-./\\:]+$/;
 export const MIN_PORT = 1024;
 export const MAX_PORT = 65535;
 export class LauncherError extends Error {
@@ -42,7 +42,7 @@ export function validateExecPath(path) {
         throw new LauncherError("EXEC_PATH_TOO_LONG", "keiko launcher: resolved executable path exceeds 4096 chars.");
     }
     if (!EXEC_PATH_RE.test(path)) {
-        throw new LauncherError("EXEC_PATH_UNSAFE", `keiko launcher: resolved executable path contains disallowed characters: ${path}\nOnly [A-Za-z0-9_\\-./\\\\:] are permitted. Re-install keiko under a path without spaces or shell metacharacters.`);
+        throw new LauncherError("EXEC_PATH_UNSAFE", `keiko launcher: resolved executable path contains disallowed characters: ${path}\nOnly [A-Za-z0-9_@\\-./\\\\:] are permitted. Re-install keiko under a path without spaces or shell metacharacters.`);
     }
     return path;
 }

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

@@ -6,6 +6,7 @@ type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) =>
 type FetchFn = (input: string, init?: RequestInit) => Promise<Response>;
 type SleepFn = (ms: number) => Promise<void>;
 type ProcessKiller = (pid: number, signal?: NodeJS.Signals | 0) => void;
+type PortAvailabilityFn = (host: string, port: number) => Promise<boolean>;
 export interface LifecycleCliDeps {
     readonly cwd?: string | undefined;
     readonly spawnFn?: SpawnFn | undefined;
@@ -13,6 +14,7 @@ export interface LifecycleCliDeps {
     readonly sleep?: SleepFn | undefined;
     readonly isProcessAlive?: ((pid: number) => boolean) | undefined;
     readonly killProcess?: ProcessKiller | undefined;
+    readonly isPortAvailable?: PortAvailabilityFn | undefined;
 }
 export declare function runLifecycleCli(command: LifecycleCommand, args: readonly string[], io: CliIo, env: EnvSource, deps?: LifecycleCliDeps): Promise<number>;
 export {};

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

@@ -1 +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"}
+{"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;AAIjF,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;AACxE,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAgD3E,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;IACjD,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CAC3D;AAwaD,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,CAqBjB"}

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

@@ -1,5 +1,6 @@
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { spawn } from "node:child_process";
+import { createServer as createNetServer } from "node:net";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SDK_VERSION } from "@oscharko-dev/keiko-sdk";
@@ -151,6 +152,33 @@ function defaultIsProcessAlive(pid) {
         return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM";
     }
 }
+function defaultIsPortAvailable(host, port) {
+    return new Promise((resolveAvailable) => {
+        const server = createNetServer();
+        let settled = false;
+        const settle = (available) => {
+            if (settled)
+                return;
+            settled = true;
+            server.removeAllListeners("error");
+            server.removeAllListeners("listening");
+            if (server.listening) {
+                server.close(() => {
+                    resolveAvailable(available);
+                });
+                return;
+            }
+            resolveAvailable(available);
+        };
+        server.once("error", () => {
+            settle(false);
+        });
+        server.once("listening", () => {
+            settle(true);
+        });
+        server.listen(port, host);
+    });
+}
 function runningPid(options, isAlive) {
     const path = pidFile(options);
     const pid = readPid(path);
@@ -193,12 +221,13 @@ function spawnUiProcess(options, env, deps, cwd) {
     mkdirSync(options.stateDir, { recursive: true, mode: 0o700 });
     const logPath = logFile(options);
     const fd = openSync(logPath, "a", 0o600);
+    const uiEnv = childEnv({ ...env, KEIKO_STATE_DIR: options.stateDir });
     try {
         return {
             child: deps.spawnFn(process.execPath, [cliEntryPath(), "ui", "--port", String(options.port), "--host", options.host], {
                 cwd,
                 detached: true,
-                env: childEnv(env),
+                env: uiEnv,
                 stdio: ["ignore", fd, fd],
             }),
             logPath,
@@ -217,7 +246,7 @@ async function waitForHealth(options, pid, deps) {
             const response = await deps.fetchImpl(healthUrl(options), {
                 signal: AbortSignal.timeout(1_000),
             });
-            if (response.ok) {
+            if (response.ok && deps.isProcessAlive(pid)) {
                 return true;
             }
         }
@@ -228,6 +257,12 @@ async function waitForHealth(options, pid, deps) {
     }
     return false;
 }
+async function ensureStartPortAvailable(options, io, deps) {
+    if (await deps.isPortAvailable(options.host, options.port))
+        return true;
+    io.err(`keiko start: port ${options.host}:${String(options.port)} is already in use. Stop the existing process or choose another port with --port.\n`);
+    return false;
+}
 async function cmdStart(options, io, env, deps, cwd) {
     const running = runningPid(options, deps.isProcessAlive);
     if (running !== undefined) {
@@ -246,6 +281,8 @@ async function cmdStart(options, io, env, deps, cwd) {
         if (stopped !== 0)
             return stopped;
     }
+    if (!(await ensureStartPortAvailable(options, io, deps)))
+        return 1;
     const { child, logPath } = spawnUiProcess(options, env, deps, cwd);
     if (child.pid === undefined) {
         io.err("keiko start: failed to spawn the UI process.\n");
@@ -308,6 +345,17 @@ async function cmdRestart(options, io, env, deps, cwd) {
         return stopped;
     return cmdStart(options, io, env, deps, cwd);
 }
+function runtimeDeps(deps) {
+    return {
+        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),
+        isPortAvailable: deps.isPortAvailable ?? defaultIsPortAvailable,
+    };
+}
 export async function runLifecycleCli(command, args, io, env, deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const options = parseLifecycleArgs(args, cwd, env);
@@ -319,14 +367,7 @@ export async function runLifecycleCli(command, args, io, env, deps = {}) {
         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 fullDeps = runtimeDeps(deps);
     const handlers = {
         start: () => cmdStart(options, io, env, fullDeps, cwd),
         stop: () => cmdStop(options, io, fullDeps),

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.d.ts

@@ -9,6 +9,7 @@ export interface UiCliArgs {
     readonly config: string | undefined;
     readonly uiDbPath: string | undefined;
 }
+type UiParseResult = UiCliArgs | "help" | null;
 export interface UiCliDeps {
     readonly createServer?: (deps: {
         staticRoot: string;
@@ -24,9 +25,10 @@ export interface UiCliDeps {
     readonly cwd?: string | undefined;
 }
 export type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) => ChildProcess;
-export declare function parseUiArgs(args: readonly string[]): UiCliArgs | null;
+export declare function parseUiArgs(args: readonly string[]): UiParseResult;
 export declare function applyServerTimeouts(server: Server): void;
 export declare function waitForShutdown(server: Server): Promise<void>;
 export declare function reExecWithSqliteFlag(_env: EnvSource, spawnFn: SpawnFn): Promise<number>;
 export declare function runUiCli(args: readonly string[], io: CliIo, env: EnvSource, deps?: UiCliDeps): Promise<number>;
+export {};
 //# sourceMappingURL=ui.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKxC,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAazC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAID,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,aAAa,CAAC;KAC5B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAI7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAG3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAEnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,YAAY,KACf,YAAY,CAAC;AAqBlB,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAuBrE;AAsDD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGxD;AAWD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D;AA0BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB7F;AAmDD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,MAAM,CAAC,CAyBjB"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKxC,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAmBzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAa/C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,aAAa,CAAC;KAC5B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAI7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAG3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAEnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,YAAY,KACf,YAAY,CAAC;AA8DlB,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAYlE;AAkFD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGxD;AAWD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D;AA0BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB7F;AAqGD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.js

@@ -11,7 +11,7 @@
 // inheriting stdio and forwarding SIGINT/SIGTERM to the child, then propagates the child's exit
 // code. Injected-test invocations skip the guard entirely.
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
@@ -19,20 +19,18 @@ import { createUiServer, loadCspHeader, buildUiHandlerDeps, DEFAULT_UI_PORT, UI_
 const ALLOWED_HOSTS = new Set(["127.0.0.1", "localhost"]);
 const SQLITE_FLAG = "--experimental-sqlite";
 const KEIKO_ENV_NAME_RE = /^KEIKO_[A-Z0-9_]+$/;
+// Non-KEIKO names the local .env loader may import. Deliberately a closed allowlist —
+// arbitrary secrets must never be slurped into the server process. FIGMA_ACCESS_TOKEN is
+// part of the documented Figma connector contract (#751): the read-only PAT is configured
+// via .env and consumed server-side only.
+const ENV_NAME_ALLOWLIST = new Set(["FIGMA_ACCESS_TOKEN"]);
+const DEFAULT_STATE_DIR = ".keiko";
 const USAGE = `Usage:
   keiko ui [--port PORT] [--host 127.0.0.1|localhost] [--evidence-dir PATH] [--config PATH] [--ui-db PATH]
 
 Launches the local Keiko UI on the loopback interface and prints its URL. The server
 binds 127.0.0.1 only and serves the packaged UI assets (built with \`npm run build:ui\`).
 `;
-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 parsePort(raw) {
     if (!/^\d{1,5}$/.test(raw)) {
         return null;
@@ -40,21 +38,61 @@ function parsePort(raw) {
     const port = Number(raw);
     return port >= 1 && port <= 65535 ? port : null;
 }
+function readFlagValue(args, index) {
+    const value = args[index + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+function isUiFlag(arg) {
+    return (arg === "--port" ||
+        arg === "--host" ||
+        arg === "--evidence-dir" ||
+        arg === "--config" ||
+        arg === "--ui-db");
+}
+function setRawUiOption(raw, flag, value) {
+    switch (flag) {
+        case "--port":
+            raw.portRaw = value;
+            return;
+        case "--host":
+            raw.hostRaw = value;
+            return;
+        case "--evidence-dir":
+            raw.evidenceRaw = value;
+            return;
+        case "--config":
+            raw.configRaw = value;
+            return;
+        case "--ui-db":
+            raw.uiDbRaw = value;
+            return;
+    }
+}
+function collectUiOptions(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 (!isUiFlag(arg))
+            return null;
+        const value = readFlagValue(args, i);
+        if (value === null)
+            return null;
+        setRawUiOption(raw, arg, value);
+        i += 1;
+    }
+    return raw;
+}
 // Parses flags. Returns the parsed args, or null on any usage error (missing flag value, invalid
 // port, or a host other than the two loopback names).
 export function parseUiArgs(args) {
-    const portRaw = flagValue(args, "--port");
-    const hostRaw = flagValue(args, "--host");
-    const evidenceRaw = flagValue(args, "--evidence-dir");
-    const configRaw = flagValue(args, "--config");
-    const uiDbRaw = flagValue(args, "--ui-db");
-    if (portRaw === null ||
-        hostRaw === null ||
-        evidenceRaw === null ||
-        configRaw === null ||
-        uiDbRaw === null) {
-        return null;
-    }
+    const raw = collectUiOptions(args);
+    if (raw === "help" || raw === null)
+        return raw;
+    const { portRaw, hostRaw, evidenceRaw, configRaw, uiDbRaw } = raw;
     if (hostRaw !== undefined && !ALLOWED_HOSTS.has(hostRaw)) {
         return null;
     }
@@ -100,7 +138,7 @@ function loadLocalKeikoEnv(cwd, env) {
         if (equals <= 0)
             continue;
         const key = line.slice(0, equals).trim();
-        if (!KEIKO_ENV_NAME_RE.test(key))
+        if (!KEIKO_ENV_NAME_RE.test(key) && !ENV_NAME_ALLOWLIST.has(key))
             continue;
         if (merged[key] !== undefined)
             continue;
@@ -111,6 +149,27 @@ function loadLocalKeikoEnv(cwd, env) {
 function resolveUiConfigPath(parsed, env) {
     return parsed.config ?? env.KEIKO_CONFIG_FILE;
 }
+function hasEnvValue(value) {
+    return value !== undefined && value.length > 0;
+}
+function resolveRuntimeStateDir(cwd, env) {
+    const raw = env.KEIKO_STATE_DIR;
+    if (hasEnvValue(raw)) {
+        return isAbsolute(raw) ? raw : resolve(cwd, raw);
+    }
+    return resolve(cwd, DEFAULT_STATE_DIR);
+}
+function withDefaultLocalRuntimeStateEnv(cwd, parsed, env) {
+    const stateDir = resolveRuntimeStateDir(cwd, env);
+    const next = { ...env, KEIKO_STATE_DIR: stateDir };
+    if (parsed.uiDbPath === undefined && !hasEnvValue(next.KEIKO_UI_DATA_DIR)) {
+        next.KEIKO_UI_DATA_DIR = join(stateDir, "ui");
+    }
+    if (!hasEnvValue(next.KEIKO_MEMORY_DIR)) {
+        next.KEIKO_MEMORY_DIR = join(stateDir, "memory");
+    }
+    return next;
+}
 // Conservative request/header timeouts on the loopback BFF (defense in depth, L2/L3): even on
 // 127.0.0.1 a slow or stuck client must not hold a connection indefinitely. headersTimeout must be
 // at or below requestTimeout so an incomplete request line/header set is cut first.
@@ -211,12 +270,13 @@ async function maybeReExecForSqlite(env, deps) {
     const spawnFn = deps.spawnFn ?? spawn;
     return reExecWithSqliteFlag(env, spawnFn);
 }
-function buildHandlerDepsOrReport(parsed, effectiveEnv, io) {
+function buildHandlerDepsOrReport(parsed, cwd, effectiveEnv, io) {
     try {
         return buildUiHandlerDeps({
             configPath: resolveUiConfigPath(parsed, effectiveEnv),
             evidenceDir: parsed.evidenceDir,
             uiDbPath: parsed.uiDbPath,
+            initialProjectPath: cwd,
             env: effectiveEnv,
         });
     }
@@ -228,6 +288,19 @@ function buildHandlerDepsOrReport(parsed, effectiveEnv, io) {
         throw error;
     }
 }
+function registerLaunchProjectOrReport(cwd, handlerDeps, io) {
+    try {
+        handlerDeps.store.createProject(cwd);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof UiStoreError) {
+            io.err(`keiko ui: ${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+}
 function ensureStaticRoot(staticRoot, io) {
     if (existsSync(staticRoot)) {
         return true;
@@ -235,37 +308,54 @@ function ensureStaticRoot(staticRoot, io) {
     io.err(`keiko ui: UI assets not found at ${staticRoot}. Run \`npm run build:ui\` first.\n`);
     return false;
 }
+function parseUiArgsOrExit(args, io) {
+    const parsed = parseUiArgs(args);
+    if (parsed === "help") {
+        io.out(USAGE);
+        return 0;
+    }
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    return parsed;
+}
 async function maybeWaitForShutdown(server, deps) {
     if (deps.createServer !== undefined) {
         return;
     }
     await waitForShutdown(server);
 }
+async function startUiServer(staticRoot, csp, parsed, handlerDeps, io, deps) {
+    const factory = deps.createServer ?? createUiServer;
+    const server = await factory({ staticRoot, csp, port: parsed.port, handlerDeps });
+    applyServerTimeouts(server);
+    await listen(server, parsed.port);
+    io.out(`Keiko UI listening on http://${UI_HOST}:${String(parsed.port)}\n`);
+    // Block only in the real CLI path (no injected factory). Injected-server tests skip blocking so
+    // they don't hang; the real process must stay alive until signalled.
+    await maybeWaitForShutdown(server, deps);
+}
 export async function runUiCli(args, io, env, deps = {}) {
-    const effectiveEnv = loadLocalKeikoEnv(deps.cwd ?? process.cwd(), env);
+    const cwd = deps.cwd ?? process.cwd();
+    const effectiveEnv = loadLocalKeikoEnv(cwd, env);
+    const parsed = parseUiArgsOrExit(args, io);
+    if (typeof parsed === "number")
+        return parsed;
     const reExec = await maybeReExecForSqlite(effectiveEnv, deps);
     if (reExec !== undefined)
         return reExec;
-    const parsed = parseUiArgs(args);
-    if (parsed === null) {
-        io.err(USAGE);
-        return 2;
-    }
     const staticRoot = deps.staticRoot ?? defaultStaticRoot();
     if (!ensureStaticRoot(staticRoot, io)) {
         return 1;
     }
     const csp = await loadCspHeader(deps.hashesFile ?? join(staticRoot, "..", "csp-hashes.json"));
-    const handlerDeps = buildHandlerDepsOrReport(parsed, effectiveEnv, io);
+    const handlerDeps = buildHandlerDepsOrReport(parsed, cwd, withDefaultLocalRuntimeStateEnv(cwd, parsed, effectiveEnv), io);
     if (typeof handlerDeps === "number")
         return handlerDeps;
-    const factory = deps.createServer ?? createUiServer;
-    const server = await factory({ staticRoot, csp, port: parsed.port, handlerDeps });
-    applyServerTimeouts(server);
-    await listen(server, parsed.port);
-    io.out(`Keiko UI listening on http://${UI_HOST}:${String(parsed.port)}\n`);
-    // Block only in the real CLI path (no injected factory). Injected-server tests skip blocking so
-    // they don't hang; the real process must stay alive until signalled.
-    await maybeWaitForShutdown(server, deps);
+    const launchProjectResult = registerLaunchProjectOrReport(cwd, handlerDeps, io);
+    if (launchProjectResult !== null)
+        return launchProjectResult;
+    await startUiServer(staticRoot, csp, parsed, handlerDeps, io, deps);
     return 0;
 }