@oscharko-dev/keiko 0.1.0-beta.0 → 0.1.0-beta.3

package/dist/cli/gen-tests.js

@@ -97,7 +97,8 @@ function resolveTarget(parsed) {
     };
 }
 // Builds a ModelPort from the gateway config, or returns a usage/runtime error code via io. The
-// workflow sends plain chat messages, so the default only requires a configured chat model.
+// default selector is workflow-safe: generated test patches need tool use and structured output.
+// Explicit --model remains operator-controlled after config membership checks.
 function buildModel(parsed, io, env) {
     try {
         const path = parsed.config ?? env.KEIKO_CONFIG_FILE;
@@ -111,9 +112,11 @@ function buildModel(parsed, io, env) {
         const modelId = parsed.model ??
             selectConfiguredModel(config, {
                 kind: "chat",
+                toolCalling: true,
+                structuredOutput: true,
             });
         if (modelId === undefined) {
-            io.err("Error: no configured chat model is available.\n");
+            io.err("Error: no configured workflow-capable chat model is available.\n");
             return 1;
         }
         return { port: new GatewayModelPort(new Gateway(config)), modelId };
@@ -139,6 +142,8 @@ function resolveConfiguredModelId(parsed, env) {
     }
     return selectConfiguredModel(config, {
         kind: "chat",
+        toolCalling: true,
+        structuredOutput: true,
     });
 }
 function resolveModel(parsed, io, env, deps) {
@@ -146,7 +151,7 @@ function resolveModel(parsed, io, env, deps) {
         try {
             const modelId = resolveConfiguredModelId(parsed, env);
             if (modelId === undefined) {
-                io.err("Error: no configured chat model is available.\n");
+                io.err("Error: no configured workflow-capable chat model is available.\n");
                 return 1;
             }
             return { port: deps.model, modelId };

package/dist/cli/init.d.ts

@@ -0,0 +1,8 @@
+import type { EnvSource } from "../gateway/config.js";
+import type { CliIo } from "./runner.js";
+export declare const KEIKO_START_SCRIPT = "keiko start";
+export declare const KEIKO_STOP_SCRIPT = "keiko stop";
+export interface InitCliDeps {
+    readonly cwd?: string | undefined;
+}
+export declare function runInitCli(args: readonly string[], io: CliIo, _env: EnvSource, deps?: InitCliDeps): number;

package/dist/cli/init.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+export const KEIKO_START_SCRIPT = "keiko start";
+export const KEIKO_STOP_SCRIPT = "keiko stop";
+const USAGE = `Usage:
+  keiko init [--package PATH] [--force] [--dry-run]
+
+Adds local package.json scripts for running Keiko:
+  keiko:start  -> keiko start
+  keiko:stop   -> keiko stop
+
+Run this from the project where @oscharko-dev/keiko is installed.
+`;
+const EXPECTED_SCRIPTS = {
+    "keiko:start": KEIKO_START_SCRIPT,
+    "keiko:stop": KEIKO_STOP_SCRIPT,
+};
+function readFlagValue(args, index) {
+    const value = args[index + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+function parseInitArgs(args, cwd) {
+    let packagePath = resolve(cwd, "package.json");
+    let force = false;
+    let dryRun = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--help" || arg === "-h") {
+            return "help";
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--package") {
+            const value = readFlagValue(args, i);
+            if (value === null)
+                return null;
+            packagePath = resolve(cwd, value);
+            i += 1;
+            continue;
+        }
+        return null;
+    }
+    return { packagePath, force, dryRun };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringifyPackageJson(data) {
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+function loadPackageJson(packagePath) {
+    if (!existsSync(packagePath)) {
+        return { ok: false, message: `keiko init: package.json not found at ${packagePath}.\n` };
+    }
+    let packageJson;
+    try {
+        packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    }
+    catch {
+        return {
+            ok: false,
+            message: `keiko init: package.json at ${packagePath} is not valid JSON.\n`,
+        };
+    }
+    if (!isRecord(packageJson)) {
+        return { ok: false, message: "keiko init: package.json must contain a JSON object.\n" };
+    }
+    return { ok: true, packageJson };
+}
+function initializedPackageJson(packageJson, force) {
+    const existingScripts = packageJson.scripts;
+    if (existingScripts !== undefined && !isRecord(existingScripts)) {
+        return { ok: false, message: "keiko init: package.json scripts must be a JSON object.\n" };
+    }
+    const scripts = existingScripts ?? {};
+    const conflicts = Object.entries(EXPECTED_SCRIPTS)
+        .filter(([name, value]) => scripts[name] !== undefined && scripts[name] !== value)
+        .map(([name]) => name);
+    if (conflicts.length > 0 && !force) {
+        return {
+            ok: false,
+            message: `keiko init: package.json already defines conflicting script(s): ${conflicts.join(", ")}.\n` +
+                "Run `npx keiko init --force` to overwrite them.\n",
+        };
+    }
+    return { ok: true, value: { ...packageJson, scripts: { ...scripts, ...EXPECTED_SCRIPTS } } };
+}
+export function runInitCli(args, io, _env, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const parsed = parseInitArgs(args, cwd);
+    if (parsed === "help") {
+        io.out(USAGE);
+        return 0;
+    }
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    const loaded = loadPackageJson(parsed.packagePath);
+    if (!loaded.ok) {
+        io.err(loaded.message);
+        return 1;
+    }
+    const initialized = initializedPackageJson(loaded.packageJson, parsed.force);
+    if (!initialized.ok) {
+        io.err(initialized.message);
+        return 1;
+    }
+    if (parsed.dryRun) {
+        io.out(stringifyPackageJson(initialized.value));
+        return 0;
+    }
+    writeFileSync(parsed.packagePath, stringifyPackageJson(initialized.value), "utf8");
+    io.out("Keiko scripts added to package.json:\n" + "  npm run keiko:start\n" + "  npm run keiko:stop\n");
+    return 0;
+}

package/dist/cli/investigate.js

@@ -125,9 +125,11 @@ function buildModel(parsed, io, env) {
         const modelId = parsed.model ??
             selectConfiguredModel(config, {
                 kind: "chat",
+                toolCalling: true,
+                structuredOutput: true,
             });
         if (modelId === undefined) {
-            io.err("Error: no configured chat model is available.\n");
+            io.err("Error: no configured workflow-capable chat model is available.\n");
             return 1;
         }
         return { port: new GatewayModelPort(new Gateway(config)), modelId };
@@ -153,6 +155,8 @@ function resolveConfiguredModelId(parsed, env) {
     }
     return selectConfiguredModel(config, {
         kind: "chat",
+        toolCalling: true,
+        structuredOutput: true,
     });
 }
 function resolveModel(parsed, io, env, deps) {
@@ -160,7 +164,7 @@ function resolveModel(parsed, io, env, deps) {
         try {
             const modelId = resolveConfiguredModelId(parsed, env);
             if (modelId === undefined) {
-                io.err("Error: no configured chat model is available.\n");
+                io.err("Error: no configured workflow-capable chat model is available.\n");
                 return 1;
             }
             return { port: deps.model, modelId };

package/dist/cli/lifecycle.d.ts

@@ -0,0 +1,18 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import type { EnvSource } from "../gateway/config.js";
+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 {};

package/dist/cli/lifecycle.js

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

package/dist/cli/models.js

@@ -1,5 +1,5 @@
-// `keiko models` CLI handler. Synchronous by design: `list` reads the static
-// capability registry; `validate` reads a config file with readFileSync and runs
+// `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.

package/dist/cli/runner.js

@@ -6,6 +6,8 @@ import { runGenTestsCli } from "./gen-tests.js";
 import { runInvestigateCli } from "./investigate.js";
 import { runEvidenceCli } from "./evidence.js";
 import { runEvaluateCli } from "./evaluate.js";
+import { runInitCli } from "./init.js";
+import { runLifecycleCli } from "./lifecycle.js";
 import { runUiCli } from "./ui.js";
 import { SDK_VERSION } from "../sdk/index.js";
 const HELP_TEXT = `keiko ${SDK_VERSION}
@@ -14,6 +16,8 @@ Enterprise model-agnostic developer-assist coding agent.
 Usage:
   keiko [--help | -h]      Print this help and exit.
   keiko [--version | -v]   Print the version and exit.
+  keiko init [OPTIONS]     Add local package.json start/stop scripts.
+  keiko start|stop|status|restart Manage the local Keiko UI process.
   keiko models list        List registered model capabilities.
   keiko models validate    Validate gateway configuration.
   keiko run <task>         Run a bounded dry-run task through the agent harness.
@@ -30,36 +34,25 @@ Exit codes:
   1  Runtime error
   2  Usage error
 `;
+const COMMAND_HANDLERS = {
+    models: runModelsCli,
+    run: runAgentCli,
+    context: (rest, io) => runContextCli(rest, io),
+    verify: (rest, io) => runVerifyCli(rest, io),
+    "gen-tests": runGenTestsCli,
+    investigate: runInvestigateCli,
+    evidence: (rest, io, env) => runEvidenceCli(rest, io, { env }),
+    evaluate: (rest, io, env) => runEvaluateCli(rest, io, env, {}),
+    init: runInitCli,
+    start: (rest, io, env) => runLifecycleCli("start", rest, io, env),
+    stop: (rest, io, env) => runLifecycleCli("stop", rest, io, env),
+    status: (rest, io, env) => runLifecycleCli("status", rest, io, env),
+    restart: (rest, io, env) => runLifecycleCli("restart", rest, io, env),
+    ui: runUiCli,
+};
 // Dispatches named subcommands; returns undefined when the name is not recognised.
 function dispatchCommand(name, rest, io, env) {
-    if (name === "models") {
-        return runModelsCli(rest, io, env);
-    }
-    if (name === "run") {
-        return runAgentCli(rest, io, env);
-    }
-    if (name === "context") {
-        return runContextCli(rest, io);
-    }
-    if (name === "verify") {
-        return runVerifyCli(rest, io);
-    }
-    if (name === "gen-tests") {
-        return runGenTestsCli(rest, io, env);
-    }
-    if (name === "investigate") {
-        return runInvestigateCli(rest, io, env);
-    }
-    if (name === "evidence") {
-        return runEvidenceCli(rest, io, { env });
-    }
-    if (name === "evaluate") {
-        return runEvaluateCli(rest, io, env, {});
-    }
-    if (name === "ui") {
-        return runUiCli(rest, io, env);
-    }
-    return undefined;
+    return COMMAND_HANDLERS[name]?.(rest, io, env);
 }
 // Returns a number for synchronous commands; the async `run` command returns a Promise.
 // The process shim in index.ts awaits the union before calling process.exit.

package/dist/gateway/capabilities.d.ts

@@ -8,4 +8,5 @@ export interface CapabilityQuery {
 }
 export declare function findCapability(modelId: string): ModelCapability | undefined;
 export declare function listCapabilities(): readonly ModelCapability[];
+export declare function createDefaultChatCapability(modelId: string): ModelCapability;
 export declare function selectCheapest(query: CapabilityQuery): ModelCapability | undefined;