codex-plugin-doctor 1.58.0 → 1.60.0

package/README.md

@@ -134,6 +134,25 @@ 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).
 
+### Public Directory Submission Preflight
+
+Check a plugin package for deterministic public-directory submission issues without contacting a portal:
+
+```bash
+codex-plugin-doctor doctor submission <path>
+codex-plugin-doctor doctor submission <path> --json
+codex-plugin-doctor doctor submission <path> --markdown
+codex-plugin-doctor doctor submission <path> --require-ready
+codex-plugin-doctor doctor submission archive <zip>
+codex-plugin-doctor doctor submission archive <zip> --json --output submission-archive.json
+codex-plugin-doctor doctor submission archive <zip> --markdown --output submission-archive.md
+codex-plugin-doctor doctor submission archive <zip> --require-ready
+```
+
+The preflight is offline and non-executing: it does not submit a package, make network requests, start MCP servers, verify domains, or handle OAuth credentials. Its automatic `status` is `pass` or `fail`; a passing automatic result remains `manual_review_required` until portal-only review is complete. It never claims directory acceptance. See [Public Directory Submission Preflight](./docs/architecture/public-directory-submission-preflight.md).
+
+The archive variant accepts an existing skills-only ZIP and does not extract archive entries to disk, execute package code, or repair the archive. It reports malformed ZIP structures and deterministic package blockers; unsupported portal rules remain manual or `coverage: unavailable` rather than an automatic pass.
+
 Output formats:
 
 - human text output
@@ -480,9 +499,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.58.0
+      - uses: Esquetta/CodexPluginDoctor@v1.60.0
         with:
