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

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;AAczC,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;AAgED,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,CA2BjB"}

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,13 @@ 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_]+$/;
+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 +33,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;
     }
@@ -111,6 +144,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.
@@ -235,6 +289,18 @@ 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;
@@ -242,21 +308,20 @@ async function maybeWaitForShutdown(server, deps) {
     await waitForShutdown(server);
 }
 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, withDefaultLocalRuntimeStateEnv(cwd, parsed, effectiveEnv), io);
     if (typeof handlerDeps === "number")
         return handlerDeps;
     const factory = deps.createServer ?? createUiServer;

package/node_modules/@oscharko-dev/keiko-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko-cli",
-  "version": "0.2.0-beta.2",
+  "version": "0.2.0-beta.3",
   "private": true,
   "type": "module",
   "license": "Apache-2.0",