codex-plugin-doctor 1.53.0 → 1.55.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Furkan Tasci
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Furkan Tasci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -83,18 +83,56 @@ Runtime MCP validation with `--runtime`:
 
 ### Remote MCP Readiness
 
-Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
+Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
 
 ```bash
 codex-plugin-doctor check ./remote-mcp --runtime --allow-network
 codex-plugin-doctor check ./remote-mcp --runtime --allow-network --allow-local-network
 ```
 
-The probe makes only bounded protocol and OAuth metadata-discovery requests, redacts report output, and applies SSRF controls. It does not authenticate or follow redirects.
-
-Remote transport reliability adds one bounded SSE GET after initialization. HTTP `200` must be `text/event-stream`; HTTP `405` is compliant when the endpoint does not offer server-to-client SSE. At most one SSE resume and one session restart are attempted, and no remote response content is retained. This is a bounded readiness check, not a live interoperability, delivery-guarantee, or load-test claim.
-
-`--allow-session-lifecycle` is disabled by default and is state-changing: only after a valid `MCP-Session-Id` it permits one bounded session `DELETE`. `--require-remote-reliability` is a strict result gate: it fails unless every attempted remote reliability scorecard passes. Local-only runs are unaffected. It grants no network consent, so `--runtime --allow-network` (and loopback consent when applicable) remain required. See [Remote MCP Readiness](./docs/architecture/remote-mcp-readiness.md) and [Remote MCP Transport Reliability](./docs/architecture/remote-mcp-transport-reliability.md).
+The probe makes only bounded protocol and OAuth metadata-discovery requests, redacts report output, and applies SSRF controls. It does not authenticate or follow redirects.
+
+Remote transport reliability adds one bounded SSE GET after initialization. HTTP `200` must be `text/event-stream`; HTTP `405` is compliant when the endpoint does not offer server-to-client SSE. At most one SSE resume and one session restart are attempted, and no remote response content is retained. This is a bounded readiness check, not a live interoperability, delivery-guarantee, or load-test claim.
+
+`--allow-session-lifecycle` is disabled by default and is state-changing: only after a valid `MCP-Session-Id` it permits one bounded session `DELETE`. `--require-remote-reliability` is a strict result gate: it fails unless every attempted remote reliability scorecard passes. Local-only runs are unaffected. It grants no network consent, so `--runtime --allow-network` (and loopback consent when applicable) remain required. See [Remote MCP Readiness](./docs/architecture/remote-mcp-readiness.md) and [Remote MCP Transport Reliability](./docs/architecture/remote-mcp-transport-reliability.md).
+
+### MCP Registry Readiness
+
+Validate official MCP Registry publication metadata without publishing or installing anything:
+
+```bash
+codex-plugin-doctor registry check path/to/server.json
+codex-plugin-doctor registry check path/to/server.json --json --require-registry-readiness
+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:
 
@@ -442,9 +480,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.53.0
+      - uses: Esquetta/CodexPluginDoctor@v1.55.0
         with:
-          version: "1.53.0"
+          version: "1.55.0"
           path: .
           runtime: "true"
           policy: codex-publish

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/mcp-registry.d.ts

@@ -0,0 +1,57 @@
+import { type BoundedHttpRequestOptions, type BoundedHttpResponse } from "./bounded-http-client.js";
+type RegistryCheckStatus = "pass" | "warn" | "fail" | "skipped";
+type RegistryRequest = (url: string, options?: BoundedHttpRequestOptions) => Promise<BoundedHttpResponse>;
+export interface McpRegistryFinding {
+    id: string;
+    severity: "warn" | "fail";
+    message: string;
+    path?: string;
+}
+export interface McpRegistryScorecard {
+    metadata: RegistryCheckStatus;
+    ownership: RegistryCheckStatus;
+    packageIntegrity: RegistryCheckStatus;
+    transportReadiness: RegistryCheckStatus;
+    clientInstallability: RegistryCheckStatus;
+    overall: Exclude<RegistryCheckStatus, "skipped">;
+}
+export interface McpRegistryInstallability {
+    codex: "ready" | "manual" | "unavailable";
+    packageTypes: string[];
+    remoteTransports: string[];
+    codexPreview?: {
+        mcpServers: Record<string, {
+            command?: string;
+            args?: string[];
+            url?: string;
+        }>;
+    };
+}
+export interface McpRegistryReadinessReport {
+    schemaVersion: "1.0.0";
+    kind: "mcp-registry-readiness";
+    generatedAt: string;
+    source: "file" | "registry";
+    target: string;
+    serverName?: string;
+    serverVersion?: string;
+    status: "pass" | "warn" | "fail";
+    scorecard: McpRegistryScorecard;
+    installability: McpRegistryInstallability;
+    findings: McpRegistryFinding[];
+    registry?: {
+        lifecycleStatus: string;
+        isLatest?: boolean;
+        publishedAt?: string;
+    };
+}
+export interface InspectMcpRegistryOptions {
+    allowNetwork?: boolean;
+    request?: RegistryRequest;
+}
+export declare function buildMcpRegistryReadiness(targetPath: string): Promise<McpRegistryReadinessReport>;
+export declare function inspectMcpRegistryServer(serverName: string, options?: InspectMcpRegistryOptions): Promise<McpRegistryReadinessReport>;
+export declare function registryReadinessExitCode(report: McpRegistryReadinessReport, requireReadiness?: boolean): 0 | 1;
+export declare function renderMcpRegistryReadinessJson(report: McpRegistryReadinessReport): string;
+export declare function renderMcpRegistryReadiness(report: McpRegistryReadinessReport): string;
+export {};