codex-plugin-doctor 0.17.0 → 0.18.0

package/README.md

@@ -76,6 +76,7 @@ Output formats:
 - Shields-compatible badge JSON and static badge Markdown
 - validation history JSONL and trend summaries
 - deterministic local attestation artifacts
+- output contract and rule catalog freeze metadata
 - `--output` file writing
 - CI summary and artifact generation
 
@@ -177,6 +178,8 @@ Run these from a Codex plugin package root:
 codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+codex-plugin-doctor doctor contract
+codex-plugin-doctor doctor contract --json --output output-contract.json
 codex-plugin-doctor doctor npm codex-plugin-doctor
 codex-plugin-doctor doctor npm codex-plugin-doctor --json --output npm-preinstall.json
 codex-plugin-doctor doctor attest .
@@ -259,7 +262,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a deterministic local attestation with a package fingerprint, report digest, validation/security/compatibility/trust summary, and unsigned verification metadata. Add `--json` for automation or `--output attestation.json` to write the artifact to disk. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a deterministic local attestation with a package fingerprint, report digest, validation/security/compatibility/trust summary, and unsigned verification metadata. Add `--json` for automation or `--output attestation.json` to write the artifact to disk. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
 `audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 

package/dist/core/output-contract.d.ts

@@ -0,0 +1,40 @@
+import { type RuleCategory, type RuleSeverity } from "../rules/rule-catalog.js";
+type JsonSchema = Record<string, unknown>;
+export interface OutputContractRule {
+    id: string;
+    category: RuleCategory;
+    defaultSeverity: RuleSeverity;
+}
+export interface OutputContractSchema {
+    id: string;
+    command: string;
+    schemaVersion: "1.0.0";
+    stability: "stable-through-1.0";
+    outputKind: string | null;
+    schema: JsonSchema;
+}
+export interface DoctorOutputContract {
+    schemaVersion: "1.0.0";
+    kind: "doctor.output.contract";
+    generatedAt: string;
+    version: string;
+    contract: {
+        frozenSince: "0.18.0";
+        stability: "stable-through-1.0";
+        compatibility: string;
+    };
+    ruleCatalog: {
+        status: "frozen";
+        frozenSince: "0.18.0";
+        ruleCount: number;
+        digest: string;
+        rules: OutputContractRule[];
+    };
+    schemas: OutputContractSchema[];
+}
+export declare function buildDoctorOutputContract(generatedAt?: string): DoctorOutputContract;
+export declare function renderDoctorOutputContractJson(contract: DoctorOutputContract): string;
+export declare function renderDoctorOutputContract(contract: DoctorOutputContract, options?: {
+    outputPath?: string | null;
+}): string;
+export {};

package/dist/core/output-contract.js

@@ -0,0 +1,202 @@
+import { createHash } from "node:crypto";
+import { packageVersion } from "../version.js";
+import { ruleCatalog } from "../rules/rule-catalog.js";
+const publicSchemaDefinitions = [
+    {
+        id: "doctor.check.json",
+        command: "codex-plugin-doctor check <path> --json",
+        required: ["schemaVersion", "generatedAt", "summary", "findings"]
+    },
+    {
+        id: "doctor.security.json",
+        command: "codex-plugin-doctor security <path> --json",
+        required: ["schemaVersion", "generatedAt", "targetPath", "status", "score", "findings"]
+    },
+    {
+        id: "doctor.compatibility.json",
+        command: "codex-plugin-doctor compat <path> --json",
+        required: ["schemaVersion", "targetPath", "results"]
+    },
+    {
+        id: "doctor.mcp.json",
+        command: "codex-plugin-doctor mcp <path> --json",
+        required: ["schemaVersion", "targetPath", "status", "summary", "findings"]
+    },
+    {
+        id: "doctor.audit.json",
+        command: "codex-plugin-doctor audit --installed --json",
+        required: ["schemaVersion", "generatedAt", "summary", "items"]
+    },
+    {
+        id: "doctor.fix.plan.json",
+        command: "codex-plugin-doctor fix <path> --dry-run --json",
+        required: ["schemaVersion", "targetPath", "mode", "actions"]
+    },
+    {
+        id: "doctor.history.json",
+        command: "codex-plugin-doctor history <history.jsonl> --json",
+        required: ["schemaVersion", "entryCount", "latest", "previous", "delta", "regression"]
+    },
+    {
+        id: "doctor.environment.json",
+        command: "codex-plugin-doctor doctor --json",
+        required: ["schemaVersion", "generatedAt", "version", "platform", "node", "checks"]
+    },
+    {
+        id: "doctor.recommendations.json",
+        command: "codex-plugin-doctor doctor recommend <path> --json",
+        required: ["schemaVersion", "generatedAt", "targetPath", "status", "summary", "actions"]
+    },
+    {
+        id: "doctor.trust.json",
+        command: "codex-plugin-doctor doctor trust <path> --json",
+        required: ["schemaVersion", "generatedAt", "targetPath", "status", "score", "findings"]
+    },
+    {
+        id: "doctor.performance.json",
+        command: "codex-plugin-doctor doctor perf <path> --json",
+        outputKind: "doctor.perf",
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "summary", "stages"]
+    },
+    {
+        id: "doctor.export.bundle.json",
+        command: "codex-plugin-doctor doctor export --bundle <path> --json",
+        outputKind: "doctor.export.bundle",
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "validation", "security", "compatibility", "recommendations", "trust"]
+    },
+    {
+        id: "doctor.attestation.json",
+        command: "codex-plugin-doctor doctor attest <path> --json",
+        outputKind: "doctor.attestation",
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "subject", "packageFingerprint", "reportDigest", "summary", "verification", "signature"]
+    },
+    {
+        id: "doctor.npm.json",
+        command: "codex-plugin-doctor doctor npm <package> --json",
+        outputKind: "doctor.npm",
+        required: ["schemaVersion", "kind", "generatedAt", "package", "summary", "validation", "security", "trust", "recommendations"]
+    },
+    {
+        id: "doctor.risk.diff.json",
+        command: "codex-plugin-doctor doctor diff --before <path> --after <path> --json",
+        outputKind: "doctor.risk.diff",
+        required: ["schemaVersion", "kind", "generatedAt", "before", "after", "summary", "risk"]
+    },
+    {
+        id: "doctor.inspector.json",
+        command: "codex-plugin-doctor doctor inspector <path> --json",
+        outputKind: "doctor.inspector",
+        required: ["schemaVersion", "kind", "generatedAt", "targetPath", "status"]
+    },
+    {
+        id: "doctor.snapshot.json",
+        command: "codex-plugin-doctor doctor snapshot --json",
+        required: ["schemaVersion", "generatedAt", "version", "environment", "clients", "installedPlugins", "nextCommands"]
+    }
+];
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    if (isPlainObject(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function contractRules(rules) {
+    return rules
+        .map((rule) => ({
+        id: rule.id,
+        category: rule.category,
+        defaultSeverity: rule.defaultSeverity
+    }))
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+function buildSchema(id, outputKind, required) {
+    const properties = {
+        schemaVersion: {
+            const: "1.0.0"
+        }
+    };
+    if (outputKind) {
+        properties.kind = {
+            const: outputKind
+        };
+    }
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $id: `https://github.com/Esquetta/CodexPluginDoctor/schemas/${id}`,
+        title: id,
+        type: "object",
+        required: [...new Set(["schemaVersion", ...required])],
+        properties,
+        additionalProperties: true
+    };
+}
+function buildSchemas() {
+    return publicSchemaDefinitions.map((definition) => {
+        const outputKind = definition.outputKind ?? null;
+        return {
+            id: definition.id,
+            command: definition.command,
+            schemaVersion: "1.0.0",
+            stability: "stable-through-1.0",
+            outputKind,
+            schema: buildSchema(definition.id, outputKind, definition.required ?? [])
+        };
+    });
+}
+export function buildDoctorOutputContract(generatedAt = new Date().toISOString()) {
+    const rules = contractRules(ruleCatalog);
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.output.contract",
+        generatedAt,
+        version: packageVersion,
+        contract: {
+            frozenSince: "0.18.0",
+            stability: "stable-through-1.0",
+            compatibility: "Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0.0; breaking changes require a schemaVersion or major version change."
+        },
+        ruleCatalog: {
+            status: "frozen",
+            frozenSince: "0.18.0",
+            ruleCount: rules.length,
+            digest: sha256(stableStringify(rules)),
+            rules
+        },
+        schemas: buildSchemas()
+    };
+}
+export function renderDoctorOutputContractJson(contract) {
+    return JSON.stringify(contract, null, 2);
+}
+export function renderDoctorOutputContract(contract, options = {}) {
+    const lines = [
+        "Doctor Output Contract",
+        "======================",
+        `Version: ${contract.version}`,
+        `Contract: ${contract.contract.stability} (since ${contract.contract.frozenSince})`,
+        `Rule catalog: ${contract.ruleCatalog.status}`,
+        `Rule digest: ${contract.ruleCatalog.digest}`,
+        `Rules: ${contract.ruleCatalog.ruleCount}`,
+        `Schemas: ${contract.schemas.length}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Schema surfaces", "---------------");
+    for (const schema of contract.schemas) {
+        lines.push(`- ${schema.id}: ${schema.command}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, ty
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson, type DoctorRecommendationAction, type DoctorRecommendationsReport } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson, type DoctorExportBundle } from "./core/doctor-export-bundle.js";
 export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, type DoctorAttestation, type Digest, type PackageFingerprint } from "./core/attestation.js";
