codex-plugin-doctor 0.1.1

package/dist/core/runtime-transcript.d.ts

@@ -0,0 +1,5 @@
+type JsonObject = Record<string, unknown>;
+export declare function sanitizeTranscriptValue(value: unknown, pathSegments?: string[]): unknown;
+export declare function formatRequestTranscript(method: string, params: JsonObject | undefined): string;
+export declare function formatResponseTranscript(method: string, message: JsonObject): string;
+export {};

package/dist/core/runtime-transcript.js

@@ -0,0 +1,139 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isErrorResponse(message) {
+    return isPlainObject(message.error);
+}
+function getErrorObject(message) {
+    return isErrorResponse(message) ? message.error : null;
+}
+function isSensitiveKey(key) {
+    return /(token|secret|password|api[_-]?key|private[_-]?key|sig|signature|auth|session)/i.test(key);
+}
+function looksLikeToken(value) {
+    return /(sk-[A-Za-z0-9_-]{8,}|Bearer\s+[A-Za-z0-9._-]{8,}|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+)/.test(value);
+}
+function sanitizeUriQuery(value) {
+    try {
+        const uri = new URL(value);
+        const sanitizedQuery = Object.fromEntries(Array.from(uri.searchParams.entries()).map(([key, queryValue]) => [
+            key,
+            isSensitiveKey(key) || looksLikeToken(queryValue)
+                ? "[REDACTED]"
+                : queryValue
+        ]));
+        if (Object.keys(sanitizedQuery).length === 0) {
+            return null;
+        }
+        return sanitizedQuery;
+    }
+    catch {
+        return null;
+    }
+}
+export function sanitizeTranscriptValue(value, pathSegments = []) {
+    const currentKey = pathSegments[pathSegments.length - 1];
+    if (typeof value === "string") {
+        if (currentKey === "uri") {
+            const query = sanitizeUriQuery(value);
+            if (query) {
+                return {
+                    uri: value.split("?")[0],
+                    query
+                };
+            }
+        }
+        if (currentKey === "text" ||
+            currentKey === "blob" ||
+            currentKey === "data" ||
+            currentKey === "diff" ||
+            currentKey === "arguments" ||
+            isSensitiveKey(currentKey ?? "") ||
+            pathSegments.includes("arguments") ||
+            looksLikeToken(value)) {
+            return "[REDACTED]";
+        }
+        if (value.length > 80) {
+            return "[TRUNCATED]";
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => sanitizeTranscriptValue(entry, [...pathSegments, String(index)]));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+            key,
+            sanitizeTranscriptValue(entryValue, [...pathSegments, key])
+        ]));
+    }
+    return value;
+}
+export function formatRequestTranscript(method, params) {
+    if (!params) {
+        return `-> ${method}`;
+    }
+    return `-> ${method} ${JSON.stringify(sanitizeTranscriptValue(params))}`;
+}
+export function formatResponseTranscript(method, message) {
+    const error = getErrorObject(message);
+    if (error) {
+        const code = typeof error.code === "number" ? error.code : "?";
+        const messageText = typeof error.message === "string"
+            ? sanitizeTranscriptValue(error.message, ["error", "message"])
+            : "error";
+        return `<- ${method} error ${JSON.stringify({
+            code,
+            message: messageText
+        })}`;
+    }
+    if (!isPlainObject(message.result)) {
+        return `<- ${method} result`;
+    }
+    const result = message.result;
+    switch (method) {
+        case "initialize":
+            return `<- initialize ${JSON.stringify({
+                protocolVersion: result.protocolVersion,
+                capabilities: isPlainObject(result.capabilities)
+                    ? Object.keys(result.capabilities)
+                    : []
+            })}`;
+        case "tools/list":
+            return `<- tools/list ${JSON.stringify({
+                tools: Array.isArray(result.tools) ? result.tools.length : 0,
+                nextCursor: typeof result.nextCursor === "string" ? "[CURSOR]" : undefined
+            })}`;
+        case "tools/call":
+            return `<- tools/call ${JSON.stringify({
+                content: Array.isArray(result.content) ? result.content.length : 0
+            })}`;
+        case "resources/list":
+            return `<- resources/list ${JSON.stringify({
+                resources: Array.isArray(result.resources) ? result.resources.length : 0,
+                nextCursor: typeof result.nextCursor === "string" ? "[CURSOR]" : undefined
+            })}`;
+        case "resources/read":
+            return `<- resources/read ${JSON.stringify({
+                contents: Array.isArray(result.contents) ? result.contents.length : 0
+            })}`;
+        case "resources/templates/list":
+            return `<- resources/templates/list ${JSON.stringify({
+                resourceTemplates: Array.isArray(result.resourceTemplates)
+                    ? result.resourceTemplates.length
+                    : 0,
+                nextCursor: typeof result.nextCursor === "string" ? "[CURSOR]" : undefined
+            })}`;
+        case "prompts/list":
+            return `<- prompts/list ${JSON.stringify({
+                prompts: Array.isArray(result.prompts) ? result.prompts.length : 0,
+                nextCursor: typeof result.nextCursor === "string" ? "[CURSOR]" : undefined
+            })}`;
+        case "prompts/get":
+            return `<- prompts/get ${JSON.stringify({
+                messages: Array.isArray(result.messages) ? result.messages.length : 0
+            })}`;
+        default:
+            return `<- ${method}`;
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { CheckOptions, CheckResult } from "../domain/types.js";
+export declare function validatePlugin(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/core/validate-plugin.js

@@ -0,0 +1,341 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { discoverPackage } from "./discover-package.js";
+import { probeRuntime } from "./runtime-probe.js";
+function buildFailure(id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity: "fail",
+        message,
+        impact,
+        suggestedFix
+    };
+}
+function buildWarning(id, message, impact, suggestedFix) {
+    return {
+        id,
+        severity: "warn",
+        message,
+        impact,
+        suggestedFix
+    };
+}
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+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)));
+}
+function isSensitiveKey(key) {
+    return /(token|secret|password|api[_-]?key|private[_-]?key)/i.test(key);
+}
+function looksLikeLiteralSecret(value) {
+    const trimmed = value.trim();
+    if (trimmed.length < 12) {
+        return false;
+    }
+    if (/^\$\{?[A-Z0-9_]+\}?$/i.test(trimmed)) {
+        return false;
+    }
+    return true;
+}
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match) {
+        return null;
+    }
+    const lines = match[1].split(/\r?\n/);
+    const entries = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!line.trim()) {
+            continue;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const rawValue = line.slice(separatorIndex + 1).trim();
+        if (!key || !rawValue) {
+            continue;
+        }
+        const blockScalarMatch = rawValue.match(/^([|>])[+-]?$/);
+        if (blockScalarMatch) {
+            const blockLines = [];
+            let blockIndex = index + 1;
+            for (; blockIndex < lines.length; blockIndex += 1) {
+                const blockLine = lines[blockIndex];
+                if (blockLine.trim() !== "" && !/^\s/.test(blockLine)) {
+                    break;
+                }
+                blockLines.push(blockLine.replace(/^\s{2}/, ""));
+            }
+            const value = blockScalarMatch[1] === ">"
+                ? blockLines.join("\n").replace(/\n[ \t]*\n/g, "\n\n").replace(/\n/g, " ").trim()
+                : blockLines.join("\n").trim();
+            if (value) {
+                entries.push([key, value]);
+            }
+            index = blockIndex - 1;
+            continue;
+        }
+        const value = rawValue.replace(/^"([\s\S]*)"$/, "$1").replace(/^'([\s\S]*)'$/, "$1");
+        if (value) {
+            entries.push([key, value]);
+        }
+    }
+    return Object.fromEntries(entries);
+}
+function countMatches(input, pattern) {
+    const matches = input.match(pattern);
+    return matches ? matches.length : 0;
+}
+function isDescriptionLikelyVerbose(description, mode) {
+    const trimmed = description.trim();
+    const length = trimmed.length;
+    const technicalSignals = countMatches(trimmed, /`[^`]+`/g) +
+        countMatches(trimmed, /\b(MCP|SDK|CLI|API|JSON|schema|resource|resources|prompt|prompts|tool|tools|repo|repository|command|commands|connector|metadata|workflow|validation|inputs|outputs|GitHub|GraphQL|PR|review|Cloudflare|Workers|Wrangler|D1|R2|Vectorize|Queues|Workflows|Tunnel|Spectrum|WAF|DDoS|Terraform|Pulumi|Figma|FigJam|design system|component|components|variants|auto-layout|token|tokens|library|libraries|screen|screens|React|WebSocket)\b/gi);
+    const productSignals = countMatches(trimmed, /\b(frontend|dashboard|dashboards|website|websites|hero|UI|browser|testing|Stripe|Checkout|PaymentIntents|Connect|billing|subscriptions|payment|payments|marketplace|marketplaces|Jira|Confluence|bug|bugs|issue|issues|ticket|tickets|backlog|Epic|Epics|status|report|reports|project|tasks|meeting|notes|action items|assignees|knowledge|documentation|deployment|authentication|infrastructure|architecture|duplicates|Postgres|database|databases|bills|costs|transfer|egress|query|queries|overfetching|SELECT|optimization|application|GSAP|animation|animations|animate|easing|stagger|timeline|timelines|playback|transforms|will-change|quickTo|video|videos|composition|compositions|title cards|overlays|captions|subtitles|voiceovers|audio|audio-reactive|visuals|scene|scenes|transitions|HTML|text-to-speech|music|highlighting|crossfades|wipes|shader|media|render|preview|transcribe|Canva|presentation|presentations|slide|slides|deck|brief|outline|design|designs|brand|brand kit|social media|Facebook|Instagram|LinkedIn|export-ready|formats|localized|translated|layout)\b/gi);
+    const structuredSignals = countMatches(trimmed, /\(\d+\)/g) +
+        countMatches(trimmed, /\b(Use when|When an agent needs to|Triggers:)\b/gi);
+    const concreteSignals = technicalSignals + productSignals + structuredSignals;
+    const vagueSignals = countMatches(trimmed, /\b(general|generally|many different|many|broad|various|different situations|possibilities|ideas|concepts|directions)\b/gi);
+    if (mode === "plugin") {
+        return length > 240;
+    }
+    if (length <= 240) {
+        return false;
+    }
+    if (vagueSignals >= 4) {
+        return true;
+    }
+    if (vagueSignals >= 2 && concreteSignals < 8) {
+        return true;
+    }
+    if (concreteSignals >= 8 && vagueSignals <= 2 && length <= 650) {
+        return false;
+    }
+    if (concreteSignals >= 12 && vagueSignals <= 2 && length <= 780) {
+        return false;
+    }
+    if (technicalSignals >= 8 && vagueSignals <= 1 && length <= 760) {
+        return false;
+    }
+    if (length >= 700) {
+        return true;
+    }
+    if (technicalSignals >= 3 && vagueSignals === 0 && length <= 600) {
+        return false;
+    }
+    if (technicalSignals >= 8 && vagueSignals <= 1 && length <= 420) {
+        return false;
+    }
+    if (concreteSignals >= 4 && vagueSignals <= 1 && length <= 520) {
+        return false;
+    }
+    if (technicalSignals >= 2 && vagueSignals === 0 && length <= 480) {
+        return false;
+    }
+    return true;
+}
+function validateRequiredManifestFields(discoveredPackage) {
+    const findings = [];
+    const { manifest } = discoveredPackage;
+    if (!manifest.name) {
+        findings.push(buildFailure("plugin.manifest.name.missing", "The plugin manifest is missing a `name` field.", "Codex cannot identify the plugin reliably without a stable package name.", "Add a kebab-case `name` field to `.codex-plugin/plugin.json`."));
+    }
+    if (!manifest.version) {
+        findings.push(buildFailure("plugin.manifest.version.missing", "The plugin manifest is missing a `version` field.", "Release and compatibility workflows cannot reason about the package version.", "Add a semantic `version` field to `.codex-plugin/plugin.json`."));
+    }
+    if (!manifest.description) {
+        findings.push(buildFailure("plugin.manifest.description.missing", "The plugin manifest is missing a `description` field.", "The package will be harder to understand and present in Codex surfaces.", "Add a concise `description` field to `.codex-plugin/plugin.json`."));
+    }
+    if (manifest.description &&
+        isDescriptionLikelyVerbose(manifest.description, "plugin")) {
+        findings.push(buildWarning("plugin.heuristic.description.too_long", "The plugin manifest description is likely too verbose.", "Overly long metadata increases context cost and can dilute plugin discovery quality.", "Shorten the manifest description to a precise one- or two-sentence summary."));
+    }
+    return findings;
+}
+async function validateSkillsDirectory(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (!manifest.skills) {
+        return [];
+    }
+    const skillsPath = path.resolve(rootPath, manifest.skills);
+    if (!isPathWithinRoot(rootPath, skillsPath)) {
+        return [
+            buildFailure("plugin.security.path_traversal", "The plugin manifest points the skills path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `skills` path inside the plugin root.")
+        ];
+    }
+    const exists = await directoryExists(skillsPath);
+    if (exists) {
+        return [];
+    }
+    return [
+        buildFailure("plugin.skills.path.missing", "The plugin manifest points to a missing skills directory.", "Codex will not be able to load the packaged skills as expected.", `Create the skills directory at \`${skillsPath}\` or update the manifest path.`)
+    ];
+}
+async function validateSkillDefinitions(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (!manifest.skills) {
+        return [];
+    }
+    const skillsPath = path.resolve(rootPath, manifest.skills);
+    if (!isPathWithinRoot(rootPath, skillsPath)) {
+        return [];
+    }
+    const skillsDirectoryExists = await directoryExists(skillsPath);
+    if (!skillsDirectoryExists) {
+        return [];
+    }
+    const entries = await readdir(skillsPath, { withFileTypes: true });
+    const skillDirectories = entries.filter((entry) => entry.isDirectory());
+    const findings = [];
+    for (const skillDirectory of skillDirectories) {
+        const skillRoot = path.join(skillsPath, skillDirectory.name);
+        const skillFilePath = path.join(skillRoot, "SKILL.md");
+        const skillFileExists = await fileExists(skillFilePath);
+        if (!skillFileExists) {
+            findings.push(buildFailure("plugin.skill.skill_md.missing", `The skill \`${skillDirectory.name}\` is missing \`SKILL.md\`.`, "Codex cannot load a skill directory that does not contain the required SKILL.md entrypoint.", `Add \`SKILL.md\` to \`${skillRoot}\` with at least \`name\` and \`description\` frontmatter.`));
+            continue;
+        }
+        const skillContent = await readFile(skillFilePath, "utf8");
+        const frontmatter = parseSkillFrontmatter(skillContent);
+        if (!frontmatter?.name) {
+            findings.push(buildFailure("plugin.skill.name.missing", `The skill \`${skillDirectory.name}\` is missing a \`name\` field in frontmatter.`, "Codex cannot expose skill metadata correctly without a stable skill name.", `Add a \`name\` field to the frontmatter in \`${skillFilePath}\`.`));
+        }
+        if (!frontmatter?.description) {
+            findings.push(buildFailure("plugin.skill.description.missing", `The skill \`${skillDirectory.name}\` is missing a \`description\` field in frontmatter.`, "Codex uses skill descriptions for discovery and implicit matching, so missing descriptions reduce skill usability.", `Add a scoped \`description\` field to the frontmatter in \`${skillFilePath}\`.`));
+        }
+        if (frontmatter?.description &&
+            isDescriptionLikelyVerbose(frontmatter.description, "skill")) {
+            findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`));
+        }
+    }
+    return findings;
+}
+async function validateMcpConfig(discoveredPackage) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (!manifest.mcpServers) {
+        return [];
+    }
+    const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
+    if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
+        return [
+            buildFailure("plugin.security.path_traversal", "The plugin manifest points the MCP config path outside the package root.", "Paths that escape the package root make the package harder to audit and can expose unintended files during packaging or validation.", "Keep the `mcpServers` path inside the plugin root.")
+        ];
+    }
+    const mcpConfigExists = await fileExists(mcpConfigPath);
+    if (!mcpConfigExists) {
+        return [
+            buildFailure("plugin.mcp.path.missing", "The plugin manifest points to a missing `.mcp.json` file.", "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.", `Create \`${mcpConfigPath}\` or update the manifest \`mcpServers\` path.`)
+        ];
+    }
+    let parsedConfig;
+    try {
+        parsedConfig = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+    }
+    catch {
+        return [
+            buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+        ];
+    }
+    if (!isPlainObject(parsedConfig)) {
+        return [
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`)
+        ];
+    }
+    const servers = parsedConfig.mcpServers;
+    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+        return [
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+        ];
+    }
+    const findings = [];
+    for (const [serverName, serverConfig] of Object.entries(servers)) {
+        if (!isPlainObject(serverConfig)) {
+            findings.push(buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            continue;
+        }
+        const command = serverConfig.command;
+        const url = serverConfig.url;
+        const env = serverConfig.env;
+        if (typeof command !== "string" && typeof url !== "string") {
+            findings.push(buildFailure("plugin.mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "Codex needs a process command for STDIO servers or a URL for streamable HTTP servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+        }
+        if (isPlainObject(env)) {
+            for (const [envKey, envValue] of Object.entries(env)) {
+                if (isSensitiveKey(envKey) &&
+                    typeof envValue === "string" &&
+                    looksLikeLiteralSecret(envValue)) {
+                    findings.push(buildFailure("plugin.security.hard_coded_secret", `The MCP server \`${serverName}\` contains a hard-coded secret-like env value for \`${envKey}\`.`, "Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult.", `Replace the literal value for \`${envKey}\` with an environment reference or injected secret outside the package.`));
+                }
+            }
+        }
+    }
+    return findings;
+}
+export async function validatePlugin(targetPath, options = {}) {
+    const discoveredPackage = await discoverPackage(targetPath);
+    if (!discoveredPackage) {
+        return {
+            targetPath: path.resolve(targetPath),
+            status: "fail",
+            exitCode: 1,
+            findings: [
+                buildFailure("plugin.manifest.missing", "Missing required `.codex-plugin/plugin.json` manifest.", "Codex cannot treat this directory as a plugin package without the required manifest entry point.", "Create `.codex-plugin/plugin.json` with at least `name`, `version`, and `description`.")
+            ]
+        };
+    }
+    const runtimeResult = options.runtime
+        ? await probeRuntime(discoveredPackage, {
+            transcript: options.runtimeTranscript
+        })
+        : null;
+    const findings = [
+        ...validateRequiredManifestFields(discoveredPackage),
+        ...(await validateSkillsDirectory(discoveredPackage)),
+        ...(await validateSkillDefinitions(discoveredPackage)),
+        ...(await validateMcpConfig(discoveredPackage)),
+        ...(runtimeResult ? runtimeResult.findings : [])
+    ];
+    const hasFailures = findings.some((finding) => finding.severity === "fail");
+    const hasWarnings = findings.some((finding) => finding.severity === "warn");
+    if (!hasFailures && !hasWarnings) {
+        return {
+            targetPath: discoveredPackage.rootPath,
+            status: "pass",
+            exitCode: 0,
+            findings: [],
+            ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {})
+        };
+    }
+    return {
+        targetPath: discoveredPackage.rootPath,
+        status: hasFailures ? "fail" : "warn",
+        exitCode: hasFailures ? 1 : 0,
+        findings,
+        ...(runtimeResult ? { runtimeScorecard: runtimeResult.scorecard } : {})
+    };
+}

