@oscharko-dev/keiko-cli 0.2.0

package/dist/ui.js

@@ -0,0 +1,450 @@
+// `keiko ui` — launches the local Wave 1 UI BFF (ADR-0011). It resolves the packaged static export
+// (dist/ui/static) and the precomputed CSP hashes (dist/ui/csp-hashes.json) relative to this
+// compiled module, builds the CSP, starts createUiServer bound to 127.0.0.1 only, prints the local
+// URL, and keeps running until the process is signalled. Exit 2 on a usage error (bad --host/--port
+// or a flag missing its value), 1 when the static export is not present (the package was built with
+// `npm run build` but not `npm run build:ui`).
+//
+// ADR-0013 D2 site 1 — Detect-and-re-exec guard. Node 22.0–22.11 builds require
+// --experimental-sqlite to import node:sqlite; 22.22+ loads it without the flag. The guard tries
+// the import; on failure it re-spawns the current process with --experimental-sqlite prepended,
+// 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, unwatchFile, watchFile } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+import { buildCspHeader, createUiServer, buildUiHandlerDeps, DEFAULT_UI_PORT, UI_HOST, UiStoreError, extractInlineScriptHashes, } from "@oscharko-dev/keiko-server";
+import { resolvePreferredInstallLayout } from "./install-layout.js";
+const ALLOWED_HOSTS = new Set(["127.0.0.1", "localhost"]);
+const KEIKO_PROCESS_TITLE = "Keiko";
+const SQLITE_FLAG = "--experimental-sqlite";
+// Deliberately a closed allowlist: repo-local .env discovery must not import KEIKO_*
+// runtime configuration because the UI may be launched from an untrusted project root.
+// FIGMA_ACCESS_TOKEN is the documented Figma connector exception (#751); it is consumed
+// server-side only and never sent to the browser.
+const LOCAL_DOTENV_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\`).
+`;
+async function collectHtmlFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectHtmlFiles(full)));
+            continue;
+        }
+        if (entry.name.endsWith(".html")) {
+            files.push(full);
+        }
+    }
+    return files;
+}
+function parseHashList(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.filter((entry) => typeof entry === "string");
+}
+async function loadCspMaterial(staticRoot, hashesFile) {
+    const htmlFiles = await collectHtmlFiles(staticRoot);
+    const documents = await Promise.all(htmlFiles.map((file) => readFile(file, "utf8")));
+    const runtimeHashes = extractInlineScriptHashes(documents);
+    try {
+        const raw = await readFile(hashesFile, "utf8");
+        const storedHashes = parseHashList(raw);
+        if (storedHashes.length === runtimeHashes.length &&
+            storedHashes.every((hash, index) => hash === runtimeHashes[index])) {
+            return { hashes: storedHashes, header: buildCspHeader(storedHashes) };
+        }
+    }
+    catch {
+        // Fall back to the runtime export-derived hashes below.
+    }
+    return { hashes: runtimeHashes, header: buildCspHeader(runtimeHashes) };
+}
+function parsePort(raw) {
+    if (!/^\d{1,5}$/.test(raw)) {
+        return null;
+    }
+    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 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;
+    }
+    const port = portRaw === undefined ? DEFAULT_UI_PORT : parsePort(portRaw);
+    if (port === null) {
+        return null;
+    }
+    return { port, evidenceDir: evidenceRaw, config: configRaw, uiDbPath: uiDbRaw };
+}
+function defaultStaticRoot(cwd) {
+    const preferredLayout = resolvePreferredInstallLayout(cwd);
+    if (preferredLayout !== undefined)
+        return preferredLayout.staticRoot;
+    // The root bin shim (`dist/cli/index.js`) surfaces `KEIKO_UI_STATIC_ROOT` so the
+    // cli package does not have to know its own installation layout. The
+    // import.meta.url fallback preserves the standalone behaviour for callers that
+    // construct UiCliDeps without going through the bin shim (e.g. in tests).
+    const fromEnv = process.env.KEIKO_UI_STATIC_ROOT;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv;
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "ui", "static");
+}
+function parseEnvValue(raw) {
+    const value = raw.trim();
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === `"` && last === `"`) || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function loadLocalKeikoEnv(cwd, env) {
+    const file = join(cwd, ".env");
+    if (!existsSync(file)) {
+        return env;
+    }
+    const merged = { ...env };
+    const text = readFileSync(file, "utf8");
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const equals = line.indexOf("=");
+        if (equals <= 0)
+            continue;
+        const key = line.slice(0, equals).trim();
+        if (!LOCAL_DOTENV_ENV_NAME_ALLOWLIST.has(key))
+            continue;
+        if (merged[key] !== undefined)
+            continue;
+        merged[key] = parseEnvValue(line.slice(equals + 1));
+    }
+    return merged;
+}
+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.
+const REQUEST_TIMEOUT_MS = 30_000;
+const HEADERS_TIMEOUT_MS = 10_000;
+export function applyServerTimeouts(server) {
+    server.requestTimeout = REQUEST_TIMEOUT_MS;
+    server.headersTimeout = HEADERS_TIMEOUT_MS;
+}
+async function listen(server, port) {
+    await new Promise((res, rej) => {
+        server.once("error", rej);
+        server.listen(port, UI_HOST, res);
+    });
+}
+// Keeps the real-CLI process alive until a shutdown signal or server close. Resolves cleanly so
+// the caller can return 0. Registered listeners are removed on resolve to prevent leaks.
+export function waitForShutdown(server) {
+    return new Promise((resolve) => {
+        const onClose = () => {
+            process.removeListener("SIGINT", onSignal);
+            process.removeListener("SIGTERM", onSignal);
+            resolve();
+        };
+        const onSignal = () => {
+            server.removeListener("close", onClose);
+            server.close(() => {
+                resolve();
+            });
+        };
+        server.once("close", onClose);
+        process.once("SIGINT", onSignal);
+        process.once("SIGTERM", onSignal);
+    });
+}
+// Default probe: try to require node:sqlite. Any failure (ERR_UNKNOWN_BUILTIN_MODULE on early
+// 22.x, or a thrown ExperimentalWarning that escaped) means we need the flag. The require is
+// guarded inside a try; we never throw past here.
+function defaultSqliteProbe() {
+    try {
+        const req = createRequire(import.meta.url);
+        req("node:sqlite");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Returns true if `--experimental-sqlite` is already on execArgv, meaning we are inside the child
+// already and must not loop. Inspects both the supplied execArgv source (Node-level flags the
+// parent inherited) AND NODE_OPTIONS (where the flag may live in env).
+function alreadyFlagged(env, execArgv) {
+    if (execArgv.includes(SQLITE_FLAG))
+        return true;
+    const nodeOptions = env.NODE_OPTIONS;
+    return typeof nodeOptions === "string" && nodeOptions.includes(SQLITE_FLAG);
+}
+// Re-spawns the current process with --experimental-sqlite prepended, inheriting stdio. Returns
+// the exit code the child terminated with so the parent can propagate it.
+export async function reExecWithSqliteFlag(_env, spawnFn, cwd) {
+    const entry = resolvePreferredInstallLayout(cwd)?.binPath ?? process.argv[1];
+    if (entry === undefined)
+        return 1;
+    const childArgs = [SQLITE_FLAG, ...process.execArgv, entry, ...process.argv.slice(2)];
+    const child = spawnFn(process.execPath, childArgs, {
+        argv0: KEIKO_PROCESS_TITLE,
+        stdio: "inherit",
+    });
+    const forwardSigint = () => {
+        child.kill("SIGINT");
+    };
+    const forwardSigterm = () => {
+        child.kill("SIGTERM");
+    };
+    process.on("SIGINT", forwardSigint);
+    process.on("SIGTERM", forwardSigterm);
+    return new Promise((res) => {
+        child.on("exit", (code, signal) => {
+            process.removeListener("SIGINT", forwardSigint);
+            process.removeListener("SIGTERM", forwardSigterm);
+            if (typeof code === "number") {
+                res(code);
+                return;
+            }
+            res(signal === null ? 1 : 128);
+        });
+    });
+}
+// Returns undefined when no re-exec is needed; returns the child's exit code when a re-exec
+// happened. The guard never runs when an injected test factory bypasses the production loop, and
+// it never re-loops once --experimental-sqlite is already in execArgv.
+async function maybeReExecForSqlite(env, deps, cwd) {
+    if (deps.createServer !== undefined)
+        return undefined;
+    const execArgv = (deps.currentExecArgv ?? (() => process.execArgv))();
+    if (alreadyFlagged(env, execArgv))
+        return undefined;
+    const probe = deps.sqliteProbe ?? defaultSqliteProbe;
+    if (probe())
+        return undefined;
+    const spawnFn = deps.spawnFn ?? spawn;
+    return reExecWithSqliteFlag(env, spawnFn, cwd);
+}
+function buildHandlerDepsOrReport(parsed, cwd, effectiveEnv, io) {
+    try {
+        return buildUiHandlerDeps({
+            configPath: resolveUiConfigPath(parsed, effectiveEnv),
+            evidenceDir: parsed.evidenceDir,
+            uiDbPath: parsed.uiDbPath,
+            initialProjectPath: cwd,
+            env: effectiveEnv,
+        });
+    }
+    catch (error) {
+        if (error instanceof UiStoreError) {
+            io.err(`keiko ui: ${error.message}\n`);
+            return 2;
+        }
+        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;
+    }
+    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 createLiveCspSource(staticRoot, hashesFile, io) {
+    let current = (await loadCspMaterial(staticRoot, hashesFile)).header;
+    let reloading = false;
+    let disposed = false;
+    let warned = false;
+    const reload = async () => {
+        if (reloading || disposed)
+            return;
+        reloading = true;
+        try {
+            current = (await loadCspMaterial(staticRoot, hashesFile)).header;
+            warned = false;
+        }
+        catch (error) {
+            if (!warned) {
+                const message = error instanceof Error ? error.message : String(error);
+                io.err(`Warning: failed to reload CSP hashes from ${hashesFile}: ${message}\n`);
+                warned = true;
+            }
+        }
+        finally {
+            reloading = false;
+        }
+    };
+    // Issue #1214 follow-up: when the UI process starts while build:ui is still writing the static
+    // export and `csp-hashes.json`, a one-shot CSP read can freeze a stale policy into the process.
+    // Watching the hash file keeps fresh page loads aligned with the latest exported inline scripts.
+    watchFile(hashesFile, { interval: 500 }, () => {
+        void reload();
+    });
+    return {
+        csp: () => current,
+        dispose: () => {
+            disposed = true;
+            unwatchFile(hashesFile);
+        },
+    };
+}
+export async function runUiCli(args, io, env, deps = {}) {
+    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, cwd);
+    if (reExec !== undefined)
+        return reExec;
+    const staticRoot = deps.staticRoot ?? defaultStaticRoot(cwd);
+    if (!ensureStaticRoot(staticRoot, io)) {
+        return 1;
+    }
+    const cspRuntime = await createLiveCspSource(staticRoot, deps.hashesFile ?? join(staticRoot, "..", "csp-hashes.json"), io);
+    const handlerDeps = buildHandlerDepsOrReport(parsed, cwd, withDefaultLocalRuntimeStateEnv(cwd, parsed, effectiveEnv), io);
+    if (typeof handlerDeps === "number")
+        return handlerDeps;
+    const launchProjectResult = registerLaunchProjectOrReport(cwd, handlerDeps, io);
+    if (launchProjectResult !== null)
+        return launchProjectResult;
+    try {
+        await startUiServer(staticRoot, cspRuntime.csp(), parsed, handlerDeps, io, deps);
+        return 0;
+    }
+    finally {
+        cspRuntime.dispose();
+    }
+}

package/dist/uninstall.d.ts

@@ -0,0 +1,10 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+export interface UninstallCliDeps {
+    readonly cwd?: string | undefined;
+    readonly homedir?: () => string;
+    readonly isProcessAlive?: (pid: number) => boolean;
+    readonly killProcess?: (pid: number, signal?: NodeJS.Signals | 0) => void;
+}
+export declare function runUninstallCli(args: readonly string[], io: CliIo, env: EnvSource, deps?: UninstallCliDeps): number;
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/uninstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAsDzC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,IAAI,CAAC;CAC3E;AAoTD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,gBAAqB,GAC1B,MAAM,CA+BR"}