codex-plugin-doctor 1.72.1 → 1.74.0

package/README.md

@@ -149,7 +149,11 @@ live list with `tools-capture-url` (and `tools-capture-token-env`) or, for a loc
 stdio server with `runtime: "true"`, `tools-capture-server`, and skip the
 plugin package check with `check: "false"` in repositories that only ship an MCP
 server. With `tools-diff-comment: "true"` it also posts the comparison as one
-pull request comment that later runs update.
+pull request comment that later runs update. `tools-capture-sandbox: docker`
+starts a stdio server in the Docker sandbox, and
+`codex-plugin-doctor init-ci . --tools-diff-server <name> --sandbox docker`
+writes a pull request workflow that captures in one job and compares and
+comments in another.
 
 Local stdio servers from a package's MCP configuration can be cataloged too.
 `--runtime` is required because this starts package code; the server is stopped
@@ -585,9 +589,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.72.1
+      - uses: Esquetta/CodexPluginDoctor@v1.74.0
         with:
-          version: "1.72.1"
+          version: "1.74.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/init-ci.d.ts

@@ -2,4 +2,10 @@ export interface InitCiResult {
     rootPath: string;
     workflowPath: string;
 }
+export interface ToolsDiffWorkflowOptions {
+    server: string;
+    baseline: string;
+    sandbox: "docker" | null;
+}
+export declare function initToolsDiffWorkflow(targetPath: string, options: ToolsDiffWorkflowOptions): Promise<InitCiResult>;
 export declare function initCiWorkflow(targetPath: string): Promise<InitCiResult>;

package/dist/core/init-ci.js

@@ -31,6 +31,80 @@ function buildWorkflow() {
         ""
     ].join("\n");
 }