package/dist/domain/types.d.ts

@@ -0,0 +1,64 @@
+export type FindingSeverity = "warn" | "fail";
+export interface Finding {
+    id: string;
+    severity: FindingSeverity;
+    message: string;
+    impact: string;
+    suggestedFix: string;
+}
+export interface CheckResult {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    findings: Finding[];
+    runtimeScorecard?: RuntimeScorecard;
+}
+export interface CheckOptions {
+    runtime?: boolean;
+    runtimeTranscript?: (line: string) => void;
+}
+export interface PluginManifest {
+    name?: string;
+    version?: string;
+    description?: string;
+    skills?: string;
+    mcpServers?: string;
+}
+export interface DiscoveredPackage {
+    rootPath: string;
+    manifestPath: string;
+    manifest: PluginManifest;
+}
+export interface JsonReportSummary {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    runtimeProbeEnabled: boolean;
+    runtimeScorecard?: RuntimeScorecard;
+    findingCounts: {
+        fail: number;
+        warn: number;
+        total: number;
+    };
+}
+export interface JsonReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    summary: JsonReportSummary;
+    findings: Finding[];
+}
+export type RuntimeCapabilityStatus = "pass" | "fail" | "warn" | "skipped" | "unsupported";
+export interface RuntimeScorecard {
+    initialize: RuntimeCapabilityStatus;
+    toolsList: RuntimeCapabilityStatus;
+    toolsCall: RuntimeCapabilityStatus;
+    resourcesList: RuntimeCapabilityStatus;
+    resourceRead: RuntimeCapabilityStatus;
+    resourceTemplatesList: RuntimeCapabilityStatus;
+    promptsList: RuntimeCapabilityStatus;
+    promptGet: RuntimeCapabilityStatus;
+}
+export interface RuntimeProbeResult {
+    findings: Finding[];
+    scorecard: RuntimeScorecard;
+}

