codex-plugin-doctor 1.54.0 → 1.56.0

package/README.md

@@ -108,6 +108,32 @@ codex-plugin-doctor registry inspect io.github.example/weather --allow-network
 
 Local checks validate metadata, ownership consistency, package integrity, transports, and Codex installability. Exact Registry lookup is read-only, requires explicit network consent, and contacts only the fixed official Registry endpoint. It never follows advertised package, icon, repository, or remote MCP URLs. See [MCP Registry Readiness](./docs/architecture/mcp-registry-readiness.md).
 
+### MCP Registry Publication Preflight
+
+Check a publication candidate locally without making a network request:
+
+```bash
+codex-plugin-doctor registry preflight path/to/server.json --json
+```
+
+Opt in to bounded public npm and MCP Registry metadata checks:
+
+```bash
+codex-plugin-doctor registry preflight path/to/server.json --allow-network --json
+```
+
+Require a publish-ready result in CI:
+
+```bash
+codex-plugin-doctor registry preflight path/to/server.json --allow-network --require-publish-ready --json
+```
+
+Preflight checks the exact npm package version, then the exact Registry version
+and latest Registry record on fixed public hosts. An existing exact Registry
+version is an immutable collision and must be replaced by a version bump. The
+command is advisory: it never authenticates, publishes, or changes npm or
+Registry records. See [MCP Registry Publication Preflight](./docs/architecture/mcp-registry-publication-preflight.md).
+
 Output formats:
 
 - human text output
@@ -454,9 +480,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.54.0
+      - uses: Esquetta/CodexPluginDoctor@v1.56.0
         with:
-          version: "1.54.0"
+          version: "1.56.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/doctor-size.d.ts

@@ -0,0 +1,16 @@
+export interface DoctorSizeReport {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    totalSize: number;
+    totalSizeHuman: string;
+    fileCount: number;
+    largeFiles: Array<{
+        path: string;
+        size: number;
+        sizeHuman: string;
+    }>;
+    warnings: string[];
+}
+export declare function buildDoctorSize(targetPath: string): Promise<DoctorSizeReport>;
+export declare function renderDoctorSize(report: DoctorSizeReport): string;
+export declare function renderDoctorSizeJson(report: DoctorSizeReport): string;

package/dist/core/doctor-size.js