-          version: "1.58.0"
+          version: "1.60.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -494,7 +513,7 @@ jobs:
           review-bundle-verify: "true"
 ```
 
-The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
+The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Set `submission: "true"` to add offline submission preflight reports; set `require-submission-ready: "true"` only with that opt-in to make automatic blockers fail the job. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
 
 To self-test this repository after cloning it:
 

package/dist/core/output-contract.js

@@ -186,6 +186,144 @@ const publicSchemaDefinitions = [
             }
         }
     },
+    {
+        id: "doctor.submission.json",
+        command: "codex-plugin-doctor doctor submission <path> --json",
+        required: [
+            "schemaVersion",
+            "rulesetVersion",
+            "targetType",
+            "status",
+            "readiness",
+            "summary",
+            "checks",
+            "findings",
+            "manualChecklist"
+        ],
+        properties: {
+            rulesetVersion: { const: "openai-directory-2026-08-15" },
+            targetType: { type: "string", enum: ["skills-only", "mcp-backed"] },
+            status: { type: "string", enum: ["pass", "fail"] },
+            readiness: { type: "string", enum: ["blocked", "manual_review_required"] },
+            summary: {
+                type: "object",
+                required: ["passed", "warnings", "blockers", "manualChecks"],
+                properties: {
+                    passed: { type: "integer", minimum: 0 },
+                    warnings: { type: "integer", minimum: 0 },
+                    blockers: { type: "integer", minimum: 0 },
+                    manualChecks: { type: "integer", minimum: 0 }
+                },
+                additionalProperties: false
+            },
+            checks: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["id", "status", "findingIds"],
+                    properties: {
+                        id: { type: "string", enum: ["listing", "components", "assets", "skills"] },
+                        status: { type: "string", enum: ["pass", "warn", "fail"] },
+                        findingIds: { type: "array", items: { type: "string" } }
+                    },
+                    additionalProperties: false
+                }
+            },
+            findings: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["id", "severity", "message"],
+                    properties: {
+                        id: { type: "string", pattern: "^plugin\\.submission\\." },
+                        severity: { type: "string", enum: ["warn", "fail"] },
+                        message: { type: "string" },
+                        portalCode: { type: "string" },
+                        evidence: {
+                            type: "object",
+                            additionalProperties: { type: ["string", "number", "boolean", "null"] }
+                        }
+                    },
+                    additionalProperties: false
+                }
+            },
+            manualChecklist: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["id", "label", "state"],
+                    properties: {
+                        id: { type: "string" },
+                        label: { type: "string" },
+                        state: { type: "string", enum: ["required", "not_applicable"] }
+                    },
+                    additionalProperties: false
+                }
+            }
+        }
+    },
+    {
+        id: "doctor.submission.archive.json",
+        command: "codex-plugin-doctor doctor submission archive <zip> --json",
+        required: [
+            "schemaVersion",
+            "rulesetVersion",
+            "status",
+            "readiness",
+            "archive",
+            "summary",
+            "archiveChecks",
+            "submission",
+            "findings",
+            "coverage",
+            "manualChecklist"
+        ],
+        properties: {
+            rulesetVersion: { const: "openai-directory-archive-2026-08-23" },
+            status: { type: "string", enum: ["pass", "fail"] },
+            readiness: { type: "string", enum: ["blocked", "manual_review_required"] },
+            archive: {
+                type: "object",
+                required: ["fileName", "compressedBytes", "uncompressedBytes", "entryCount", "rootLayout"],
+                properties: {
+                    fileName: { type: "string" },
+                    compressedBytes: { type: "integer", minimum: 0 },
+                    uncompressedBytes: { type: "integer", minimum: 0 },
+                    entryCount: { type: "integer", minimum: 0 },
+                    rootLayout: { type: "string", enum: ["archive-root", "single-top-level-directory", "unavailable"] }
+                },
+                additionalProperties: false
+            },
+            summary: {
+                type: "object",
+                required: ["passed", "warnings", "blockers", "manualChecks"],
+                properties: {
+                    passed: { type: "integer", minimum: 0 },
+                    warnings: { type: "integer", minimum: 0 },
+                    blockers: { type: "integer", minimum: 0 },
+                    manualChecks: { type: "integer", minimum: 0 }
+                },
+                additionalProperties: false
+            },
+            archiveChecks: { type: "array" },
+            submission: { type: ["object", "null"] },
+            findings: { type: "array" },
+            coverage: {
+                type: "array",
+                items: {
+                    type: "object",
+                    required: ["id", "status", "reason"],
+                    properties: {
+                        id: { type: "string", pattern: "^plugin\\.submission\\.archive\\." },
+                        status: { type: "string", enum: ["automatic", "manual", "unavailable"] },
+                        reason: { type: "string" }
+                    },
+                    additionalProperties: false
+                }
+            },
+            manualChecklist: { type: "array" }
+        }
+    },
     {
         id: "doctor.installed.check.json",
         command: "codex-plugin-doctor check --installed --json",

package/dist/core/shell-completion.js

@@ -17,6 +17,10 @@ const topLevelCommands = [
     "explain",
     "config"
 ];
+const doctorCommands = ["submission"];
+const submissionTargets = ["archive"];
+const submissionFlags = ["--json", "--markdown", "--output", "--require-ready"];
+const fishSubmissionCondition = "__fish_seen_subcommand_from doctor; and __fish_seen_subcommand_from submission";
 function bashCompletion() {
     return [
         "_codex_plugin_doctor() {",
@@ -26,16 +30,44 @@ function bashCompletion() {
         "  prev=\"${COMP_WORDS[COMP_CWORD-1]}\"",
         "",
         `  local commands="${topLevelCommands.join(" ")}"`,
+        `  local doctor_commands="${doctorCommands.join(" ")}"`,
+        `  local submission_targets="${submissionTargets.join(" ")}"`,
+        `  local submission_flags="${submissionFlags.join(" ")}"`,
         "",
         "  case \"${prev}\" in",
         "    codex-plugin-doctor)",
         "      COMPREPLY=( $(compgen -W \"${commands}\" -- \"${cur}\") )",
         "      return 0",
         "      ;;",
+        "    doctor)",
+        "      COMPREPLY=( $(compgen -W \"${doctor_commands}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
+        "    submission)",
+        "      COMPREPLY=( $(compgen -W \"${submission_targets}\" -- \"${cur}\") )",
+        "      return 0",
+        "      ;;",
         "  esac",
         "",
+        "  if [[ ${COMP_WORDS[1]} == \"doctor\" && ${COMP_WORDS[2]} == \"submission\" && ${COMP_WORDS[3]} == \"archive\" ]]; then",
+        "    case \"${cur}\" in",
+        "      --*)",
+        "        COMPREPLY=( $(compgen -W \"${submission_flags}\" -- \"${cur}\") )",
+        "        return 0",
+        "        ;;",
+        "      *)",
+        "        COMPREPLY=( $(compgen -f -- \"${cur}\") )",
+        "        return 0",
+        "        ;;",
+        "    esac",
+        "  fi",
+        "",
         "  case \"${cur}\" in",
         "    --*)",
+        "      if [[ ${COMP_WORDS[1]} == \"doctor\" && ${COMP_WORDS[2]} == \"submission\" ]]; then",
+        "        COMPREPLY=( $(compgen -W \"${submission_flags}\" -- \"${cur}\") )",
+        "        return 0",
+        "      fi",
         "      local flags=\"--json --output --runtime --policy --help\"",
         "      COMPREPLY=( $(compgen -W \"${flags}\" -- \"${cur}\") )",
         "      return 0",
@@ -60,9 +92,22 @@ function zshCompletion() {
         "  typeset -A opt_args",
         "",
         `  local commands=(${topLevelCommands.join(" ")})`,
+        `  local doctor_commands=(${doctorCommands.join(" ")})`,
+        "",
+        "  if [[ \"$words[2]\" == \"doctor\" && \"$words[3]\" == \"submission\" ]]; then",
+        "    _arguments -C \\",
+        "      '3:archive target:(archive)' \\",
+        "      '4:ZIP archive:_files' \\",
+        "      '*--json[Output as JSON]' \\",
+        "      '*--markdown[Output as Markdown]' \\",
+        "      '*--output[Write to file]:file:_files' \\",
+        "      '*--require-ready[Fail when automatic checks are blocked]'",
+        "    return",
+        "  fi",
         "",
         "  _arguments -C \\",
         "    '1:command:(${commands})' \\",
+        "    '2:doctor command:(${doctor_commands})' \\",
         "    '*--json[Output as JSON]' \\",
         "    '*--output[Write to file]:file:_files' \\",
         "    '*--runtime[Enable runtime probes]' \\",
@@ -80,6 +125,13 @@ function fishCompletion() {
         "complete -c codex-plugin-doctor -s h -l help -d 'Show help'",
         "complete -c codex-plugin-doctor -l json -d 'Output as JSON'",
         "complete -c codex-plugin-doctor -l output -d 'Write to file' -r",
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l json -d 'Output as JSON'`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l markdown -d 'Output as Markdown'`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l output -d 'Write to file' -r`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}" -l require-ready -d 'Fail when automatic checks are blocked'`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}; and __fish_seen_subcommand_from archive" -F`,
+        `complete -c codex-plugin-doctor -n "${fishSubmissionCondition}; and not __fish_seen_subcommand_from archive" -a "${submissionTargets.join(" ")}" -d 'ZIP archive'`,
+        `complete -c codex-plugin-doctor -n "__fish_seen_subcommand_from doctor; and not __fish_seen_subcommand_from ${doctorCommands.join(" ")}" -a "${doctorCommands.join(" ")}"`,
         "complete -c codex-plugin-doctor -l runtime -d 'Enable runtime probes'",
         "complete -c codex-plugin-doctor -l policy -d 'Apply policy' -x -a 'codex-publish mcp-strict security'",
         ""

package/dist/core/submission-archive-preflight.d.ts

@@ -0,0 +1,24 @@
+import { type SubmissionArchiveCoverage, type SubmissionArchiveFinding } from "./submission-archive-reader.js";
+import { type SubmissionCheck, type SubmissionFinding, type SubmissionManualCheck, type SubmissionPreflightReport } from "./submission-preflight.js";
+export type SubmissionArchiveRootLayout = "archive-root" | "single-top-level-directory" | "unavailable";
+export interface SubmissionArchivePreflightReport {
+    schemaVersion: "1.0.0";
+    rulesetVersion: "openai-directory-archive-2026-08-23";
+    status: "pass" | "fail";
+    readiness: "blocked" | "manual_review_required";
+    archive: {
+        fileName: string;
+        compressedBytes: number;
+        uncompressedBytes: number;
+        entryCount: number;
+        rootLayout: SubmissionArchiveRootLayout;
+    };
+    summary: SubmissionPreflightReport["summary"];
+    archiveChecks: readonly SubmissionCheck[];
+    submission: SubmissionPreflightReport | null;
+    findings: readonly SubmissionArchiveFinding[] | readonly (SubmissionArchiveFinding | SubmissionFinding)[];
+    coverage: readonly SubmissionArchiveCoverage[];
+    manualChecklist: readonly SubmissionManualCheck[];
+}
+export declare function submissionArchiveExitCode(report: SubmissionArchivePreflightReport, requireReady: boolean): 0 | 1;
+export declare function buildSubmissionArchivePreflight(archivePath: string): Promise<SubmissionArchivePreflightReport>;

package/dist/core/submission-archive-preflight.js

@@ -0,0 +1,259 @@
+import { validateSubmissionAssetsFromReader } from "./submission-assets.js";
+import { inspectSubmissionArchive } from "./submission-archive-reader.js";
+import { submissionArchiveRuleset } from "./submission-archive-ruleset.js";
+import { validateSubmissionListing } from "./submission-preflight.js";
+import { submissionManualChecks } from "./submission-ruleset.js";
+import { validateSubmissionSkillMetadataFromReader } from "./submission-skill-metadata.js";
+const manifestPaths = [".codex-plugin/plugin.json", ".agent-plugin/plugin.json", ".claude-plugin/plugin.json"];
+const maxManifestBytes = 1024 * 1024;
+function archiveFinding(id, severity, message, portalCode) {
+    return portalCode === undefined ? { id, severity, message } : { id, severity, message, portalCode };
+}
+function archiveCoverage() {
+    return submissionArchiveRuleset.portalRules.map(({ id, status, reason }) => ({ id, status, reason }));
+}
+function checkStatus(findings) {
+    return findings.some((finding) => finding.severity === "fail")
+        ? "fail"
+        : findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function submissionCheck(id, findings) {
+    return { id, status: checkStatus(findings), findingIds: findings.map((finding) => finding.id) };
+}
+function manualChecklist() {
+    return submissionManualChecks.map((item) => ({
+        id: item.id,
+        label: item.label,
+        state: item.mcpOnly ? "not_applicable" : "required"
+    }));
+}
+function reportSummary(checks, findings, checklist) {
+    return {
+        passed: checks.filter((check) => check.status === "pass").length,
+        warnings: findings.filter((finding) => finding.severity === "warn").length,
+        blockers: findings.filter((finding) => finding.severity === "fail").length,
+        manualChecks: checklist.filter((item) => item.state === "required").length
+    };
+}
+function normalizePath(value, allowRoot = false) {
+    if (value === "" && allowRoot)
+        return "";
+    if (typeof value !== "string" || value === "" || value.startsWith("/") || value.startsWith("\\")
+        || /^[A-Za-z]:/u.test(value) || value.includes("\\") || /[\u0000-\u001F\u007F]/u.test(value))
+        return null;
+    const segments = value.split("/");
+    return segments.some((segment) => segment === "" || segment === "." || segment === "..") ? null : segments.join("/");
+}
+function discoverRoot(entries) {
+    const paths = entries.map((entry) => entry.packagePath);
+    if (paths.length === 0) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.root_missing", "fail", "Archive does not contain a plugin root.")] };
+    }
+    const rootManifests = manifestPaths.filter((manifestPath) => paths.includes(manifestPath));
+    const nestedRoots = new Set();
+    for (const entryPath of paths) {
+        const separator = entryPath.indexOf("/");
+        if (separator > 0 && manifestPaths.includes(entryPath.slice(separator + 1))) {
+            nestedRoots.add(entryPath.slice(0, separator));
+        }
+    }
+    if (rootManifests.length + nestedRoots.size > 1) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.root_ambiguous", "fail", "Archive contains more than one plugin root.")] };
+    }
+    if (rootManifests.length === 1) {
+        return {
+            discovery: { rootPrefix: "", rootLayout: "archive-root", manifestPath: rootManifests[0], manifestFormat: rootManifests[0] },
+            findings: []
+        };
+    }
+    if (nestedRoots.size === 0) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.manifest_missing", "fail", "Archive root does not contain a recognized plugin manifest.")] };
+    }
+    const hasRootFile = entries.some((entry) => !entry.packagePath.includes("/") && entry.resolvedKind === "file");
+    const topLevels = new Set(paths.map((entryPath) => entryPath.split("/", 1)[0]));
+    if (hasRootFile || nestedRoots.size !== 1 || topLevels.size !== 1) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.root_siblings", "fail", "A top-level plugin directory cannot have siblings.")] };
+    }
+    const topLevel = [...nestedRoots][0];
+    const prefix = `${topLevel}/`;
+    const nestedManifests = manifestPaths.filter((manifestPath) => paths.includes(`${prefix}${manifestPath}`));
+    if (nestedManifests.length === 0) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.manifest_missing", "fail", "Archive root does not contain a recognized plugin manifest.")] };
+    }
+    if (nestedManifests.length > 1) {
+        return { discovery: null, findings: [archiveFinding("plugin.submission.archive.root_ambiguous", "fail", "Archive contains more than one plugin manifest.")] };
+    }
+    return {
+        discovery: {
+            rootPrefix: prefix,
+            rootLayout: "single-top-level-directory",
+            manifestPath: `${prefix}${nestedManifests[0]}`,
+            manifestFormat: nestedManifests[0]
+        },
+        findings: []
+    };
+}
+function rootedReader(inspection, rootPrefix) {
+    if (inspection.reader === null)
+        return null;
+    const entries = inspection.entries
+        .filter((entry) => entry.packagePath.startsWith(rootPrefix))
+        .map((entry) => ({ ...entry, packagePath: entry.packagePath.slice(rootPrefix.length) }));
+    const byPath = new Map(entries.map((entry) => [entry.packagePath, entry]));
+    const reader = inspection.reader;
+    function directoryEntry(packagePath) {
+        if (entries.some((entry) => entry.packagePath.startsWith(`${packagePath}/`))) {
+            return { packagePath, kind: "directory", resolvedKind: "directory", size: 0, safeResolution: "safe" };
+        }
+        return null;
+    }
+    return {
+        async list(directory) {
+            const normalizedDirectory = normalizePath(directory, true);
+            if (normalizedDirectory === null)
+                return [];
+            const prefix = normalizedDirectory === "" ? "" : `${normalizedDirectory}/`;
+            const children = new Map();
+            for (const entry of entries) {
+                if (!entry.packagePath.startsWith(prefix))
+                    continue;
+                const remaining = entry.packagePath.slice(prefix.length);
+                if (remaining === "")
+                    continue;
+                const [name] = remaining.split("/", 1);
+                const packagePath = normalizedDirectory === "" ? name : `${normalizedDirectory}/${name}`;
+                if (remaining.includes("/")) {
+                    children.set(packagePath, directoryEntry(packagePath));
+                }
+                else {
+                    children.set(packagePath, entry);
+                }
+            }
+            return [...children.values()].sort((left, right) => left.packagePath.localeCompare(right.packagePath));
+        },
+        async stat(packagePath) {
+            const normalizedPath = normalizePath(packagePath);
+            return normalizedPath === null ? null : byPath.get(normalizedPath) ?? directoryEntry(normalizedPath);
+        },
+        async read(packagePath, maxBytes) {
+            const normalizedPath = normalizePath(packagePath);
+            if (normalizedPath === null || !byPath.has(normalizedPath))
+                return null;
+            return reader.read(`${rootPrefix}${normalizedPath}`, maxBytes);
+        }
+    };
+}
+async function parseManifest(reader, manifestPath) {
+    const bytes = await reader.read(manifestPath, maxManifestBytes).catch(() => null);
+    if (bytes === null)
+        return null;
+    try {
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasImmediateSkill(entries) {
+    return entries.some((entry) => /^skills\/[^/]+\/SKILL\.md$/u.test(entry.packagePath) && entry.resolvedKind === "file");
+}
+function exclusionFindings(manifest, entries) {
+    const findings = [];
+    const interfaceValue = manifest.interface;
+    if (manifest.mcpServers !== undefined || entries.some((entry) => entry.packagePath === ".mcp.json")) {
+        findings.push(archiveFinding("plugin.submission.archive.mcp_excluded", "warn", "MCP configuration requires the MCP-backed submission flow.", "mcp_configuration_excluded"));
+    }
+    if (manifest.apps !== undefined || entries.some((entry) => entry.packagePath === ".app.json")) {
+        findings.push(archiveFinding("plugin.submission.archive.app_excluded", "warn", "App configuration requires the MCP-backed submission flow.", "app_configuration_excluded"));
+    }
+    if (typeof interfaceValue === "object" && interfaceValue !== null && !Array.isArray(interfaceValue)
+        && "screenshots" in interfaceValue && interfaceValue.screenshots !== undefined) {
+        findings.push(archiveFinding("plugin.submission.archive.screenshot_excluded", "warn", "Screenshots require the MCP-backed submission flow.", "screenshot_configuration_excluded"));
+    }
+    return findings;
+}
+async function nestedSubmission(manifest, reader) {
+    const targetType = "skills-only";
+    const listing = validateSubmissionListing(manifest, targetType);
+    const components = [];
+    const assets = (await validateSubmissionAssetsFromReader(manifest, reader)).findings;
+    const skills = (await validateSubmissionSkillMetadataFromReader(manifest, targetType, reader)).findings;
+    const checks = [
+        submissionCheck("listing", listing),
+        submissionCheck("components", components),
+        submissionCheck("assets", assets),
+        submissionCheck("skills", skills)
+    ];
+    const findings = [...listing, ...components, ...assets, ...skills];
+    const manual = manualChecklist();
+    const summary = reportSummary(checks, findings, manual);
+    return {
+        schemaVersion: "1.0.0",
+        rulesetVersion: "openai-directory-2026-08-15",
+        targetType,
+        status: summary.blockers > 0 ? "fail" : "pass",
+        readiness: summary.blockers > 0 ? "blocked" : "manual_review_required",
+        summary,
+        checks,
+        findings,
+        manualChecklist: manual
+    };
+}
+export function submissionArchiveExitCode(report, requireReady) {
+    return requireReady && report.status === "fail" ? 1 : 0;
+}
+export async function buildSubmissionArchivePreflight(archivePath) {
+    const inspection = await inspectSubmissionArchive(archivePath);
+    const coverage = [...inspection.coverage, ...archiveCoverage()];
+    const manual = manualChecklist();
+    const archiveFindings = [...inspection.findings];
+    let rootLayout = "unavailable";
+    let submission = null;
+    if (!archiveFindings.some((finding) => finding.severity === "fail") && inspection.reader !== null) {
+        const root = discoverRoot(inspection.entries);
+        archiveFindings.push(...root.findings);
+        if (root.discovery !== null) {
+            rootLayout = root.discovery.rootLayout;
+            const reader = rootedReader(inspection, root.discovery.rootPrefix);
+            const manifest = reader === null ? null : await parseManifest(reader, root.discovery.manifestPath.slice(root.discovery.rootPrefix.length));
+            if (manifest === null || reader === null) {
+                archiveFindings.push(archiveFinding("plugin.submission.archive.manifest_missing", "fail", "Plugin manifest must be a bounded UTF-8 JSON object."));
+            }
+            else {
+                const entries = inspection.entries
+                    .filter((entry) => entry.packagePath.startsWith(root.discovery.rootPrefix))
+                    .map((entry) => ({ ...entry, packagePath: entry.packagePath.slice(root.discovery.rootPrefix.length) }));
+                if (!hasImmediateSkill(entries)) {
+                    archiveFindings.push(archiveFinding("plugin.submission.archive.skill_missing", "fail", "Archive must contain an immediate skills/<skill>/SKILL.md entrypoint."));
+                }
+                archiveFindings.push(...exclusionFindings(manifest, entries));
+                submission = await nestedSubmission(manifest, reader);
+            }
+        }
+    }
+    const findings = [...archiveFindings, ...(submission?.findings ?? [])];
+    const blockers = findings.filter((finding) => finding.severity === "fail").length;
+    const summary = submission === null
+        ? { passed: 0, warnings: findings.filter((finding) => finding.severity === "warn").length, blockers, manualChecks: manual.filter((item) => item.state === "required").length }
+        : { ...submission.summary, warnings: findings.filter((finding) => finding.severity === "warn").length, blockers };
+    return {
+        schemaVersion: "1.0.0",
+        rulesetVersion: submissionArchiveRuleset.version,
+        status: blockers > 0 ? "fail" : "pass",
+        readiness: blockers > 0 ? "blocked" : "manual_review_required",
+        archive: {
+            fileName: inspection.fileName,
+            compressedBytes: inspection.compressedBytes,
+            uncompressedBytes: inspection.uncompressedBytes,
+            entryCount: inspection.entryCount,
+            rootLayout
+        },
+        summary,
+        archiveChecks: [],
+        submission,
+        findings,
+        coverage,
+        manualChecklist: manual
+    };
+}

package/dist/core/submission-archive-reader.d.ts

@@ -0,0 +1,21 @@
+import type { SubmissionPackageEntry, SubmissionPackageReader } from "./submission-package-reader.js";
+import type { SubmissionFinding } from "./submission-preflight.js";
+export interface SubmissionArchiveFinding extends SubmissionFinding {
+    id: `plugin.submission.archive.${string}`;
+}
+export interface SubmissionArchiveCoverage {
+    id: string;
+    status: "automatic" | "manual" | "unavailable";
+    reason: string;
+}
+export interface SubmissionArchiveInspection {
+    fileName: string;
+    compressedBytes: number;
+    uncompressedBytes: number;
+    entryCount: number;
+    entries: readonly SubmissionPackageEntry[];
+    findings: readonly SubmissionArchiveFinding[];
+    coverage: readonly SubmissionArchiveCoverage[];
+    reader: SubmissionPackageReader | null;
+}
+export declare function inspectSubmissionArchive(zipPath: string): Promise<SubmissionArchiveInspection>;