@oscharko-dev/keiko-cli 0.2.0

package/dist/gen-tests.js

@@ -0,0 +1,216 @@
+// `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 (loadGatewayConfigFromFile); 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, ConfigInvalidError, GatewayError, assertConfiguredModel, selectConfiguredModel, redact, } from "@oscharko-dev/keiko-model-gateway";
+import { GatewayModelPort } from "@oscharko-dev/keiko-harness";
+import { WorkspaceError } from "@oscharko-dev/keiko-workspace";
+import { generateUnitTests, renderMarkdownReport } from "@oscharko-dev/keiko-workflows";
+import { loadGatewayConfigFromFile } from "./gateway-config.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
+// 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;
+        if (path === undefined) {
+            throw new ConfigInvalidError("no config source; pass --config PATH or set KEIKO_CONFIG_FILE");
+        }
+        const config = loadGatewayConfigFromFile(path, env);
+        if (parsed.model !== undefined) {
+            assertConfiguredModel(config, parsed.model);
+        }
+        const modelId = parsed.model ??
+            selectConfiguredModel(config, {
+                kind: "chat",
+                toolCalling: true,
+                structuredOutput: true,
+            });
+        if (modelId === undefined) {
+            io.err("Error: no configured workflow-capable 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 = loadGatewayConfigFromFile(path, env);
+    if (parsed.model !== undefined) {
+        assertConfiguredModel(config, parsed.model);
+        return parsed.model;
+    }
+    return selectConfiguredModel(config, {
+        kind: "chat",
+        toolCalling: true,
+        structuredOutput: true,
+    });
+}
+function resolveModel(parsed, io, env, deps) {
+    if (deps.model !== undefined) {
+        try {
+            const modelId = resolveConfiguredModelId(parsed, env);
+            if (modelId === undefined) {
+                io.err("Error: no configured workflow-capable 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 = {}) {
+    // Issue #640: handle --help / -h before workflow-arg validation so help discovery exits 0
+    // with usage on stdout, not 2 with a validation error on stderr.
+    if (args.includes("--help") || args.includes("-h")) {
+        io.out(USAGE);
+        return 0;
+    }
+    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/index.d.ts

@@ -0,0 +1,18 @@
+export { runCli, type CliIo } from "./runner.js";
+export { runAgentCli } from "./run.js";
+export { runGenTestsCli } from "./gen-tests.js";
+export { runInvestigateCli } from "./investigate.js";
+export { runVerifyCli } from "./verify.js";
+export { runEvaluateCli, type EvaluateDeps } from "./evaluate.js";
+export { runPromptEnhancerCli, type PromptEnhancerCliDeps } from "./prompt-enhancer.js";
+export { runEvidenceCli } from "./evidence.js";
+export { runContextCli } from "./context.js";
+export { runModelsCli } from "./models.js";
+export { runInitCli, KEIKO_START_SCRIPT, KEIKO_STOP_SCRIPT, type InitCliDeps } from "./init.js";
+export { runDoctorCli, type DoctorCliDeps } from "./doctor.js";
+export { runRepairCli, type RepairCliDeps } from "./repair.js";
+export { runUninstallCli, type UninstallCliDeps } from "./uninstall.js";
+export { runLifecycleCli, type LifecycleCliDeps } from "./lifecycle.js";
+export { runUiCli, parseUiArgs, waitForShutdown, type UiCliDeps } from "./ui.js";
+export { runLauncherCli, type LauncherCliDeps } from "./launcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAChG,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+// Public barrel for the keiko-cli package (ADR-0019 §"Target Package Topology"
+// row keiko-cli). The CLI command surface — runCli dispatcher, the per-command
+// handlers, and the small set of CLI-layer types each handler exposes — is
+// re-exported here so the root product package's bin shim
+// (`src/cli/index.ts` → `dist/cli/index.js`) and the surface-parity evaluator
+// (`src/evaluations/surface-parity.ts`) consume the public surface only.
+// Explicit-named re-exports (no `export *`) keep the surface auditable.
+export { runCli } from "./runner.js";
+export { runAgentCli } from "./run.js";
+export { runGenTestsCli } from "./gen-tests.js";
+export { runInvestigateCli } from "./investigate.js";
+export { runVerifyCli } from "./verify.js";
+export { runEvaluateCli } from "./evaluate.js";
+export { runPromptEnhancerCli } from "./prompt-enhancer.js";
+export { runEvidenceCli } from "./evidence.js";
+export { runContextCli } from "./context.js";
+export { runModelsCli } from "./models.js";
+export { runInitCli, KEIKO_START_SCRIPT, KEIKO_STOP_SCRIPT } from "./init.js";
+export { runDoctorCli } from "./doctor.js";
+export { runRepairCli } from "./repair.js";
+export { runUninstallCli } from "./uninstall.js";
+export { runLifecycleCli } from "./lifecycle.js";
+export { runUiCli, parseUiArgs, waitForShutdown } from "./ui.js";
+export { runLauncherCli } from "./launcher.js";
+// gateway-config.ts is a helper module (resolveConfigPathFromArgs) used internally by
+// models.ts; it does not expose a CLI command, so nothing is re-exported here.

package/dist/init.d.ts

@@ -0,0 +1,9 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+export declare const KEIKO_START_SCRIPT = "node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js start";
+export declare const KEIKO_STOP_SCRIPT = "node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js stop";
+export interface InitCliDeps {
+    readonly cwd?: string | undefined;
+}
+export declare function runInitCli(args: readonly string[], io: CliIo, _env: EnvSource, deps?: InitCliDeps): number;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,eAAO,MAAM,kBAAkB,oEAAoE,CAAC;AACpG,eAAO,MAAM,iBAAiB,mEAAmE,CAAC;AAkBlG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AA0GD,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,IAAI,EAAE,SAAS,EACf,IAAI,GAAE,WAAgB,GACrB,MAAM,CAiCR"}

package/dist/init.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+export const KEIKO_START_SCRIPT = "node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js start";
+export const KEIKO_STOP_SCRIPT = "node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js stop";
+const USAGE = `Usage:
+  keiko init [--package PATH] [--force] [--dry-run]
+
+Adds local package.json scripts for running Keiko:
+  keiko:start  -> node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js start
+  keiko:stop   -> node ./node_modules/@oscharko-dev/keiko/dist/cli/index.js 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/install-layout.d.ts

@@ -0,0 +1,19 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+export interface PreferredInstallLayout {
+    readonly binPath: string;
+    readonly staticRoot: string;
+}
+export interface LocalPackageInstallLayout extends PreferredInstallLayout {
+    readonly packageRoot: string;
+}
+export type KeikoBinarySource = "local-build" | "local-package" | "env-override" | "argv" | "path";
+export interface KeikoBinaryResolution {
+    readonly binPath: string;
+    readonly source: KeikoBinarySource;
+}
+export declare function hasBuiltKeikoLayout(root: string): boolean;
+export declare function localPackageRoot(cwd: string): string;
+export declare function builtCheckoutLayout(cwd: string): PreferredInstallLayout | undefined;
+export declare function resolvePreferredInstallLayout(cwd: string): PreferredInstallLayout | undefined;
+export declare function resolveKeikoBinary(cwd: string, env?: EnvSource, argv?: readonly string[]): KeikoBinaryResolution | undefined;
+//# sourceMappingURL=install-layout.d.ts.map

package/dist/install-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-layout.d.ts","sourceRoot":"","sources":["../src/install-layout.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAInE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,eAAe,GACf,cAAc,GACd,MAAM,GACN,MAAM,CAAC;AAEX,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAiBD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAUD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAGnF;AASD,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,MAAM,GACV,sBAAsB,GAAG,SAAS,CAEpC;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,SAAuB,EAC5B,IAAI,GAAE,SAAS,MAAM,EAAiB,GACrC,qBAAqB,GAAG,SAAS,CAsBnC"}

package/dist/install-layout.js

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+const ROOT_PACKAGE_NAME = "@oscharko-dev/keiko";
+function readRootPackageName(cwd) {
+    const packageJsonPath = join(cwd, "package.json");
+    if (!existsSync(packageJsonPath))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        return typeof parsed.name === "string" ? parsed.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasBuiltKeikoLayout(root) {
+    return (existsSync(resolve(root, "dist", "cli", "index.js")) &&
+        existsSync(resolve(root, "dist", "ui", "static", "index.html")));
+}
+export function localPackageRoot(cwd) {
+    return resolve(cwd, "node_modules", "@oscharko-dev", "keiko");
+}
+function builtLayoutAt(root) {
+    if (!hasBuiltKeikoLayout(root))
+        return undefined;
+    return {
+        binPath: resolve(root, "dist", "cli", "index.js"),
+        staticRoot: resolve(root, "dist", "ui", "static"),
+    };
+}
+export function builtCheckoutLayout(cwd) {
+    if (readRootPackageName(cwd) !== ROOT_PACKAGE_NAME)
+        return undefined;
+    return builtLayoutAt(cwd);
+}
+function localPackageLayout(cwd) {
+    const packageRoot = localPackageRoot(cwd);
+    const preferred = builtLayoutAt(packageRoot);
+    if (preferred === undefined)
+        return undefined;
+    return { ...preferred, packageRoot };
+}
+export function resolvePreferredInstallLayout(cwd) {
+    return builtCheckoutLayout(cwd) ?? localPackageLayout(cwd);
+}
+export function resolveKeikoBinary(cwd, env = process.env, argv = process.argv) {
+    const checks = [
+        { source: "env-override", binPath: absoluteExistingPath(env.KEIKO_CLI_BIN_PATH ?? process.env.KEIKO_CLI_BIN_PATH) },
+        { source: "argv", binPath: absoluteExistingPath(argv[1]) },
+        { source: "local-build", binPath: builtCheckoutLayout(cwd)?.binPath },
+        { source: "local-package", binPath: localPackageLayout(cwd)?.binPath },
+    ];
+    for (const candidate of checks) {
+        if (candidate.binPath !== undefined) {
+            return { source: candidate.source, binPath: candidate.binPath };
+        }
+    }
+    const pathHit = resolveKeikoBinaryFromPath(process.platform, env.PATH ?? process.env.PATH);
+    if (pathHit !== undefined) {
+        return { source: "path", binPath: pathHit };
+    }
+    return undefined;
+}
+function absoluteExistingPath(value) {
+    return typeof value === "string" && isAbsolute(value) && existsSync(value) ? value : undefined;
+}
+function resolveKeikoBinaryFromPath(platform, pathValue) {
+    if (typeof pathValue !== "string" || pathValue.length === 0)
+        return undefined;
+    const delimiter = platform === "win32" ? ";" : ":";
+    const names = platform === "win32" ? ["keiko.cmd", "keiko.exe", "keiko.bat", "keiko"] : ["keiko"];
+    return pathValue
+        .split(delimiter)
+        .flatMap((directory) => names.map((name) => join(directory, name)))
+        .find((candidate) => existsSync(candidate));
+}

package/dist/investigate.d.ts

@@ -0,0 +1,9 @@
+import { type EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import { type ModelPort } from "@oscharko-dev/keiko-harness";
+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>;
+//# sourceMappingURL=investigate.d.ts.map

package/dist/investigate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"investigate.d.ts","sourceRoot":"","sources":["../src/investigate.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,SAAS,EAMf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAU/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAczC,MAAM,WAAW,eAAe;IAE9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAEvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;CAC5D;AA4OD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,MAAM,CAAC,CAgCjB"}