@@ -0,0 +1,139 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+const skippedDirs = new Set([
+    "node_modules",
+    ".git",
+    ".cache",
+    "dist",
+    "coverage",
+    "__pycache__",
+    ".turbo",
+    ".next",
+    ".nuxt"
+]);
+const largeFileThreshold = 1024 * 1024;
+const packageSizeWarnThreshold = 10 * 1024 * 1024;
+const packageSizeFailThreshold = 50 * 1024 * 1024;
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GB`;
+}
+async function scanDirectory(rootPath, currentPath = rootPath) {
+    let totalSize = 0;
+    let fileCount = 0;
+    const largeFiles = [];
+    let entries;
+    try {
+        entries = await readdir(currentPath, { withFileTypes: true });
+    }
+    catch {
+        return { totalSize: 0, fileCount: 0, largeFiles: [] };
+    }
+    for (const entry of entries) {
+        const entryPath = path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirs.has(entry.name)) {
+                continue;
+            }
+            const subResult = await scanDirectory(rootPath, entryPath);
+            totalSize += subResult.totalSize;
+            fileCount += subResult.fileCount;
+            largeFiles.push(...subResult.largeFiles);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        let details;
+        try {
+            details = await stat(entryPath);
+        }
+        catch {
+            continue;
+        }
+        totalSize += details.size;
+        fileCount += 1;
+        if (details.size >= largeFileThreshold) {
+            largeFiles.push({
+                path: path.relative(rootPath, entryPath).replace(/\\/g, "/"),
+                size: details.size,
+                sizeHuman: formatSize(details.size)
+            });
+        }
+    }
+    return { totalSize, fileCount, largeFiles };
+}
+export async function buildDoctorSize(targetPath) {
+    const resolvedPath = path.resolve(targetPath);
+    const { totalSize, fileCount, largeFiles } = await scanDirectory(resolvedPath);
+    const warnings = [];
+    let status = "pass";
+    if (totalSize >= packageSizeFailThreshold) {
+        status = "fail";
+        warnings.push(`Package size (${formatSize(totalSize)}) exceeds ${formatSize(packageSizeFailThreshold)}.`);
+    }
+    else if (totalSize >= packageSizeWarnThreshold) {
+        status = "warn";
+        warnings.push(`Package size (${formatSize(totalSize)}) exceeds ${formatSize(packageSizeWarnThreshold)}.`);
+    }
+    if (largeFiles.length > 0) {
+        if (status === "pass")
+            status = "warn";
+        warnings.push(`${largeFiles.length} file(s) exceed ${formatSize(largeFileThreshold)}.`);
+    }
+    largeFiles.sort((a, b) => b.size - a.size);
+    return {
+        targetPath: resolvedPath,
+        status,
+        totalSize,
+        totalSizeHuman: formatSize(totalSize),
+        fileCount,
+        largeFiles: largeFiles.slice(0, 10),
+        warnings
+    };
+}
+export function renderDoctorSize(report) {
+    const lines = [
+        "Codex Plugin Doctor Size Analysis",
+        "=================================",
+        `Path: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Total size: ${report.totalSizeHuman} (${report.fileCount} files)`,
+        ""
+    ];
+    if (report.warnings.length > 0) {
+        lines.push("Warnings", "--------");
+        for (const warning of report.warnings) {
+            lines.push(`  - ${warning}`);
+        }
+        lines.push("");
+    }
+    if (report.largeFiles.length > 0) {
+        lines.push("Large Files", "-----------");
+        for (const file of report.largeFiles) {
+            lines.push(`  ${file.sizeHuman.padEnd(8)}  ${file.path}`);
+        }
+        lines.push("");
+    }
+    if (report.status === "pass") {
+        lines.push("Package size within acceptable limits.");
+    }
+    return lines.join("\n");
+}
+export function renderDoctorSizeJson(report) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        targetPath: report.targetPath,
+        status: report.status,
+        totalSize: report.totalSize,
+        totalSizeHuman: report.totalSizeHuman,
+        fileCount: report.fileCount,
+        largeFiles: report.largeFiles,
+        warnings: report.warnings
+    }, null, 2);
+}

package/dist/core/mcp-registry-preflight.d.ts

@@ -0,0 +1,38 @@
+import { type BoundedHttpRequestOptions, type BoundedHttpResponse } from "./bounded-http-client.js";
+export type McpRegistryPublicationPreflightStatus = "pass" | "warn" | "fail";
+type RegistryRequest = (url: string, options?: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+export interface McpRegistryPublicationPreflightFinding {
+    id: string;
+    severity: "warn" | "fail";
+    message: string;
+}
+export interface McpRegistryPublicationPreflightReport {
+    schemaVersion: "1.0.0";
+    kind: "mcp-registry-publication-preflight";
+    generatedAt: string;
+    target: "server.json";
+    serverName?: string;
+    serverVersion?: string;
+    status: McpRegistryPublicationPreflightStatus;
+    localReadiness: McpRegistryPublicationPreflightStatus;
+    packagePublication: "pass" | "fail" | "skipped" | "unknown";
+    registryVersionAvailability: "available-first-publication" | "available-new-version" | "already-published" | "unknown";
+    publisherPlan: {
+        executable: false;
+        steps: Array<{
+            order: number;
+            command: "mcp-publisher login github" | "mcp-publisher publish";
+            purpose: string;
+        }>;
+    };
+    findings: McpRegistryPublicationPreflightFinding[];
+}
+export interface BuildMcpRegistryPublicationPreflightOptions {
+    allowNetwork?: boolean;
+    request?: RegistryRequest;
+}
+export declare function buildMcpRegistryPublicationPreflight(targetPath: string, options?: BuildMcpRegistryPublicationPreflightOptions): Promise<McpRegistryPublicationPreflightReport>;
+export declare function renderMcpRegistryPublicationPreflightJson(report: McpRegistryPublicationPreflightReport): string;
+export declare function renderMcpRegistryPublicationPreflight(report: McpRegistryPublicationPreflightReport): string;
+export declare function registryPublicationPreflightExitCode(report: McpRegistryPublicationPreflightReport, requirePublishReady?: boolean): 0 | 1;
+export {};

package/dist/core/mcp-registry-preflight.js

@@ -0,0 +1,358 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { buildMcpRegistryReadiness } from "./mcp-registry.js";
+import { requestBoundedHttp } from "./bounded-http-client.js";
+const SERVER_NAME_PATTERN = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+const VERSION_RANGE_PATTERN = /^(?:latest|[~^]|[<>]=?)|(?:\s+\|\|\s+)|(?:^|[.\s])[x*](?:$|[.\s])/i;
+const OFFICIAL_SCHEMA_PATTERN = /^https:\/\/static\.modelcontextprotocol\.io\/schemas\/\d{4}-\d{2}-\d{2}\/server\.schema\.json$/;
+const NPM_IDENTIFIER_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]{0,213}\/)?[a-z0-9][a-z0-9._-]{0,213}$/;
+const INTEGRITY_PATTERN = /^(sha256|sha384|sha512)-([A-Za-z0-9+/]*={0,2})$/;
+const SHA256_PATTERN = /^[a-f0-9]{64}$/;
+const NPM_REGISTRY = "https://registry.npmjs.org";
+const MCP_REGISTRY = "https://registry.modelcontextprotocol.io";
+const REQUEST_OPTIONS = {
+    method: "GET",
+    headers: {
+        accept: "application/json",
+        "user-agent": "codex-plugin-doctor"
+    }
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function publicFinding(finding) {
+    return {
+        id: finding.id,
+        severity: finding.severity,
+        message: finding.message
+    };
+}
+function statusFromFindings(findings) {
+    if (findings.some((finding) => finding.severity === "fail")) {
+        return "fail";
+    }
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function isSafeServerName(value) {
+    return value !== undefined && value.length >= 3 && value.length <= 200 && SERVER_NAME_PATTERN.test(value);
+}
+function isSafeServerVersion(value) {
+    return value !== undefined && value.length >= 1 && value.length <= 255
+        && !/[\\/\u0000-\u001F\u007F]/.test(value) && !VERSION_RANGE_PATTERN.test(value);
+}
+function isSafeNpmIdentifier(value) {
+    return typeof value === "string" && NPM_IDENTIFIER_PATTERN.test(value);
+}
+function isIntegrity(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const match = INTEGRITY_PATTERN.exec(value);
+    if (!match || match[2].length % 4 !== 0) {
+        return false;
+    }
+    const digest = Buffer.from(match[2], "base64");
+    const expectedBytes = match[1] === "sha256" ? 32 : match[1] === "sha384" ? 48 : 64;
+    return digest.length === expectedBytes && digest.toString("base64") === match[2];
+}
+function responseJson(response) {
+    try {
+        return JSON.parse(response.body.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function validNotFound(response) {
+    const payload = responseJson(response);
+    if (response.statusCode !== 404 || !isRecord(payload)) {
+        return false;
+    }
+    return (typeof payload.error === "string" && payload.error.trim().length > 0)
+        || (payload.title === "Not Found"
+            && payload.status === 404
+            && typeof payload.detail === "string"
+            && payload.detail.trim().length > 0);
+}
+function hasValidHttpUrl(value) {
+    if (typeof value !== "string" || value.length === 0 || /\s/.test(value)) {
+        return false;
+    }
+    try {
+        const url = new URL(value.replace(/\{[^{}]+\}/g, "template-value"));
+        return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+function hasValidPackageShape(value) {
+    if (!isRecord(value)
+        || typeof value.registryType !== "string" || value.registryType.length === 0
+        || typeof value.identifier !== "string" || value.identifier.length === 0
+        || !isRecord(value.transport)
+        || !["stdio", "streamable-http", "sse"].includes(value.transport.type)) {
+        return false;
+    }
+    if (/^https?:\/\//i.test(value.identifier) && !hasValidHttpUrl(value.identifier)) {
+        return false;
+    }
+    if (typeof value.version === "string" && VERSION_RANGE_PATTERN.test(value.version)) {
+        return false;
+    }
+    return value.registryType !== "mcpb" || (typeof value.fileSha256 === "string" && SHA256_PATTERN.test(value.fileSha256));
+}
+function hasValidRemoteShape(value) {
+    return isRecord(value)
+        && (value.type === "streamable-http" || value.type === "sse")
+        && hasValidHttpUrl(value.url);
+}
+function hasValidRegistryServerShape(server) {
+    return typeof server.$schema === "string"
+        && OFFICIAL_SCHEMA_PATTERN.test(server.$schema)
+        && isSafeServerName(typeof server.name === "string" ? server.name : undefined)
+        && isSafeServerVersion(typeof server.version === "string" ? server.version : undefined)
+        && typeof server.description === "string"
+        && server.description.length >= 1
+        && server.description.length <= 100
+        && (server.packages === undefined || (Array.isArray(server.packages) && server.packages.every(hasValidPackageShape)))
+        && (server.remotes === undefined || (Array.isArray(server.remotes) && server.remotes.every(hasValidRemoteShape)));
+}
+function matchingRegistryServer(response, serverName, serverVersion) {
+    const payload = responseJson(response);
+    if (response.statusCode !== 200 || !isRecord(payload) || !isRecord(payload.server)) {
+        return false;
+    }
+    const server = payload.server;
+    return hasValidRegistryServerShape(server)
+        && server.name === serverName
+        && (serverVersion === undefined || server.version === serverVersion);
+}
+function matchingNpmPackument(response, packageName, packageVersion, serverName) {
+    const payload = responseJson(response);
+    if (response.statusCode !== 200 || !isRecord(payload) || payload.name !== packageName || !isRecord(payload.versions)) {
+        return false;
+    }
+    const version = payload.versions[packageVersion];
+    return isRecord(version)
+        && version.name === packageName
+        && version.version === packageVersion
+        && version.mcpName === serverName
+        && isRecord(version.dist)
+        && isIntegrity(version.dist.integrity);
+}
+function addFinding(findings, id, message) {
+    findings.push({ id, severity: "fail", message });
+}
+async function resolveServerJsonPath(targetPath) {
+    const resolved = path.resolve(targetPath);
+    try {
+        return (await stat(resolved)).isDirectory() ? path.join(resolved, "server.json") : resolved;
+    }
+    catch {
+        return resolved.endsWith(".json") ? resolved : path.join(resolved, "server.json");
+    }
+}
+async function readJson(pathname) {
+    try {
+        const parsed = JSON.parse(await readFile(pathname, "utf8"));
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function npmDeclarations(server) {
+    return Array.isArray(server?.packages)
+        ? server.packages.filter((entry) => isRecord(entry) && entry.registryType === "npm")
+        : [];
+}
+function publisherPlan() {
+    return {
+        executable: false,
+        steps: [
+            {
+                order: 1,
+                command: "mcp-publisher login github",
+                purpose: "Authenticate with GitHub for Registry publication."
+            },
+            {
+                order: 2,
+                command: "mcp-publisher publish",
+                purpose: "Publish the validated Registry metadata."
+            }
+        ]
+    };
+}
+export async function buildMcpRegistryPublicationPreflight(targetPath, options = {}) {
+    void options;
+    const readiness = await buildMcpRegistryReadiness(targetPath);
+    const findings = readiness.findings.map(publicFinding);
+    const serverJsonPath = await resolveServerJsonPath(targetPath);
+    const server = await readJson(serverJsonPath);
+    const declarations = npmDeclarations(server);
+    const packageJson = await readJson(path.join(path.dirname(serverJsonPath), "package.json"));
+    if (declarations.length > 1) {
+        findings.push({
+            id: "registry.preflight.package.multiple-npm-declarations",
+            severity: "fail",
+            message: "Publication evidence supports exactly one npm package declaration."
+        });
+    }
+    else if (declarations.length === 1
+        && typeof declarations[0].identifier === "string"
+        && packageJson
+        && packageJson.name !== declarations[0].identifier) {
+        findings.push({
+            id: "registry.preflight.package.local-name-mismatch",
+            severity: "fail",
+            message: "package.json name must match the declared npm package identifier."
+        });
+    }
+    if (declarations.length === 1 && !isSafeNpmIdentifier(declarations[0].identifier)) {
+        findings.push({
+            id: "registry.preflight.package.invalid-npm-identifier",
+            severity: "fail",
+            message: "The declared npm package identifier is not valid for public registry verification."
+        });
+    }
+    const localReadiness = statusFromFindings(findings);
+    let packagePublication = declarations.length === 0
+        ? "skipped"
+        : localReadiness === "fail" ? "fail" : "unknown";
+    let registryVersionAvailability = "unknown";
+    const declaration = declarations.length === 1 ? declarations[0] : undefined;
+    const serverName = isSafeServerName(readiness.serverName) ? readiness.serverName : undefined;
+    const serverVersion = isSafeServerVersion(readiness.serverVersion) ? readiness.serverVersion : undefined;
+    const packageName = isSafeNpmIdentifier(declaration?.identifier) ? declaration.identifier : undefined;
+    const declarationVersion = typeof declaration?.version === "string" ? declaration.version : undefined;
+    const packageVersion = isSafeServerVersion(declarationVersion)
+        ? declarationVersion
+        : undefined;
+    const canVerifyNetwork = options.allowNetwork === true
+        && localReadiness === "pass"
+        && declaration !== undefined
+        && serverName !== undefined
+        && serverVersion !== undefined
+        && packageName !== undefined
+        && packageVersion !== undefined;
+    if (!canVerifyNetwork && localReadiness !== "fail") {
+        findings.push({
+            id: "registry.preflight.network-unverified",
+            severity: "warn",
+            message: "Package publication and Registry version availability require explicit network verification."
+        });
+    }
+    if (canVerifyNetwork && packageName && packageVersion && serverName && serverVersion) {
+        const request = options.request ?? requestBoundedHttp;
+        let npmResponse;
+        try {
+            npmResponse = await request(`${NPM_REGISTRY}/${encodeURIComponent(packageName)}`, REQUEST_OPTIONS);
+        }
+        catch {
+            addFinding(findings, "registry.preflight.npm.request", "Public npm metadata could not be verified.");
+            packagePublication = "unknown";
+            return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+        }
+        if (npmResponse.statusCode !== 200 && npmResponse.statusCode !== 404) {
+            addFinding(findings, "registry.preflight.npm.response", "Public npm metadata could not prove package publication.");
+            packagePublication = "unknown";
+            return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+        }
+        if (!matchingNpmPackument(npmResponse, packageName, packageVersion, serverName)) {
+            addFinding(findings, "registry.preflight.npm.metadata", "Published npm metadata does not match the declared package version.");
+            packagePublication = "fail";
+            return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+        }
+        packagePublication = "pass";
+        let exactResponse;
+        try {
+            exactResponse = await request(`${MCP_REGISTRY}/v0.1/servers/${encodeURIComponent(serverName)}/versions/${encodeURIComponent(serverVersion)}`, REQUEST_OPTIONS);
+        }
+        catch {
+            addFinding(findings, "registry.preflight.registry.exact-request", "Exact Registry version availability could not be verified.");
+            return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+        }
+        if (matchingRegistryServer(exactResponse, serverName, serverVersion)) {
+            registryVersionAvailability = "already-published";
+            addFinding(findings, "registry.preflight.registry.already-published", "The exact Registry version is already published and cannot be overwritten.");
+        }
+        else if (validNotFound(exactResponse)) {
+            let latestResponse;
+            try {
+                latestResponse = await request(`${MCP_REGISTRY}/v0.1/servers/${encodeURIComponent(serverName)}/versions/latest`, REQUEST_OPTIONS);
+            }
+            catch {
+                addFinding(findings, "registry.preflight.registry.latest-request", "Latest Registry version availability could not be verified.");
+                return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+            }
+            if (validNotFound(latestResponse)) {
+                registryVersionAvailability = "available-first-publication";
+            }
+            else if (matchingRegistryServer(latestResponse, serverName) && responseJson(latestResponse) !== null) {
+                const payload = responseJson(latestResponse);
+                const latestVersion = payload.server.version;
+                if (latestVersion !== serverVersion) {
+                    registryVersionAvailability = "available-new-version";
+                }
+                else {
+                    addFinding(findings, "registry.preflight.registry.latest-response", "Latest Registry metadata did not prove a different published version.");
+                }
+            }
+            else {
+                addFinding(findings, "registry.preflight.registry.latest-response", "Latest Registry metadata could not prove version availability.");
+            }
+        }
+        else {
+            addFinding(findings, "registry.preflight.registry.exact-response", "Exact Registry metadata could not prove version availability.");
+        }
+    }
+    return buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings);
+}
+function buildReport(readiness, localReadiness, packagePublication, registryVersionAvailability, findings) {
+    return {
+        schemaVersion: "1.0.0",
+        kind: "mcp-registry-publication-preflight",
+        generatedAt: new Date().toISOString(),
+        target: "server.json",
+        ...(isSafeServerName(readiness.serverName) ? { serverName: readiness.serverName } : {}),
+        ...(isSafeServerVersion(readiness.serverVersion) ? { serverVersion: readiness.serverVersion } : {}),
+        status: statusFromFindings(findings),
+        localReadiness,
+        packagePublication,
+        registryVersionAvailability,
+        publisherPlan: publisherPlan(),
+        findings
+    };
+}
+export function renderMcpRegistryPublicationPreflightJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderMcpRegistryPublicationPreflight(report) {
+    const networkVerification = report.findings.some((finding) => finding.id === "registry.preflight.network-unverified")
+        ? "NOT REQUESTED"
+        : report.packagePublication === "pass" && report.registryVersionAvailability !== "unknown"
+            ? "COMPLETED"
+            : report.localReadiness === "fail"
+                ? "NOT AVAILABLE"
+                : "INCOMPLETE";
+    const lines = [
+        `Registry publication preflight: ${report.status.toUpperCase()}`,
+        `Target: ${report.target}`,
+        report.serverName ? `Server: ${report.serverName}@${report.serverVersion ?? "unknown"}` : null,
+        `Local readiness: ${report.localReadiness.toUpperCase()}`,
+        `Package publication: ${report.packagePublication.toUpperCase()}`,
+        `Registry version availability: ${report.registryVersionAvailability.toUpperCase()}`,
+        `Network verification: ${networkVerification}`
+    ].filter((line) => line !== null);
+    if (report.findings.length > 0) {
+        lines.push("", "Findings", "--------");
+        for (const finding of report.findings) {
+            lines.push(`${finding.severity.toUpperCase()} ${finding.id}: ${finding.message}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function registryPublicationPreflightExitCode(report, requirePublishReady = false) {
+    return report.status === "fail" || (requirePublishReady && report.status !== "pass") ? 1 : 0;
+}

