codex-plugin-doctor 1.59.0 → 1.61.0

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

@@ -1,6 +1,6 @@
-import { lstat, opendir, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { isAlias, isNode, parseDocument, visit } from "yaml";
+import { createDirectorySubmissionPackageReader } from "./submission-package-reader.js";
 const maxSkillBytes = 1024 * 1024;
 const maxAgentBytes = 256 * 1024;
 const maxAggregateMetadataBytes = 16 * 1024 * 1024;
@@ -15,17 +15,8 @@ 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 };
+    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);
@@ -52,34 +43,53 @@ function parseSafeYaml(source) {
 }
 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 !match || match[2].trim().length === 0 ? null : { frontmatter: match[1], body: match[2] };
+}
+function skillsRoot(value) {
+    if (typeof value !== "string" || !value.startsWith("./") || value.includes("\\") || /[\u0000-\u001F\u007F]/u.test(value))
         return null;
-    return { frontmatter: match[1], body: match[2] };
+    const normalized = path.posix.normalize(value.slice(2)).replace(/\/$/u, "");
+    return normalized === "skills" ? normalized : null;
 }
-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 {
+function relativePackagePath(base, value) {
+    if (path.posix.isAbsolute(value) || /^[A-Za-z]:[\\/]/u.test(value))
         return null;
-    }
+    const resolved = path.posix.normalize(path.posix.join(base, value));
+    return resolved === ".." || resolved.startsWith("../") || resolved === "." ? null : resolved;
+}
+function normalizeResolvedPackagePath(value) {
+    if (typeof value !== "string" || value === "" || value.includes("\\") || path.posix.isAbsolute(value)
+        || /^[A-Za-z]:/u.test(value) || /[\u0000-\u001F\u007F]/u.test(value))
+        return null;
+    const normalized = path.posix.normalize(value);
+    if (normalized === "" || normalized === "." || normalized === ".." || normalized.startsWith("../"))
+        return null;
+    return normalized;
+}
+function isWithinPackagePath(root, candidate) {
+    return candidate === root || candidate.startsWith(`${root}/`);
 }
 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) {
+async function safeStat(reader, packagePath) {
+    return reader.stat(packagePath).catch(() => null);
+}
+async function readSafeUtf8(reader, packagePath, maximum, budget) {
+    const details = await safeStat(reader, packagePath);
+    if (details === null || details.safeResolution !== "safe" || details.resolvedKind !== "file" || details.size > maximum)
+        return { kind: "invalid" };
+    const nextBytes = budget.bytes + details.size;
+    if (nextBytes > maxAggregateMetadataBytes)
+        return { kind: "budget", nextBytes };
+    const bytes = await reader.read(packagePath, maximum).catch(() => null);
+    if (bytes === null || bytes.byteLength !== details.size)
+        return { kind: "invalid" };
     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)) };
+        return { kind: "source", source: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
     }
     catch {
         return { kind: "invalid" };
@@ -97,205 +107,176 @@ function isToolDescriptor(value) {
         && (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)) {
+async function validateIconPath(reader, skillRoot, skillPath, field, value) {
+    if (typeof value !== "string" || value.trim() !== value || !supportedText(value)) {
         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 {
+    const iconPath = relativePackagePath(skillRoot, value);
+    const details = iconPath === null ? null : await safeStat(reader, iconPath);
+    if (details === null || details.safeResolution !== "safe" || details.resolvedKind !== "file") {
         return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
     }
+    return null;
 }
-async function validateAgentFile(rootPath, skillRoot, skillPath, budget) {
-    const agentPath = path.join(skillRoot, "agents", "openai.yaml");
-    let agentDetails;
-    try {
-        agentDetails = await lstat(agentPath);
-    }
-    catch {
+async function validateAgentFile(reader, skillRoot, resolvedSkillRoot, budget) {
+    const skillPath = skillRoot;
+    const agentPath = `${skillRoot}/agents/openai.yaml`;
+    const agentDetails = await safeStat(reader, agentPath);
+    if (agentDetails === null)
         return [];
-    }
-    if (agentDetails.isSymbolicLink()) {
+    if (agentDetails.kind === "symlink") {
         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) })];
+    if (agentDetails.safeResolution === "outside") {
+        return [finding("plugin.submission.skill.agent.invalid_path", "Optional agent metadata resolves outside its skill.", { path: skillPath })];
     }
-    let canonicalRoot;
-    let canonicalSkill;
-    let canonicalAgent;
-    try {
-        [canonicalRoot, canonicalSkill, canonicalAgent] = await Promise.all([realpath(rootPath), realpath(skillRoot), realpath(agentPath)]);
+    if (agentDetails.safeResolution !== "safe") {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a readable regular file.", { path: agentPath })];
     }
-    catch {
-        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a readable regular file.", { path: packagePath(rootPath, agentPath) })];
+    if (agentDetails.resolvedKind !== "file") {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a regular file.", { path: agentPath })];
     }
-    if (!isWithin(canonicalRoot, canonicalAgent) || !isWithin(canonicalSkill, canonicalAgent)) {
+    const normalizedSkillRoot = normalizeResolvedPackagePath(resolvedSkillRoot);
+    const resolvedAgentPath = normalizeResolvedPackagePath(agentDetails.resolvedPackagePath ?? agentPath);
+    if (normalizedSkillRoot === null || resolvedAgentPath === null || !isWithinPackagePath(normalizedSkillRoot, resolvedAgentPath)) {
         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") {
+    const source = await readSafeUtf8(reader, 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 })];
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a bounded UTF-8 regular file.", { path: 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) })];
+        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: 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) })];
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an unsupported shape.", { path: 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" })];
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid brand color.", { path: 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" })];
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid default prompt.", { path: 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")))
+            || 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" })];
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent policy has an unsupported shape.", { path: 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" })];
+        || !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: 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)
+        const iconFinding = await validateIconPath(reader, skillRoot, skillPath, field, value);
+        if (iconFinding !== null)
             return [iconFinding];
     }
     return [];
 }
