codex-plugin-doctor 1.57.0 → 1.58.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

@@ -480,9 +480,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.57.0
+      - uses: Esquetta/CodexPluginDoctor@v1.58.0
         with:
-          version: "1.57.0"
+          version: "1.58.0"
           path: .
           runtime: "true"
           policy: codex-publish
@@ -518,6 +518,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/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[]>;

package/dist/core/plugin-components.js

@@ -0,0 +1,169 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+const interfaceStringFields = [
+    "displayName",
+    "shortDescription",
+    "longDescription",
+    "developerName",
+    "category",
+    "websiteURL",
+    "privacyPolicyURL",
+    "termsOfServiceURL",
+    "brandColor"
+];
+const interfaceUrlFields = new Set(["websiteURL", "privacyPolicyURL", "termsOfServiceURL"]);
+const interfacePathFields = ["composerIcon", "logo"];
+const interfaceStringArrayFields = ["capabilities", "defaultPrompt"];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function relativePackagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).split(path.sep).join("/");
+}
+function isWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return relativePath === "" || (!relativePath.startsWith(`..${path.sep}`) && relativePath !== ".." && !path.isAbsolute(relativePath));
+}
+export async function resolveSafePackagePath(rootPath, value) {
+    if (!value.startsWith("./")) {
+        return null;
+    }
+    const resolvedPath = path.resolve(rootPath, value);
+    if (!isWithinRoot(rootPath, resolvedPath)) {
+        return null;
+    }
+    try {
+        const canonicalRoot = await realpath(rootPath);
+        const canonicalPath = await realpath(resolvedPath);
+        if (!isWithinRoot(canonicalRoot, canonicalPath)) {
+            return null;
+        }
+    }
+    catch {
+        // The path may be intentionally absent; callers that require it report that separately.
+    }
+    return { path: resolvedPath, packagePath: relativePackagePath(rootPath, resolvedPath) };
+}
+function invalidField(field, manifestPath) {
+    return failure("plugin.manifest.invalid_field", `The plugin manifest field \`${field}\` has an invalid value.`, "Malformed optional metadata cannot be interpreted reliably by Codex clients.", `Use the official type for \`${field}\` in .codex-plugin/plugin.json.`, { manifestPath, field });
+}
+function invalidPath(id, field, manifestPath) {
+    return failure(id, `The plugin manifest field \`${field}\` must reference a safe package-relative path.`, "Paths outside the plugin package can expose files that are not part of the plugin bundle.", `Use a \`./\` path that remains inside the plugin package for \`${field}\`.`, { manifestPath, field });
+}
+function failure(id, message, impact, suggestedFix, evidence) {
+    return { id, severity: "fail", message, impact, suggestedFix, evidence };
+}
+async function safePath(rootPath, manifestPath, field, value, id) {
+    if (typeof value !== "string") {
+        return invalidField(field, manifestPath);
+    }
+    return (await resolveSafePackagePath(rootPath, value)) ?? invalidPath(id, field, manifestPath);
+}
+function validateString(value, field, manifestPath, findings) {
+    if (value !== undefined && typeof value !== "string") {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateHttpUrl(value, field, manifestPath, findings) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "string" || !isHttpUrl(value)) {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateStringArray(value, field, manifestPath, findings) {
+    if (value !== undefined && (!Array.isArray(value) || value.some((item) => typeof item !== "string"))) {
+        findings.push(invalidField(field, manifestPath));
+    }
+}
+function validateMetadata(manifest, manifestPath) {
+    const findings = [];
+    if (manifest.author !== undefined) {
+        if (!isPlainObject(manifest.author)) {
+            findings.push(invalidField("author", manifestPath));
+        }
+        else {
+            validateString(manifest.author.name, "author.name", manifestPath, findings);
+            validateString(manifest.author.email, "author.email", manifestPath, findings);
+            validateHttpUrl(manifest.author.url, "author.url", manifestPath, findings);
+        }
+    }
+    validateHttpUrl(manifest.homepage, "homepage", manifestPath, findings);
+    validateHttpUrl(manifest.repository, "repository", manifestPath, findings);
+    validateString(manifest.license, "license", manifestPath, findings);
+    validateStringArray(manifest.keywords, "keywords", manifestPath, findings);
+    if (manifest.interface === undefined)
+        return findings;
+    if (!isPlainObject(manifest.interface)) {
+        findings.push(invalidField("interface", manifestPath));
+        return findings;
+    }
+    for (const field of interfaceStringFields) {
+        const value = manifest.interface[field];
+        if (interfaceUrlFields.has(field)) {
+            validateHttpUrl(value, `interface.${field}`, manifestPath, findings);
+        }
+        else {
+            validateString(value, `interface.${field}`, manifestPath, findings);
+        }
+    }
+    for (const field of interfaceStringArrayFields) {
+        validateStringArray(manifest.interface[field], `interface.${field}`, manifestPath, findings);
+    }
+    return findings;
+}
+export async function validatePluginComponents(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = relativePackagePath(rootPath, discoveredPackage.manifestPath);
+    const findings = validateMetadata(manifest, manifestPath);
+    const componentPaths = [
+        ["skills", manifest.skills],
+        ["mcpServers", manifest.mcpServers]
+    ];
+    if (isPlainObject(manifest.interface)) {
+        for (const field of interfacePathFields)
+            componentPaths.push([`interface.${field}`, manifest.interface[field]]);
+        const screenshots = manifest.interface.screenshots;
+        if (screenshots !== undefined && (!Array.isArray(screenshots) || screenshots.some((item) => typeof item !== "string"))) {
+            findings.push(invalidField("interface.screenshots", manifestPath));
+        }
+        else if (Array.isArray(screenshots)) {
+            screenshots.forEach((screenshot, index) => componentPaths.push([`interface.screenshots[${index}]`, screenshot]));
+        }
+    }
+    for (const [field, value] of componentPaths) {
+        if (value === undefined)
+            continue;
+        const result = await safePath(rootPath, manifestPath, field, value, "plugin.manifest.invalid_path");
+        if ("id" in result)
+            findings.push(result);
+    }
+    if (manifest.apps === undefined)
+        return findings;
+    const appPath = await safePath(rootPath, manifestPath, "apps", manifest.apps, "plugin.app.invalid_path");
+    if ("id" in appPath)
+        return [...findings, appPath];
+    try {
+        if (!(await stat(appPath.path)).isFile())
+            throw new Error("not a regular file");
+    }
+    catch {
+        return [...findings, failure("plugin.app.missing_file", "The plugin manifest points to a missing .app.json file.", "Codex cannot load an app manifest that is absent or not a regular file.", "Create the referenced app manifest as a regular JSON file inside the plugin package.", { field: "apps", path: appPath.packagePath })];
+    }
+    try {
+        JSON.parse(await readFile(appPath.path, "utf8"));
+    }
+    catch {
+        findings.push(failure("plugin.app.invalid_json", "The referenced .app.json file is not valid JSON.", "Codex cannot parse the app manifest.", "Fix the JSON syntax in the referenced app manifest.", { field: "apps", path: appPath.packagePath }));
+    }
+    return findings;
+}

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

@@ -0,0 +1,2 @@
+import { type DiscoveredPackage, type Finding } from "../domain/types.js";
+export declare function validatePluginHooks(discoveredPackage: DiscoveredPackage): Promise<Finding[]>;