code-ai-installer 2.5.0 → 4.0.0

package/dist/mcp/tools/request_decision.js

@@ -0,0 +1,53 @@
+import { recordDecision } from "./record_decision.js";
+/**
+ * Passthrough decision channel.
+ *
+ * MCP can't prompt the user directly mid-tool-call, so this tool is split into
+ * two parts:
+ *   1. Caller invokes request_decision with question + options. The tool
+ *      validates input but does NOT record an ADR yet. It returns a structured
+ *      "pending" envelope that Claude (the LLM) relays to DEN in chat.
+ *   2. After DEN replies in chat, Claude calls record_decision with the chosen
+ *      option_id + rationale, which writes the ADR atomically (3 places).
+ *
+ * The returned object satisfies the RequestDecisionOutput contract by emitting
+ * a synthetic adr_id like `PENDING-<task_id>-<gate>-<hash>` that Claude is
+ * expected to discard. When the real ADR is written via record_decision, that
+ * tool returns the actual ADR id.
+ *
+ * Future replacement: if Claude Code (or the MCP transport) gains an
+ * `elicitation` primitive, this tool can be reworked to actually block on user
+ * input. The contract above stays valid; only the body changes.
+ */
+export async function requestDecision(input) {
+    const hash = simpleHash(`${input.task_id}|${input.gate}|${input.question}`).toUpperCase();
+    const safeTask = input.task_id.toUpperCase().replace(/[^A-Z0-9-]/g, "");
+    return {
+        chosen_option_id: "__pending__",
+        signer: "den",
+        adr_id: `ADR-PENDING-${safeTask}-${input.gate}-${hash}`,
+        timestamp: new Date().toISOString(),
+    };
+}
+/**
+ * Convenience: convert request_decision output into a record_decision input
+ * once Claude has surfaced the question to DEN and received an answer.
+ * Not part of the MCP surface — use as a helper from the LLM relay flow.
+ */
+export async function commitRequestedDecision(args) {
+    return recordDecision({
+        task_id: args.input.task_id,
+        gate: args.input.gate,
+        question: args.input.question,
+        options: args.input.options,
+        chosen_option_id: args.chosen_option_id,
+        rationale: args.rationale,
+        signer: "den",
+    });
+}
+function simpleHash(s) {
+    let h = 0;
+    for (let i = 0; i < s.length; i++)
+        h = (h * 31 + s.charCodeAt(i)) | 0;
+    return Math.abs(h).toString(16).slice(0, 6);
+}

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

@@ -0,0 +1,14 @@
+import { type SignOffInput, type SignOffOutput } from "../../shared/index.js";
+/**
+ * Records a sign-off event for the task's current gate. Validates that:
+ *   1. Task exists and is at the named gate.
+ *   2. Signer matches sign_off_policy:
+ *        sign_off_policy=den            → signer must be "den"
+ *        sign_off_policy=mcp_auto_pass  → signer must be "mcp"
+ *        sign_off_policy=either         → signer must be "den" or "mcp"
+ *   3. Gate has a classification recorded if classify_required=true.
+ *
+ * Does NOT advance the gate — that's advance_gate's job. sign_off only
+ * records evidence; advance_gate gates on it.
+ */
+export declare function signOff(input: SignOffInput): Promise<SignOffOutput>;

package/dist/mcp/tools/sign_off.js

@@ -0,0 +1,58 @@
+import { getGateConfig, loadPipeline } from "../pipeline.js";
+import { readTaskState, writeTaskState } from "../task_state.js";
+const DEFAULT_DOMAIN = "development";
+/**
+ * Records a sign-off event for the task's current gate. Validates that:
+ *   1. Task exists and is at the named gate.
+ *   2. Signer matches sign_off_policy:
+ *        sign_off_policy=den            → signer must be "den"
+ *        sign_off_policy=mcp_auto_pass  → signer must be "mcp"
+ *        sign_off_policy=either         → signer must be "den" or "mcp"
+ *   3. Gate has a classification recorded if classify_required=true.
+ *
+ * Does NOT advance the gate — that's advance_gate's job. sign_off only
+ * records evidence; advance_gate gates on it.
+ */
+export async function signOff(input) {
+    const pipeline = await loadPipeline(DEFAULT_DOMAIN);
+    const state = await readTaskState(input.task_id);
+    if (!state) {
+        throw new Error(`sign_off: no task state for ${input.task_id} (call current_gate or classify_gate first)`);
+    }
+    if (state.current_gate !== input.gate) {
+        throw new Error(`sign_off: task ${input.task_id} is at gate ${state.current_gate}, not ${input.gate}`);
+    }
+    const gateCfg = getGateConfig(pipeline, state.mode, input.gate);
+    switch (gateCfg.sign_off_policy) {
+        case "den":
+            if (input.signer !== "den") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'den' (policy=den), got '${input.signer}'`);
+            }
+            break;
+        case "mcp_auto_pass":
+            if (input.signer !== "mcp") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'mcp' (policy=mcp_auto_pass), got '${input.signer}'`);
+            }
+            break;
+        case "either":
+            if (input.signer !== "den" && input.signer !== "mcp") {
+                throw new Error(`sign_off: gate ${input.gate} requires signer 'den' or 'mcp' (policy=either), got '${input.signer}'`);
+            }
+            break;
+    }
+    if (gateCfg.classify_required) {
+        const hasClassification = state.classifications.some((c) => c.gate === input.gate);
+        if (!hasClassification) {
+            throw new Error(`sign_off: gate ${input.gate} requires classify_gate first (classify_required=true)`);
+        }
+    }
+    const timestamp = new Date().toISOString();
+    state.signoffs.push({
+        gate: input.gate,
+        signer: input.signer,
+        timestamp,
+        evidence: input.evidence,
+    });
+    await writeTaskState(state);
+    return { signed: true, signer: input.signer, timestamp };
+}

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

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+import { TOOL_REGISTRY, type ToolName } from "../../shared/index.js";
+/**
+ * Typed handler signature derived from the I/O contracts in the shared types module (src/shared).
+ */
+export type ToolHandler<N extends ToolName> = (input: z.infer<(typeof TOOL_REGISTRY)[N]["input"]>) => Promise<z.infer<(typeof TOOL_REGISTRY)[N]["output"]>>;
+/** Thrown by every stub until the real implementation lands. */
+export declare class NotImplementedError extends Error {
+    constructor(tool: ToolName);
+}
+/**
+ * Default handler registry — every tool starts as a NotImplementedError stub.
+ * Real implementations replace entries here as they land (pre-req #3 baseline prototype).
+ */
+export declare const DEFAULT_HANDLERS: {
+    [N in ToolName]: ToolHandler<N>;
+};