-export async function validateSubmissionSkillMetadata(discoveredPackage, targetType) {
-    const { manifest, rootPath } = discoveredPackage;
+export async function validateSubmissionSkillMetadataFromReader(manifest, targetType, reader) {
     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 };
+        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/") {
+    const root = skillsRoot(manifest.skills);
+    if (root === null) {
         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 rootDetails = await safeStat(reader, root);
+    if (rootDetails === null || rootDetails.safeResolution !== "safe" || rootDetails.resolvedKind !== "directory") {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory must be canonically contained in the package.", { path: root })], skillCount: 0 };
+    }
+    const listed = await reader.list(root).catch(() => null);
+    if (listed === null) {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory cannot be inspected safely.", { path: root })], 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 skillCount = 0;
     let skillDirectoryCount = 0;
-    for await (const entry of entries) {
-        entryCount += 1;
+    const entries = [...listed].sort((left, right) => left.packagePath.localeCompare(right.packagePath));
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const entryCount = index + 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())
+        const name = path.posix.basename(entry.packagePath);
+        if (path.posix.dirname(entry.packagePath) !== root || name.startsWith(".") || entry.resolvedKind !== "directory")
+            continue;
+        if (entry.safeResolution !== "safe" || entry.kind === "symlink") {
+            findings.push(finding("plugin.submission.skill.invalid_path", "Skill directory resolves outside the declared skills directory.", { path: entry.packagePath }));
             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) }));
+        const skillRoot = entry.packagePath;
+        const skillFile = `${skillRoot}/SKILL.md`;
+        const fileDetails = await safeStat(reader, skillFile);
+        if (fileDetails?.kind === "symlink" || fileDetails?.safeResolution === "outside") {
+            findings.push(finding("plugin.submission.skill.invalid_path", "Skill entrypoint must not be a symbolic link.", { path: skillFile }));
             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 }));
+        if (fileDetails === null || fileDetails.safeResolution !== "safe" || fileDetails.resolvedKind !== "file") {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a contained regular file.", { path: skillFile }));
             continue;
         }
-        const source = await readSafeUtf8(skillFile, maxSkillBytes, budget);
+        const source = await readSafeUtf8(reader, 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 }));
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a bounded UTF-8 regular file.", { path: skillFile, 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 }));
+        if (split === null) {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint requires delimited frontmatter and a nonempty body.", { path: skillFile }));
             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 }));
+            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: skillFile }));
             continue;
         }
-        const name = parsed.value.name;
+        const nameValue = parsed.value.name;
         const description = parsed.value.description;
-        const normalizedName = typeof name === "string" ? name.normalize("NFKC").trim() : "";
+        const normalizedName = typeof nameValue === "string" ? nameValue.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 }));
+        if (!supportedText(nameValue) || !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: skillFile, limit: 64 }));
             continue;
         }
         identities.add(normalizedName);
         skillCount += 1;
-        const agentFindings = await validateAgentFile(rootPath, skillRoot, packagePath(rootPath, skillRoot), budget);
+        const resolvedSkillRoot = entry.resolvedPackagePath ?? skillRoot;
+        const agentFindings = await validateAgentFile(reader, skillRoot, resolvedSkillRoot, 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")) {
+    if (targetType === "skills-only" && skillCount === 0) {
         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" }));
+        findings.push(finding("plugin.submission.skill.invalid_file", "Declared skills must include at least one valid immediate skill entrypoint.", { path: root }));
     }
     return { findings, skillCount };
 }
