@aidemd-mcp/server 0.2.0

package/dist/tools/read/index.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { readFile, readdir } from "node:fs/promises";
+import { join, dirname, basename, isAbsolute, relative } from "node:path";
+import { classifyFile } from "../../util/classify/index.js";
+export const ReadInput = z.object({
+    path: z.string().describe("Path to the .aide file to read"),
+});
+/** Extract links from .aide content: [[wikilinks]], relative paths, URLs. */
+function extractLinks(content) {
+    const links = [];
+    const seen = new Set();
+    const add = (link) => {
+        if (!seen.has(link)) {
+            seen.add(link);
+            links.push(link);
+        }
+    };
+    // [[wikilinks]]
+    for (const match of content.matchAll(/\[\[([^\]]+)\]\]/g))
+        add(`[[${match[1]}]]`);
+    // Relative paths: ./something or ../something
+    for (const match of content.matchAll(/(?:^|\s)(\.\.?\/[^\s),\]]+)/gm))
+        add(match[1]);
+    // URLs
+    for (const match of content.matchAll(/https?:\/\/[^\s),\]>]+/g))
+        add(match[0]);
+    return links;
+}
+/** Find sibling .aide files in the same directory. */
+async function findSiblings(filePath, root) {
+    const dir = dirname(filePath);
+    const currentName = basename(filePath);
+    const siblings = [];
+    try {
+        const entries = await readdir(dir);
+        for (const name of entries) {
+            if (name === currentName)
+                continue;
+            if (!name.endsWith(".aide"))
+                continue;
+            const sibPath = join(dir, name);
+            const relativePath = relative(root, sibPath).split("\\").join("/");
+            siblings.push({
+                path: sibPath,
+                relativePath,
+                type: classifyFile(name),
+                summary: "",
+            });
+        }
+    }
+    catch {
+        // skip unreadable dirs
+    }
+    return siblings;
+}
+/**
+ * Read an .aide file with context awareness.
+ * Returns the file content, classified type, sibling specs in the same
+ * directory, and links found in the content.
+ */
+export default async function read(root, filePath) {
+    const resolved = isAbsolute(filePath) ? filePath : join(root, filePath);
+    let content;
+    try {
+        content = await readFile(resolved, "utf-8");
+    }
+    catch {
+        return {
+            content: `Path not found: ${filePath}`,
+            type: "intent",
+            siblings: [],
+            links: [],
+        };
+    }
+    const type = classifyFile(basename(resolved));
+    const siblings = await findSiblings(resolved, root);
+    const links = extractLinks(content);
+    return { content, type, siblings, links };
+}

package/dist/tools/scaffold/index.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const ScaffoldInput: z.ZodObject<{
+    directory: z.ZodString;
+    type: z.ZodEnum<["intent", "research", "both", "todo", "plan"]>;
+}, "strip", z.ZodTypeAny, {
+    type: "intent" | "research" | "todo" | "plan" | "both";
+    directory: string;
+}, {
+    type: "intent" | "research" | "todo" | "plan" | "both";
+    directory: string;
+}>;
+/**
+ * Create new .aide files with correct naming conventions.
+ * Handles auto-rename logic:
+ * - type=intent + no research.aide → creates .aide
+ * - type=intent + research.aide exists → creates intent.aide
+ * - type=research → creates research.aide; renames existing .aide to intent.aide
+ * - type=both → creates research.aide + intent.aide
+ * - type=todo → creates todo.aide
+ * - type=plan → creates plan.aide
+ */
+export default function scaffold(root: string, directory: string, type: "intent" | "research" | "both" | "todo" | "plan"): Promise<string>;