package/dist/core/output-contract.js

@@ -9,6 +9,68 @@ const remoteTransportReliabilityStatusSchema = {
     type: "string",
     enum: ["pass", "warn", "fail", "skipped"]
 };
+const registryPublicationPreflightStatusSchema = {
+    type: "string",
+    enum: ["pass", "warn", "fail"]
+};
+const registryPackagePublicationSchema = {
+    type: "string",
+    enum: ["pass", "fail", "skipped", "unknown"]
+};
+const registryVersionAvailabilitySchema = {
+    type: "string",
+    enum: ["available-first-publication", "available-new-version", "already-published", "unknown"]
+};
+const registryPublisherPlanSchema = {
+    type: "object",
+    properties: {
+        executable: {
+            const: false
+        },
+        steps: {
+            type: "array",
+            minItems: 2,
+            maxItems: 2,
+            prefixItems: [
+                {
+                    type: "object",
+                    properties: {
+                        order: {
+                            const: 1
+                        },
+                        command: {
+                            const: "mcp-publisher login github"
+                        },
+                        purpose: {
+                            type: "string"
+                        }
+                    },
+                    required: ["order", "command", "purpose"],
+                    additionalProperties: false
+                },
+                {
+                    type: "object",
+                    properties: {
+                        order: {
+                            const: 2
+                        },
+                        command: {
+                            const: "mcp-publisher publish"
+                        },
+                        purpose: {
+                            type: "string"
+                        }
+                    },
+                    required: ["order", "command", "purpose"],
+                    additionalProperties: false
+                }
+            ],
+            items: false
+        }
+    },
+    required: ["executable", "steps"],
+    additionalProperties: false
+};
 const runtimeConformanceSchema = {
     type: "object",
     properties: {
@@ -198,6 +260,36 @@ const publicSchemaDefinitions = [
             }
         }
     },
