code-ai-installer 3.0.0 → 4.0.1-a

package/dist/mcp/tools/submit_artifact.js

@@ -0,0 +1,91 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, normalize, resolve, sep } from "node:path";
+import { ARTIFACT_LINE_CAP, RoleFrontmatter, SkillFrontmatter, } from "../../shared/index.js";
+/**
+ * Single write path for every artifact class. Enforces:
+ *   1. ARTIFACT_LINE_CAP[class] — content line count must not exceed cap (null = no cap).
+ *   2. Frontmatter zod validation for class="skill" and class="role" (owners.min(1),
+ *      controlled vocab, related[], schema_version, budget_lines<=300, etc.).
+ *   3. Path safety: no absolute paths, no parent-dir escape; resolved under process.cwd().
+ *
+ * Bidirectional related[] enforcement (skill A links B → B must link A) is OUT OF SCOPE
+ * here — that's regenerate_manifest's job at the corpus level. submit_artifact is single-file
+ * gating; cross-file consistency is a separate concern.
+ *
+ * For class="adr": no frontmatter validation (ADRs are plain markdown); cap=150 still applies.
+ * For class="diary"/"working_report": cap=null, no schema constraints, free-form.
+ * For class="handoff": cap=1 — a one-line AAAK-style string between gates.
+ * For class="persona"/"memory_index": cap enforced but no frontmatter schema validation yet
+ *   (PersonaBase zod exists but its on-disk format is markdown sections, not YAML frontmatter).
+ */
+export async function submitArtifact(input) {
+    // ─── Path safety ─────────────────────────────────────────────────────────
+    if (isAbsolute(input.path)) {
+        throw new Error(`submit_artifact: path must be relative, got absolute '${input.path}'`);
+    }
+    const cwd = process.cwd();
+    const resolved = resolve(cwd, input.path);
+    const normalizedCwd = normalize(cwd) + (cwd.endsWith(sep) ? "" : sep);
+    if (!resolved.startsWith(normalizedCwd)) {
+        throw new Error(`submit_artifact: path escapes project root: '${input.path}' resolved to '${resolved}'`);
+    }
+    // ─── Frontmatter validation ──────────────────────────────────────────────
+    if (input.class === "skill") {
+        if (input.frontmatter === undefined) {
+            throw new Error(`submit_artifact: class='skill' requires frontmatter`);
+        }
+        SkillFrontmatter.parse(input.frontmatter); // throws on invalid (owners.min(1), etc.)
+    }
+    else if (input.class === "role") {
+        if (input.frontmatter === undefined) {
+            throw new Error(`submit_artifact: class='role' requires frontmatter`);
+        }
+        RoleFrontmatter.parse(input.frontmatter);
+    }
+    // ─── Line cap enforcement ────────────────────────────────────────────────
+    const line_count = countLines(input.content);
+    const cap = ARTIFACT_LINE_CAP[input.class];
+    if (cap !== null && line_count > cap) {
+        throw new Error(`submit_artifact: class='${input.class}' line cap is ${cap}, got ${line_count} lines (over by ${line_count - cap}). Consolidate before retry.`);
+    }
+    // ─── Write ───────────────────────────────────────────────────────────────
+    await mkdir(dirname(resolved), { recursive: true });
+    await writeFile(resolved, input.content, "utf8");
+    // ─── Per-task artifact index ────────────────────────────────────────────
+    // When `gate` is provided, append to .code-ai/state/artifacts/<task_id>.jsonl
+    // so list_artifacts/get_artifact can resolve (task_id, gate) → file.
+    if (input.gate !== undefined) {
+        const { appendFile } = await import("node:fs/promises");
+        const indexDir = resolve(cwd, ".code-ai", "state", "artifacts");
+        await mkdir(indexDir, { recursive: true });
+        const safe = input.task_id.replace(/[^A-Za-z0-9_.-]/g, "_");
+        const indexPath = resolve(indexDir, `${safe}.jsonl`);
+        const entry = {
+            task_id: input.task_id,
+            gate: input.gate,
+            class: input.class,
+            path: resolved,
+            line_count,
+            timestamp: new Date().toISOString(),
+        };
+        await appendFile(indexPath, JSON.stringify(entry) + "\n", "utf8");
+    }
+    return {
+        written: true,
+        path: resolved,
+        line_count,
+        cap,
+    };
+}
+/**
+ * Count newline-terminated lines plus a trailing partial line if present.
+ * Matches what a user typically thinks of as "line count" — a file ending in
+ * "a\nb\n" has 2 lines; "a\nb" also has 2; "" has 0.
+ */
+function countLines(content) {
+    if (content.length === 0)
+        return 0;
+    // Count \n then add 1 for trailing non-newline content if any.
+    const newlines = (content.match(/\n/g) ?? []).length;
+    return content.endsWith("\n") ? newlines : newlines + 1;
+}