+export async function validateSubmissionSkillMetadata(discoveredPackage, targetType) {
+    return validateSubmissionSkillMetadataFromReader(discoveredPackage.manifest, targetType, createDirectorySubmissionPackageReader(discoveredPackage.rootPath));
+}

package/dist/index.d.ts

@@ -16,9 +16,11 @@ export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, C
 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 { buildSubmissionArchivePreflight, submissionArchiveExitCode, type SubmissionArchivePreflightReport, type SubmissionArchiveRootLayout } from "./core/submission-archive-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 { renderSubmissionArchiveJson, renderSubmissionArchiveMarkdown, renderSubmissionArchiveText } from "./reporting/render-submission-archive-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

@@ -16,9 +16,11 @@ export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, C
 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 { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./core/submission-archive-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 { renderSubmissionArchiveJson, renderSubmissionArchiveMarkdown, renderSubmissionArchiveText } from "./reporting/render-submission-archive-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-mcp-discovery-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpDiscoveryReport } from "../core/mcp-discovery.js";
+export declare function renderMcpDiscoveryReport(report: McpDiscoveryReport): string;

package/dist/reporting/render-mcp-discovery-report.js

@@ -0,0 +1,14 @@
+export function renderMcpDiscoveryReport(report) {
+    return [
+        "MCP Discovery",
+        "=============",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Requested protocol: ${report.requestedVersion}`,
+        `Advertised versions: ${report.supportedVersions.join(", ") || "not available"}`,
+        `Discovery response: ${report.coverage.discovery}`,
+        `Runtime: ${report.coverage.runtime}`,
+        "Discovery does not establish full protocol conformance or client compatibility.",
+        ...report.findings.map((finding) => `${finding.severity.toUpperCase()} ${finding.id}: ${finding.message}\n  ${finding.suggestedFix}`)
+    ].join("\n");
+}

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

@@ -0,0 +1,4 @@
+import type { SubmissionArchivePreflightReport } from "../core/submission-archive-preflight.js";
+export declare function renderSubmissionArchiveJson(report: SubmissionArchivePreflightReport): string;
+export declare function renderSubmissionArchiveText(report: SubmissionArchivePreflightReport): string;
+export declare function renderSubmissionArchiveMarkdown(report: SubmissionArchivePreflightReport): string;

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

@@ -0,0 +1,52 @@
+function upper(value) {
+    return value.replace(/[-_]/gu, " ").toUpperCase();
+}
+function escapeMarkdown(value) {
+    return value.replace(/[\\`*_{}\[\]()<>#+\-.!|]/gu, "\\$&");
+}
+function summary(report) {
+    return [
+        `Ruleset: ${report.rulesetVersion}`,
+        `Archive: ${report.archive.fileName}`,
+        `Root layout: ${report.archive.rootLayout}`,
+        `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 archive review."
+    ];
+}
+export function renderSubmissionArchiveJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+export function renderSubmissionArchiveText(report) {
+    const lines = ["Submission archive preflight", "============================", ...summary(report), "", "Findings"];
+    lines.push(...(report.findings.length === 0
+        ? ["  None"]
+        : report.findings.map((finding) => `  ${upper(finding.severity)} ${finding.id}: ${finding.message}`)));
+    lines.push("", "Coverage");
+    lines.push(...(report.coverage.length === 0
+        ? ["  None"]
+        : report.coverage.map((item) => `  ${upper(item.status)} ${item.id}: ${item.reason}`)));
+    lines.push("", "Manual checklist");
+    lines.push(...report.manualChecklist.map((item) => `  ${upper(item.state)} ${item.id}: ${item.label}`));
+    return `${lines.join("\n")}\n`;
+}
+export function renderSubmissionArchiveMarkdown(report) {
+    const lines = [
+        "# Submission archive preflight",
+        "",
+        ...summary(report).map((item) => `- ${escapeMarkdown(item)}`),
+        "",
+        "## Findings"
+    ];
+    lines.push(...(report.findings.length === 0
+        ? ["- None"]
+        : report.findings.map((finding) => `- **${escapeMarkdown(upper(finding.severity))}** ${escapeMarkdown(finding.id)}: ${escapeMarkdown(finding.message)}`)));
+    lines.push("", "## Coverage");
+    lines.push(...(report.coverage.length === 0
+        ? ["- None"]
+        : report.coverage.map((item) => `- ${escapeMarkdown(upper(item.status))}: ${escapeMarkdown(item.id)} — ${escapeMarkdown(item.reason)}`)));
+    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`;
+}

package/dist/run-cli.d.ts

@@ -1,3 +1,4 @@
+import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
 import { runCheck } from "./index.js";
 import { writeRawDoctorConfig } from "./index.js";
@@ -13,6 +14,7 @@ export interface CliTerminalContext {
     platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
+    discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;
     writeRawDoctorConfigImpl?: typeof writeRawDoctorConfig;