package/dist/domain/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { CheckOptions, CheckResult } from "./domain/types.js";
+export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -0,0 +1,4 @@
+import { validatePlugin } from "./core/validate-plugin.js";
+export async function runCheck(targetPath, options = {}) {
+    return validatePlugin(targetPath, options);
+}

package/dist/release/release-notes.d.ts

@@ -0,0 +1,9 @@
+export declare function extractReleaseSection(changelog: string, version: string): string | null;
+export declare function buildReleaseCandidateNotes(input: {
+    version: string;
+    generatedAt: string;
+    validationTarget: string;
+    runtimeTarget: string;
+    packageFilename: string;
+    changelogSection: string | null;
+}): string;

package/dist/release/release-notes.js

@@ -0,0 +1,46 @@
+export function extractReleaseSection(changelog, version) {
+    const lines = changelog.split(/\r?\n/);
+    const sectionHeader = `## [${version}]`;
+    const startIndex = lines.findIndex((line) => line.startsWith(sectionHeader));
+    if (startIndex === -1) {
+        return null;
+    }
+    let endIndex = lines.length;
+    for (let index = startIndex + 1; index < lines.length; index += 1) {
+        if (lines[index].startsWith("## [")) {
+            endIndex = index;
+            break;
+        }
+    }
+    return lines.slice(startIndex, endIndex).join("\n").trim();
+}
+export function buildReleaseCandidateNotes(input) {
+    const { version, generatedAt, validationTarget, runtimeTarget, packageFilename, changelogSection } = input;
+    return [
+        `# Release Candidate ${version}`,
+        "",
+        `Generated at: ${generatedAt}`,
+        "",
+        "## Package Artifact",
+        "",
+        `- Tarball: \`${packageFilename}\``,
+        "",
+        "## Validation Targets",
+        "",
+        `- Static target: \`${validationTarget}\``,
+        `- Runtime target: \`${runtimeTarget}\``,
+        "",
+        "## Included Release Notes",
+        "",
+        changelogSection ?? "_No changelog section found for this version._",
+        "",
+        "## Validation Checklist",
+        "",
+        "- `npm test`",
+        "- `npm run build`",
+        "- `npm run prepare-release`",
+        "- local validation artifacts generated",
+        "- tarball generated for inspection",
+        ""
+    ].join("\n");
+}

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