package/dist/mcp/tools/verify_claim.d.ts

@@ -0,0 +1,18 @@
+import { type VerifyClaimInput, type VerifyClaimOutput } from "../../shared/index.js";
+/**
+ * Code-verifiable claims. Per the silent-by-default contract, every claim a
+ * gate makes ("tests pass", "no orphan skills", "vocab clean") should be
+ * verifiable by a deterministic check — not by DEN reading the report.
+ *
+ * v1 implements three corpus-level checks against the installed development
+ * domain on disk:
+ *   - no_orphan_skills: every SKILL.md has frontmatter.owners non-empty
+ *   - owners_present: alias for no_orphan_skills (kept for caller clarity)
+ *   - vocab_valid: every tech[] and topic[] value is in the seed enums
+ *
+ * Other claim_types (tests_pass / build_succeeds / lint_clean / custom)
+ * return verified=false with a failure noting that the dispatcher for that
+ * claim hasn't been wired yet — they need the Phase 2 tools (run_tests,
+ * build, check_lint) to land first.
+ */
+export declare function verifyClaim(input: VerifyClaimInput): Promise<VerifyClaimOutput>;

package/dist/mcp/tools/verify_claim.js

@@ -0,0 +1,175 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { SkillFrontmatter, TechSeed, TopicSeed, } from "../../shared/index.js";
+import { resolveSkillsRoot } from "../paths.js";
+import { runTests } from "./run_tests.js";
+import { checkLint } from "./check_lint.js";
+import { build } from "./build.js";
+/**
+ * Code-verifiable claims. Per the silent-by-default contract, every claim a
+ * gate makes ("tests pass", "no orphan skills", "vocab clean") should be
+ * verifiable by a deterministic check — not by DEN reading the report.
+ *
+ * v1 implements three corpus-level checks against the installed development
+ * domain on disk:
+ *   - no_orphan_skills: every SKILL.md has frontmatter.owners non-empty
+ *   - owners_present: alias for no_orphan_skills (kept for caller clarity)
+ *   - vocab_valid: every tech[] and topic[] value is in the seed enums
+ *
+ * Other claim_types (tests_pass / build_succeeds / lint_clean / custom)
+ * return verified=false with a failure noting that the dispatcher for that
+ * claim hasn't been wired yet — they need the Phase 2 tools (run_tests,
+ * build, check_lint) to land first.
+ */
+export async function verifyClaim(input) {
+    const domain = input.args.domain ?? "development";
+    switch (input.claim_type) {
+        case "no_orphan_skills":
+        case "owners_present": {
+            const result = await checkOwnersPresent(domain);
+            return result;
+        }
+        case "vocab_valid": {
+            const result = await checkVocab(domain);
+            return result;
+        }
+        case "tests_pass": {
+            const cwd = input.args.cwd ?? undefined;
+            const r = await runTests({ task_id: input.task_id, cwd });
+            return {
+                verified: r.failed === 0 && r.failures.length === 0,
+                evidence: { passed: r.passed, failed: r.failed, duration_ms: r.duration_ms },
+                failures: r.failures,
+            };
+        }
+        case "lint_clean": {
+            const cwd = input.args.cwd ?? undefined;
+            const r = await checkLint({ task_id: input.task_id, cwd });
+            return {
+                verified: r.clean,
+                evidence: { clean: r.clean },
+                failures: r.issues,
+            };
+        }
+        case "build_succeeds": {
+            const cwd = input.args.cwd ?? undefined;
+            const r = await build({ task_id: input.task_id, cwd });
+            return {
+                verified: r.succeeded,
+                evidence: { succeeded: r.succeeded },
+                failures: r.errors,
+            };
+        }
+        case "custom": {
+            return {
+                verified: false,
+                evidence: { reason: `claim_type='custom' not wired (project-specific dispatcher needed)` },
+                failures: [
+                    {
+                        code: `custom-unwired`,
+                        message: `verify_claim: claim_type='custom' requires a project-specific dispatcher (not part of DEV-101).`,
+                    },
+                ],
+            };
+        }
+        default:
+            // Should be unreachable thanks to the zod enum, but TS doesn't know.
+            return {
+                verified: false,
+                evidence: null,
+                failures: [{ code: "unknown-claim", message: `unknown claim_type` }],
+            };
+    }
+}
+async function checkOwnersPresent(domain) {
+    const root = resolveSkillsRoot(domain);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const orphans = [];
+    let scanned = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const file = join(root, entry.name, "SKILL.md");
+        const raw = await readFile(file, "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        scanned++;
+        const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+        const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!m) {
+            orphans.push(entry.name);
+            continue;
+        }
+        try {
+            const fm = SkillFrontmatter.safeParse(parseYaml(m[1]));
+            if (!fm.success || fm.data.owners.length === 0) {
+                orphans.push(entry.name);
+            }
+        }
+        catch {
+            orphans.push(entry.name);
+        }
+    }
+    const failures = orphans.map((n) => ({
+        code: `orphan-${n}`,
+        message: `skill '${n}' has no owners[] in frontmatter — MCP structural rule violated`,
+    }));
+    return {
+        verified: orphans.length === 0,
+        evidence: { scanned, orphans },
+        failures,
+    };
+}
+async function checkVocab(domain) {
+    const root = resolveSkillsRoot(domain);
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const allowedTech = new Set(TechSeed.options);
+    const allowedTopic = new Set(TopicSeed.options);
+    const failures = [];
+    let scanned = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const file = join(root, entry.name, "SKILL.md");
+        const raw = await readFile(file, "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        scanned++;
+        const stripped = raw.startsWith("") ? raw.slice(1) : raw;
+        const m = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!m)
+            continue;
+        let parsedYaml;
+        try {
+            parsedYaml = parseYaml(m[1]);
+        }
+        catch {
+            continue;
+        }
+        const fm = SkillFrontmatter.safeParse(parsedYaml);
+        if (!fm.success)
+            continue;
+        for (const t of fm.data.tech) {
+            if (!allowedTech.has(t)) {
+                failures.push({
+                    code: `tech-${entry.name}-${t}`,
+                    message: `skill '${entry.name}' uses tech '${t}' outside controlled vocab`,
+                });
+            }
+        }
+        for (const t of fm.data.topic) {
+            if (!allowedTopic.has(t)) {
+                failures.push({
+                    code: `topic-${entry.name}-${t}`,
+                    message: `skill '${entry.name}' uses topic '${t}' outside controlled vocab`,
+                });
+            }
+        }
+    }
+    return {
+        verified: failures.length === 0,
+        evidence: { scanned, violations: failures.length },
+        failures,
+    };
+}

