codex-plugin-doctor 0.16.0 → 0.17.0

package/README.md

@@ -75,8 +75,9 @@ Output formats:
 - Markdown reports
 - Shields-compatible badge JSON and static badge Markdown
 - validation history JSONL and trend summaries
+- deterministic local attestation artifacts
 - `--output` file writing
-- CI summary and artifact generation
+- CI summary and artifact generation
 
 ## Quick Start
 
@@ -178,6 +179,8 @@ codex-plugin-doctor self-test
 codex-plugin-doctor doctor
 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 .
+codex-plugin-doctor doctor attest . --json --output attestation.json
 codex-plugin-doctor doctor inspector .
 codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
 codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
@@ -256,7 +259,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 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 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/attestation.d.ts

@@ -0,0 +1,62 @@
+export interface PackageFingerprint {
+    algorithm: "sha256";
+    digest: string;
+    files: {
+        total: number;
+        bytes: number;
+    };
+}
+export interface Digest {
+    algorithm: "sha256";
+    digest: string;
+}
+export interface DoctorAttestation {
+    schemaVersion: "1.0.0";
+    kind: "doctor.attestation";
+    generatedAt: string;
+    version: string;
+    targetPath: string;
+    subject: {
+        name: string;
+        version: string | null;
+        description: string | null;
+    };
+    packageFingerprint: PackageFingerprint;
+    reportDigest: Digest;
+    summary: {
+        status: "pass" | "warn" | "fail";
+        validation: {
+            status: "pass" | "warn" | "fail";
+            findingCount: number;
+        };
+        security: {
+            status: "pass" | "warn" | "fail";
+            score: number;
+            findingCount: number;
+        };
+        compatibility: {
+            failedClients: string[];
+        };
+        trust: {
+            status: "pass" | "warn" | "fail";
+            score: number;
+            findingCount: number;
+        };
+        recommendations: {
+            actionCount: number;
+        };
+    };
+    verification: {
+        recomputeCommand: string;
+        notes: string[];
+    };
+    signature: {
+        status: "unsigned";
+        reason: string;
+    };
+}
+export declare function buildDoctorAttestation(targetPath: string): Promise<DoctorAttestation>;
+export declare function renderDoctorAttestationJson(attestation: DoctorAttestation): string;
+export declare function renderDoctorAttestation(attestation: DoctorAttestation, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/attestation.js

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+import { discoverPackage } from "./discover-package.js";
+import { readJsonFile } from "./read-json-file.js";
+import { matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { packageVersion } from "../version.js";
+const excludedDirectoryNames = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".cache",
+    ".turbo",
+    ".codex-doctor",
+    "node_modules",
+    "coverage"
+]);
+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);
+}
+async function collectFileEntries(rootPath, currentPath = rootPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    const fileEntries = await Promise.all(entries.map(async (entry) => {
+        if (entry.isDirectory() && excludedDirectoryNames.has(entry.name)) {
+            return [];
+        }
+        const entryPath = path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            return collectFileEntries(rootPath, entryPath);
+        }
+        if (!entry.isFile()) {
+            return [];
+        }
+        const [details, content] = await Promise.all([
+            stat(entryPath),
+            readFile(entryPath)
+        ]);
+        return [
+            {
+                relativePath: path.relative(rootPath, entryPath).split(path.sep).join("/"),
+                size: details.size,
+                digest: sha256(content)
+            }
+        ];
+    }));
+    return fileEntries.flat().sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+async function buildPackageFingerprint(rootPath) {
+    const files = await collectFileEntries(rootPath);
+    const bytes = files.reduce((total, file) => total + file.size, 0);
+    const digest = sha256(stableStringify(files));
+    return {
+        algorithm: "sha256",
+        digest,
+        files: {
+            total: files.length,
+            bytes
+        }
+    };
+}
+async function readPackageSubject(rootPath) {
+    try {
+        const packageJson = await readJsonFile(path.join(rootPath, "package.json"));
+        return isPlainObject(packageJson) ? packageJson : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildSubject(analysis, packageJson, manifest) {
+    const name = typeof manifest?.name === "string"
+        ? manifest.name
+        : typeof packageJson?.name === "string"
+            ? packageJson.name
+            : path.basename(analysis.targetPath);
+    const version = typeof manifest?.version === "string"
+        ? manifest.version
+        : typeof packageJson?.version === "string"
+            ? packageJson.version
+            : null;
+    const description = typeof manifest?.description === "string"
+        ? manifest.description
+        : typeof packageJson?.description === "string"
+            ? packageJson.description
+            : null;
+    return {
+        name,
+        version,
+        description
+    };
+}
+async function readManifestSubject(rootPath) {
+    const discoveredPackage = await discoverPackage(rootPath);
+    if (!discoveredPackage) {
+        return null;
+    }
+    return {
+        name: discoveredPackage.manifest.name,
+        version: discoveredPackage.manifest.version,
+        description: discoveredPackage.manifest.description
+    };
+}
+function buildReportDigestPayload(analysis, packageFingerprint) {
+    return {
+        version: packageVersion,
+        packageFingerprint,
+        validation: {
+            status: analysis.validation.status,
+            findings: analysis.validation.findings
+        },
+        security: {
+            status: analysis.security.status,
+            score: analysis.security.score,
+            findings: analysis.security.findings
+        },
+        compatibility: analysis.compatibility.results.map((result) => ({
+            client: result.client,
+            status: result.status,
+            summary: result.summary
+        })),
+        trust: {
+            status: analysis.trust.status,
+            score: analysis.trust.score,
+            findings: analysis.trust.findings
+        },
+        recommendations: buildDoctorRecommendationsFromAnalysis(analysis).actions
+    };
+}
+function buildSummary(analysis) {
+    const recommendations = buildDoctorRecommendationsFromAnalysis(analysis);
+    const failedClients = analysis.compatibility.results
+        .filter((result) => result.status === "fail")
+        .map((result) => result.client);
+    const status = analysis.validation.status === "fail" ||
+        analysis.security.status === "fail" ||
+        analysis.trust.status === "fail" ||
+        matrixExitCode(analysis.compatibility) === 1
+        ? "fail"
+        : analysis.validation.status === "warn" ||
+            analysis.security.status === "warn" ||
+            analysis.trust.status === "warn"
+            ? "warn"
+            : "pass";
+    return {
+        status,
+        validation: {
+            status: analysis.validation.status,
+            findingCount: analysis.validation.findings.length
+        },
+        security: {
+            status: analysis.security.status,
+            score: analysis.security.score,
+            findingCount: analysis.security.findings.length
+        },
+        compatibility: {
+            failedClients
+        },
+        trust: {
+            status: analysis.trust.status,
+            score: analysis.trust.score,
+            findingCount: analysis.trust.findings.length
+        },
+        recommendations: {
+            actionCount: recommendations.actions.length
+        }
+    };
+}
+export async function buildDoctorAttestation(targetPath) {
+    const analysis = await buildPackageAnalysis(targetPath);
+    const [packageFingerprint, packageJson, manifest] = await Promise.all([
+        buildPackageFingerprint(analysis.targetPath),
+        readPackageSubject(analysis.targetPath),
+        readManifestSubject(analysis.targetPath)
+    ]);
+    const reportDigest = sha256(stableStringify(buildReportDigestPayload(analysis, packageFingerprint)));
+    return {
+        schemaVersion: "1.0.0",
+        kind: "doctor.attestation",
+        generatedAt: analysis.generatedAt,
+        version: packageVersion,
+        targetPath: analysis.targetPath,
+        subject: buildSubject(analysis, packageJson, manifest),
+        packageFingerprint,
+        reportDigest: {
+            algorithm: "sha256",
+            digest: reportDigest
+        },
+        summary: buildSummary(analysis),
+        verification: {
+            recomputeCommand: `codex-plugin-doctor doctor attest ${analysis.targetPath} --json`,
+            notes: [
+                "Compare packageFingerprint.digest to confirm the same local package contents.",
+                "Compare reportDigest.digest to confirm the same validation, security, compatibility, trust, and recommendation signals."
+            ]
+        },
+        signature: {
+            status: "unsigned",
+            reason: "v0.17 creates deterministic local attestations without key management or hosted signing."
+        }
+    };
+}
+export function renderDoctorAttestationJson(attestation) {
+    return JSON.stringify(attestation, null, 2);
+}
+export function renderDoctorAttestation(attestation, options = {}) {
+    const lines = [
+        "Doctor Attestation",
+        "==================",
+        `Target: ${attestation.targetPath}`,
+        `Subject: ${attestation.subject.name}${attestation.subject.version ? `@${attestation.subject.version}` : ""}`,
+        `Status: ${attestation.summary.status.toUpperCase()}`,
+        `Package fingerprint: ${attestation.packageFingerprint.digest}`,
+        `Report digest: ${attestation.reportDigest.digest}`,
+        `Signature: ${attestation.signature.status}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Verification", "------------");
+    lines.push(attestation.verification.recomputeCommand);
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrus
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson, type DoctorSnapshot } from "./core/doctor-snapshot.js";
 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 { 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

@@ -4,6 +4,7 @@ export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./secur
 export { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
 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 { 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

@@ -16,6 +16,7 @@ import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 import { buildDoctorSnapshot, renderDoctorSnapshot, renderDoctorSnapshotJson } from "./core/doctor-snapshot.js";
 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 { 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";
@@ -65,7 +66,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>|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>|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 = [
@@ -230,6 +231,30 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(renderedReport);
             return report.exitCode;
         }
+        if (maybePath === "attest") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs[0]
+                : ".";
+            const attestFlags = remainingArgs[0] && !remainingArgs[0].startsWith("--")
+                ? remainingArgs.slice(1)
+                : remainingArgs;
+            const jsonOutput = attestFlags.includes("--json");
+            const outputIndex = attestFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : attestFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const attestation = await buildDoctorAttestation(targetPath);
+            const attestationJson = renderDoctorAttestationJson(attestation);
+            if (outputPath) {
+                await writeFile(outputPath, attestationJson, "utf8");
+            }
+            io.writeStdout(jsonOutput
+                ? attestationJson
+                : renderDoctorAttestation(attestation, { outputPath }));
+            return attestation.summary.status === "fail" ? 1 : 0;
+        }
         if (maybePath === "npm") {
             const packageSpec = remainingArgs[0] && !remainingArgs[0].startsWith("--")
                 ? remainingArgs[0]

package/package.json

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