@@ -0,0 +1,7 @@
+import type { CheckResult, JsonReport } from "../domain/types.js";
+export declare function buildJsonReport(result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): JsonReport;
+export declare function renderJsonReport(result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): string;

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

@@ -0,0 +1,26 @@
+export function buildJsonReport(result, options) {
+    const failCount = result.findings.filter((finding) => finding.severity === "fail").length;
+    const warnCount = result.findings.filter((finding) => finding.severity === "warn").length;
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        summary: {
+            targetPath: result.targetPath,
+            status: result.status,
+            exitCode: result.exitCode,
+            runtimeProbeEnabled: options.runtimeProbeEnabled,
+            ...(result.runtimeScorecard
+                ? { runtimeScorecard: result.runtimeScorecard }
+                : {}),
+            findingCounts: {
+                fail: failCount,
+                warn: warnCount,
+                total: result.findings.length
+            }
+        },
+        findings: result.findings
+    };
+}
+export function renderJsonReport(result, options) {
+    return JSON.stringify(buildJsonReport(result, options), null, 2);
+}

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

@@ -0,0 +1,4 @@
+import type { CheckResult } from "../domain/types.js";
+export declare function buildMarkdownReport(result: CheckResult, options: {
+    runtimeProbeEnabled: boolean;
+}): string;