package/dist/tools/scaffold/index.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { readdir, writeFile, rename, mkdir } from "node:fs/promises";
+import { join, isAbsolute } from "node:path";
+export const ScaffoldInput = z.object({
+    directory: z.string().describe("Directory where the .aide file(s) will be created"),
+    type: z
+        .enum(["intent", "research", "both", "todo", "plan"])
+        .describe("Type of .aide file to create (intent, research, both, todo, or plan)"),
+});
+const INTENT_TEMPLATE = `# Intent Spec
+
+## Strategy
+
+
+
+## Implementation Contract
+
+
+
+## Anti-Patterns
+
+`;
+const RESEARCH_TEMPLATE = `# Research
+
+## Sources
+
+
+
+## Data Points
+
+
+
+## Patterns
+
+`;
+const TODO_TEMPLATE = `# QA Re-alignment Document
+
+- [ ]
+`;
+const PLAN_TEMPLATE = `---
+intent: >
+
+---
+
+## Plan
+
+- [ ]
+
+## Decisions
+
+`;
+/** List existing .aide files in a directory. */
+async function existingAideFiles(dir) {
+    try {
+        const entries = await readdir(dir);
+        return entries.filter((name) => name.endsWith(".aide"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Create new .aide files with correct naming conventions.
+ * Handles auto-rename logic:
+ * - type=intent + no research.aide → creates .aide
+ * - type=intent + research.aide exists → creates intent.aide
+ * - type=research → creates research.aide; renames existing .aide to intent.aide
+ * - type=both → creates research.aide + intent.aide
+ * - type=todo → creates todo.aide
+ * - type=plan → creates plan.aide
+ */
+export default async function scaffold(root, directory, type) {
+    const dir = isAbsolute(directory) ? directory : join(root, directory);
+    // Ensure directory exists
+    await mkdir(dir, { recursive: true });
+    const existing = await existingAideFiles(dir);
+    const actions = [];
+    if (type === "todo") {
+        const target = join(dir, "todo.aide");
+        await writeFile(target, TODO_TEMPLATE, "utf-8");
+        actions.push("Created todo.aide");
+    }
+    else if (type === "plan") {
+        const target = join(dir, "plan.aide");
+        await writeFile(target, PLAN_TEMPLATE, "utf-8");
+        actions.push("Created plan.aide");
+    }
+    else if (type === "intent") {
+        if (existing.includes("research.aide")) {
+            const target = join(dir, "intent.aide");
+            await writeFile(target, INTENT_TEMPLATE, "utf-8");
+            actions.push("Created intent.aide (research.aide exists, so using explicit name)");
+        }
+        else {
+            const target = join(dir, ".aide");
+            await writeFile(target, INTENT_TEMPLATE, "utf-8");
+            actions.push("Created .aide");
+        }
+    }
+    else if (type === "research") {
+        // If .aide exists, rename to intent.aide first
+        if (existing.includes(".aide") && !existing.includes("intent.aide")) {
+            await rename(join(dir, ".aide"), join(dir, "intent.aide"));
+            actions.push("Renamed .aide → intent.aide");
+        }
+        const target = join(dir, "research.aide");
+        await writeFile(target, RESEARCH_TEMPLATE, "utf-8");
+        actions.push("Created research.aide");
+    }
+    else if (type === "both") {
+        // If .aide exists, remove it since we're creating intent.aide
+        if (existing.includes(".aide") && !existing.includes("intent.aide")) {
+            await rename(join(dir, ".aide"), join(dir, "intent.aide"));
+            actions.push("Renamed .aide → intent.aide");
+        }
+        else if (!existing.includes("intent.aide")) {
+            await writeFile(join(dir, "intent.aide"), INTENT_TEMPLATE, "utf-8");
+            actions.push("Created intent.aide");
+        }
+        if (!existing.includes("research.aide")) {
+            await writeFile(join(dir, "research.aide"), RESEARCH_TEMPLATE, "utf-8");
+            actions.push("Created research.aide");
+        }
+    }
+    if (actions.length === 0)
+        return "No changes needed — files already exist.";
+    return actions.join("\n");
+}

package/dist/tools/upgrade/applyFiles/index.d.ts

@@ -0,0 +1,33 @@
+import type { UpgradeFileResult } from "../../../types/index.js";
+/**
+ * Apply mode writer for aide_upgrade — turns comparison results into disk state
+ * and returns the manifest the agent reports to the user.
+ *
+ * Dispatch logic per file:
+ *
+ * - `"differs"` or `"missing"`, NOT mcp category, NOT VS Code IDE:
+ *   Creates parent directories and writes `canonicalContent` to `filePath`.
+ *   Returns the result with `status` changed to `"updated"` (was differs) or
+ *   `"created"` (was missing), and `canonicalContent` stripped.
+ *
+ * - `"differs"` or `"missing"`, mcp category:
+ *   Passed through unchanged with `prescription` intact — the agent merges
+ *   prescriptions into the existing MCP config itself. Never written here.
+ *
+ * - `"differs"` IDE VS Code step (name contains "VS Code"):
+ *   Passed through with `instructions` field set to
+ *   `code --install-extension <filePath>`. The VS Code CLI is required for
+ *   extension installs — the MCP server cannot invoke it. No disk write.
+ *
+ * - `"differs"` or `"missing"` IDE Zed step:
+ *   Has `canonicalContent` — written to disk normally via the regular file path.
+ *
+ * - `"matches"`:
+ *   Returned as `"unchanged"` — already current, no write needed. This maps
+ *   the dry-run vocabulary to the apply-mode terminal vocabulary defined in
+ *   the spec (`"updated"`, `"created"`, `"unchanged"`).
+ *
+ * - `"malformed"`, `"updated"`, `"created"`, `"unchanged"`:
+ *   Passed through unchanged — no action available or already applied.
+ */
+export default function applyFiles(files: UpgradeFileResult[]): Promise<UpgradeFileResult[]>;

package/dist/tools/upgrade/applyFiles/index.js

@@ -0,0 +1,65 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * Apply mode writer for aide_upgrade — turns comparison results into disk state
+ * and returns the manifest the agent reports to the user.
+ *
+ * Dispatch logic per file:
+ *
+ * - `"differs"` or `"missing"`, NOT mcp category, NOT VS Code IDE:
+ *   Creates parent directories and writes `canonicalContent` to `filePath`.
+ *   Returns the result with `status` changed to `"updated"` (was differs) or
+ *   `"created"` (was missing), and `canonicalContent` stripped.
+ *
+ * - `"differs"` or `"missing"`, mcp category:
+ *   Passed through unchanged with `prescription` intact — the agent merges
+ *   prescriptions into the existing MCP config itself. Never written here.
+ *
+ * - `"differs"` IDE VS Code step (name contains "VS Code"):
+ *   Passed through with `instructions` field set to
+ *   `code --install-extension <filePath>`. The VS Code CLI is required for
+ *   extension installs — the MCP server cannot invoke it. No disk write.
+ *
+ * - `"differs"` or `"missing"` IDE Zed step:
+ *   Has `canonicalContent` — written to disk normally via the regular file path.
+ *
+ * - `"matches"`:
+ *   Returned as `"unchanged"` — already current, no write needed. This maps
+ *   the dry-run vocabulary to the apply-mode terminal vocabulary defined in
+ *   the spec (`"updated"`, `"created"`, `"unchanged"`).
+ *
+ * - `"malformed"`, `"updated"`, `"created"`, `"unchanged"`:
+ *   Passed through unchanged — no action available or already applied.
+ */
+export default async function applyFiles(files) {
+    return Promise.all(files.map(applyFile));
+}
+async function applyFile(file) {
+    // Files that already match canonical are reported as "unchanged" in apply output
+    if (file.status === "matches") {
+        return { ...file, status: "unchanged" };
+    }
+    // Only act on files that need writing — differs or missing
+    if (file.status !== "differs" && file.status !== "missing") {
+        return file;
+    }
+    // MCP files carry a prescription — the agent merges them; never written here
+    if (file.category === "mcp") {
+        return file;
+    }
+    // IDE VS Code steps require the external `code` CLI — pass through with
+    // instructions so the agent knows what command to run
+    if (file.category === "ide" && file.name.includes("VS Code")) {
+        return { ...file, instructions: `code --install-extension ${file.filePath}` };
+    }
+    // Regular file step (including IDE Zed) — write canonicalContent to filePath
+    if (file.canonicalContent !== undefined) {
+        await mkdir(dirname(file.filePath), { recursive: true });
+        await writeFile(file.filePath, file.canonicalContent, "utf-8");
+        // Strip canonicalContent; map comparison status to execution status
+        const { canonicalContent: _content, ...rest } = file;
+        return { ...rest, status: file.status === "differs" ? "updated" : "created" };
+    }
+    // No content and not a special case — pass through unchanged
+    return file;
+}

package/dist/tools/upgrade/buildVersionsMeta/index.d.ts

@@ -0,0 +1,20 @@
+/** Git-derived version metadata for a single methodology doc. */
+export interface VersionMeta {
+    /** ISO 8601 author timestamp of the last commit touching this doc. */
+    publishedAt: string;
+    /** 7-char short SHA of the last commit touching this doc. */
+    sourceCommit: string;
+    /** 7-char short SHA of the prior commit touching this doc, if one exists. */
+    previousCommit?: string;
+}
+/** Map of doc slug → version metadata. */
+export type VersionsMap = Record<string, VersionMeta>;
+/**
+ * Extract git commit metadata for each methodology doc from this repo's
+ * own history. Returns a map keyed by doc slug (filename without .md).
+ *
+ * Uses `git log --follow` so history survives file renames. Gracefully
+ * returns an empty object if git is unavailable, and omits individual
+ * slugs whose files have no commit history (e.g. newly added, untracked).
+ */
+export default function buildVersionsMeta(): Promise<VersionsMap>;

package/dist/tools/upgrade/buildVersionsMeta/index.js

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { listMethodologyDocs } from "../../../tools/init/initContent/index.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Repo root resolved from this module's location. Same 4-hop walk as
+ * initContent — src/ and dist/ are siblings under the repo root at the
+ * same depth (src/tools/upgrade/buildVersionsMeta or
+ * dist/tools/upgrade/buildVersionsMeta).
+ */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(MODULE_DIR, "..", "..", "..", "..");
+/**
+ * Extract git commit metadata for each methodology doc from this repo's
+ * own history. Returns a map keyed by doc slug (filename without .md).
+ *
+ * Uses `git log --follow` so history survives file renames. Gracefully
+ * returns an empty object if git is unavailable, and omits individual
+ * slugs whose files have no commit history (e.g. newly added, untracked).
+ */
+export default async function buildVersionsMeta() {
+    const docs = listMethodologyDocs();
+    const result = {};
+    for (const entry of docs) {
+        const slug = entry.hostFilename.replace(/\.md$/, "");
+        const docPath = `.aide/docs/${entry.hostFilename}`;
+        try {
+            const { stdout } = await execFileAsync("git", ["log", "--follow", "--format=%H %aI", "-n", "2", "--", docPath], { cwd: REPO_ROOT });
+            const lines = stdout.trim().split("\n").filter(Boolean);
+            if (lines.length === 0)
+                continue;
+            const [latestSha, latestDate] = lines[0].split(" ", 2);
+            const meta = {
+                publishedAt: latestDate,
+                sourceCommit: latestSha.slice(0, 7),
+            };
+            if (lines.length > 1) {
+                const [priorSha] = lines[1].split(" ", 2);
+                meta.previousCommit = priorSha.slice(0, 7);
+            }
+            result[slug] = meta;
+        }
+        catch {
+            // Git unavailable or command failed for this file — skip slug.
+            continue;
+        }
+    }
+    return result;
+}

package/dist/tools/upgrade/checkIdeConfig/index.d.ts

@@ -0,0 +1,24 @@
+import type { UpgradeFileResult } from "../../../types/index.js";
+/**
+ * Compare the Zed `*.aide` file-type association against canonical.
+ * Read-only — never writes.
+ *
+ * Returns an `UpgradeFileResult` with category `"ide"`:
+ * - `"malformed"` when `.zed/settings.json` exists but is not valid JSON.
+ * - `"missing"` when the settings file does not exist.
+ * - `"matches"` when `*.aide` is already in `file_types.Markdown`.
+ * - `"differs"` when the file exists but the association is absent.
+ *   `canonicalContent` is the full settings file with the association merged in.
+ */
+export declare function checkZedConfig(projectRoot: string): Promise<UpgradeFileResult>;
+/**
+ * Check whether the VS Code aide-markdown extension is installed.
+ * Read-only — never installs.
+ *
+ * Returns an `UpgradeFileResult` with category `"ide"`:
+ * - `"matches"` when the extension is already installed or the `code` CLI is
+ *   unavailable (cannot determine state).
+ * - `"differs"` when the extension is not installed and can be installed.
+ *   `canonicalContent` is the absolute path to the bundled `.vsix` file.
+ */
+export declare function checkVscodeExtension(): Promise<UpgradeFileResult>;

package/dist/tools/upgrade/checkIdeConfig/index.js

@@ -0,0 +1,134 @@
+import { readFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+const execFileAsync = promisify(execFile);
+/** Read a file, returning undefined if it does not exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compare the Zed `*.aide` file-type association against canonical.
+ * Read-only — never writes.
+ *
+ * Returns an `UpgradeFileResult` with category `"ide"`:
+ * - `"malformed"` when `.zed/settings.json` exists but is not valid JSON.
+ * - `"missing"` when the settings file does not exist.
+ * - `"matches"` when `*.aide` is already in `file_types.Markdown`.
+ * - `"differs"` when the file exists but the association is absent.
+ *   `canonicalContent` is the full settings file with the association merged in.
+ */
+export async function checkZedConfig(projectRoot) {
+    const name = "Zed config";
+    const settingsPath = join(projectRoot, ".zed", "settings.json");
+    const existing = await safeReadFile(settingsPath);
+    if (existing !== undefined) {
+        let settings;
+        try {
+            settings = JSON.parse(existing);
+        }
+        catch {
+            return {
+                name,
+                filePath: settingsPath,
+                status: "malformed",
+                category: "ide",
+            };
+        }
+        const mdTypes = settings.file_types?.Markdown ?? [];
+        if (mdTypes.includes("*.aide")) {
+            return {
+                name,
+                filePath: settingsPath,
+                status: "matches",
+                category: "ide",
+            };
+        }
+        // Merge the association and return the full content for the agent.
+        const merged = {
+            ...settings,
+            file_types: {
+                ...(settings.file_types ?? {}),
+                Markdown: [...mdTypes, "*.aide"],
+            },
+        };
+        return {
+            name,
+            filePath: settingsPath,
+            status: "differs",
+            category: "ide",
+            canonicalContent: JSON.stringify(merged, null, 2) + "\n",
+        };
+    }
+    // Settings file absent — canonical is a fresh file with the association.
+    const canonical = { file_types: { Markdown: ["*.aide"] } };
+    return {
+        name,
+        filePath: settingsPath,
+        status: "missing",
+        category: "ide",
+        canonicalContent: JSON.stringify(canonical, null, 2) + "\n",
+    };
+}
+/**
+ * Check whether the VS Code aide-markdown extension is installed.
+ * Read-only — never installs.
+ *
+ * Returns an `UpgradeFileResult` with category `"ide"`:
+ * - `"matches"` when the extension is already installed or the `code` CLI is
+ *   unavailable (cannot determine state).
+ * - `"differs"` when the extension is not installed and can be installed.
+ *   `canonicalContent` is the absolute path to the bundled `.vsix` file.
+ */
+export async function checkVscodeExtension() {
+    const name = "VS Code extension";
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const vsixPath = join(moduleDir, "..", "..", "..", "..", "extensions", "vscode", "aide-markdown-0.0.1.vsix");
+    // Ensure `code` CLI is available.
+    try {
+        await execFileAsync("code", ["--version"]);
+    }
+    catch {
+        return {
+            name,
+            filePath: vsixPath,
+            status: "matches",
+            category: "ide",
+        };
+    }
+    // Check installation state.
+    let installed;
+    try {
+        const { stdout } = await execFileAsync("code", ["--list-extensions"]);
+        installed = stdout.toLowerCase().includes("aide-markdown");
+    }
+    catch {
+        return {
+            name,
+            filePath: vsixPath,
+            status: "matches",
+            category: "ide",
+        };
+    }
+    if (installed) {
+        return {
+            name,
+            filePath: vsixPath,
+            status: "matches",
+            category: "ide",
+        };
+    }
+    return {
+        name,
+        filePath: vsixPath,
+        status: "differs",
+        category: "ide",
+        canonicalContent: vsixPath,
+    };
+}

package/dist/tools/upgrade/checkMcpConfig/index.d.ts

@@ -0,0 +1,17 @@
+import type { UpgradeFileResult } from "../../../types/index.js";
+/**
+ * Compare the `aide` / `aidemd-mcp` key in an MCP config file against the
+ * canonical shape. Read-only — never writes.
+ *
+ * Returns an `UpgradeFileResult` with category `"mcp"`:
+ * - `"malformed"` when the file exists but is not valid JSON.
+ * - `"missing"` when the file does not exist. `prescription` carries the
+ *   canonical server entry for the agent to merge.
+ * - `"matches"` when the aide entry already matches canonical.
+ * - `"differs"` when the aide entry is absent or differs. `prescription`
+ *   carries the canonical server entry for the agent to merge.
+ *
+ * The legacy `"aidemd-mcp"` key (old unscoped package) is detected as
+ * `"differs"` so the agent can migrate it to the canonical `"aide"` key.
+ */
+export default function checkMcpConfig(mcpConfigPath: string): Promise<UpgradeFileResult>;

package/dist/tools/upgrade/checkMcpConfig/index.js

@@ -0,0 +1,81 @@
+import { readFile } from "node:fs/promises";
+/** Canonical aide server entry that upgrade checks and reports. */
+const CANONICAL_AIDE_SERVER = {
+    command: "npx",
+    args: ["@aidemd-mcp/server"],
+};
+/** Read a file, returning undefined if it does not exist. */
+async function safeReadFile(path) {
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compare the `aide` / `aidemd-mcp` key in an MCP config file against the
+ * canonical shape. Read-only — never writes.
+ *
+ * Returns an `UpgradeFileResult` with category `"mcp"`:
+ * - `"malformed"` when the file exists but is not valid JSON.
+ * - `"missing"` when the file does not exist. `prescription` carries the
+ *   canonical server entry for the agent to merge.
+ * - `"matches"` when the aide entry already matches canonical.
+ * - `"differs"` when the aide entry is absent or differs. `prescription`
+ *   carries the canonical server entry for the agent to merge.
+ *
+ * The legacy `"aidemd-mcp"` key (old unscoped package) is detected as
+ * `"differs"` so the agent can migrate it to the canonical `"aide"` key.
+ */
+export default async function checkMcpConfig(mcpConfigPath) {
+    const name = "MCP config";
+    const prescription = { key: "aide", entry: CANONICAL_AIDE_SERVER };
+    const existing = await safeReadFile(mcpConfigPath);
+    if (existing === undefined) {
+        return {
+            name,
+            filePath: mcpConfigPath,
+            status: "missing",
+            category: "mcp",
+            prescription,
+        };
+    }
+    let config;
+    try {
+        config = JSON.parse(existing);
+    }
+    catch {
+        return {
+            name,
+            filePath: mcpConfigPath,
+            status: "malformed",
+            category: "mcp",
+        };
+    }
+    const servers = (config.mcpServers ?? {});
+    // Check both key names init may have used.
+    const hasLegacyKey = "aidemd-mcp" in servers;
+    const aideEntry = ("aide" in servers ? servers["aide"] : servers["aidemd-mcp"]);
+    const isCanonical = !hasLegacyKey &&
+        aideEntry !== undefined &&
+        aideEntry.command === CANONICAL_AIDE_SERVER.command &&
+        Array.isArray(aideEntry.args) &&
+        aideEntry.args.length === CANONICAL_AIDE_SERVER.args.length &&
+        CANONICAL_AIDE_SERVER.args.every((a, i) => aideEntry.args[i] === a);
+    if (isCanonical) {
+        return {
+            name,
+            filePath: mcpConfigPath,
+            status: "matches",
+            category: "mcp",
+        };
+    }
+    return {
+        name,
+        filePath: mcpConfigPath,
+        status: "differs",
+        category: "mcp",
+        prescription,
+    };
+}

package/dist/tools/upgrade/compareFile/index.d.ts

@@ -0,0 +1,12 @@
+import type { UpgradeFileStatus } from "../../../types/index.js";
+/**
+ * Compare a host file against canonical content.
+ *
+ * Read-only — never writes. Returns:
+ * - `"missing"` when the file does not exist
+ * - `"matches"` when the file content is byte-identical to canonical
+ * - `"differs"` when the file exists but content differs
+ *
+ * Non-ENOENT read errors are re-thrown.
+ */
+export default function compareFile(hostPath: string, canonicalContent: string): Promise<UpgradeFileStatus>;