codex-plugin-doctor 1.58.0 → 1.59.0

package/dist/core/submission-skill-metadata.js

@@ -0,0 +1,301 @@
+import { lstat, opendir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { isAlias, isNode, parseDocument, visit } from "yaml";
+const maxSkillBytes = 1024 * 1024;
+const maxAgentBytes = 256 * 1024;
+const maxAggregateMetadataBytes = 16 * 1024 * 1024;
+const maxDirectoryEntries = 256;
+const maxSkillDirectories = 100;
+const unsupportedText = /[\u0000-\u001F\u007F\u2028\u2029\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/u;
+const interfaceKeys = new Set(["display_name", "short_description", "icon_small", "icon_large", "brand_color", "default_prompt"]);
+const policyKeys = new Set(["products", "allow_implicit_invocation"]);
+const dependencyKeys = new Set(["tools"]);
+const toolDescriptorKeys = new Set(["type", "value", "description", "transport", "url"]);
+const agentKeys = new Set(["interface", "policy", "dependencies"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isWithin(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function packagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).split(path.sep).join("/");
+}
+function finding(id, message, evidence) {
+    return evidence === undefined
+        ? { id, severity: "fail", message }
+        : { id, severity: "fail", message, evidence };
+}
+function supportedText(value, limit = Number.MAX_SAFE_INTEGER) {
+    return typeof value === "string" && value.trim().length > 0 && value.length <= limit && !unsupportedText.test(value);
+}
+function parseSafeYaml(source) {
+    const document = parseDocument(source, { schema: "core", uniqueKeys: true, strict: true, prettyErrors: false });
+    let alias = false;
+    let nonCoreTag = false;
+    visit(document, (_key, node) => {
+        if (isAlias(node))
+            alias = true;
+        if (isNode(node) && node.tag !== undefined && !node.tag.startsWith("tag:yaml.org,2002:"))
+            nonCoreTag = true;
+    });
+    if (document.errors.length > 0 || alias || nonCoreTag)
+        return { error: "yaml" };
+    try {
+        const value = document.toJS({ maxAliasCount: 0 });
+        return isRecord(value) ? { value } : { error: "shape" };
+    }
+    catch {
+        return { error: "yaml" };
+    }
+}
+function splitSkillFile(source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/u.exec(source);
+    if (!match || match[2].trim().length === 0)
+        return null;
+    return { frontmatter: match[1], body: match[2] };
+}
+async function safeDirectory(rootPath, skillsPath) {
+    try {
+        const [canonicalRoot, canonicalSkills, details] = await Promise.all([realpath(rootPath), realpath(skillsPath), stat(skillsPath)]);
+        return details.isDirectory() && isWithin(canonicalRoot, canonicalSkills) ? { canonicalRoot, canonicalSkills } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function budgetFinding(bytes) {
+    return finding("plugin.submission.skill.budget_exceeded", "Skill metadata exceeds the aggregate submission preflight size limit.", {
+        count: bytes, limit: maxAggregateMetadataBytes
+    });
+}
+async function readSafeUtf8(filePath, maximum, budget) {
+    try {
+        const details = await stat(filePath);
+        if (!details.isFile() || details.size > maximum)
+            return { kind: "invalid" };
+        const nextBytes = budget.bytes + details.size;
+        if (nextBytes > maxAggregateMetadataBytes)
+            return { kind: "budget", nextBytes };
+        budget.bytes = nextBytes;
+        return { kind: "source", source: new TextDecoder("utf-8", { fatal: true }).decode(await readFile(filePath)) };
+    }
+    catch {
+        return { kind: "invalid" };
+    }
+}
+function rejectUnknownKeys(value, allowed) {
+    return Object.keys(value).some((key) => !allowed.has(key));
+}
+function isToolDescriptor(value) {
+    return isRecord(value) && !rejectUnknownKeys(value, toolDescriptorKeys)
+        && (value.type === "mcp" || value.type === "cli")
+        && (value.type !== "cli" || (value.transport === undefined && value.url === undefined))
+        && supportedText(value.value)
+        && (value.description === undefined || supportedText(value.description))
+        && (value.transport === undefined || supportedText(value.transport))
+        && (value.url === undefined || supportedText(value.url));
+}
+async function validateIconPath(rootPath, canonicalRoot, skillRoot, skillPath, field, value) {
+    if (typeof value !== "string" || value.trim() !== value || !supportedText(value)
+        || path.isAbsolute(value) || /^[A-Za-z]:[\\/]/u.test(value)) {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+    const iconPath = path.resolve(skillRoot, value);
+    if (!isWithin(rootPath, iconPath)) {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+    try {
+        const [canonicalIcon, details] = await Promise.all([realpath(iconPath), stat(iconPath)]);
+        if (!details.isFile() || !isWithin(canonicalRoot, canonicalIcon))
+            throw new Error("unsafe icon");
+        return null;
+    }
+    catch {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+}
+async function validateAgentFile(rootPath, skillRoot, skillPath, budget) {
+    const agentPath = path.join(skillRoot, "agents", "openai.yaml");
+    let agentDetails;
+    try {
+        agentDetails = await lstat(agentPath);
+    }
+    catch {
+        return [];
+    }
+    if (agentDetails.isSymbolicLink()) {
+        return [finding("plugin.submission.skill.agent.invalid_path", "Optional agent metadata must not be a symbolic link.", { path: skillPath })];
+    }
+    if (!agentDetails.isFile()) {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a regular file.", { path: packagePath(rootPath, agentPath) })];
+    }
+    let canonicalRoot;
+    let canonicalSkill;
+    let canonicalAgent;
+    try {
+        [canonicalRoot, canonicalSkill, canonicalAgent] = await Promise.all([realpath(rootPath), realpath(skillRoot), realpath(agentPath)]);
+    }
+    catch {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a readable regular file.", { path: packagePath(rootPath, agentPath) })];
+    }
+    if (!isWithin(canonicalRoot, canonicalAgent) || !isWithin(canonicalSkill, canonicalAgent)) {
+        return [finding("plugin.submission.skill.agent.invalid_path", "Optional agent metadata resolves outside its skill.", { path: skillPath })];
+    }
+    const source = await readSafeUtf8(agentPath, maxAgentBytes, budget);
+    if (source.kind === "budget") {
+        return [budgetFinding(source.nextBytes)];
+    }
+    if (source.kind === "invalid") {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a bounded UTF-8 regular file.", { path: packagePath(rootPath, agentPath), limit: maxAgentBytes })];
+    }
+    const parsed = parseSafeYaml(source.source);
+    if ("error" in parsed) {
+        return [finding(parsed.error === "yaml" ? "plugin.submission.skill.agent.invalid_yaml" : "plugin.submission.skill.agent.invalid_shape", "Optional agent metadata must be a safe YAML mapping.", { path: packagePath(rootPath, agentPath) })];
+    }
+    const metadata = parsed.value;
+    if (rejectUnknownKeys(metadata, agentKeys) || !isRecord(metadata.interface) || rejectUnknownKeys(metadata.interface, interfaceKeys)
+        || !supportedText(metadata.interface.display_name) || !supportedText(metadata.interface.short_description)) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an unsupported shape.", { path: packagePath(rootPath, agentPath) })];
+    }
+    if (metadata.interface.brand_color !== undefined && (typeof metadata.interface.brand_color !== "string" || !/^#[0-9A-Fa-f]{6}$/u.test(metadata.interface.brand_color))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid brand color.", { path: packagePath(rootPath, agentPath), field: "brand_color" })];
+    }
+    if (metadata.interface.default_prompt !== undefined && !supportedText(metadata.interface.default_prompt)) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid default prompt.", { path: packagePath(rootPath, agentPath), field: "default_prompt" })];
+    }
+    if (metadata.policy !== undefined && (!isRecord(metadata.policy) || rejectUnknownKeys(metadata.policy, policyKeys)
+        || (metadata.policy.products !== undefined && (!Array.isArray(metadata.policy.products) || metadata.policy.products.length === 0
+            || new Set(metadata.policy.products).size !== metadata.policy.products.length
+            || metadata.policy.products.some((product) => product !== "CHAT" && product !== "CODEX")))
+        || (metadata.policy.allow_implicit_invocation !== undefined && typeof metadata.policy.allow_implicit_invocation !== "boolean"))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent policy has an unsupported shape.", { path: packagePath(rootPath, agentPath), field: "policy" })];
+    }
+    if (metadata.dependencies !== undefined && (!isRecord(metadata.dependencies) || rejectUnknownKeys(metadata.dependencies, dependencyKeys)
+        || !Array.isArray(metadata.dependencies.tools) || metadata.dependencies.tools.length === 0
+        || metadata.dependencies.tools.some((tool) => !isToolDescriptor(tool)))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent dependencies have an unsupported shape.", { path: packagePath(rootPath, agentPath), field: "dependencies" })];
+    }
+    for (const field of ["icon_small", "icon_large"]) {
+        const value = metadata.interface[field];
+        if (value === undefined)
+            continue;
+        const iconFinding = await validateIconPath(rootPath, canonicalRoot, skillRoot, skillPath, field, value);
+        if (iconFinding)
+            return [iconFinding];
+    }
+    return [];
+}
+export async function validateSubmissionSkillMetadata(discoveredPackage, targetType) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (manifest.skills === undefined) {
+        return targetType === "skills-only"
+            ? { findings: [finding("plugin.submission.skill.required", "Skills-only submissions require a valid skill.")], skillCount: 0 }
+            : { findings: [], skillCount: 0 };
+    }
+    if (manifest.skills !== "./skills" && manifest.skills !== "./skills/") {
+        return { findings: [finding("plugin.submission.skill.invalid_manifest", "Skills must be declared as the root ./skills directory.", { field: "skills" })], skillCount: 0 };
+    }
+    const skillsPath = path.resolve(rootPath, manifest.skills);
+    const safe = await safeDirectory(rootPath, skillsPath);
+    if (!safe) {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory must be canonically contained in the package.", { path: "skills" })], skillCount: 0 };
+    }
+    const findings = [];
+    const identities = new Set();
+    let skillCount = 0;
+    const budget = { bytes: 0 };
+    let entries;
+    try {
+        entries = await opendir(skillsPath);
+    }
+    catch {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory cannot be inspected safely.", { path: "skills" })], skillCount: 0 };
+    }
+    let entryCount = 0;
+    let skillDirectoryCount = 0;
+    for await (const entry of entries) {
+        entryCount += 1;
+        if (entryCount > maxDirectoryEntries) {
+            findings.push(finding("plugin.submission.skill.too_many", "Skills directory exceeds the submission preflight entry limit.", { count: entryCount, limit: maxDirectoryEntries }));
+            break;
+        }
+        if (entry.name.startsWith(".") || !entry.isDirectory())
+            continue;
+        skillDirectoryCount += 1;
+        if (skillDirectoryCount > maxSkillDirectories) {
+            findings.push(finding("plugin.submission.skill.too_many", "Skills directory exceeds the submission preflight skill limit.", { count: skillDirectoryCount, limit: maxSkillDirectories }));
+            break;
+        }
+        const skillRoot = path.join(skillsPath, entry.name);
+        const skillFile = path.join(skillRoot, "SKILL.md");
+        const relativeSkillPath = packagePath(rootPath, skillFile);
+        let canonicalSkill;
+        try {
+            canonicalSkill = await realpath(skillRoot);
+            if (!isWithin(safe.canonicalSkills, canonicalSkill))
+                throw new Error("unsafe skill root");
+        }
+        catch {
+            findings.push(finding("plugin.submission.skill.invalid_path", "Skill directory resolves outside the declared skills directory.", { path: packagePath(rootPath, skillRoot) }));
+            continue;
+        }
+        try {
+            const details = await lstat(skillFile);
+            if (details.isSymbolicLink()) {
+                findings.push(finding("plugin.submission.skill.invalid_path", "Skill entrypoint must not be a symbolic link.", { path: relativeSkillPath }));
+                continue;
+            }
+            if (!details.isFile() || !isWithin(canonicalSkill, await realpath(skillFile))) {
+                findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a contained regular file.", { path: relativeSkillPath }));
+                continue;
+            }
+        }
+        catch {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a contained regular file.", { path: relativeSkillPath }));
+            continue;
+        }
+        const source = await readSafeUtf8(skillFile, maxSkillBytes, budget);
+        if (source.kind === "budget") {
+            findings.push(budgetFinding(source.nextBytes));
+            break;
+        }
+        if (source.kind === "invalid") {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a bounded UTF-8 regular file.", { path: relativeSkillPath, limit: maxSkillBytes }));
+            continue;
+        }
+        const split = splitSkillFile(source.source);
+        if (!split) {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint requires delimited frontmatter and a nonempty body.", { path: relativeSkillPath }));
+            continue;
+        }
+        const parsed = parseSafeYaml(split.frontmatter);
+        if ("error" in parsed) {
+            findings.push(finding(parsed.error === "yaml" ? "plugin.submission.skill.invalid_yaml" : "plugin.submission.skill.invalid_shape", "Skill frontmatter must be a safe YAML mapping.", { path: relativeSkillPath }));
+            continue;
+        }
+        const name = parsed.value.name;
+        const description = parsed.value.description;
+        const normalizedName = typeof name === "string" ? name.normalize("NFKC").trim() : "";
+        const pluginName = typeof manifest.name === "string" ? manifest.name.normalize("NFKC").trim() : "";
+        if (!supportedText(name) || !supportedText(description, 1024) || normalizedName.length === 0
+            || `${pluginName}:${normalizedName}`.length > 64 || identities.has(normalizedName)) {
+            findings.push(finding("plugin.submission.skill.identity", "Skill identity metadata is invalid or duplicated.", { path: relativeSkillPath, limit: 64 }));
+            continue;
+        }
+        identities.add(normalizedName);
+        skillCount += 1;
+        const agentFindings = await validateAgentFile(rootPath, skillRoot, packagePath(rootPath, skillRoot), budget);
+        findings.push(...agentFindings);
+        if (agentFindings.some((item) => item.id === "plugin.submission.skill.budget_exceeded"))
+            break;
+    }
+    if (targetType === "skills-only" && skillCount === 0 && !findings.some((item) => item.id === "plugin.submission.skill.required")) {
+        findings.push(finding("plugin.submission.skill.required", "Skills-only submissions require at least one valid skill.", { count: 0 }));
+    }
+    if (targetType === "mcp-backed" && skillCount === 0 && findings.length === 0) {
+        findings.push(finding("plugin.submission.skill.invalid_file", "Declared skills must include at least one valid immediate skill entrypoint.", { path: "skills" }));
+    }
+    return { findings, skillCount };
+}

package/dist/index.d.ts

@@ -14,6 +14,11 @@ export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest, type BuildExternalValidationCorpusOptions, type ExternalCorpusCaseResult, type ExternalCorpusClassificationCounts, type ExternalCorpusFindingReview, type ExternalCorpusManifest, type ExternalCorpusMode, type ExternalCorpusProfile, type ExternalCorpusSourceType, type ExternalValidationCorpusReport, type FindingReviewClassification } from "./core/external-validation-corpus.js";
 export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, loadCorpusMetricsManifest, reconcileCorpusMetricFindings, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText, type BuildCorpusMetricsDiffOptions, type BuildCorpusMetricsOptions, type CorpusMetricCounts, type CorpusMetricCountDeltas, type CorpusMetricFinding, type CorpusMetricFindingReview, type CorpusMetricReconciliation, type CorpusMetricsManifest, type CorpusMetricSource, type CorpusMetricThresholdCheck, type CorpusMetricThresholds, type CorpusMetricValues, type CorpusMetricValueComparison, type CorpusQualityMetricsDiffReport, type CorpusQualityMetricsDiffTarget, type CorpusQualityMetricsReport, type CorpusQualityMetricsTargetResult } from "./core/corpus-quality-metrics.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson, type DoctorOutputContract, type OutputContractRule, type OutputContractSchema } from "./core/output-contract.js";
+export { submissionRuleset, submissionManualChecks } from "./core/submission-ruleset.js";
+export { buildSubmissionPreflight, type SubmissionCheck, type SubmissionFinding, type SubmissionManualCheck, type SubmissionPreflightReport } from "./core/submission-preflight.js";
+export { validateSubmissionAssets, type SubmissionAssetResult } from "./core/submission-assets.js";
+export { validateSubmissionSkillMetadata, type SubmissionSkillMetadataResult } from "./core/submission-skill-metadata.js";
+export { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport, type BuildDoctorValidationCorpusOptions, type DoctorValidationCorpusReport, type ValidationCorpusCaseDefinition, type ValidationCorpusCaseResult } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";

package/dist/index.js

@@ -14,6 +14,11 @@ export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest } from "./core/external-validation-corpus.js";
 export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, loadCorpusMetricsManifest, reconcileCorpusMetricFindings, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText } from "./core/corpus-quality-metrics.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
+export { submissionRuleset, submissionManualChecks } from "./core/submission-ruleset.js";
+export { buildSubmissionPreflight } from "./core/submission-preflight.js";
+export { validateSubmissionAssets } from "./core/submission-assets.js";
+export { validateSubmissionSkillMetadata } from "./core/submission-skill-metadata.js";
+export { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";

package/dist/reporting/render-submission-report.d.ts

@@ -0,0 +1,5 @@
+import type { SubmissionPreflightReport } from "../core/submission-preflight.js";
+export declare function renderSubmissionPreflightJson(report: SubmissionPreflightReport): string;
+export declare function renderSubmissionPreflightText(report: SubmissionPreflightReport): string;
+export declare function renderSubmissionPreflightMarkdown(report: SubmissionPreflightReport): string;
+export declare function submissionPreflightExitCode(report: SubmissionPreflightReport, requireReady: boolean): 0 | 1;

package/dist/reporting/render-submission-report.js

@@ -0,0 +1,68 @@
+function upper(value) {
+    return value.replace(/[-_]/gu, " ").toUpperCase();
+}
+function findingsByCheck(report) {
+    const findings = new Map(report.findings.map((finding) => [finding.id, finding]));
+    return report.checks.map((check) => ({
+        check,
+        findings: check.findingIds.flatMap((id) => {
+            const finding = findings.get(id);
+            return finding ? [finding] : [];
+        })
+    }));
+}
+function escapeMarkdown(value) {
+    return value.replace(/[\\`*_{}\[\]()<>#+\-.!|]/gu, "\\$&");
+}
+function textSummary(report) {
+    return [
+        `Ruleset: ${report.rulesetVersion}`,
+        `Target: ${report.targetType}`,
+        `Automatic status: ${upper(report.status)}`,
+        `Readiness: ${upper(report.readiness)}`,
+        `Summary: ${report.summary.passed} passed, ${report.summary.warnings} warnings, ${report.summary.blockers} blockers, ${report.summary.manualChecks} manual checks`,
+        "Manual review is required; automatic checks do not complete directory review."
+    ];
+}
+export function renderSubmissionPreflightJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+export function renderSubmissionPreflightText(report) {
+    const lines = ["Submission preflight", "====================", ...textSummary(report), "", "Findings by check"];
+    for (const { check, findings } of findingsByCheck(report)) {
+        lines.push(`${check.id} (${upper(check.status)})`);
+        lines.push(...(findings.length === 0
+            ? ["  None"]
+            : findings.map((finding) => `  ${upper(finding.severity)} ${finding.id}: ${finding.message}`)));
+    }
+    lines.push("", "Manual checklist");
+    lines.push(...report.manualChecklist.map((item) => `  ${upper(item.state)} ${item.id}: ${item.label}`));
+    return `${lines.join("\n")}\n`;
+}
+export function renderSubmissionPreflightMarkdown(report) {
+    const lines = [
+        "# Submission preflight",
+        "",
+        `- Ruleset: ${escapeMarkdown(report.rulesetVersion)}`,
+        `- Target: ${escapeMarkdown(report.targetType)}`,
+        `- Automatic status: ${escapeMarkdown(upper(report.status))}`,
+        `- Readiness: ${escapeMarkdown(upper(report.readiness))}`,
+        `- Summary: ${report.summary.passed} passed, ${report.summary.warnings} warnings, ${report.summary.blockers} blockers, ${report.summary.manualChecks} manual checks`,
+        "",
+        "Manual review is required; automatic checks do not complete directory review.",
+        "",
+        "## Findings by check"
+    ];
+    for (const { check, findings } of findingsByCheck(report)) {
+        lines.push("", `### ${escapeMarkdown(check.id)} (${escapeMarkdown(upper(check.status))})`);
+        lines.push(...(findings.length === 0
+            ? ["- None"]
+            : findings.map((finding) => `- **${escapeMarkdown(upper(finding.severity))}** ${escapeMarkdown(finding.id)}: ${escapeMarkdown(finding.message)}`)));
+    }
+    lines.push("", "## Manual checklist");
+    lines.push(...report.manualChecklist.map((item) => `- ${escapeMarkdown(upper(item.state))}: ${escapeMarkdown(item.id)} — ${escapeMarkdown(item.label)}`));
+    return `${lines.join("\n")}\n`;
+}
+export function submissionPreflightExitCode(report, requireReady) {
+    return requireReady && report.status === "fail" ? 1 : 0;
+}

package/dist/run-cli.js

@@ -19,6 +19,7 @@ import { buildDoctorRecommendations, renderDoctorRecommendations, renderDoctorRe
 import { buildDoctorExportBundle, renderDoctorExportBundle, renderDoctorExportBundleJson } from "./core/doctor-export-bundle.js";
 import { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestationJson, renderDoctorAttestationVerification, renderDoctorAttestationVerificationJson, verifyDoctorAttestation } from "./core/attestation.js";
 import { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
+import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 import { buildExternalValidationCorpusReport, ExternalCorpusManifestError } from "./core/external-validation-corpus.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText } from "./core/corpus-quality-metrics.js";
@@ -57,6 +58,7 @@ import { renderSuppressionList, renderSuppressionListJson, renderSuppressionMuta
 import { renderRuleExplanation } from "./reporting/render-rule-explanation.js";
 import { renderSarifReport } from "./reporting/render-sarif-report.js";
 import { renderTextReport } from "./reporting/render-text-report.js";
+import { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 import { applyPolicyToDepAudit, applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 import { findRuleDefinition } from "./rules/rule-catalog.js";
 import { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
@@ -86,6 +88,13 @@ const defaultIo = {
         }
     }
 };
+function writeExactStdout(io, message) {
+    if (io === defaultIo) {
+        process.stdout.write(message);
+        return;
+    }
+    io.writeStdout(message);
+}
 class CliUsageError extends Error {
 }
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
@@ -177,6 +186,7 @@ function printUsage(io) {
     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>");
     io.writeStderr("Remote MCP runtime flags (check, mcp, release check, and doctor release-evidence): --runtime --allow-network [--allow-local-network] [--allow-session-lifecycle] [--require-remote-reliability]\n       --allow-session-lifecycle requires --runtime --allow-network and can terminate a remote session.\n       --require-remote-reliability requires --runtime --allow-network, blocks non-pass reliability, and does not grant network consent.");
+    io.writeStderr("       codex-plugin-doctor doctor submission <path> [--json|--markdown] [--output <path>] [--require-ready]");
 }
 const suppressUsageText = [
     "Usage:",
@@ -970,6 +980,74 @@ function parseSelectedFixActionIndexes(answer, actionCount) {
         ? actionIndexes
         : null;
 }
+function parseSubmissionCommandArgs(args) {
+    let targetPath = null;
+    let jsonOutput = false;
+    let markdownOutput = false;
+    let outputPath = null;
+    let requireReady = false;
+    let optionsEnded = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--" && !optionsEnded) {
+            optionsEnded = true;
+        }
+        else if (optionsEnded) {
+            if (targetPath === null) {
+                targetPath = argument;
+            }
+            else {
+                return new CliUsageError(`Unexpected submission argument: ${argument}.`);
+            }
+        }
+        else if (argument === "--json") {
+            if (jsonOutput)
+                return new CliUsageError("Duplicate submission flag: --json.");
+            jsonOutput = true;
+        }
+        else if (argument === "--markdown") {
+            if (markdownOutput)
+                return new CliUsageError("Duplicate submission flag: --markdown.");
+            markdownOutput = true;
+        }
+        else if (argument === "--require-ready") {
+            if (requireReady)
+                return new CliUsageError("Duplicate submission flag: --require-ready.");
+            requireReady = true;
+        }
+        else if (argument === "--output") {
+            if (outputPath !== null)
+                return new CliUsageError("Duplicate submission flag: --output.");
+            const value = args[index + 1];
+            if (!value || value.startsWith("--"))
+                return new CliUsageError("Missing path after --output.");
+            outputPath = value;
+            index += 1;
+        }
+        else if (argument.startsWith("--output=")) {
+            if (outputPath !== null)
+                return new CliUsageError("Duplicate submission flag: --output.");
+            const value = argument.slice("--output=".length);
+            if (!value)
+                return new CliUsageError("Missing path after --output.");
+            outputPath = value;
+        }
+        else if (argument.startsWith("--")) {
+            return new CliUsageError(`Unknown submission flag: ${argument}.`);
+        }
+        else if (targetPath === null) {
+            targetPath = argument;
+        }
+        else {
+            return new CliUsageError(`Unexpected submission argument: ${argument}.`);
+        }
+    }
+    if (targetPath === null)
+        return new CliUsageError("Missing target path for submission.");
+    if (jsonOutput && markdownOutput)
+        return new CliUsageError("Use either --json or --markdown, not both.");
+    return { targetPath, jsonOutput, markdownOutput, outputPath, requireReady };
+}
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
     const runtimeSandboxSupported = (command === "check" &&
@@ -1079,6 +1157,24 @@ export async function runCli(args, io = defaultIo, options = {}) {
                 : renderDoctorOutputContract(contract, { outputPath }));
             return 0;
         }
+        if (maybePath === "submission") {
+            const parsedSubmissionArgs = parseSubmissionCommandArgs(remainingArgs);
+            if (parsedSubmissionArgs instanceof CliUsageError) {
+                io.writeStderr(parsedSubmissionArgs.message);
+                return 2;
+            }
+            const report = await buildSubmissionPreflight(parsedSubmissionArgs.targetPath);
+            const renderedReport = parsedSubmissionArgs.jsonOutput
+                ? renderSubmissionPreflightJson(report)
+                : parsedSubmissionArgs.markdownOutput
+                    ? renderSubmissionPreflightMarkdown(report)
+                    : renderSubmissionPreflightText(report);
+            if (parsedSubmissionArgs.outputPath) {
+                await writeFile(parsedSubmissionArgs.outputPath, renderedReport, "utf8");
+            }
+            writeExactStdout(io, renderedReport);
+            return submissionPreflightExitCode(report, parsedSubmissionArgs.requireReady);
+        }
         if (maybePath === "mcp") {
             const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--")
                 ? remainingArgs[0]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.58.0",
+  "version": "1.59.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,5 +60,9 @@
     "tsx": "^4.20.4",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.11.0",
+    "yaml": "^2.9.0"
   }
 }