codex-plugin-doctor 1.59.0 → 1.60.0

package/README.md

@@ -131,21 +131,27 @@ codex-plugin-doctor registry preflight path/to/server.json --allow-network --req
 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).
-
-### 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
-```
-
-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).
+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:
 
@@ -493,9 +499,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.59.0
-        with:
-          version: "1.59.0"
+      - uses: Esquetta/CodexPluginDoctor@v1.60.0
+        with:
+          version: "1.60.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -507,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. 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).
+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

@@ -262,6 +262,68 @@ const publicSchemaDefinitions = [
             }
         }
     },
+    {
+        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

@@ -18,6 +18,7 @@ const topLevelCommands = [
     "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() {
@@ -30,6 +31,7 @@ function bashCompletion() {
         "",
         `  local commands="${topLevelCommands.join(" ")}"`,
         `  local doctor_commands="${doctorCommands.join(" ")}"`,
+        `  local submission_targets="${submissionTargets.join(" ")}"`,
         `  local submission_flags="${submissionFlags.join(" ")}"`,
         "",
         "  case \"${prev}\" in",
@@ -41,8 +43,25 @@ function bashCompletion() {
         "      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",
@@ -77,6 +96,8 @@ function zshCompletion() {
         "",
         "  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' \\",
@@ -108,6 +129,8 @@ function fishCompletion() {
         `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>;