codex-plugin-doctor 1.57.0 → 1.59.0

package/LICENSE

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

package/README.md

@@ -131,8 +131,21 @@ 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).
+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).
 
 Output formats:
 
@@ -480,9 +493,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.57.0
-        with:
-          version: "1.57.0"
+      - uses: Esquetta/CodexPluginDoctor@v1.59.0
+        with:
+          version: "1.59.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -494,7 +507,7 @@ jobs:
           review-bundle-verify: "true"
 ```
 
-The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
+The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional validation corpus and quality metrics reports, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Set `submission: "true"` to add offline submission preflight reports; set `require-submission-ready: "true"` only with that opt-in to make automatic blockers fail the job. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus quality regression gates, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
 
 To self-test this repository after cloning it:
 
@@ -518,6 +531,7 @@ The validator is tuned against local fixtures and real marketplace-style plugin
 - [Real-World Validation Workflow](./docs/guides/real-world-validation.md)
 - [Examples](./examples/README.md)
 - [Rule Catalog](./docs/rules/catalog.md)
+- [Official Plugin Components](./docs/architecture/official-plugin-components.md)
 
 Recent validation waves covered:
 

package/dist/compatibility/claude-desktop-install-preview.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { getClaudeDesktopConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -38,16 +39,15 @@ export async function buildClaudeDesktopInstallPreview(targetPath, environment =
     if (!mcpConfigPath) {
         throw new Error("No MCP config found for install preview.");
     }
-    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
-    const servers = parsed.mcpServers;
-    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(JSON.parse(await readFile(mcpConfigPath, "utf8")));
+    if (!normalizedConfig.ok) {
         throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
     }
     return {
         targetPath: rootPath,
         configPath,
         snippet: {
-            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+            mcpServers: Object.fromEntries(Object.entries(normalizedConfig.servers).map(([serverName, serverConfig]) => [
                 serverName,
                 normalizeServerConfig(serverConfig, rootPath)
             ]))

package/dist/compatibility/cline-install-preview.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { getClineMcpConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -34,16 +35,15 @@ export async function buildClineInstallPreview(targetPath, environment = {}) {
     if (!mcpConfigPath) {
         throw new Error("No MCP config found for install preview.");
     }
-    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
-    const servers = parsed.mcpServers;
-    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(JSON.parse(await readFile(mcpConfigPath, "utf8")));
+    if (!normalizedConfig.ok) {
         throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
     }
     return {
         targetPath: rootPath,
         configPath: getClineMcpConfigPath(environment),
         snippet: {
-            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+            mcpServers: Object.fromEntries(Object.entries(normalizedConfig.servers).map(([serverName, serverConfig]) => [
                 serverName,
                 normalizeServerConfig(serverConfig, rootPath)
             ]))

package/dist/compatibility/compatibility-matrix.js

@@ -2,7 +2,9 @@ import { stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { validatePlugin } from "../core/validate-plugin.js";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { readJsonFile } from "../core/read-json-file.js";
+import { resolveContainedPackagePath } from "../core/package-path.js";
 async function fileExists(targetPath) {
     try {
         const details = await stat(targetPath);
@@ -30,16 +32,15 @@ function statusFromCheckResult(result) {
     }
     return "pass";
 }
-function isPathWithinRoot(rootPath, candidatePath) {
-    const relativePath = path.relative(rootPath, candidatePath);
-    return (relativePath === "" ||
-        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
-}
 export async function readMcpConfigPath(targetPath) {
     const rootPath = path.resolve(targetPath);
     const directMcpPath = path.join(rootPath, ".mcp.json");
     if (await fileExists(directMcpPath)) {
-        return directMcpPath;
+        const containedDirectMcpPath = await resolveContainedPackagePath(rootPath, directMcpPath);
+        if (!containedDirectMcpPath) {
+            throw new Error("MCP config path resolves outside the package root.");
+        }
+        return containedDirectMcpPath;
     }
     const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
     if (!(await fileExists(manifestPath))) {
@@ -55,8 +56,8 @@ export async function readMcpConfigPath(targetPath) {
     if (typeof manifest.mcpServers !== "string") {
         return null;
     }
-    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
-    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+    const mcpConfigPath = await resolveContainedPackagePath(rootPath, manifest.mcpServers);
+    if (!mcpConfigPath) {
         throw new Error("Manifest MCP config path resolves outside the package root.");
     }
     return mcpConfigPath;
@@ -87,11 +88,8 @@ async function checkGenericMcp(targetPath) {
     }
     try {
         const parsed = await readJsonFile(mcpConfigPath);
-        const servers = parsed.mcpServers;
-        if (typeof servers !== "object" ||
-            servers === null ||
-            Array.isArray(servers) ||
-            Object.keys(servers).length === 0) {
+        const normalizedConfig = normalizeMcpConfig(parsed);
+        if (!normalizedConfig.ok) {
             return {
                 client: "Generic MCP",
                 status: "fail",
@@ -122,10 +120,8 @@ async function readMcpServerNames(targetPath) {
     }
     try {
         const parsed = await readJsonFile(mcpConfigPath);
-        const servers = parsed.mcpServers;
-        return typeof servers === "object" && servers !== null && !Array.isArray(servers)
-            ? Object.keys(servers)
-            : [];
+        const normalizedConfig = normalizeMcpConfig(parsed);
+        return normalizedConfig.ok ? Object.keys(normalizedConfig.servers) : [];
     }
     catch {
         return [];

package/dist/compatibility/cursor-install-preview.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { getCursorMcpConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -34,16 +35,15 @@ export async function buildCursorInstallPreview(targetPath, environment = {}) {
     if (!mcpConfigPath) {
         throw new Error("No MCP config found for install preview.");
     }
-    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
-    const servers = parsed.mcpServers;
-    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(JSON.parse(await readFile(mcpConfigPath, "utf8")));
+    if (!normalizedConfig.ok) {
         throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
     }
     return {
         targetPath: rootPath,
         configPath: await getCursorMcpConfigPath(rootPath, environment),
         snippet: {
-            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+            mcpServers: Object.fromEntries(Object.entries(normalizedConfig.servers).map(([serverName, serverConfig]) => [
                 serverName,
                 normalizeServerConfig(serverConfig, rootPath)
             ]))

package/dist/compatibility/windsurf-install-preview.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { normalizeMcpConfig } from "../core/mcp-config-normalizer.js";
 import { getWindsurfMcpConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -34,16 +35,15 @@ export async function buildWindsurfInstallPreview(targetPath, environment = {})
     if (!mcpConfigPath) {
         throw new Error("No MCP config found for install preview.");
     }
-    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
-    const servers = parsed.mcpServers;
-    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(JSON.parse(await readFile(mcpConfigPath, "utf8")));
+    if (!normalizedConfig.ok) {
         throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
     }
     return {
         targetPath: rootPath,
         configPath: getWindsurfMcpConfigPath(environment),
         snippet: {
-            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+            mcpServers: Object.fromEntries(Object.entries(normalizedConfig.servers).map(([serverName, serverConfig]) => [
                 serverName,
                 normalizeServerConfig(serverConfig, rootPath)
             ]))

package/dist/core/doctor-size.js

@@ -15,6 +15,20 @@ const skippedDirs = new Set([
 const largeFileThreshold = 1024 * 1024;
 const packageSizeWarnThreshold = 10 * 1024 * 1024;
 const packageSizeFailThreshold = 50 * 1024 * 1024;
+function npmPackCommand() {
+    if (process.platform === "win32") {
+        const npmExecPath = process.env.npm_execpath;
+        // Only use the inherited npm CLI path when it is an absolute npm entrypoint.
+        const npmCliPath = npmExecPath && path.isAbsolute(npmExecPath) && path.basename(npmExecPath).toLowerCase() === "npm-cli.js"
+            ? npmExecPath
+            : path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+        return {
+            command: process.execPath,
+            args: [npmCliPath, "pack", "--dry-run"]
+        };
+    }
+    return { command: "npm", args: ["pack", "--dry-run"] };
+}
 function formatSize(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -79,7 +93,8 @@ export async function buildDoctorSize(targetPath, options = {}) {
     if (options.npmPack) {
         try {
             const packOutput = await new Promise((resolve, reject) => {
-                execFile("npm", ["pack", "--dry-run"], { cwd: resolvedPath, timeout: 30000, shell: process.platform === "win32" }, (error, stdout, stderr) => {
+                const npmPack = npmPackCommand();
+                execFile(npmPack.command, npmPack.args, { cwd: resolvedPath, timeout: 30000 }, (error, stdout, stderr) => {
                     if (error) {
                         reject(new Error(stderr.trim() || error.message));
                         return;

package/dist/core/init-plugin.js

@@ -162,8 +162,8 @@ export async function initPluginPackage(targetPath, options = {}) {
         name: packageName,
         version: "0.1.0",
         description: "A Codex plugin package scaffolded by Codex Plugin Doctor.",
-        skills: "skills",
-        ...(template === "skill-only" ? {} : { mcpServers: ".mcp.json" })
+        skills: "./skills",
+        ...(template === "skill-only" ? {} : { mcpServers: "./.mcp.json" })
     }, null, 2)}\n`, "utf8");
     await writeFile(skillPath, buildSkillMarkdown(template), "utf8");
     if (template === "mcp-stdio" || template === "full-runtime") {

package/dist/core/inspector-bridge.js

@@ -1,14 +1,8 @@
 import path from "node:path";
 import { readJsonFile } from "./read-json-file.js";
 import { discoverPackage } from "./discover-package.js";
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isPathWithinRoot(rootPath, candidatePath) {
-    const relativePath = path.relative(rootPath, candidatePath);
-    return (relativePath === "" ||
-        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
-}
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
+import { resolveContainedPackagePath } from "./package-path.js";
 function buildFailure(targetPath, message, mcpConfigPath = null) {
     return {
         schemaVersion: "1.0.0",
@@ -28,9 +22,9 @@ export async function buildDoctorInspectorReport(targetPath, options = {}) {
     if (!discoveredPackage?.manifest.mcpServers) {
         return buildFailure(targetPath, "The target package does not declare an MCP server config in `.codex-plugin/plugin.json`.");
     }
-    const mcpConfigPath = path.resolve(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers);
-    if (!isPathWithinRoot(discoveredPackage.rootPath, mcpConfigPath)) {
-        return buildFailure(discoveredPackage.rootPath, "The target package points the MCP server config outside the package root.", mcpConfigPath);
+    const mcpConfigPath = await resolveContainedPackagePath(discoveredPackage.rootPath, discoveredPackage.manifest.mcpServers);
+    if (!mcpConfigPath) {
+        return buildFailure(discoveredPackage.rootPath, "The target package points the MCP server config outside the package root.", null);
     }
     let parsedConfig;
     try {
@@ -39,10 +33,11 @@ export async function buildDoctorInspectorReport(targetPath, options = {}) {
     catch {
         return buildFailure(discoveredPackage.rootPath, "The MCP server config could not be parsed as JSON.", mcpConfigPath);
     }
-    if (!isPlainObject(parsedConfig) || !isPlainObject(parsedConfig.mcpServers)) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
         return buildFailure(discoveredPackage.rootPath, "The MCP server config does not contain a valid `mcpServers` object.", mcpConfigPath);
     }
-    const serverNames = Object.keys(parsedConfig.mcpServers).sort();
+    const serverNames = Object.keys(normalizedConfig.servers).sort();
     const selectedServerName = options.serverName ?? serverNames[0] ?? null;
     if (!selectedServerName || !serverNames.includes(selectedServerName)) {
         return buildFailure(discoveredPackage.rootPath, options.serverName

package/dist/core/mcp-config-normalizer.d.ts

@@ -0,0 +1,18 @@
+export type McpServerConfig = Record<string, unknown>;
+export type McpServerMap = Record<string, McpServerConfig>;
+export type McpConfigLayout = "direct" | "snake_case_wrapper" | "camel_case_wrapper";
+export type McpConfigNormalizationResult = {
+    ok: true;
+    layout: McpConfigLayout;
+    servers: McpServerMap;
+} | {
+    ok: false;
+    reason: "ambiguous_shape";
+    field: "root";
+} | {
+    ok: false;
+    reason: "invalid_shape";
+    field: "root" | "mcp_servers" | "mcpServers" | "server";
+    invalidServerNames?: string[];
+};
+export declare function normalizeMcpConfig(value: unknown): McpConfigNormalizationResult;

package/dist/core/mcp-config-normalizer.js

@@ -0,0 +1,50 @@
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function normalizeServerMap(value, field, layout) {
+    if (!isPlainObject(value) || Object.keys(value).length === 0) {
+        return { ok: false, reason: "invalid_shape", field };
+    }
+    const invalidServerNames = [];
+    const servers = Object.create(null);
+    for (const [name, server] of Object.entries(value)) {
+        if (!isPlainObject(server)) {
+            invalidServerNames.push(name);
+        }
+        else {
+            servers[name] = server;
+        }
+    }
+    if (invalidServerNames.length > 0) {
+        return {
+            ok: false,
+            reason: "invalid_shape",
+            field: "server",
+            invalidServerNames: invalidServerNames.sort()
+        };
+    }
+    return { ok: true, layout, servers };
+}
+export function normalizeMcpConfig(value) {
+    if (!isPlainObject(value)) {
+        return { ok: false, reason: "invalid_shape", field: "root" };
+    }
+    const hasSnakeCaseWrapper = Object.hasOwn(value, "mcp_servers");
+    const hasCamelCaseWrapper = Object.hasOwn(value, "mcpServers");
+    if (hasSnakeCaseWrapper && hasCamelCaseWrapper) {
+        return { ok: false, reason: "ambiguous_shape", field: "root" };
+    }
+    if (hasSnakeCaseWrapper || hasCamelCaseWrapper) {
+        if (Object.keys(value).length !== 1) {
+            return { ok: false, reason: "ambiguous_shape", field: "root" };
+        }
+        return hasSnakeCaseWrapper
+            ? normalizeServerMap(value.mcp_servers, "mcp_servers", "snake_case_wrapper")
+            : normalizeServerMap(value.mcpServers, "mcpServers", "camel_case_wrapper");
+    }
+    return normalizeServerMap(value, "root", "direct");
+}

package/dist/core/output-contract.js

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

package/dist/core/package-path.d.ts

@@ -0,0 +1 @@
+export declare function resolveContainedPackagePath(rootPath: string, candidatePath: string): Promise<string | null>;

package/dist/core/package-path.js

@@ -0,0 +1,25 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+export async function resolveContainedPackagePath(rootPath, candidatePath) {
+    const resolvedRootPath = path.resolve(rootPath);
+    const resolvedCandidatePath = path.resolve(resolvedRootPath, candidatePath);
+    if (!isPathWithinRoot(resolvedRootPath, resolvedCandidatePath)) {
+        return null;
+    }
+    try {
+        const [canonicalRootPath, canonicalCandidatePath] = await Promise.all([
+            realpath(resolvedRootPath),
+            realpath(resolvedCandidatePath)
+        ]);
+        return isPathWithinRoot(canonicalRootPath, canonicalCandidatePath)
+            ? resolvedCandidatePath
+            : null;
+    }
+    catch {
+        return resolvedCandidatePath;
+    }
+}

package/dist/core/plugin-components.d.ts

@@ -0,0 +1,7 @@
+import type { DiscoveredPackage, Finding } from "../domain/types.js";
+export interface SafePackagePath {
+    path: string;
+    packagePath: string;
+}
+export declare function resolveSafePackagePath(rootPath: string, value: string): Promise<SafePackagePath | null>;
+export declare function validatePluginComponents(discoveredPackage: DiscoveredPackage): Promise<Finding[]>;