@curiousnerd/keel 0.1.0

package/dist/llm/claimsFromDocs.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Per-file cap so a giant README can't blow up the prompt. */
+const MAX_CHARS_PER_DOC = 6000;
+/** Map an extracted JSON key to the claim key the drift engine understands. */
+const KEY_MAP = {
+    packagemanager: "package manager",
+    database: "database",
+    db: "database",
+    naming: "naming",
+};
+function gatherDocs(root, config) {
+    const names = [...new Set([...config.claims.sources, "README.md"])];
+    const parts = [];
+    for (const name of names) {
+        const path = join(root, name);
+        if (!existsSync(path))
+            continue;
+        try {
+            const text = readFileSync(path, "utf8").slice(0, MAX_CHARS_PER_DOC);
+            if (text.trim())
+                parts.push(`### ${name}\n${text}`);
+        }
+        catch {
+            // unreadable — skip
+        }
+    }
+    return parts.join("\n\n");
+}
+function buildPrompt(docs) {
+    return [
+        "From the project documentation below, extract the technology choices the project SAYS it uses.",
+        "Return ONLY a JSON object containing any of these keys that are clearly stated (omit the rest):",
+        '{"validation":"","database":"","orm":"","http":"","state":"","test":"","packageManager":"","naming":""}',
+        'Use the canonical tool name as the value (e.g. "Zod", "PostgreSQL", "Prisma", "pnpm", "camelCase").',
+        "Do not guess or infer from filenames — only include what the prose explicitly states. No markdown.",
+        "",
+        "Documentation:",
+        docs,
+    ].join("\n");
+}
+function parseClaims(raw, source) {
+    const start = raw.indexOf("{");
+    const end = raw.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return [];
+    let obj;
+    try {
+        obj = JSON.parse(raw.slice(start, end + 1));
+    }
+    catch {
+        return [];
+    }
+    const claims = [];
+    for (const [rawKey, rawValue] of Object.entries(obj)) {
+        if (typeof rawValue !== "string" || rawValue.trim() === "")
+            continue;
+        const key = KEY_MAP[rawKey.toLowerCase()] ?? rawKey.toLowerCase();
+        claims.push({ key, value: rawValue.trim(), source, line: 1 });
+    }
+    return claims;
+}
+/**
+ * Tier 2 of doc/knowledge drift: use the LLM to extract checkable stack claims
+ * from freeform documentation prose. The LLM only turns English into claims —
+ * the deterministic drift engine still does the verifying. Returns [] on any
+ * failure or when no provider is available. Cached by prompt.
+ */
+export async function extractClaimsFromDocs(root, config, provider, cache) {
+    if (provider.name === "off")
+        return [];
+    const docs = gatherDocs(root, config);
+    if (!docs.trim())
+        return [];
+    const prompt = buildPrompt(docs);
+    let raw = cache.get(provider.name, prompt);
+    if (raw === undefined) {
+        const response = await provider.complete(prompt);
+        if (response === null)
+            return [];
+        raw = response;
+        cache.set(provider.name, prompt, raw);
+    }
+    return parseClaims(raw, "docs (inferred)");
+}
+/**
+ * Add inferred stack claims that the structured block didn't already cover.
+ * Structured claims always win (a hand-written `## Stack` beats prose inference).
+ */
+export function mergeInferredClaims(existing, inferred) {
+    const haveKeys = new Set(existing.map((c) => c.key.toLowerCase()));
+    const added = inferred.filter((c) => !haveKeys.has(c.key.toLowerCase()));
+    return [...existing, ...added];
+}
+//# sourceMappingURL=claimsFromDocs.js.map

package/dist/llm/claimsFromDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimsFromDocs.js","sourceRoot":"","sources":["../../src/llm/claimsFromDocs.ts"],"names":[],"mappings":"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"}

package/dist/llm/explain.d.ts

@@ -0,0 +1,10 @@
+import type { Finding } from "../types.js";
+import type { LLMProvider } from "./provider.js";
+import type { LLMCache } from "./cache.js";
+/**
+ * Attach plain-language `explanation`s to findings via one batched LLM call.
+ * Advisory only — never changes the score. Cached by prompt; on any failure
+ * the findings are left untouched (templated `detail` remains the fallback).
+ * Returns the number of findings that got an explanation.
+ */
+export declare function explainFindings(findings: Finding[], provider: LLMProvider, cache: LLMCache): Promise<number>;