+    {
+        id: "doctor.registry.preflight.json",
+        command: "codex-plugin-doctor registry preflight <server.json|directory> --json",
+        outputKind: "mcp-registry-publication-preflight",
+        required: [
+            "schemaVersion",
+            "kind",
+            "generatedAt",
+            "target",
+            "status",
+            "localReadiness",
+            "packagePublication",
+            "registryVersionAvailability",
+            "publisherPlan",
+            "findings"
+        ],
+        properties: {
+            target: {
+                const: "server.json"
+            },
+            status: registryPublicationPreflightStatusSchema,
+            localReadiness: registryPublicationPreflightStatusSchema,
+            packagePublication: registryPackagePublicationSchema,
+            registryVersionAvailability: registryVersionAvailabilitySchema,
+            publisherPlan: registryPublisherPlanSchema,
+            findings: {
+                type: "array"
+            }
+        }
+    },
     {
         id: "doctor.audit.json",
         command: "codex-plugin-doctor audit --installed --json",

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
+export { buildDoctorSize, renderDoctorSize, renderDoctorSizeJson, type DoctorSizeReport } from "./core/doctor-size.js";
 export { applyDoctorConfig, loadDoctorConfig, type DoctorConfig } from "./core/doctor-config.js";
 export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig, type LoadedDoctorConfig, type RawDoctorConfig } from "./core/doctor-config-store.js";
 export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord, type ClassifiedSuppressionRecord, type InvalidSuppressionRecord, type SuppressionRecordField, type ValidSuppressionRecord } from "./core/suppression-record.js";
