@oscharko-dev/keiko 0.1.0-beta.0

package/dist/cli/gen-tests.js

@@ -0,0 +1,208 @@
+// `keiko gen-tests` — generates a reviewable unit-test patch for a target file/dir/changed-set
+// (ADR-0008 D9). Dry-run by default; --apply writes the tests and runs verification. The text path
+// prints the reviewable proposed diff AND the #6 validation summary so a terminal reviewer sees the
+// actual generated test code (AC #4/#6); --json emits the full UnitTestWorkflowReport. The gateway
+// ModelPort is built from config (loadConfigFromFile); tests inject deps.model directly so no live
+// gateway is needed. Exit 0 on completed/dry-run, 1 on rejected/cancelled/failed/runtime, 2 on
+// usage. Mirrors runVerifyCli's flag-parse / typed-error-catch structure.
+import { Gateway } from "../gateway/gateway.js";
+import { loadConfigFromFile } from "../gateway/config.js";
+import { ConfigInvalidError, GatewayError } from "../gateway/errors.js";
+import { assertConfiguredModel, selectConfiguredModel } from "../gateway/model-selection.js";
+import { redact } from "../gateway/redaction.js";
+import { GatewayModelPort } from "../harness/adapters.js";
+import { WorkspaceError } from "../workspace/index.js";
+import { generateUnitTests, renderMarkdownReport } from "../workflows/index.js";
+const USAGE = `Usage:
+  keiko gen-tests (--file PATH | --dir PATH) [--function NAME] [--changed FILE[,FILE]]
+                  [--apply] [--model MODEL_ID] [--config PATH] [--json] [--dir-root PATH]
+
+Generates a reviewable unit-test patch for a target TypeScript file, function, or
+module. Dry-run by default (prints the proposed diff, writes nothing); pass --apply
+to write the tests and run verification through the safe tool + verification layers.
+`;
+// Returns the value of a `--flag value` pair, undefined if absent, or null if present without a
+// value (a usage error) — identical contract to runVerifyCli's flagValue.
+function flagValue(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1) {
+        return undefined;
+    }
+    const value = args[i + 1];
+    return value === undefined || value.startsWith("--") ? null : value;
+}
+const VALUE_FLAGS = [
+    "--file",
+    "--dir",
+    "--function",
+    "--changed",
+    "--model",
+    "--config",
+    "--dir-root",
+];
+// Reads every value flag once; returns null if any is present without a value (a usage error).
+function readValueFlags(args) {
+    const values = {};
+    for (const flag of VALUE_FLAGS) {
+        const value = flagValue(args, flag);
+        if (value === null) {
+            return null;
+        }
+        values[flag] = value;
+    }
+    return values;
+}
+function parseArgs(args) {
+    const values = readValueFlags(args);
+    if (values === null) {
+        return null;
+    }
+    const file = values["--file"];
+    const dir = values["--dir"];
+    // Exactly one of --file / --dir is required.
+    if ((file === undefined) === (dir === undefined)) {
+        return null;
+    }
+    const changedRaw = values["--changed"];
+    const changedPaths = changedRaw === undefined
+        ? undefined
+        : changedRaw
+            .split(",")
+            .map((p) => p.trim())
+            .filter((p) => p.length > 0);
+    return {
+        file,
+        dir,
+        fn: values["--function"],
+        changed: changedPaths === undefined || changedPaths.length === 0 ? undefined : changedPaths,
+        apply: args.includes("--apply"),
+        model: values["--model"],
+        config: values["--config"],
+        json: args.includes("--json"),
+        dirRoot: values["--dir-root"] ?? ".",
+    };
+}
+// --changed composes with both --file and --dir: when present it is the authoritative target set.
+function resolveTarget(parsed) {
+    if (parsed.changed !== undefined) {
+        return { kind: "changedFiles", filePaths: parsed.changed };
+    }
+    if (parsed.dir !== undefined) {
+        return { kind: "module", moduleDir: parsed.dir };
+    }
+    return {
+        kind: "file",
+        filePath: parsed.file ?? "",
+        ...(parsed.fn === undefined ? {} : { targetFunction: parsed.fn }),
+    };
+}
+// 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.
+function buildModel(parsed, io, env) {
+    try {
+        const path = parsed.config ?? env.KEIKO_CONFIG_FILE;
+        if (path === undefined) {
+            throw new ConfigInvalidError("no config source; pass --config PATH or set KEIKO_CONFIG_FILE");
+        }
+        const config = loadConfigFromFile(path, env);
+        if (parsed.model !== undefined) {
+            assertConfiguredModel(config, parsed.model);
+        }
+        const modelId = parsed.model ??
+            selectConfiguredModel(config, {
+                kind: "chat",
+            });
+        if (modelId === undefined) {
+            io.err("Error: no configured chat model is available.\n");
+            return 1;
+        }
+        return { port: new GatewayModelPort(new Gateway(config)), modelId };
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n` +
+                `Provide a gateway config with --config PATH or KEIKO_CONFIG_FILE.\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+function resolveConfiguredModelId(parsed, env) {
+    const path = parsed.config ?? env.KEIKO_CONFIG_FILE;
+    if (path === undefined) {
+        return parsed.model ?? "default";
+    }
+    const config = loadConfigFromFile(path, env);
+    if (parsed.model !== undefined) {
+        assertConfiguredModel(config, parsed.model);
+        return parsed.model;
+    }
+    return selectConfiguredModel(config, {
+        kind: "chat",
+    });
+}
+function resolveModel(parsed, io, env, deps) {
+    if (deps.model !== undefined) {
+        try {
+            const modelId = resolveConfiguredModelId(parsed, env);
+            if (modelId === undefined) {
+                io.err("Error: no configured chat model is available.\n");
+                return 1;
+            }
+            return { port: deps.model, modelId };
+        }
+        catch (error) {
+            if (error instanceof GatewayError) {
+                io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n`);
+                return 1;
+            }
+            throw error;
+        }
+    }
+    return buildModel(parsed, io, env);
+}
+function printText(report, io) {
+    io.out(`${renderMarkdownReport(report)}\n`);
+    if (report.dryRunPreview !== undefined) {
+        io.out(`\n${report.dryRunPreview}\n`);
+    }
+    if (report.proposedDiff !== undefined) {
+        io.out(`\n--- proposed test patch ---\n${report.proposedDiff}\n`);
+    }
+}
+function exitCodeFor(status) {
+    return status === "completed" || status === "dry-run" ? 0 : 1;
+}
+export async function runGenTestsCli(args, io, env = {}, deps = {}) {
+    const parsed = parseArgs(args);
+    if (parsed === null) {
+        io.err(USAGE);
+        return 2;
+    }
+    const model = resolveModel(parsed, io, env, deps);
+    if (typeof model === "number") {
+        return model;
+    }
+    try {
+        const report = await generateUnitTests({
+            workspaceRoot: parsed.dirRoot,
+            target: resolveTarget(parsed),
+            apply: parsed.apply,
+            modelId: model.modelId,
+        }, { model: model.port });
+        if (parsed.json) {
+            io.out(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            printText(report, io);
+        }
+        return exitCodeFor(report.status);
+    }
+    catch (error) {
+        if (error instanceof WorkspaceError) {
+            io.err(`Error [${error.code}]: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runCli } from "./runner.js";
+// runCli returns a number for synchronous commands and a Promise<number> for the async
+// `run` command. Promise.resolve normalises both before exiting with the resulting code.
+void Promise.resolve(runCli(process.argv.slice(2), {
+    out: (text) => {
+        process.stdout.write(text);
+    },
+    err: (text) => {
+        process.stderr.write(text);
+    },
+}, process.env)).then((code) => {
+    process.exit(code);
+});

package/dist/cli/investigate.d.ts

@@ -0,0 +1,8 @@
+import { type EnvSource } from "../gateway/config.js";
+import type { ModelPort } from "../harness/ports.js";
+import type { CliIo } from "./runner.js";
+export interface InvestigateDeps {
+    readonly model?: ModelPort | undefined;
+    readonly readFile?: ((path: string) => string) | undefined;
+}
+export declare function runInvestigateCli(args: readonly string[], io: CliIo, env?: EnvSource, deps?: InvestigateDeps): Promise<number>;

package/dist/cli/investigate.js

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

package/dist/cli/models.d.ts

@@ -0,0 +1,3 @@
+import { type EnvSource } from "../gateway/config.js";
+import type { CliIo } from "./runner.js";
+export declare function runModelsCli(args: readonly string[], io: CliIo, env: EnvSource): number;

package/dist/cli/models.js

@@ -0,0 +1,64 @@
+// `keiko models` CLI handler. Synchronous by design: `list` reads the static
+// capability registry; `validate` reads a config file with readFileSync and runs
+// the hand-rolled validator. Neither path needs a live async Gateway, so the
+// existing `process.exit(runCli(...))` shim stays synchronous. No credential value
+// is ever written to stdout or stderr.
+import { listCapabilities } from "../gateway/capabilities.js";
+import { loadConfigFromFile } from "../gateway/config.js";
+import { GatewayError } from "../gateway/errors.js";
+import { resolveConfigPathFromArgs } from "./gateway-config.js";
+const USAGE = `Usage:
+  keiko models list                      List registered model capabilities.
+  keiko models validate [--config PATH]  Validate gateway configuration.
+`;
+function formatUseCases(useCases) {
+    return useCases.map((useCase) => useCase.toLowerCase().replace(/\s+/g, "-")).join(",");
+}
+function listModels(io) {
+    io.out("ID\tKIND\tCOST\tLATENCY\tTOOLS\tSTRUCT\tUSE-CASES\n");
+    for (const cap of listCapabilities()) {
+        const tools = cap.toolCalling ? "yes" : "no";
+        const struct = cap.structuredOutput ? "yes" : "no";
+        io.out(`${cap.id}\t${cap.kind}\t${cap.costClass}\t${cap.latencyClass}\t${tools}\t${struct}\t${formatUseCases(cap.preferredUseCases)}\n`);
+    }
+    return 0;
+}
+function validateConfig(args, io, env) {
+    const resolution = resolveConfigPathFromArgs(args, env);
+    if (resolution.kind === "missing-value") {
+        io.err("Error: --config requires a path argument.\n");
+        return 2;
+    }
+    if (resolution.kind === "not-configured") {
+        io.err("Error [GATEWAY_CONFIG_INVALID]: no config source; pass --config PATH or set KEIKO_CONFIG_FILE.\n");
+        return 1;
+    }
+    try {
+        const config = loadConfigFromFile(resolution.path, env);
+        io.out(`Gateway config valid. ${String(config.providers.length)} model providers configured.\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            io.err(`Error [${error.code}]: ${error.message}\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
+export function runModelsCli(args, io, env) {
+    const sub = args[0];
+    if (sub === "list") {
+        return listModels(io);
+    }
+    if (sub === "validate") {
+        return validateConfig(args.slice(1), io, env);
+    }
+    if (sub === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    io.err(`keiko models: unknown sub-command: ${sub}\n`);
+    io.err(USAGE);
+    return 2;
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,7 @@
+import { type EvidenceStore } from "../audit/store.js";
+import type { EnvSource } from "../gateway/config.js";
+import type { CliIo } from "./runner.js";
+export interface RunDeps {
+    readonly store?: EvidenceStore | undefined;
+}
+export declare function runAgentCli(args: readonly string[], io: CliIo, env?: EnvSource, deps?: RunDeps): Promise<number>;