package/dist/mcp/tools/stubs.js

@@ -0,0 +1,65 @@
+import { TOOL_REGISTRY } from "../../shared/index.js";
+import { listSkills } from "./list_skills.js";
+import { loadRole } from "./load_role.js";
+import { requestDecision } from "./request_decision.js";
+import { recordDecision } from "./record_decision.js";
+import { currentGate } from "./current_gate.js";
+import { classifyGate } from "./classify_gate.js";
+import { signOff } from "./sign_off.js";
+import { advanceGate } from "./advance_gate.js";
+import { submitArtifact } from "./submit_artifact.js";
+import { getSkill } from "./get_skill.js";
+import { regenerateManifest } from "./regenerate_manifest.js";
+import { reportException } from "./report_exception.js";
+import { recentDecisions } from "./recent_decisions.js";
+import { auditTrail } from "./audit_trail.js";
+import { listArtifacts } from "./list_artifacts.js";
+import { getArtifact } from "./get_artifact.js";
+import { verifyClaim } from "./verify_claim.js";
+/** Thrown by every stub until the real implementation lands. */
+export class NotImplementedError extends Error {
+    constructor(tool) {
+        super(`tool not yet implemented: ${tool}`);
+        this.name = "NotImplementedError";
+    }
+}
+/** Build a stub handler that validates input then throws NotImplementedError. */
+function stub(name) {
+    const schema = TOOL_REGISTRY[name].input;
+    return async (raw) => {
+        schema.parse(raw);
+        throw new NotImplementedError(name);
+    };
+}
+/**
+ * Default handler registry — every tool starts as a NotImplementedError stub.
+ * Real implementations replace entries here as they land (pre-req #3 baseline prototype).
+ */
+export const DEFAULT_HANDLERS = {
+    load_role: loadRole,
+    list_skills: listSkills,
+    get_skill: getSkill,
+    request_decision: requestDecision,
+    record_decision: recordDecision,
+    classify_gate: classifyGate,
+    advance_gate: advanceGate,
+    current_gate: currentGate,
+    sign_off: signOff,
+    submit_artifact: submitArtifact,
+    verify_claim: verifyClaim,
+    report_exception: reportException,
+    get_artifact: getArtifact,
+    list_artifacts: listArtifacts,
+    audit_trail: auditTrail,
+    recent_decisions: recentDecisions,
+    regenerate_manifest: regenerateManifest,
+    run_drift_audit: stub("run_drift_audit"),
+    run_tests: stub("run_tests"),
+    apply_diff: stub("apply_diff"),
+    git_commit: stub("git_commit"),
+    check_lint: stub("check_lint"),
+    build: stub("build"),
+    dependency_supply_chain: stub("dependency_supply_chain"),
+    docker_compose: stub("docker_compose"),
+    e2e_playwright: stub("e2e_playwright"),
+};

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

@@ -0,0 +1,19 @@
+import { type SubmitArtifactInput, type SubmitArtifactOutput } 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 declare function submitArtifact(input: SubmitArtifactInput): Promise<SubmitArtifactOutput>;

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,148 @@
+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";
+/**
+ * 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":
+        case "build_succeeds":
+        case "lint_clean":
+        case "custom": {
+            return {
+                verified: false,
+                evidence: { reason: `claim_type='${input.claim_type}' not wired yet (Phase 2 tool dependency)` },
+                failures: [
+                    {
+                        code: `${input.claim_type}-unwired`,
+                        message: `verify_claim: claim_type='${input.claim_type}' will be enabled once the corresponding Phase 2 auto-check tool lands.`,
+                    },
+                ],
+            };
+        }
+        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,101 @@
+/**
+ * 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;
+}
+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";
+}, 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>;