codex-plugin-doctor 1.76.0 → 1.77.0

package/README.md

@@ -172,6 +172,22 @@ Doctor tries `server/discover` (`2026-07-28`) first and falls back to the
 container by name.
 See [MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
 
+### MCP Prompt Catalog and Diff
+
+Record a server's prompt list and catch prompt changes that break clients:
+
+```bash
+codex-plugin-doctor doctor prompts https://mcp.example.com/mcp --allow-network --save-response ./mcp/prompts-baseline.json
+codex-plugin-doctor doctor prompts-diff --before ./mcp/prompts-baseline.json --after ./prompts-current.json --fail-on breaking
+```
+
+`doctor prompts` reads `prompts/list` from an HTTP server, or from a local stdio
+server with `--server <name> --runtime`, without retrieving any prompt.
+`doctor prompts-file` inspects a saved list offline, and `doctor prompts-diff`
+labels a removed prompt, a removed argument, or a newly required argument as
+breaking. Like the tool diff, reports omit names unless `--show-names` is given.
+See [MCP Prompt Catalog and Diff](docs/guides/mcp-prompts.md).
+
 ### Remote MCP Readiness
 
 Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
@@ -590,9 +606,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.76.0
+      - uses: Esquetta/CodexPluginDoctor@v1.77.0
         with:
-          version: "1.76.0"
+          version: "1.77.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-prompt-catalog.d.ts

@@ -0,0 +1,36 @@
+import type { RuntimeExecutionEvidence } from "../domain/types.js";
+import type { McpDiscoveryReport } from "./mcp-discovery.js";
+import { type PromptCatalogFinding } from "./mcp-prompt-definition.js";
+import { type McpStdioServer, type McpStdioToolCatalogOptions } from "./mcp-stdio-tool-catalog.js";
+import { type CatalogStatus, type EnumerationCoverage, type McpCatalogList, type McpToolCatalogCache, type McpToolCatalogOptions, type McpToolCatalogProtocol } from "./mcp-tool-catalog.js";
+export declare const MCP_PROMPTS_LIST: McpCatalogList<PromptCatalogFinding>;
+export interface McpPromptCatalogReport {
+    schemaVersion: 1;
+    scope: "prompt-catalog-structure";
+    transport?: "stdio";
+    status: CatalogStatus;
+    protocol?: McpToolCatalogProtocol;
+    execution?: RuntimeExecutionEvidence | null;
+    discovery: McpDiscoveryReport;
+    catalog: {
+        complete: boolean;
+        pagesRead: number;
+        promptsChecked: number;
+        reason: string | null;
+    };
+    coverage: {
+        discovery: "pass" | "fail" | "skipped";
+        catalogEnumeration: EnumerationCoverage;
+        definitions: "shape-only";
+        promptRetrieval: "not-tested";
+        fullConformance: "not-tested";
+    };
+    findings: PromptCatalogFinding[];
+}
+export interface McpPromptCatalogSnapshot {
+    report: McpPromptCatalogReport;
+    prompts: unknown[] | null;
+    cache: McpToolCatalogCache | null;
+}
+export declare function captureMcpPromptCatalog(rawUrl: string, options?: McpToolCatalogOptions): Promise<McpPromptCatalogSnapshot>;
+export declare function captureStdioMcpPromptCatalog(server: McpStdioServer, options?: McpStdioToolCatalogOptions): Promise<McpPromptCatalogSnapshot>;

package/dist/core/mcp-prompt-catalog.js

@@ -0,0 +1,53 @@
+import { createMcpPromptCatalogInspector } from "./mcp-prompt-definition.js";
+import { captureStdioMcpCatalog } from "./mcp-stdio-tool-catalog.js";
+import { captureMcpCatalog } from "./mcp-tool-catalog.js";
+export const MCP_PROMPTS_LIST = {
+    method: "prompts/list",
+    capability: "prompts",
+    noun: "prompt",
+    createInspector() {
+        const inspector = createMcpPromptCatalogInspector();
+        return {
+            findings: inspector.findings,
+            items: inspector.prompts,
+            get checked() {
+                return inspector.promptsChecked;
+            },
+            addFindings: inspector.addFindings,
+            inspectPage: inspector.inspectPage
+        };
+    }
+};
+function promptSnapshot(capture, stdio) {
+    const { complete, pagesRead, checked, reason } = capture.catalog;
+    return {
+        report: {
+            schemaVersion: 1,
+            scope: "prompt-catalog-structure",
+            ...(stdio === undefined ? {} : { transport: "stdio" }),
+            status: capture.status,
+            ...(stdio === undefined ? {} : { protocol: stdio.protocol, execution: stdio.execution }),
+            discovery: capture.discovery,
+            catalog: { complete, pagesRead, promptsChecked: checked, reason },
+            coverage: {
+                discovery: capture.discovery.coverage.discovery,
+                catalogEnumeration: capture.enumeration,
+                definitions: "shape-only",
+                promptRetrieval: "not-tested",
+                fullConformance: "not-tested"
+            },
+            findings: capture.findings
+        },
+        prompts: capture.items,
+        cache: capture.cache
+    };
+}
+// Prompts and cache metadata are returned only for a complete enumeration; prompts are never retrieved.
+export async function captureMcpPromptCatalog(rawUrl, options = {}) {
+    return promptSnapshot(await captureMcpCatalog(rawUrl, MCP_PROMPTS_LIST, options));
+}
+// Starts one configured stdio server, reads its prompt list without retrieving prompts, and stops it.
+export async function captureStdioMcpPromptCatalog(server, options = {}) {
+    const { capture, protocol, execution } = await captureStdioMcpCatalog(server, MCP_PROMPTS_LIST, options);
+    return promptSnapshot(capture, { protocol, execution });
+}

package/dist/core/mcp-prompt-definition.d.ts

@@ -0,0 +1,24 @@
+import type { Finding } from "../domain/types.js";
+export interface PromptCatalogLocation {
+    page: number;
+    promptIndex: number;
+    argumentIndex?: number;
+    relatedPromptIndex?: number;
+    relatedArgumentIndex?: number;
+}
+export interface PromptCatalogFinding extends Finding {
+    location?: PromptCatalogLocation;
+}
+export declare const MAX_PROMPTS = 500;
+export declare function inspectMcpPromptDefinition(value: unknown, location: {
+    page: number;
+    promptIndex: number;
+}): PromptCatalogFinding[];
+export interface McpPromptCatalogInspector {
+    readonly findings: PromptCatalogFinding[];
+    readonly prompts: unknown[];
+    readonly promptsChecked: number;
+    addFindings(items: PromptCatalogFinding[]): boolean;
+    inspectPage(pagePrompts: unknown[], page: number, timeExpired: () => boolean): "prompt-limit" | "finding-limit" | "total-time-limit" | null;
+}
+export declare function createMcpPromptCatalogInspector(): McpPromptCatalogInspector;

package/dist/core/mcp-prompt-definition.js

@@ -0,0 +1,107 @@
+export const MAX_PROMPTS = 500;
+const MAX_FINDINGS = 100;
+const DUPLICATE_PROMPT_NAME = "plugin.catalog.prompt.name.duplicate";
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finding(id, message, impact, suggestedFix, location) {
+    return { id, severity: id === DUPLICATE_PROMPT_NAME ? "warn" : "fail", message, impact, suggestedFix, location };
+}
+function inspectArguments(value, location, findings) {
+    if (!Array.isArray(value)) {
+        findings.push(finding("plugin.catalog.prompt.arguments.invalid", "A catalog prompt arguments field must be an array when provided.", "Clients cannot determine which arguments the prompt accepts.", "Provide arguments as an array of argument objects or omit the field.", location));
+        return;
+    }
+    const names = new Map();
+    value.forEach((argument, offset) => {
+        const argumentLocation = { ...location, argumentIndex: offset + 1 };
+        if (!isJsonObject(argument)) {
+            findings.push(finding("plugin.catalog.prompt.argument.invalid_object", "A catalog prompt argument must be an object.", "Clients cannot read an argument definition that is not an object.", "Return each prompt argument as an object.", argumentLocation));
+            return;
+        }
+        if (typeof argument.name !== "string" || argument.name === "") {
+            findings.push(finding("plugin.catalog.prompt.argument.name.invalid", "A catalog prompt argument name must be a non-empty string.", "Clients cannot supply an argument without a name.", "Provide a non-empty string name for the argument.", argumentLocation));
+        }
+        else {
+            const previous = names.get(argument.name);
+            if (previous === undefined) {
+                names.set(argument.name, offset + 1);
+            }
+            else {
+                findings.push(finding("plugin.catalog.prompt.argument.name.duplicate", "Two arguments of a catalog prompt use the same name.", "Clients cannot tell which definition applies to the argument they supply.", "Use a unique name for each prompt argument.", { ...argumentLocation, relatedArgumentIndex: previous }));
+            }
+        }
+        if (Object.hasOwn(argument, "required") && typeof argument.required !== "boolean") {
+            findings.push(finding("plugin.catalog.prompt.argument.required.invalid", "A catalog prompt argument required field must be a boolean when provided.", "Clients cannot tell whether the argument must be supplied.", "Set required to true or false, or omit it.", argumentLocation));
+        }
+        for (const field of ["title", "description"]) {
+            if (Object.hasOwn(argument, field) && typeof argument[field] !== "string") {
+                findings.push(finding(`plugin.catalog.prompt.argument.${field}.invalid`, `A catalog prompt argument ${field} must be a string when provided.`, `Clients cannot reliably display a non-string argument ${field}.`, `Provide a string ${field} or omit the field.`, argumentLocation));
+            }
+        }
+    });
+}
+export function inspectMcpPromptDefinition(value, location) {
+    const findings = [];
+    const baseLocation = { page: location.page, promptIndex: location.promptIndex };
+    if (!isJsonObject(value)) {
+        findings.push(finding("plugin.catalog.prompt.invalid_object", "A catalog prompt entry must be an object.", "The validator cannot inspect a prompt definition that is not an object.", "Return each prompts/list entry as an object.", baseLocation));
+        return findings;
+    }
+    if (typeof value.name !== "string" || value.name === "") {
+        findings.push(finding("plugin.catalog.prompt.name.invalid", "A catalog prompt name must be a non-empty string.", "Clients cannot identify or retrieve a prompt without a name.", "Provide a non-empty string name for the prompt.", baseLocation));
+    }
+    for (const field of ["title", "description"]) {
+        if (Object.hasOwn(value, field) && typeof value[field] !== "string") {
+            findings.push(finding(`plugin.catalog.prompt.${field}.invalid`, `A catalog prompt ${field} must be a string when provided.`, `Clients cannot reliably display a non-string prompt ${field}.`, `Provide a string ${field} or omit the field.`, baseLocation));
+        }
+    }
+    if (Object.hasOwn(value, "arguments"))
+        inspectArguments(value.arguments, baseLocation, findings);
+    return findings;
+}
+// Shared by saved-file inspection and the HTTP and stdio catalogs so all apply the same prompt, finding, and duplicate-name rules.
+export function createMcpPromptCatalogInspector() {
+    const findings = [];
+    const prompts = [];
+    const names = new Map();
+    let promptsChecked = 0;
+    const addFindings = (items) => {
+        if (findings.length + items.length > MAX_FINDINGS) {
+            findings.push(...items.slice(0, MAX_FINDINGS - findings.length));
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    return {
+        findings,
+        prompts,
+        get promptsChecked() {
+            return promptsChecked;
+        },
+        addFindings,
+        inspectPage(pagePrompts, page, timeExpired) {
+            for (const prompt of pagePrompts) {
+                if (promptsChecked >= MAX_PROMPTS)
+                    return "prompt-limit";
+                promptsChecked += 1;
+                prompts.push(prompt);
+                const location = { page, promptIndex: promptsChecked };
+                if (!addFindings(inspectMcpPromptDefinition(prompt, location)))
+                    return "finding-limit";
+                if (isJsonObject(prompt) && typeof prompt.name === "string" && prompt.name !== "") {
+                    const previous = names.get(prompt.name);
+                    if (previous !== undefined && !addFindings([finding(DUPLICATE_PROMPT_NAME, "Two enumerated prompts use the same name.", "Duplicate prompt names can make client selection ambiguous.", "Use a unique MCP prompt name for each definition.", { ...location, relatedPromptIndex: previous })])) {
+                        return "finding-limit";
+                    }
+                    if (previous === undefined)
+                        names.set(prompt.name, promptsChecked);
+                }
+                if (timeExpired())
+                    return "total-time-limit";
+            }
+            return null;
+        }
+    };
+}

package/dist/core/mcp-prompt-diff.d.ts

@@ -0,0 +1,43 @@
+import { type McpPromptFileReport } from "./mcp-prompt-file.js";
+import { type PromptChangeImpact, type PromptChangeLocation, type PromptChangeReason } from "./mcp-prompt-impact.js";
+type DiffField = "arguments" | "description" | "title" | "other";
+export interface McpPromptDiffReport {
+    schemaVersion: 1;
+    scope: "prompt-definitions-diff";
+    status: "pass" | "warn" | "incomplete" | "blocked";
+    before: McpPromptFileReport;
+    after: McpPromptFileReport;
+    comparison: {
+        complete: boolean;
+        reason: "input-blocked" | "input-incomplete" | "invalid-definitions" | "ambiguous-names" | null;
+        added: number | null;
+        removed: number | null;
+        changed: number | null;
+        unchanged: number | null;
+        breaking: number | null;
+        unclassified: number | null;
+    };
+    coverage: {
+        comparison: "structural-only";
+        definitions: "shape-only";
+        compatibility: "not-tested";
+        serverCatalog: "not-tested";
+        promptRetrieval: "not-tested";
+        impactClassification: "heuristic";
+    };
+    changes: Array<{
+        kind: "added" | "removed" | "changed";
+        beforePromptIndex: number | null;
+        afterPromptIndex: number | null;
+        fields: DiffField[];
+        impact: PromptChangeImpact;
+        reasons: PromptChangeReason[];
+        name?: string;
+        locations?: PromptChangeLocation[];
+    }>;
+}
+export interface McpPromptDiffOptions {
+    showNames?: boolean;
+}
+export declare function compareMcpPromptFiles(beforePath: string, afterPath: string, options?: McpPromptDiffOptions): Promise<McpPromptDiffReport>;
+export {};

package/dist/core/mcp-prompt-diff.js

@@ -0,0 +1,132 @@
+import { loadMcpPromptFileSnapshot } from "./mcp-prompt-file.js";
+import { classifyAddedPrompt, classifyChangedPrompt, classifyRemovedPrompt } from "./mcp-prompt-impact.js";
+import { structurallyEqual } from "./mcp-tool-diff.js";
+const FIXED_FIELDS = ["arguments", "description", "title"];
+const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
+const COVERAGE = {
+    comparison: "structural-only",
+    definitions: "shape-only",
+    compatibility: "not-tested",
+    serverCatalog: "not-tested",
+    promptRetrieval: "not-tested",
+    impactClassification: "heuristic"
+};
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function filteredOther(definition) {
+    const other = Object.create(null);
+    for (const key of Object.keys(definition)) {
+        if (!EXCLUDED_OTHER_FIELDS.has(key))
+            other[key] = definition[key];
+    }
+    return other;
+}
+function changedFields(before, after) {
+    const fields = [];
+    for (const field of FIXED_FIELDS) {
+        if (!structurallyEqual(before[field], after[field]))
+            fields.push(field);
+    }
+    if (!structurallyEqual(filteredOther(before), filteredOther(after)))
+        fields.push("other");
+    return fields;
+}
+function promptDefinitions(prompts) {
+    const definitions = new Map();
+    for (let offset = 0; offset < prompts.length; offset += 1) {
+        const value = prompts[offset];
+        if (!isJsonObject(value) || typeof value.name !== "string" || definitions.has(value.name))
+            return null;
+        definitions.set(value.name, { index: offset + 1, value });
+    }
+    return definitions;
+}
+function incompleteReport(before, after, status, reason) {
+    return {
+        schemaVersion: 1,
+        scope: "prompt-definitions-diff",
+        status,
+        before,
+        after,
+        comparison: { complete: false, reason, added: null, removed: null, changed: null, unchanged: null, breaking: null, unclassified: null },
+        coverage: { ...COVERAGE },
+        changes: []
+    };
+}
+export async function compareMcpPromptFiles(beforePath, afterPath, options = {}) {
+    const [beforeSnapshot, afterSnapshot] = await Promise.all([
+        loadMcpPromptFileSnapshot(beforePath),
+        loadMcpPromptFileSnapshot(afterPath)
+    ]);
+    const { report: before } = beforeSnapshot;
+    const { report: after } = afterSnapshot;
+    if (before.status === "blocked" || after.status === "blocked") {
+        return incompleteReport(before, after, "blocked", "input-blocked");
+    }
+    if (!before.inspection.complete || !after.inspection.complete) {
+        return incompleteReport(before, after, "incomplete", "input-incomplete");
+    }
+    if (before.status === "fail" || after.status === "fail" || beforeSnapshot.prompts === null || afterSnapshot.prompts === null) {
+        return incompleteReport(before, after, "incomplete", "invalid-definitions");
+    }
+    const beforeDefinitions = promptDefinitions(beforeSnapshot.prompts);
+    const afterDefinitions = promptDefinitions(afterSnapshot.prompts);
+    if (beforeDefinitions === null || afterDefinitions === null) {
+        return incompleteReport(before, after, "incomplete", "ambiguous-names");
+    }
+    const named = (name) => (options.showNames === true ? { name } : {});
+    const changes = [];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    let unchanged = 0;
+    for (const [name, beforeDefinition] of beforeDefinitions) {
+        const afterDefinition = afterDefinitions.get(name);
+        if (afterDefinition === undefined) {
+            removed += 1;
+            changes.push({ kind: "removed", ...named(name), beforePromptIndex: beforeDefinition.index, afterPromptIndex: null, fields: [], ...classifyRemovedPrompt() });
+            continue;
+        }
+        const fields = changedFields(beforeDefinition.value, afterDefinition.value);
+        if (fields.length === 0) {
+            unchanged += 1;
+        }
+        else {
+            changed += 1;
+            changes.push({
+                kind: "changed",
+                ...named(name),
+                beforePromptIndex: beforeDefinition.index,
+                afterPromptIndex: afterDefinition.index,
+                fields,
+                ...classifyChangedPrompt(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual, { locate: options.showNames === true })
+            });
+        }
+    }
+    for (const [name, afterDefinition] of afterDefinitions) {
+        if (!beforeDefinitions.has(name)) {
+            added += 1;
+            changes.push({ kind: "added", ...named(name), beforePromptIndex: null, afterPromptIndex: afterDefinition.index, fields: [], ...classifyAddedPrompt() });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope: "prompt-definitions-diff",
+        status: changes.length === 0 && before.status === "pass" && after.status === "pass" ? "pass" : "warn",
+        before,
+        after,
+        comparison: {
+            complete: true,
+            reason: null,
+            added,
+            removed,
+            changed,
+            unchanged,
+            breaking: changes.filter((change) => change.impact === "breaking").length,
+            unclassified: changes.filter((change) => change.impact === "unclassified").length
+        },
+        coverage: { ...COVERAGE },
+        changes
+    };
+}

package/dist/core/mcp-prompt-file.d.ts

@@ -0,0 +1,31 @@
+import { type PromptCatalogFinding } from "./mcp-prompt-definition.js";
+export interface McpPromptFileReport {
+    schemaVersion: 1;
+    scope: "prompt-definitions-file";
+    status: "pass" | "warn" | "fail" | "incomplete" | "blocked";
+    source: {
+        kind: "file";
+        format: "mcp-prompts-list-response";
+        bytesRead: number;
+    };
+    inspection: {
+        complete: boolean;
+        promptsChecked: number;
+        hasNextCursor: boolean | null;
+        reason: string | null;
+    };
+    coverage: {
+        definitions: "shape-only";
+        discovery: "not-tested";
+        serverCatalog: "not-tested";
+        promptRetrieval: "not-tested";
+        fullConformance: "not-tested";
+    };
+    findings: PromptCatalogFinding[];
+}
+export interface McpPromptFileSnapshot {
+    report: McpPromptFileReport;
+    prompts: unknown[] | null;
+}
+export declare function loadMcpPromptFileSnapshot(filePath: string): Promise<McpPromptFileSnapshot>;
+export declare function inspectMcpPromptFile(filePath: string): Promise<McpPromptFileReport>;

package/dist/core/mcp-prompt-file.js

@@ -0,0 +1,118 @@
+import { createMcpPromptCatalogInspector } from "./mcp-prompt-definition.js";
+import { isBlockedOfflinePath, readBoundedRegularFile } from "./mcp-tool-file.js";
+function snapshot(report, prompts = null) {
+    return { report, prompts };
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function report(bytesRead, status, inspection, findings) {
+    return {
+        schemaVersion: 1,
+        scope: "prompt-definitions-file",
+        status,
+        source: { kind: "file", format: "mcp-prompts-list-response", bytesRead },
+        inspection,
+        coverage: {
+            definitions: "shape-only",
+            discovery: "not-tested",
+            serverCatalog: "not-tested",
+            promptRetrieval: "not-tested",
+            fullConformance: "not-tested"
+        },
+        findings
+    };
+}
+function fileFinding(id, message, impact, suggestedFix) {
+    return { id, severity: "fail", message, impact, suggestedFix };
+}
+function incompleteFileReport(bytesRead, reason, finding) {
+    return report(bytesRead, "incomplete", { complete: false, promptsChecked: 0, hasNextCursor: null, reason }, [finding]);
+}
+function blockedFileReport(reason, finding) {
+    return report(0, "blocked", { complete: false, promptsChecked: 0, hasNextCursor: null, reason }, [finding]);
+}
+function finalStatus(findings) {
+    if (findings.some((finding) => finding.severity === "fail"))
+        return "fail";
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function parsePromptsResult(value) {
+    if (!isJsonObject(value)
+        || value.jsonrpc !== "2.0"
+        || !Object.hasOwn(value, "id")
+        || !(typeof value.id === "string" || (typeof value.id === "number" && Number.isFinite(value.id)))
+        || !Object.hasOwn(value, "result")
+        || Object.hasOwn(value, "error")
+        || !isJsonObject(value.result)
+        || value.result.resultType !== "complete"
+        || !Array.isArray(value.result.prompts)
+        || typeof value.result.ttlMs !== "number"
+        || !Number.isFinite(value.result.ttlMs)
+        || value.result.ttlMs < 0
+        || (value.result.cacheScope !== "public" && value.result.cacheScope !== "private")) {
+        return null;
+    }
+    const hasNextCursor = Object.hasOwn(value.result, "nextCursor");
+    if (hasNextCursor && typeof value.result.nextCursor !== "string")
+        return null;
+    return { prompts: value.result.prompts, hasNextCursor };
+}
+export async function loadMcpPromptFileSnapshot(filePath) {
+    if (isBlockedOfflinePath(filePath)) {
+        return snapshot(blockedFileReport("offline-path-blocked", fileFinding("plugin.prompts_file.path.blocked", "The local prompt definition path is not permitted for offline inspection.", "The offline prompt definition inspection does not access remote or device paths.", "Provide a local regular file path.")));
+    }
+    const file = await readBoundedRegularFile(filePath);
+    if (file.kind === "unavailable") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.prompts_file.file.unavailable", "The local prompt definition file could not be read.", "The offline prompt definition inspection could not start.", "Provide a readable local regular file.")));
+    }
+    if (file.kind === "too-large") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.prompts_file.file.too_large", "The local prompt definition file exceeds the one MiB inspection limit.", "The offline prompt definition inspection cannot safely read this file within its byte limit.", "Provide a prompt definition file no larger than one MiB.")));
+    }
+    if (file.kind === "changed") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.prompts_file.file.changed", "The local prompt definition file changed during inspection.", "The offline prompt definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable.")));
+    }
+    if (file.kind === "symlink") {
+        return snapshot(blockedFileReport("final-symlink", fileFinding("plugin.prompts_file.file.symlink", "The local prompt definition target is a symbolic link.", "The offline prompt definition inspection does not follow final symbolic links.", "Provide a regular file directly.")));
+    }
+    if (file.kind === "not-regular") {
+        return snapshot(blockedFileReport("non-regular-file", fileFinding("plugin.prompts_file.file.not_regular", "The local prompt definition target is not a regular file.", "The offline prompt definition inspection reads only bounded regular files.", "Provide a regular file directly.")));
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(file.content);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.prompts_file.encoding.invalid", "The local prompt definition file is not valid UTF-8.", "The offline prompt definition inspection cannot parse the file safely.", "Save the prompts/list response as UTF-8 JSON.")));
+    }
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.prompts_file.json.invalid", "The local prompt definition file is not valid JSON.", "The offline prompt definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC prompts/list response.")));
+    }
+    const parsed = parsePromptsResult(value);
+    if (parsed === null) {
+        return snapshot(incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.prompts_file.response.invalid", "The local JSON value is not a supported complete prompts/list response.", "The offline prompt definition inspection cannot identify a valid prompt list.", "Provide one JSON-RPC 2.0 complete prompts/list result with valid cache metadata.")));
+    }
+    const inspector = createMcpPromptCatalogInspector();
+    const reason = inspector.inspectPage(parsed.prompts, 1, () => false) ?? (parsed.hasNextCursor ? "more-pages-present" : null);
+    if (reason !== null) {
+        return snapshot(report(file.bytesRead, "incomplete", {
+            complete: false,
+            promptsChecked: inspector.promptsChecked,
+            hasNextCursor: parsed.hasNextCursor,
+            reason
+        }, inspector.findings), parsed.prompts);
+    }
+    return snapshot(report(file.bytesRead, finalStatus(inspector.findings), {
+        complete: true,
+        promptsChecked: inspector.promptsChecked,
+        hasNextCursor: false,
+        reason: null
+    }, inspector.findings), parsed.prompts);
+}
+export async function inspectMcpPromptFile(filePath) {
+    return (await loadMcpPromptFileSnapshot(filePath)).report;
+}

package/dist/core/mcp-prompt-impact.d.ts

@@ -0,0 +1,21 @@
+type JsonObject = Record<string, unknown>;
+type Equal = (left: unknown, right: unknown) => boolean;
+export type PromptChangeImpact = "breaking" | "compatible" | "unclassified";
+export declare const PROMPT_CHANGE_REASONS: readonly ["prompt-removed", "prompt-argument-removed", "prompt-required-argument-added", "prompt-argument-now-required", "prompt-argument-fields-unclassified", "other-fields-unclassified"];
+export type PromptChangeReason = (typeof PROMPT_CHANGE_REASONS)[number];
+export interface PromptChangeLocation {
+    reason: PromptChangeReason;
+    argument: string | null;
+}
+export interface PromptChangeClassification {
+    impact: PromptChangeImpact;
+    reasons: PromptChangeReason[];
+    locations?: PromptChangeLocation[];
+}
+export declare const MAX_PROMPT_CHANGE_LOCATIONS = 100;
+export declare function classifyRemovedPrompt(): PromptChangeClassification;
+export declare function classifyAddedPrompt(): PromptChangeClassification;
+export declare function classifyChangedPrompt(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal, options?: {
+    locate?: boolean;
+}): PromptChangeClassification;
+export {};