@@ -31,6 +32,7 @@ export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, ty
 export { applyPolicyToDepAudit, applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";
 export { buildMcpRegistryReadiness, inspectMcpRegistryServer, registryReadinessExitCode, renderMcpRegistryReadiness, renderMcpRegistryReadinessJson, type InspectMcpRegistryOptions, type McpRegistryFinding, type McpRegistryInstallability, type McpRegistryReadinessReport, type McpRegistryScorecard } from "./core/mcp-registry.js";
+export { buildMcpRegistryPublicationPreflight, registryPublicationPreflightExitCode, renderMcpRegistryPublicationPreflight, renderMcpRegistryPublicationPreflightJson, type BuildMcpRegistryPublicationPreflightOptions, type McpRegistryPublicationPreflightFinding, type McpRegistryPublicationPreflightReport, type McpRegistryPublicationPreflightStatus } from "./core/mcp-registry-preflight.js";
 export { watchPlugin, type WatchPluginOptions, type WatchPluginResult } from "./core/watch-plugin.js";
 export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif, type DepAuditRecommendation, type DepAuditReport, type DepAuditVulnerability } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks, type InitGitHooksResult, type RemoveGitHooksResult } from "./core/init-git-hooks.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 import { validatePlugin } from "./core/validate-plugin.js";