package/dist/mcp_setup.d.ts

@@ -0,0 +1,109 @@
+import type { DomainId } from "./shared/index.js";
+/**
+ * MCP auto-setup for `--target=claude` installs.
+ *
+ * Two responsibilities (ADR-DEV-099):
+ *   1. Detect / install MemPalace as an opt-in mirror for decision storage.
+ *   2. Write project-level `.mcp.json` registering `code-ai-mcp` (always) and
+ *      `mempalace` (when accepted) so Claude Code picks them up automatically.
+ *   3. Write `.code-ai/config.json` so `code-ai-mcp` knows which backend to use.
+ *
+ * Non-Claude targets skip this whole flow — MCP is Claude-specific.
+ *
+ * Graceful degradation: every step is best-effort. Failures fall back to
+ * "JsonlStore only" without breaking the rest of the install.
+ */
+export type PythonRuntimeTool = "uv" | "pipx" | "pip";
+export interface PythonRuntime {
+    /** Tool kind, in preference order: uv → pipx → pip. */
+    tool: PythonRuntimeTool;
+    /** Binary name (usually equal to `tool`). */
+    binary: string;
+}
+export interface McpServerEntry {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface McpJsonShape {
+    mcpServers?: Record<string, McpServerEntry>;
+    [key: string]: unknown;
+}
+export interface McpSetupOptions {
+    destinationDir: string;
+    /** User's answer to the MemPalace prompt (true = wants it). */
+    wantMempalace: boolean;
+    /** When true, no files are written; the report still reflects planned actions. */
+    dryRun: boolean;
+    /**
+     * The selected domain, written into `.code-ai/config.json` so the gate tools
+     * read this project's pipeline. Undefined for the legacy flat layout (no
+     * domains) — then the config omits it and the runtime defaults to development.
+     */
+    domain?: DomainId;
+}
+export interface McpSetupReport {
+    mempalaceUsed: boolean;
+    mempalaceInstallAttempted: boolean;
+    mempalaceInstallSucceeded: boolean;
+    pythonRuntime: PythonRuntime | null;
+    mcpJsonPath: string;
+    mcpJsonAction: "created" | "merged" | "skipped";
+    configPath: string;
+    notices: string[];
+}
+/**
+ * Try `mempalace --help`. Resolves true on exit code 0, false otherwise
+ * (including ENOENT — binary not on PATH).
+ */
+export declare function detectMemPalace(): Promise<boolean>;
+/**
+ * Find the first available Python install runtime, in preference order:
+ * uv → pipx → pip. Returns null if none available.
+ */
+export declare function detectPythonRuntime(): Promise<PythonRuntime | null>;
+/**
+ * Run the install command for MemPalace using the given runtime. Captures
+ * combined stdout+stderr for the report. Does NOT throw — caller branches on
+ * `ok`.
+ */
+export declare function installMemPalace(runtime: PythonRuntime): Promise<{
+    ok: boolean;
+    output: string;
+}>;
+/**
+ * Merge MCP server entries into `<destinationDir>/.mcp.json`.
+ * Behaviour:
+ *   - Missing file: create with `{ "mcpServers": <new> }`.
+ *   - Existing valid JSON: merge `mcpServers`; if a server name already exists,
+ *     keep the existing entry untouched and add a notice.
+ *   - Malformed JSON: abort (return action="skipped") with notice — never clobber.
+ */
+export declare function mergeMcpJson(destinationDir: string, servers: Record<string, McpServerEntry>, dryRun?: boolean): Promise<{
+    action: McpSetupReport["mcpJsonAction"];
+    path: string;
+    notices: string[];
+}>;
+/**
+ * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
+ * Idempotent — re-running overwrites with the same content if backend unchanged.
+ */
+export declare function writeCodeAiConfig(destinationDir: string, config: {
+    decision_store: "jsonl" | "mempalace";
+    domain?: DomainId;
+}, dryRun?: boolean): Promise<{
+    path: string;
+}>;
+/**
+ * End-to-end orchestrator. Called from the install flow when `target=claude`.
+ *
+ * Order:
+ *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
+ *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
+ *   3. Merge into .mcp.json.
+ *   4. Write .code-ai/config.json with backend choice.
+ *
+ * Reports all decisions in `McpSetupReport.notices` so callers can surface
+ * them to the user verbatim.
+ */
+export declare function setupMcp(opts: McpSetupOptions): Promise<McpSetupReport>;

package/dist/mcp_setup.js

@@ -0,0 +1,201 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Try `mempalace --help`. Resolves true on exit code 0, false otherwise
+ * (including ENOENT — binary not on PATH).
+ */
+export async function detectMemPalace() {
+    return spawnExitZero("mempalace", ["--help"]);
+}
+/**
+ * Find the first available Python install runtime, in preference order:
+ * uv → pipx → pip. Returns null if none available.
+ */
+export async function detectPythonRuntime() {
+    const candidates = [
+        { tool: "uv", binary: "uv" },
+        { tool: "pipx", binary: "pipx" },
+        { tool: "pip", binary: "pip" },
+    ];
+    for (const candidate of candidates) {
+        if (await spawnExitZero(candidate.binary, ["--version"])) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Run the install command for MemPalace using the given runtime. Captures
+ * combined stdout+stderr for the report. Does NOT throw — caller branches on
+ * `ok`.
+ */
+export async function installMemPalace(runtime) {
+    const args = installCommandArgs(runtime);
+    return spawnCapture(runtime.binary, args);
+}
+function installCommandArgs(runtime) {
+    switch (runtime.tool) {
+        case "uv":
+            return ["tool", "install", "mempalace"];
+        case "pipx":
+            return ["install", "mempalace"];
+        case "pip":
+            return ["install", "--user", "mempalace"];
+    }
+}
+/**
+ * Merge MCP server entries into `<destinationDir>/.mcp.json`.
+ * Behaviour:
+ *   - Missing file: create with `{ "mcpServers": <new> }`.
+ *   - Existing valid JSON: merge `mcpServers`; if a server name already exists,
+ *     keep the existing entry untouched and add a notice.
+ *   - Malformed JSON: abort (return action="skipped") with notice — never clobber.
+ */
+export async function mergeMcpJson(destinationDir, servers, dryRun = false) {
+    const path = join(destinationDir, ".mcp.json");
+    const notices = [];
+    const existingRaw = await readFile(path, "utf8").catch(() => null);
+    if (existingRaw === null) {
+        if (!dryRun) {
+            await mkdir(destinationDir, { recursive: true });
+            await writeFile(path, JSON.stringify({ mcpServers: servers }, null, 2) + "\n", "utf8");
+        }
+        return { action: "created", path, notices };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existingRaw);
+    }
+    catch {
+        notices.push(`Existing .mcp.json is not valid JSON — skipped to avoid clobbering it. Path: ${path}`);
+        return { action: "skipped", path, notices };
+    }
+    const merged = { ...(parsed.mcpServers ?? {}) };
+    for (const [name, entry] of Object.entries(servers)) {
+        if (name in merged) {
+            notices.push(`.mcp.json already has server '${name}' — kept existing entry.`);
+            continue;
+        }
+        merged[name] = entry;
+    }
+    parsed.mcpServers = merged;
+    if (!dryRun) {
+        await writeFile(path, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+    }
+    return { action: "merged", path, notices };
+}
+/**
+ * Write `<destinationDir>/.code-ai/config.json` with the chosen backend.
+ * Idempotent — re-running overwrites with the same content if backend unchanged.
+ */
+export async function writeCodeAiConfig(destinationDir, config, dryRun = false) {
+    const dir = join(destinationDir, ".code-ai");
+    const path = join(dir, "config.json");
+    if (!dryRun) {
+        await mkdir(dir, { recursive: true });
+        await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+    }
+    return { path };
+}
+/**
+ * End-to-end orchestrator. Called from the install flow when `target=claude`.
+ *
+ * Order:
+ *   1. If user wants MemPalace: detect → install if absent → fall back if install fails.
+ *   2. Build server entries (code-ai-mcp always; mempalace only when usable).
+ *   3. Merge into .mcp.json.
+ *   4. Write .code-ai/config.json with backend choice.
+ *
+ * Reports all decisions in `McpSetupReport.notices` so callers can surface
+ * them to the user verbatim.
+ */
+export async function setupMcp(opts) {
+    const notices = [];
+    let mempalaceUsed = false;
+    let mempalaceInstallAttempted = false;
+    let mempalaceInstallSucceeded = false;
+    let pythonRuntime = null;
+    if (opts.wantMempalace) {
+        const present = await detectMemPalace();
+        if (present) {
+            mempalaceUsed = true;
+            notices.push("MemPalace binary already on PATH — skipping install.");
+        }
+        else {
+            pythonRuntime = await detectPythonRuntime();
+            if (pythonRuntime) {
+                mempalaceInstallAttempted = true;
+                const result = await installMemPalace(pythonRuntime);
+                if (result.ok) {
+                    mempalaceInstallSucceeded = true;
+                    mempalaceUsed = true;
+                    notices.push(`MemPalace installed via ${pythonRuntime.tool}.`);
+                }
+                else {
+                    notices.push(`MemPalace install via ${pythonRuntime.tool} failed — falling back to JsonlStore. Output:\n${result.output}`);
+                }
+            }
+            else {
+                notices.push("No Python runtime (uv / pipx / pip) found on PATH — cannot install MemPalace. Falling back to JsonlStore. Install Python 3.9+ and one of uv/pipx, then re-run installer with --with-mempalace.");
+            }
+        }
+    }
+    // DEV-100 consolidation: the code-ai-mcp bin lives inside the
+    // `code-ai-installer` npm package. `npx -p <package> <bin>` tells npm to
+    // install that package and run the named bin from it.
+    const servers = {
+        "code-ai-mcp": {
+            command: "npx",
+            args: ["-y", "-p", "code-ai-installer", "code-ai-mcp"],
+        },
+    };
+    if (mempalaceUsed) {
+        servers["mempalace"] = {
+            command: "mempalace",
+            args: ["mcp"],
+        };
+    }
+    const mcp = await mergeMcpJson(opts.destinationDir, servers, opts.dryRun);
+    notices.push(...mcp.notices);
+    const cfg = await writeCodeAiConfig(opts.destinationDir, {
+        decision_store: mempalaceUsed ? "mempalace" : "jsonl",
+        ...(opts.domain ? { domain: opts.domain } : {}),
+    }, opts.dryRun);
+    return {
+        mempalaceUsed,
+        mempalaceInstallAttempted,
+        mempalaceInstallSucceeded,
+        pythonRuntime,
+        mcpJsonPath: mcp.path,
+        mcpJsonAction: mcp.action,
+        configPath: cfg.path,
+        notices,
+    };
+}
+// ─── Subprocess helpers ─────────────────────────────────────────────────────
+async function spawnExitZero(command, args) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, { stdio: "ignore", shell: false });
+        proc.on("error", () => resolve(false));
+        proc.on("exit", (code) => resolve(code === 0));
+    });
+}
+async function spawnCapture(command, args) {
+    return new Promise((resolve) => {
+        let output = "";
+        const proc = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], shell: false });
+        proc.stdout?.on("data", (chunk) => {
+            output += chunk.toString("utf8");
+        });
+        proc.stderr?.on("data", (chunk) => {
+            output += chunk.toString("utf8");
+        });
+        proc.on("error", (err) => {
+            resolve({ ok: false, output: `${output}\n[spawn error] ${err.message}` });
+        });
+        proc.on("exit", (code) => {
+            resolve({ ok: code === 0, output });
+        });
+    });
+}