+// JSON strings are valid YAML double-quoted scalars, so names and paths cannot break the document.
+const yamlString = (value) => JSON.stringify(value);
+/**
+ * A pull request workflow in two jobs: the first starts the stdio server and uploads its tool list,
+ * and the second compares it with the committed baseline and comments. Only the second job may write
+ * to pull requests, and it runs no package code.
+ */
+function buildToolsDiffWorkflow(options) {
+    return [
+        "name: MCP tool diff",
+        "",
+        "on:",
+        "  pull_request:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "",
+        "jobs:",
+        "  capture:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - uses: actions/checkout@v5",
+        "        with:",
+        "          persist-credentials: false",
+        "      # Add install or build steps here if the server needs them; the Docker sandbox has no network.",
+        `      - uses: Esquetta/CodexPluginDoctor@v${packageVersion}`,
+        "        with:",
+        `          version: \"${packageVersion}\"`,
+        "          path: .",
+        "          check: \"false\"",
+        "          runtime: \"true\"",
+        `          tools-capture-server: ${yamlString(options.server)}`,
+        ...(options.sandbox === "docker" ? ["          tools-capture-sandbox: docker"] : []),
+        "          # Catalog findings do not fail this job; the compare job re-checks the saved list.",
+        "          tools-capture-defer-findings: \"true\"",
+        "          artifact-name: mcp-tools-capture",
+        "",
+        "  compare:",
+        "    needs: capture",
+        "    runs-on: ubuntu-latest",
+        "    permissions:",
+        "      contents: read",
+        "      pull-requests: write",
+        "    steps:",
+        "      - uses: actions/checkout@v5",
+        "        with:",
+        "          persist-credentials: false",
+        "      # Outside the checkout, so files from the pull request cannot shadow the downloaded list.",
+        "      - uses: actions/download-artifact@v5",
+        "        with:",
+        "          name: mcp-tools-capture",
+        "          path: ${{ runner.temp }}/mcp-tools-capture",
+        `      - uses: Esquetta/CodexPluginDoctor@v${packageVersion}`,
+        "        with:",
+        `          version: \"${packageVersion}\"`,
+        "          check: \"false\"",
+        `          tools-diff-before: ${yamlString(options.baseline)}`,
+        "          tools-diff-after: ${{ runner.temp }}/mcp-tools-capture/mcp-tools-current.json",
+        "          tools-diff-fail-on: breaking",
+        "          tools-diff-comment: \"true\"",
+        "          output-dir: ${{ runner.temp }}/codex-plugin-doctor-reports",
+        "          artifact-name: mcp-tools-diff",
+        ""
+    ].join("\n");
+}
+export async function initToolsDiffWorkflow(targetPath, options) {
+    const rootPath = path.resolve(targetPath);
+    const workflowPath = path.join(rootPath, ".github", "workflows", "codex-plugin-doctor-tools.yml");
+    await mkdir(path.dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, buildToolsDiffWorkflow(options), "utf8");
+    // doctor tools --save-response writes into an existing directory, so the baseline can be captured next.
+    await mkdir(path.dirname(path.resolve(rootPath, options.baseline)), { recursive: true });
+    return { rootPath, workflowPath };
+}
 export async function initCiWorkflow(targetPath) {
     const rootPath = path.resolve(targetPath);
     const workflowPath = path.join(rootPath, ".github", "workflows", "codex-plugin-doctor.yml");

package/dist/core/mcp-tool-impact.js

@@ -27,13 +27,15 @@ const UNCLASSIFIED_REASONS = new Set([
 // Keywords that document a schema without constraining accepted or produced values.
 const DOCUMENTATION_KEYWORDS = new Set(["title", "description", "examples", "default", "deprecated", "$comment"]);
 const ROOT_STRUCTURAL_KEYWORDS = new Set(["type", "properties", "required", "additionalProperties", "$schema"]);
-const LOWER_BOUND_KEYWORDS = ["minimum", "minLength", "minItems"];
-const UPPER_BOUND_KEYWORDS = ["maximum", "maxLength", "maxItems"];
+const LOWER_BOUND_KEYWORDS = ["minLength", "minItems"];
+const UPPER_BOUND_KEYWORDS = ["maxLength", "maxItems"];
+// Numeric bounds, compared as one effective bound per side because the exclusive form may replace the inclusive one.
+const NUMERIC_BOUND_KEYWORDS = ["minimum", "exclusiveMinimum", "maximum", "exclusiveMaximum"];
 // String keywords that can only be introduced or removed with a known effect; a changed value is unclassified.
 const STRING_CONSTRAINT_KEYWORDS = ["pattern", "format"];
 const NESTED_STRUCTURAL_KEYWORDS = new Set([
-    "type", "enum", "const", "properties", "required", "additionalProperties", "items",
-    ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS, ...STRING_CONSTRAINT_KEYWORDS
+    "type", "enum", "const", "properties", "required", "additionalProperties", "items", "multipleOf", "uniqueItems",
+    ...LOWER_BOUND_KEYWORDS, ...UPPER_BOUND_KEYWORDS, ...NUMERIC_BOUND_KEYWORDS, ...STRING_CONSTRAINT_KEYWORDS
 ]);
 // When every reference is a same-document fragment, definition containers are compared only
 // where a resolved `$ref` reaches into them; otherwise they are compared as written.
@@ -45,11 +47,16 @@ const NESTED_STRUCTURAL_WITH_DEFINITIONS = new Set([...NESTED_STRUCTURAL_KEYWORD
 const DATA_KEYWORDS = new Set(["enum", "const", "examples", "example", "default"]);
 // Keywords whose values map names to subschemas; their keys are names, never keywords.
 const NAME_MAP_KEYWORDS = new Set(["properties", "patternProperties", "$defs", "definitions", "dependentSchemas", "dependencies"]);
-// Subschemas nested deeper than this below the root are not compared and stay unclassified.
+// Subschemas nested deeper than this below the root are not compared and stay unclassified; composition
+// wrappers keep the depth of the schema they wrap and are bounded by MAX_WRAPPER_HOPS instead.
 const MAX_NESTED_DEPTH = 8;
 // Keywords that only hold or name subschemas and never validate the object's own keys, so a
 // new property beside them stays compatible. Any other unclassified keyword may govern keys.
 const DEFINITION_KEYWORDS = new Set(["$defs", "definitions", "$id", "$anchor", "$dynamicAnchor"]);
+// `anyOf` alternatives beyond this many on either side are not paired.
+const MAX_ALTERNATIVES = 32;
+// Composition wrappers (`allOf` and `anyOf`) followed along one path; deeper wrappers are unclassified.
+const MAX_WRAPPER_HOPS = 16;
 // A `$ref` chain longer than this, such as an alias cycle, is not resolved.
 const MAX_REFERENCE_HOPS = 8;
 // Schema comparisons allowed per tool field; a schema that needs more is unclassified.
@@ -168,6 +175,176 @@ function compareBounds(inner, outer, codes, reasons) {
         }
     }
 }
+/**
+ * The tighter of a schema's inclusive and exclusive bound on one side, undefined when it has neither,
+ * or null when either is not a finite number (such as a draft-04 boolean `exclusiveMinimum`).
+ */
+function numericBound(schema, inclusive, exclusive, lower) {
+    if (typeof schema[exclusive] === "boolean") {
+        // Draft-04 marks the inclusive keyword itself as exclusive; a boolean alone is invalid in every draft.
+        const value = schema[inclusive];
+        return isFiniteNumber(value) ? { value, exclusive: schema[exclusive] } : null;
+    }
+    const candidates = [];
+    for (const [keyword, isExclusive] of [[inclusive, false], [exclusive, true]]) {
+        const value = schema[keyword];
+        if (value === undefined)
+            continue;
+        if (!isFiniteNumber(value))
+            return null;
+        candidates.push({ value, exclusive: isExclusive });
+    }
+    return candidates.reduce((tightest, candidate) => {
+        if (tightest === undefined)
+            return candidate;
+        if (candidate.value === tightest.value)
+            return candidate.exclusive ? candidate : tightest;
+        return (lower ? candidate.value > tightest.value : candidate.value < tightest.value) ? candidate : tightest;
+    }, undefined);
+}
+/** Flags numeric bounds, `multipleOf`, and `uniqueItems` of `outer` that `inner` does not satisfy. */
+function compareNumericAndArrayConstraints(inner, outer, codes, reasons) {
+    for (const [inclusive, exclusive, lower] of [["minimum", "exclusiveMinimum", true], ["maximum", "exclusiveMaximum", false]]) {
+        const innerBound = numericBound(inner, inclusive, exclusive, lower);
+        const outerBound = numericBound(outer, inclusive, exclusive, lower);
+        if (innerBound === null || outerBound === null) {
+            // A bound that cannot be read still means the same when it did not change.
+            const unchanged = Object.is(inner[inclusive], outer[inclusive]) && Object.is(inner[exclusive], outer[exclusive]);
+            if (!unchanged)
+                reasons.add(codes.unclassified);
+        }
+        else if (outerBound !== undefined) {
+            const covered = innerBound !== undefined && (innerBound.value === outerBound.value
+                ? innerBound.exclusive || !outerBound.exclusive
+                : lower ? innerBound.value > outerBound.value : innerBound.value < outerBound.value);
+            if (!covered)
+                reasons.add(codes.constraint);
+        }
+    }
+    const outerMultiple = outer.multipleOf;
+    const innerMultiple = inner.multipleOf;
+    const validMultiple = (value) => value === undefined || (isFiniteNumber(value) && value > 0);
+    if (!validMultiple(outerMultiple) || !validMultiple(innerMultiple)) {
+        if (!Object.is(innerMultiple, outerMultiple))
+            reasons.add(codes.unclassified);
+    }
+    else if (outerMultiple !== undefined) {
+        if (innerMultiple === undefined) {
+            reasons.add(codes.constraint);
+        }
+        else if (Number.isInteger(innerMultiple) && Number.isInteger(outerMultiple)) {
+            // Every multiple of innerMultiple is a multiple of outerMultiple when outerMultiple divides it.
+            if (innerMultiple % outerMultiple !== 0)
+                reasons.add(codes.constraint);
+        }
+        else if (innerMultiple !== outerMultiple) {
+            // Validators test fractional multiples with floating-point division, which can reject 0.3
+            // under multipleOf 0.1, so a changed fractional multipleOf cannot be judged.
+            reasons.add(codes.unclassified);
+        }
+    }
+    if ((outer.uniqueItems !== undefined && typeof outer.uniqueItems !== "boolean")
+        || (inner.uniqueItems !== undefined && typeof inner.uniqueItems !== "boolean")) {
+        if (!Object.is(inner.uniqueItems, outer.uniqueItems))
+            reasons.add(codes.unclassified);
+    }
+    else if (outer.uniqueItems === true && inner.uniqueItems !== true) {
+        reasons.add(codes.constraint);
+    }
+}
+/** The subschema of a schema that is only a one-element `allOf` with documentation, or null. */
+function singleAllOf(schema) {
+    if (!isJsonObject(schema) || !Array.isArray(schema.allOf) || schema.allOf.length !== 1)
+        return null;
+    return Object.keys(schema).every((key) => key === "allOf" || DOCUMENTATION_KEYWORDS.has(key)) ? { inner: schema.allOf[0] } : null;
+}
+/** The alternatives of a schema that is only `anyOf` with documentation, or null. */
+function alternatives(schema) {
+    if (!isJsonObject(schema) || !Array.isArray(schema.anyOf))
+        return null;
+    return Object.keys(schema).every((key) => key === "anyOf" || DOCUMENTATION_KEYWORDS.has(key)) ? schema.anyOf : null;
+}
+function isComposition(schema) {
+    return singleAllOf(schema) !== null || alternatives(schema) !== null;
+}
+/**
+ * Compares two schemas when at least one is a one-element `allOf` or an `anyOf` with only
+ * documentation beside it. Wrappers keep the depth, so their own count bounds how far one path unwraps.
+ */
+function compareComposition(before, after, direction, depth, equal, reasons, scope) {
+    if (scope.wrappers >= MAX_WRAPPER_HOPS) {
+        reasons.add(CODES[direction].unclassified);
+        return;
+    }
+    const wrappedBefore = singleAllOf(before);
+    const wrappedAfter = singleAllOf(after);
+    scope.wrappers += 1;
+    if (wrappedBefore !== null || wrappedAfter !== null) {
+        // A one-element allOf with only documentation beside it means the same as its subschema.
+        compareSchema(wrappedBefore === null ? before : wrappedBefore.inner, wrappedAfter === null ? after : wrappedAfter.inner, direction, depth, equal, reasons, scope);
+    }
+    else {
+        // A schema that is not an anyOf compares as an anyOf with that schema as its only alternative.
+        compareAlternatives(alternatives(before) ?? [before], alternatives(after) ?? [after], direction, depth, equal, reasons, scope);
+    }
+    scope.wrappers -= 1;
+}
+/** The reference target or declared type that pairs an alternative with its counterpart. */
+function alternativeKey(alternative) {
+    if (!isJsonObject(alternative))
+        return null;
+    if (typeof alternative.$ref === "string")
+        return `ref:${alternative.$ref}`;
+    return alternative.type === undefined ? null : `type:${JSON.stringify(alternative.type)}`;
+}
+/**
+ * Compares `anyOf` alternatives. A value is accepted when any alternative accepts it, so inputs stay
+ * compatible when every earlier alternative is covered by a later one, and outputs when every later
+ * alternative is covered by an earlier one. Identical alternatives match first, then alternatives with
+ * the same reference target or type, then a single remaining alternative on each side.
+ */
+function compareAlternatives(before, after, direction, depth, equal, reasons, scope) {
+    const codes = CODES[direction];
+    if (before.length > MAX_ALTERNATIVES || after.length > MAX_ALTERNATIVES) {
+        reasons.add(codes.unclassified);
+        return;
+    }
+    const unpairedBefore = [...before];
+    const unpairedAfter = [...after];
+    for (let index = unpairedBefore.length - 1; index >= 0; index -= 1) {
+        const match = unpairedAfter.findIndex((candidate) => sameMeaning(unpairedBefore[index], candidate, equal, scope));
+        if (match !== -1) {
+            unpairedBefore.splice(index, 1);
+            unpairedAfter.splice(match, 1);
+        }
+    }
+    const pairs = [];
+    for (const key of new Set(unpairedBefore.map(alternativeKey))) {
+        if (key === null)
+            continue;
+        const beforeMatches = unpairedBefore.filter((alternative) => alternativeKey(alternative) === key);
+        const afterMatches = unpairedAfter.filter((alternative) => alternativeKey(alternative) === key);
+        if (beforeMatches.length !== 1 || afterMatches.length !== 1)
+            continue;
+        pairs.push([beforeMatches[0], afterMatches[0]]);
+        unpairedBefore.splice(unpairedBefore.indexOf(beforeMatches[0]), 1);
+        unpairedAfter.splice(unpairedAfter.indexOf(afterMatches[0]), 1);
+    }
+    if (unpairedBefore.length === 1 && unpairedAfter.length === 1) {
+        pairs.push([unpairedBefore.pop(), unpairedAfter.pop()]);
+    }
+    else if (unpairedBefore.length > 0 && unpairedAfter.length > 0) {
+        reasons.add(codes.unclassified);
+    }
+    for (const [beforeAlternative, afterAlternative] of pairs) {
+        compareSchema(beforeAlternative, afterAlternative, direction, depth, equal, reasons, scope);
+    }
+    // A dropped input alternative may reject values callers send; an added output alternative may
+    // produce values consumers do not expect. The opposite changes only narrow or widen safely.
+    const narrowedOrWidened = direction === "input" ? unpairedAfter.length === 0 && unpairedBefore.length > 0 : unpairedBefore.length === 0 && unpairedAfter.length > 0;
+    if (narrowedOrWidened)
+        reasons.add(depth === 0 ? codes.rootType : codes.propertyType);
+}
 /** Flags a `pattern` or `format` that `outer` adds and `inner` lacks; a changed value cannot be compared. */
 function compareStringConstraints(inner, outer, codes, reasons) {
     for (const keyword of STRING_CONSTRAINT_KEYWORDS) {
@@ -291,22 +468,32 @@ function referenceScope(before, after) {
         fragmentsOnly: reachesDefinitionsOnlyThroughFragments(before) && reachesDefinitionsOnlyThroughFragments(after),
         active: new Set(),
         completed: new Map(),
+        inProgress: new Map(),
+        wrappers: 0,
         same: new Map(),
         pointers: new Map(),
         remaining: MAX_COMPARISONS
     };
 }
-/** Records a resolved pair as compared at this depth; returns false when it already was. */
-function markCompleted(scope, before, after, depth) {
-    let byAfter = scope.completed.get(before);
+function pairDepths(pairs, before, after) {
+    let byAfter = pairs.get(before);
     if (byAfter === undefined)
-        scope.completed.set(before, byAfter = new Map());
+        pairs.set(before, byAfter = new Map());
     let depths = byAfter.get(after);
     if (depths === undefined)
         byAfter.set(after, depths = new Set());
-    if (depths.has(depth))
+    return depths;
+}
+/**
+ * Records a resolved pair as compared at this depth and wrapper count; returns false when it already
+ * was. The wrapper count is part of the key because it limits how far that comparison may unwrap.
+ */
+function markCompleted(scope, before, after, depth) {
+    const depths = pairDepths(scope.completed, before, after);
+    const key = depth * (MAX_WRAPPER_HOPS + 1) + scope.wrappers;
+    if (depths.has(key))
         return false;
-    depths.add(depth);
+    depths.add(key);
     return true;
 }
 /**
@@ -401,10 +588,26 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
         return;
     const resolvedBefore = resolveReferences(before, scope.before);
     const resolvedAfter = resolveReferences(after, scope.after);
-    if (resolvedBefore === null || resolvedAfter === null) {
+    if (resolvedBefore === null || resolvedAfter === null || depth > MAX_NESTED_DEPTH) {
         reasons.add(codes.unclassified);
         return;
     }
+    // When only one side is a composition, the other keeps its reference unresolved, so it can still
+    // pair with an alternative that refers to the same definition, as when a model becomes optional.
+    const beforeComposed = isComposition(resolvedBefore.schema);
+    const afterComposed = isComposition(resolvedAfter.schema);
+    if (beforeComposed !== afterComposed) {
+        // The reference is kept only when an alternative can pair with it; otherwise its target compares
+        // with inline alternatives by type.
+        const composite = beforeComposed ? resolvedBefore.schema : resolvedAfter.schema;
+        const original = beforeComposed ? after : before;
+        const plainKey = alternativeKey(original);
+        const keepReference = (alternatives(composite) ?? [])
+            .some((alternative) => (plainKey !== null && alternativeKey(alternative) === plainKey) || sameMeaning(original, alternative, equal, scope));
+        const plain = keepReference ? original : (beforeComposed ? resolvedAfter.schema : resolvedBefore.schema);
+        compareComposition(beforeComposed ? composite : plain, beforeComposed ? plain : composite, direction, depth, equal, reasons, scope);
+        return;
+    }
     if (resolvedBefore.ref !== undefined || resolvedAfter.ref !== undefined) {
         // A reference pair already being compared further up is assumed to hold, so recursive
         // definitions terminate; a pair with one inline side is bounded by the depth limit. A pair
@@ -412,22 +615,35 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
         const pair = resolvedBefore.ref !== undefined && resolvedAfter.ref !== undefined
             ? JSON.stringify([resolvedBefore.ref, resolvedAfter.ref])
             : undefined;
+        // Reaching a pair again at the same depth, for example through a definition that wraps a
+        // reference to itself, is a cycle that never reaches a value, so it cannot be judged.
+        const inProgress = pairDepths(scope.inProgress, resolvedBefore.schema, resolvedAfter.schema);
+        if (inProgress.has(depth)) {
+            reasons.add(codes.unclassified);
+            return;
+        }
         if (pair !== undefined && scope.active.has(pair))
             return;
         if (!markCompleted(scope, resolvedBefore.schema, resolvedAfter.schema, depth))
             return;
         if (pair !== undefined)
             scope.active.add(pair);
+        inProgress.add(depth);
         compareSchema(resolvedBefore.schema, resolvedAfter.schema, direction, depth, equal, reasons, scope);
+        inProgress.delete(depth);
         if (pair !== undefined)
             scope.active.delete(pair);
         return;
     }
+    if (beforeComposed) {
+        compareComposition(before, after, direction, depth, equal, reasons, scope);
+        return;
+    }
     const root = depth === 0;
     const structural = scope.fragmentsOnly
         ? root ? ROOT_STRUCTURAL_WITH_DEFINITIONS : NESTED_STRUCTURAL_WITH_DEFINITIONS
         : root ? ROOT_STRUCTURAL_KEYWORDS : NESTED_STRUCTURAL_KEYWORDS;
-    if (depth > MAX_NESTED_DEPTH || !isJsonObject(before) || !isJsonObject(after)
+    if (!isJsonObject(before) || !isJsonObject(after)
         || !sameMeaning(keywordsOutside(before, structural), keywordsOutside(after, structural), equal, scope)
         || !equal(before.$schema, after.$schema)) {
         reasons.add(codes.unclassified);
@@ -446,6 +662,7 @@ function compareSchema(before, after, direction, depth, equal, reasons, scope) {
         else if (!enumResult)
             reasons.add(codes.enumChanged);
         compareBounds(inner, outer, codes, reasons);
+        compareNumericAndArrayConstraints(inner, outer, codes, reasons);
         compareStringConstraints(inner, outer, codes, reasons);
         if (!sameMeaning(before.items, after.items, equal, scope)) {
             if (unevaluated)

package/dist/run-cli.js

@@ -49,7 +49,7 @@ import { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorIn
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
 import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { buildDoctorSize, renderDoctorSize, renderDoctorSizeJson } from "./core/doctor-size.js";
-import { initCiWorkflow } from "./core/init-ci.js";
+import { initCiWorkflow, initToolsDiffWorkflow } from "./core/init-ci.js";
 import { watchPlugin } from "./core/watch-plugin.js";
 import { buildDepAudit, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
 import { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";
@@ -117,6 +117,40 @@ const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-networ
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json] [--bearer-token-env <NAME>]";
 const bearerTokenHelp = "--bearer-token-env reads a bearer token from the named environment variable and sends it only over HTTPS or to an approved loopback target; the token is never printed or saved.";
 const ENVIRONMENT_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/** Reads init-ci --tools-diff-server, --baseline, and --sandbox; options is null when none is given. */
+function parseToolsDiffWorkflowOptions(flags) {
+    const values = new Map();
+    for (let index = 0; index < flags.length; index += 1) {
+        if (!["--tools-diff-server", "--baseline", "--sandbox"].includes(flags[index]))
+            continue;
+        const value = flags[index + 1];
+        const present = value !== undefined && !value.startsWith("--");
+        values.set(flags[index], present ? value : undefined);
+        if (present)
+            index += 1;
+    }
+    if (values.size === 0)
+        return { options: null };
+    if (!values.has("--tools-diff-server"))
+        return { error: "--baseline and --sandbox require --tools-diff-server." };
+    // Control characters would break the generated workflow lines, GitHub evaluates "${{" in any
+    // workflow value, and the Action rejects values that start with "-".
+    const usable = (value) => value !== undefined && value.trim() !== "" && !value.startsWith("-") && !value.includes("${{")
+        && !/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value);
+    const server = values.get("--tools-diff-server");
+    if (!usable(server))
+        return { error: "--tools-diff-server requires a server name." };
+    // The workflow runs on Linux from the repository root, so the baseline is a relative POSIX path.
+    const baseline = (values.has("--baseline") ? values.get("--baseline") : "mcp/tools-baseline.json")?.replaceAll("\\", "/");
+    if (!usable(baseline) || path.posix.isAbsolute(baseline) || /^[A-Za-z]:/u.test(baseline)
+        || path.posix.normalize(baseline).split("/").includes("..")) {
+        return { error: "--baseline requires a relative path inside the repository." };
+    }
+    const sandbox = values.get("--sandbox");
+    if (values.has("--sandbox") && sandbox !== "docker")
+        return { error: "--sandbox must be docker." };
+    return { options: { server, baseline, sandbox: sandbox === "docker" ? "docker" : null } };
+}
 const MAX_FORWARDED_ENVIRONMENT_VARIABLES = 32;
 const forwardedEnvironmentHelp = "--env forwards the named host environment variable into the Docker sandbox by name; Doctor never prints its value, writes it to a report, or passes it as a command argument. Native servers already inherit Doctor's environment.";
 function resolveBearerToken(name, env) {
@@ -340,7 +374,7 @@ function parseRemoteNetworkFlags(flags, runtime) {
     return { allowNetwork, allowLocalNetwork, allowSessionLifecycle, requireRemoteReliability };
 }
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path] [--tools-diff-server <name> [--baseline <path>] [--sandbox docker]]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr(discoveryUsage);
     io.writeStderr(toolsUsage);
     io.writeStderr(toolsFileUsage);
@@ -1308,9 +1342,10 @@ export async function runCli(args, io = defaultIo, options = {}) {
         (command === "doctor" &&
             (["runtime-plan", "runtime-policy"].includes(maybePath ?? "") ||
                 (maybePath === "release-evidence" && remainingArgs[0] !== "verify") ||
-                (maybePath === "tools" && remainingArgs.includes("--server"))));
+                (maybePath === "tools" && remainingArgs.includes("--server")))) ||
+        (command === "init-ci" && args.includes("--tools-diff-server"));
     if (args.includes("--sandbox") && !runtimeSandboxSupported) {
-        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, and doctor tools --server.");
+        io.writeStderr("--sandbox is supported only by single-package check, release check, runtime-plan, runtime-policy, release-evidence, doctor tools --server, and init-ci --tools-diff-server.");
         return 2;
     }
     if (command === "--version" || command === "-v" || command === "version") {
@@ -2771,6 +2806,23 @@ export async function runCli(args, io = defaultIo, options = {}) {
     }
     if (command === "init-ci") {
         const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const initFlags = maybePath && maybePath.startsWith("--") ? [maybePath, ...remainingArgs] : remainingArgs;
+        const toolsDiff = parseToolsDiffWorkflowOptions(initFlags);
+        if ("error" in toolsDiff) {
+            io.writeStderr(toolsDiff.error);
+            return 2;
+        }
+        if (toolsDiff.options !== null) {
+            const { server, baseline, sandbox } = toolsDiff.options;
+            const toolsResult = await initToolsDiffWorkflow(targetPath, toolsDiff.options);
+            io.writeStdout([
+                "Initialized Codex Plugin Doctor tool diff workflow",
+                `Root: ${toolsResult.rootPath}`,
+                `Workflow: ${toolsResult.workflowPath}`,
+                `Capture and commit a baseline at ${baseline}, for example with: codex-plugin-doctor doctor tools ${JSON.stringify(targetPath)} --server ${JSON.stringify(server)} --runtime${sandbox === "docker" ? " --sandbox docker" : ""} --save-response ${JSON.stringify(path.join(targetPath, baseline))}`
+            ].join("\n"));
+            return 0;
+        }
         const result = await initCiWorkflow(targetPath);
         io.writeStdout([
             "Initialized Codex Plugin Doctor workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.72.1",
+  "version": "1.74.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",