codex-plugin-doctor 1.56.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.56.0
+      - uses: Esquetta/CodexPluginDoctor@v1.58.0
         with:
-          version: "1.56.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.d.ts

@@ -10,7 +10,11 @@ export interface DoctorSizeReport {
         sizeHuman: string;
     }>;
     warnings: string[];
+    npmPackSize?: number;
+    npmPackSizeHuman?: string;
 }
-export declare function buildDoctorSize(targetPath: string): Promise<DoctorSizeReport>;
+export declare function buildDoctorSize(targetPath: string, options?: {
+    npmPack?: boolean;
+}): Promise<DoctorSizeReport>;
 export declare function renderDoctorSize(report: DoctorSizeReport): string;
 export declare function renderDoctorSizeJson(report: DoctorSizeReport): string;

package/dist/core/doctor-size.js

@@ -1,4 +1,5 @@
 import { readdir, stat } from "node:fs/promises";
+import { execFile } from "node:child_process";
 import path from "node:path";
 const skippedDirs = new Set([
     "node_modules",
@@ -14,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`;
@@ -68,11 +83,63 @@ async function scanDirectory(rootPath, currentPath = rootPath) {
     }
     return { totalSize, fileCount, largeFiles };
 }
-export async function buildDoctorSize(targetPath) {
+export async function buildDoctorSize(targetPath, options = {}) {
     const resolvedPath = path.resolve(targetPath);
     const { totalSize, fileCount, largeFiles } = await scanDirectory(resolvedPath);
     const warnings = [];
     let status = "pass";
+    let npmPackSize;
+    let npmPackSizeHuman;
+    if (options.npmPack) {
+        try {
+            const packOutput = await new Promise((resolve, reject) => {
+                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;
+                    }
+                    resolve(stdout);
+                });
+            });
+            const tarballLine = packOutput.split("\n").find((line) => line.includes("total files") || line.includes("package size"));
+            if (tarballLine) {
+                const totalMatch = tarballLine.match(/(\d[\d.]*)\s*([KMG]?B)/i);
+                if (totalMatch) {
+                    const value = Number.parseFloat(totalMatch[1]);
+                    const unit = totalMatch[2].toUpperCase();
+                    switch (unit) {
+                        case "KB":
+                            npmPackSize = Math.round(value * 1024);
+                            break;
+                        case "MB":
+                            npmPackSize = Math.round(value * 1024 * 1024);
+                            break;
+                        case "GB":
+                            npmPackSize = Math.round(value * 1024 * 1024 * 1024);
+                            break;
+                        default:
+                            npmPackSize = Math.round(value);
+                    }
+                    npmPackSizeHuman = formatSize(npmPackSize);
+                }
+            }
+            if (npmPackSize === undefined) {
+                warnings.push("Could not determine npm pack size from output.");
+            }
+            else {
+                const diffPercent = totalSize > 0
+                    ? Math.abs(Math.round(((npmPackSize - totalSize) / totalSize) * 100))
+                    : 0;
+                if (diffPercent > 50 && npmPackSize > totalSize) {
+                    warnings.push(`npm pack size (${npmPackSizeHuman}) differs from local size (${formatSize(totalSize)}) by ${diffPercent}%.`);
+                }
+            }
+        }
+        catch (error) {
+            warnings.push(`npm pack failed: ${error.message}`);
+        }
+    }
     if (totalSize >= packageSizeFailThreshold) {
         status = "fail";
         warnings.push(`Package size (${formatSize(totalSize)}) exceeds ${formatSize(packageSizeFailThreshold)}.`);
@@ -94,7 +161,9 @@ export async function buildDoctorSize(targetPath) {
         totalSizeHuman: formatSize(totalSize),
         fileCount,
         largeFiles: largeFiles.slice(0, 10),
-        warnings
+        warnings,
+        npmPackSize,
+        npmPackSizeHuman
     };
 }
 export function renderDoctorSize(report) {
@@ -104,6 +173,7 @@ export function renderDoctorSize(report) {
         `Path: ${report.targetPath}`,
         `Status: ${report.status.toUpperCase()}`,
         `Total size: ${report.totalSizeHuman} (${report.fileCount} files)`,
+        report.npmPackSizeHuman ? `npm pack size: ${report.npmPackSizeHuman}` : "",
         ""
     ];
     if (report.warnings.length > 0) {
@@ -134,6 +204,10 @@ export function renderDoctorSizeJson(report) {
         totalSizeHuman: report.totalSizeHuman,
         fileCount: report.fileCount,
         largeFiles: report.largeFiles,
-        warnings: report.warnings
+        warnings: report.warnings,
+        ...(report.npmPackSize !== undefined ? {
+            npmPackSize: report.npmPackSize,
+            npmPackSizeHuman: report.npmPackSizeHuman
+        } : {})
     }, null, 2);
 }

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[]>;