+export { buildDoctorSize, renderDoctorSize, renderDoctorSizeJson } from "./core/doctor-size.js";
 export { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig } from "./core/doctor-config-store.js";
 export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord } from "./core/suppression-record.js";
@@ -31,6 +32,7 @@ export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } f
 export { applyPolicyToDepAudit, applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
 export { buildMcpRegistryReadiness, inspectMcpRegistryServer, registryReadinessExitCode, renderMcpRegistryReadiness, renderMcpRegistryReadinessJson } from "./core/mcp-registry.js";
+export { buildMcpRegistryPublicationPreflight, registryPublicationPreflightExitCode, renderMcpRegistryPublicationPreflight, renderMcpRegistryPublicationPreflightJson } from "./core/mcp-registry-preflight.js";
 export { watchPlugin } from "./core/watch-plugin.js";
 export { buildDepAudit, buildDepAuditRecommendations, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
 export { initGitHooks, removeGitHooks } from "./core/init-git-hooks.js";

package/dist/run-cli.js

@@ -29,10 +29,12 @@ import { buildDoctorReviewBundle, diffDoctorReviewBundles, renderDoctorReviewBun
 import { buildDoctorReleaseEvidenceAssetReport, buildDoctorReleaseEvidenceReport, renderDoctorReleaseEvidenceAsset, renderDoctorReleaseEvidenceAssetJson, renderDoctorReleaseEvidence, renderDoctorReleaseEvidenceJson, renderDoctorReleaseEvidenceVerification, renderDoctorReleaseEvidenceVerificationJson, verifyDoctorReleaseEvidence } from "./core/release-evidence.js";
 import { buildDoctorNpmPackageReport, renderDoctorNpmPackageReport, renderDoctorNpmPackageReportJson } from "./core/npm-package-doctor.js";
 import { buildMcpRegistryReadiness, inspectMcpRegistryServer, registryReadinessExitCode, renderMcpRegistryReadiness, renderMcpRegistryReadinessJson } from "./core/mcp-registry.js";
+import { buildMcpRegistryPublicationPreflight, registryPublicationPreflightExitCode, renderMcpRegistryPublicationPreflight, renderMcpRegistryPublicationPreflightJson } from "./core/mcp-registry-preflight.js";
 import { buildDoctorRiskDiffReport, renderDoctorRiskDiffReport, renderDoctorRiskDiffReportJson } from "./core/risk-diff.js";
 import { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorInspectorReportJson } from "./core/inspector-bridge.js";
 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 { watchPlugin } from "./core/watch-plugin.js";
 import { buildDepAudit, renderDepAudit, renderDepAuditJson, renderDepAuditSarif } from "./core/dep-audit.js";
@@ -169,7 +171,8 @@ function parseRemoteNetworkFlags(flags, runtime) {
 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>]\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("Registry readiness: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
-        + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]");
+        + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
+        + "Registry publication preflight: codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
     io.writeStderr("Corpus quality regression: codex-plugin-doctor doctor corpus metrics diff --before <metrics.json> --after <metrics.json> [--fail-on-regression] [--json|--markdown] [--output <path>]");
     io.writeStderr("Suppression governance: codex-plugin-doctor suppress list <path> [--fail-on-expired] [--fail-on-invalid] [--warn-expiring-within-days <days>]\n       codex-plugin-doctor suppress prune <path> [--apply] [--json]");
     io.writeStderr("Baseline gating: codex-plugin-doctor baseline create <path> --output <path> [--runtime]\n       codex-plugin-doctor check <path> --baseline <path>");
@@ -2099,6 +2102,19 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStdout(await renderClientDoctor(terminalContext));
             return 0;
         }
+        if (maybePath === "size") {
+            const sizeTarget = remainingArgs[0] && !remainingArgs[0].startsWith("--") ? remainingArgs[0] : ".";
+            const sizeFlags = remainingArgs[0] && remainingArgs[0].startsWith("--")
+                ? remainingArgs
+                : remainingArgs.slice(1);
+            const jsonOutput = sizeFlags.includes("--json");
+            const report = await buildDoctorSize(sizeTarget);
+            const output = jsonOutput
+                ? renderDoctorSizeJson(report)
+                : renderDoctorSize(report);
+            io.writeStdout(output);
+            return report.status === "fail" ? 1 : 0;
+        }
         io.writeStdout(maybePath === "--json"
             ? await renderEnvironmentDoctorJson(terminalContext)
             : await renderEnvironmentDoctor(terminalContext));
@@ -2363,16 +2379,18 @@ export async function runCli(args, io = defaultIo, options = {}) {
         const subcommand = maybePath;
         const target = remainingArgs[0];
         const flags = remainingArgs.slice(1);
-        if ((subcommand !== "check" && subcommand !== "inspect") || !target || target.startsWith("--")) {
+        if ((subcommand !== "check" && subcommand !== "inspect" && subcommand !== "preflight") || !target || target.startsWith("--")) {
             io.writeStderr("Usage: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
-                + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]");
+                + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
+                + "       codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
             return 2;
         }
         const allowedFlags = new Set([
             "--json",
             "--output",
             "--allow-network",
-            "--require-registry-readiness"
+            "--require-registry-readiness",
+            "--require-publish-ready"
         ]);
         let outputPath = null;
         for (let index = 0; index < flags.length; index += 1) {
@@ -2393,14 +2411,33 @@ export async function runCli(args, io = defaultIo, options = {}) {
         }
         const allowNetwork = flags.includes("--allow-network");
         if (subcommand === "check" && allowNetwork) {
-            io.writeStderr("--allow-network is supported only by registry inspect.");
+            io.writeStderr("--allow-network is not supported by registry check.");
             return 2;
         }
         if (subcommand === "inspect" && !allowNetwork) {
             io.writeStderr("registry inspect requires explicit --allow-network consent.");
             return 2;
         }
+        if (subcommand === "preflight" && flags.includes("--require-registry-readiness")) {
+            io.writeStderr("--require-registry-readiness is supported only by registry check or registry inspect.");
+            return 2;
+        }
+        if (subcommand !== "preflight" && flags.includes("--require-publish-ready")) {
+            io.writeStderr("--require-publish-ready is supported only by registry preflight.");
+            return 2;
+        }
         try {
+            if (subcommand === "preflight") {
+                const report = await buildMcpRegistryPublicationPreflight(target, { allowNetwork });
+                const rendered = flags.includes("--json")
+                    ? renderMcpRegistryPublicationPreflightJson(report)
+                    : renderMcpRegistryPublicationPreflight(report);
+                if (outputPath) {
+                    await writeFile(outputPath, rendered, "utf8");
+                }
+                io.writeStdout(rendered);
+                return registryPublicationPreflightExitCode(report, flags.includes("--require-publish-ready"));
+            }
             const report = subcommand === "check"
                 ? await buildMcpRegistryReadiness(target)
                 : await inspectMcpRegistryServer(target, { allowNetwork: true });
@@ -2414,7 +2451,12 @@ export async function runCli(args, io = defaultIo, options = {}) {
             return registryReadinessExitCode(report, flags.includes("--require-registry-readiness"));
         }
         catch (error) {
-            io.writeStderr(`Registry inspection failed: ${error.message}`);
+            if (subcommand === "preflight") {
+                io.writeStderr("Registry publication preflight failed.");
+            }
+            else {
+                io.writeStderr(`Registry inspection failed: ${error.message}`);
+            }
             return 1;
         }
     }

package/package.json

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