+export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson, type DoctorOutputContract, type OutputContractRule, type OutputContractSchema } from "./core/output-contract.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson, type BuildDoctorNpmPackageReportOptions, type DoctorNpmPackageReport } from "./core/npm-package-doctor.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } f
 export { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 export { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson } from "./core/attestation.js";
+export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 export { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";

package/dist/run-cli.js

@@ -17,6 +17,7 @@ import { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } f
 import { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRecommendationsJson } from "./core/doctor-recommendations.js";
 import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson } from "./core/attestation.js";
+import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
 import { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";
 import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
@@ -66,7 +67,7 @@ const defaultIo = {
     }
 };
 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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|attest <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|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 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] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--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 fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|attest <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path>|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 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");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -231,6 +232,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "contract") {
+            const jsonOutput = remainingArgs.includes("--json");
+            const outputIndex = remainingArgs.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : remainingArgs[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const contract = buildDoctorOutputContract();
+            const contractJson = renderDoctorOutputContractJson(contract);
+            if (outputPath) {
+                await writeFile(outputPath, contractJson, "utf8");
+            }
+            io.writeStdout(jsonOutput
+                ? contractJson
+                : renderDoctorOutputContract(contract, { outputPath }));
+            return 0;
+        }
         if (maybePath === "attest") {
             const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
                 ? remainingArgs[0]

package/package.json

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