package/dist/llm/explain.js

@@ -0,0 +1,63 @@
+/** Build one batched prompt covering all findings (explanations are short). */
+function buildPrompt(findings) {
+    const lines = findings.map((f, i) => `${i + 1}. [${f.kind.toUpperCase()}] ${f.title}`);
+    return [
+        "You are explaining code-quality findings from a static-analysis tool called keel to a developer.",
+        "For each finding, write ONE short, plain-language sentence: what it means and what to do about it.",
+        "Be concrete and specific. No preamble, no restating the finding verbatim.",
+        'Return ONLY a JSON array, one object per finding: [{"i": 1, "explanation": "..."}]. No markdown.',
+        "",
+        "Findings:",
+        ...lines,
+    ].join("\n");
+}
+/** Extract the JSON array from a model response that may have stray text around it. */
+function parseExplanations(raw) {
+    const out = new Map();
+    const start = raw.indexOf("[");
+    const end = raw.lastIndexOf("]");
+    if (start === -1 || end <= start)
+        return out;
+    try {
+        const parsed = JSON.parse(raw.slice(start, end + 1));
+        for (const item of parsed) {
+            if (typeof item.i === "number" && typeof item.explanation === "string") {
+                out.set(item.i, item.explanation.trim());
+            }
+        }
+    }
+    catch {
+        // unparseable — leave empty, caller degrades to templated output
+    }
+    return out;
+}
+/**
+ * Attach plain-language `explanation`s to findings via one batched LLM call.
+ * Advisory only — never changes the score. Cached by prompt; on any failure
+ * the findings are left untouched (templated `detail` remains the fallback).
+ * Returns the number of findings that got an explanation.
+ */
+export async function explainFindings(findings, provider, cache) {
+    if (findings.length === 0 || provider.name === "off")
+        return 0;
+    const prompt = buildPrompt(findings);
+    let raw = cache.get(provider.name, prompt);
+    if (raw === undefined) {
+        const response = await provider.complete(prompt);
+        if (response === null)
+            return 0;
+        raw = response;
+        cache.set(provider.name, prompt, raw);
+    }
+    const byIndex = parseExplanations(raw);
+    let attached = 0;
+    findings.forEach((finding, i) => {
+        const explanation = byIndex.get(i + 1);
+        if (explanation) {
+            finding.explanation = explanation;
+            attached += 1;
+        }
+    });
+    return attached;
+}
+//# sourceMappingURL=explain.js.map

package/dist/llm/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../src/llm/explain.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,SAAS,WAAW,CAAC,QAAmB;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACvF,OAAO;QACL,kGAAkG;QAClG,oGAAoG;QACpG,2EAA2E;QAC3E,kGAAkG;QAClG,EAAE;QACF,WAAW;QACX,GAAG,KAAK;KACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,uFAAuF;AACvF,SAAS,iBAAiB,CAAC,GAAW;IACpC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,GAAG,CAAC;IAC7C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAgD,CAAC;QACpG,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,OAAO,IAAI,CAAC,CAAC,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACvE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAmB,EAAE,QAAqB,EAAE,KAAe;IAC/F,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,CAAC;IAE/D,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,CAAC,CAAC;QAChC,GAAG,GAAG,QAAQ,CAAC;QACf,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE;QAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;YAClC,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/llm/improve.d.ts

@@ -0,0 +1,9 @@
+import type { Report } from "../types.js";
+import type { LLMProvider } from "./provider.js";
+import type { LLMCache } from "./cache.js";
+/**
+ * Generate a plain-language "how to raise your score" plan from the findings.
+ * Advisory only (never changes the score). Cached; returns null on any failure
+ * so callers fall back to the deterministic improvementSummary.
+ */
+export declare function suggestImprovements(report: Report, provider: LLMProvider, cache: LLMCache): Promise<string | null>;

package/dist/llm/improve.js

@@ -0,0 +1,37 @@
+import { sortFindings } from "../report/text.js";
+/** How many findings to feed the model — bounded to keep the prompt small. */
+const MAX_FINDINGS_IN_PROMPT = 40;
+function buildPrompt(report) {
+    const top = sortFindings(report.findings).slice(0, MAX_FINDINGS_IN_PROMPT);
+    const lines = top.map((f) => `- [${f.kind}] ${f.title}`);
+    return [
+        `A static-analysis tool ("keel") scored this codebase ${report.score}/100.`,
+        `Penalties — drift: ${report.breakdown.drift}, library conflicts: ${report.breakdown.conflict}, duplication: ${report.breakdown.duplication}.`,
+        "Write a short, prioritized, actionable plan (most impactful first) for raising this score.",
+        "Be specific to the findings below; group related ones; suggest concrete refactors. Markdown bullets only, max ~8 items.",
+        "Respond with ONLY the plan itself — no preamble, no meta-commentary about your process.",
+        "",
+        "Findings:",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * Generate a plain-language "how to raise your score" plan from the findings.
+ * Advisory only (never changes the score). Cached; returns null on any failure
+ * so callers fall back to the deterministic improvementSummary.
+ */
+export async function suggestImprovements(report, provider, cache) {
+    if (provider.name === "off" || report.findings.length === 0)
+        return null;
+    const prompt = buildPrompt(report);
+    let raw = cache.get(provider.name, prompt);
+    if (raw === undefined) {
+        const response = await provider.complete(prompt);
+        if (response === null)
+            return null;
+        raw = response;
+        cache.set(provider.name, prompt, raw);
+    }
+    return raw.trim() || null;
+}
+//# sourceMappingURL=improve.js.map

package/dist/llm/improve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve.js","sourceRoot":"","sources":["../../src/llm/improve.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIjD,8EAA8E;AAC9E,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAElC,SAAS,WAAW,CAAC,MAAc;IACjC,MAAM,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACzD,OAAO;QACL,wDAAwD,MAAM,CAAC,KAAK,OAAO;QAC3E,sBAAsB,MAAM,CAAC,SAAS,CAAC,KAAK,wBAAwB,MAAM,CAAC,SAAS,CAAC,QAAQ,kBAAkB,MAAM,CAAC,SAAS,CAAC,WAAW,GAAG;QAC9I,4FAA4F;QAC5F,yHAAyH;QACzH,yFAAyF;QACzF,EAAE;QACF,WAAW;QACX,GAAG,KAAK;KACT,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc,EAAE,QAAqB,EAAE,KAAe;IAC9F,IAAI,QAAQ,CAAC,IAAI,KAAK,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzE,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACnC,GAAG,GAAG,QAAQ,CAAC;QACf,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC;AAC5B,CAAC"}

package/dist/llm/provider.d.ts

@@ -0,0 +1,24 @@
+import type { KeelConfig } from "../config.js";
+/**
+ * The single seam every LLM feature goes through. An implementation either
+ * shells out to an already-authenticated agent CLI, calls a hosted API, or is
+ * the null provider. The deterministic core never depends on any of this.
+ */
+export interface LLMProvider {
+    /** Short label printed in the run summary, e.g. "claude-cli". */
+    readonly name: string;
+    /** Return the model's text for `prompt`, or null on any failure (fail soft). */
+    complete(prompt: string): Promise<string | null>;
+}
+/** No LLM available — callers fall back to templated output. */
+export declare class NullProvider implements LLMProvider {
+    readonly name = "off";
+    complete(): Promise<string | null>;
+}
+/**
+ * Resolve which provider to use. CLI-first by default (the audience already has
+ * one authenticated, so it's zero-setup and zero marginal cost), with the
+ * hosted API as an opt-in escape hatch. Returns NullProvider when nothing is
+ * available so callers degrade to templated output rather than failing.
+ */
+export declare function resolveProvider(config: KeelConfig): Promise<LLMProvider>;

package/dist/llm/provider.js

@@ -0,0 +1,210 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Default request size for hosted-API calls (explanations are short). */
+const API_MAX_TOKENS = 2048;
+/** Hard cap so a hung CLI/API call can't block a run forever. */
+const TIMEOUT_MS = 60_000;
+/** Run a command with an args array (no shell), feeding `stdin`, with a timeout. */
+function runProcess(cmd, args, stdin = "") {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => child.kill("SIGKILL"), TIMEOUT_MS);
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        });
+        if (stdin)
+            child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}
+/** Is `bin` on PATH and runnable? (probes `bin --version`). */
+async function cliAvailable(bin) {
+    try {
+        const { code } = await runProcess(bin, ["--version"]);
+        return code === 0;
+    }
+    catch {
+        return false; // ENOENT etc.
+    }
+}
+// ---------------------------------------------------------------------------
+// Providers
+// ---------------------------------------------------------------------------
+/** Shells out to Claude Code's headless print mode (`claude -p`). */
+class ClaudeCliProvider {
+    model;
+    name = "claude-cli";
+    constructor(model) {
+        this.model = model;
+    }
+    async complete(prompt) {
+        const args = ["-p", "--output-format", "text"];
+        if (this.model)
+            args.push("--model", this.model);
+        try {
+            const { code, stdout } = await runProcess("claude", args, prompt);
+            if (code !== 0)
+                return null;
+            const text = stdout.trim();
+            return text.length > 0 ? text : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Shells out to Codex's non-interactive mode, reading the clean final message. */
+class CodexCliProvider {
+    model;
+    name = "codex-cli";
+    constructor(model) {
+        this.model = model;
+    }
+    async complete(prompt) {
+        const dir = mkdtempSync(join(tmpdir(), "keel-codex-"));
+        const outFile = join(dir, "message.txt");
+        const args = ["exec", "--output-last-message", outFile, "--color", "never"];
+        if (this.model)
+            args.push("-m", this.model);
+        args.push(prompt);
+        try {
+            const { code } = await runProcess("codex", args);
+            if (code !== 0)
+                return null;
+            const text = readFileSync(outFile, "utf8").trim();
+            return text.length > 0 ? text : null;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+/** Calls the Anthropic Messages API with ANTHROPIC_API_KEY. */
+class AnthropicApiProvider {
+    apiKey;
+    model;
+    name = "anthropic-api";
+    constructor(apiKey, model) {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async complete(prompt) {
+        try {
+            const res = await fetch("https://api.anthropic.com/v1/messages", {
+                method: "POST",
+                headers: {
+                    "x-api-key": this.apiKey,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    model: this.model || "claude-haiku-4-5",
+                    max_tokens: API_MAX_TOKENS,
+                    messages: [{ role: "user", content: prompt }],
+                }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            const text = (data.content ?? [])
+                .filter((b) => b.type === "text")
+                .map((b) => b.text ?? "")
+                .join("")
+                .trim();
+            return text.length > 0 ? text : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Calls the OpenAI Chat Completions API with OPENAI_API_KEY (escape hatch). */
+class OpenAiApiProvider {
+    apiKey;
+    model;
+    name = "openai-api";
+    constructor(apiKey, model) {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async complete(prompt) {
+        try {
+            const res = await fetch("https://api.openai.com/v1/chat/completions", {
+                method: "POST",
+                headers: { authorization: `Bearer ${this.apiKey}`, "content-type": "application/json" },
+                body: JSON.stringify({
+                    model: this.model || "gpt-4o-mini",
+                    max_tokens: API_MAX_TOKENS,
+                    messages: [{ role: "user", content: prompt }],
+                }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            const text = data.choices?.[0]?.message?.content?.trim() ?? "";
+            return text.length > 0 ? text : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** No LLM available — callers fall back to templated output. */
+export class NullProvider {
+    name = "off";
+    async complete() {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+function apiProviderFromEnv(model) {
+    if (process.env.ANTHROPIC_API_KEY)
+        return new AnthropicApiProvider(process.env.ANTHROPIC_API_KEY, model);
+    if (process.env.OPENAI_API_KEY)
+        return new OpenAiApiProvider(process.env.OPENAI_API_KEY, model);
+    return null;
+}
+/**
+ * Resolve which provider to use. CLI-first by default (the audience already has
+ * one authenticated, so it's zero-setup and zero marginal cost), with the
+ * hosted API as an opt-in escape hatch. Returns NullProvider when nothing is
+ * available so callers degrade to templated output rather than failing.
+ */
+export async function resolveProvider(config) {
+    const { provider, model } = config.llm;
+    // Explicit choice.
+    if (provider === "claude")
+        return new ClaudeCliProvider(model);
+    if (provider === "codex")
+        return new CodexCliProvider(model);
+    if (provider === "api")
+        return apiProviderFromEnv(model) ?? new NullProvider();
+    if (provider === "off")
+        return new NullProvider();
+    // Auto: prefer the local CLI (included in the user's subscription) over a
+    // metered API key, then fall back to the API, then to null.
+    if (await cliAvailable("claude"))
+        return new ClaudeCliProvider(model);
+    if (await cliAvailable("codex"))
+        return new CodexCliProvider(model);
+    return apiProviderFromEnv(model) ?? new NullProvider();
+}
+//# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Run keel as an MCP server over stdio. The agent calls these tools *before* it
+ * writes, so duplication/drift is prevented at generation time, not caught
+ * after. Every answer is derived from freshly-extracted deterministic Facts
+ * (the file-hash cache makes per-call re-extraction near-instant) — no LLM.
+ */
+export declare function startMcpServer(root: string): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,43 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "../config.js";
+import { loadFacts } from "../extract/scan.js";
+import { parseClaims } from "../claims/parseBlock.js";
+import { loadCapabilityBuckets } from "../analyze/shared.js";
+import { checkBeforeWrite, getConventions, reportDrift } from "./tools.js";
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+/**
+ * Run keel as an MCP server over stdio. The agent calls these tools *before* it
+ * writes, so duplication/drift is prevented at generation time, not caught
+ * after. Every answer is derived from freshly-extracted deterministic Facts
+ * (the file-hash cache makes per-call re-extraction near-instant) — no LLM.
+ */
+export async function startMcpServer(root) {
+    const config = loadConfig(root);
+    const buckets = loadCapabilityBuckets();
+    const server = new McpServer({ name: "keel", version: "0.0.0" });
+    server.registerTool("check_before_write", {
+        description: "BEFORE writing new code, check whether this project already has a utility or library for it — so you reuse instead of reinventing, and match the existing library choice. Pass a short description of what you're about to write.",
+        inputSchema: { intent: z.string().describe("What you're about to write, e.g. 'a function to format dates'") },
+    }, async ({ intent }) => {
+        const { facts } = await loadFacts(root, config);
+        return text(checkBeforeWrite(facts, intent, buckets));
+    });
+    server.registerTool("get_conventions", {
+        description: "Get the verified, current conventions for an area of the codebase (naming style, libraries in use, language, package manager) — derived from the actual code, not a possibly-stale doc.",
+        inputSchema: { path: z.string().describe("The file or directory you're working in, e.g. 'src/api'") },
+    }, async ({ path }) => {
+        const { facts } = await loadFacts(root, config);
+        return text(getConventions(facts, path, buckets));
+    });
+    server.registerTool("report_drift", {
+        description: "List the project's current drift and library-conflict findings, so you can fix them or avoid adding to them.",
+    }, async () => {
+        const { facts } = await loadFacts(root, config);
+        const claims = parseClaims(root, config);
+        return text(reportDrift(facts, claims, config));
+    });
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3E,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY;IAC/C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,OAAO,GAAG,qBAAqB,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAEjE,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,WAAW,EACT,mOAAmO;QACrO,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+DAA+D,CAAC,EAAE;KAC9G,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;QACnB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,WAAW,EACT,yLAAyL;QAC3L,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC,EAAE;KACtG,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACjB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChD,OAAO,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EACT,8GAA8G;KACjH,EACD,KAAK,IAAI,EAAE;QACT,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,CAAC,CACF,CAAC;IAEF,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,9 @@
+import type { KeelConfig } from "../config.js";
+import type { Claims, Facts } from "../types.js";
+import { type CapabilityBuckets } from "../analyze/shared.js";
+/** Suggest existing utilities + libraries to reuse before the agent writes new code. */
+export declare function checkBeforeWrite(facts: Facts, intent: string, buckets?: CapabilityBuckets): string;
+/** Report the verified, current conventions for an area of the codebase. */
+export declare function getConventions(facts: Facts, path: string, buckets?: CapabilityBuckets): string;
+/** Current deterministic drift + library-conflict findings (the "you're inconsistent" signals). */
+export declare function reportDrift(facts: Facts, claims: Claims, config: KeelConfig): string;