codex-plugin-doctor 1.57.0 → 1.59.0

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

@@ -0,0 +1,301 @@
+import { lstat, opendir, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { isAlias, isNode, parseDocument, visit } from "yaml";
+const maxSkillBytes = 1024 * 1024;
+const maxAgentBytes = 256 * 1024;
+const maxAggregateMetadataBytes = 16 * 1024 * 1024;
+const maxDirectoryEntries = 256;
+const maxSkillDirectories = 100;
+const unsupportedText = /[\u0000-\u001F\u007F\u2028\u2029\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/u;
+const interfaceKeys = new Set(["display_name", "short_description", "icon_small", "icon_large", "brand_color", "default_prompt"]);
+const policyKeys = new Set(["products", "allow_implicit_invocation"]);
+const dependencyKeys = new Set(["tools"]);
+const toolDescriptorKeys = new Set(["type", "value", "description", "transport", "url"]);
+const agentKeys = new Set(["interface", "policy", "dependencies"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isWithin(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function packagePath(rootPath, targetPath) {
+    return path.relative(rootPath, targetPath).split(path.sep).join("/");
+}
+function finding(id, message, evidence) {
+    return evidence === undefined
+        ? { id, severity: "fail", message }
+        : { id, severity: "fail", message, evidence };
+}
+function supportedText(value, limit = Number.MAX_SAFE_INTEGER) {
+    return typeof value === "string" && value.trim().length > 0 && value.length <= limit && !unsupportedText.test(value);
+}
+function parseSafeYaml(source) {
+    const document = parseDocument(source, { schema: "core", uniqueKeys: true, strict: true, prettyErrors: false });
+    let alias = false;
+    let nonCoreTag = false;
+    visit(document, (_key, node) => {
+        if (isAlias(node))
+            alias = true;
+        if (isNode(node) && node.tag !== undefined && !node.tag.startsWith("tag:yaml.org,2002:"))
+            nonCoreTag = true;
+    });
+    if (document.errors.length > 0 || alias || nonCoreTag)
+        return { error: "yaml" };
+    try {
+        const value = document.toJS({ maxAliasCount: 0 });
+        return isRecord(value) ? { value } : { error: "shape" };
+    }
+    catch {
+        return { error: "yaml" };
+    }
+}
+function splitSkillFile(source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/u.exec(source);
+    if (!match || match[2].trim().length === 0)
+        return null;
+    return { frontmatter: match[1], body: match[2] };
+}
+async function safeDirectory(rootPath, skillsPath) {
+    try {
+        const [canonicalRoot, canonicalSkills, details] = await Promise.all([realpath(rootPath), realpath(skillsPath), stat(skillsPath)]);
+        return details.isDirectory() && isWithin(canonicalRoot, canonicalSkills) ? { canonicalRoot, canonicalSkills } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function budgetFinding(bytes) {
+    return finding("plugin.submission.skill.budget_exceeded", "Skill metadata exceeds the aggregate submission preflight size limit.", {
+        count: bytes, limit: maxAggregateMetadataBytes
+    });
+}
+async function readSafeUtf8(filePath, maximum, budget) {
+    try {
+        const details = await stat(filePath);
+        if (!details.isFile() || details.size > maximum)
+            return { kind: "invalid" };
+        const nextBytes = budget.bytes + details.size;
+        if (nextBytes > maxAggregateMetadataBytes)
+            return { kind: "budget", nextBytes };
+        budget.bytes = nextBytes;
+        return { kind: "source", source: new TextDecoder("utf-8", { fatal: true }).decode(await readFile(filePath)) };
+    }
+    catch {
+        return { kind: "invalid" };
+    }
+}
+function rejectUnknownKeys(value, allowed) {
+    return Object.keys(value).some((key) => !allowed.has(key));
+}
+function isToolDescriptor(value) {
+    return isRecord(value) && !rejectUnknownKeys(value, toolDescriptorKeys)
+        && (value.type === "mcp" || value.type === "cli")
+        && (value.type !== "cli" || (value.transport === undefined && value.url === undefined))
+        && supportedText(value.value)
+        && (value.description === undefined || supportedText(value.description))
+        && (value.transport === undefined || supportedText(value.transport))
+        && (value.url === undefined || supportedText(value.url));
+}
+async function validateIconPath(rootPath, canonicalRoot, skillRoot, skillPath, field, value) {
+    if (typeof value !== "string" || value.trim() !== value || !supportedText(value)
+        || path.isAbsolute(value) || /^[A-Za-z]:[\\/]/u.test(value)) {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+    const iconPath = path.resolve(skillRoot, value);
+    if (!isWithin(rootPath, iconPath)) {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+    try {
+        const [canonicalIcon, details] = await Promise.all([realpath(iconPath), stat(iconPath)]);
+        if (!details.isFile() || !isWithin(canonicalRoot, canonicalIcon))
+            throw new Error("unsafe icon");
+        return null;
+    }
+    catch {
+        return finding("plugin.submission.skill.agent.invalid_path", "Optional agent icon path is invalid.", { path: skillPath, field });
+    }
+}
+async function validateAgentFile(rootPath, skillRoot, skillPath, budget) {
+    const agentPath = path.join(skillRoot, "agents", "openai.yaml");
+    let agentDetails;
+    try {
+        agentDetails = await lstat(agentPath);
+    }
+    catch {
+        return [];
+    }
+    if (agentDetails.isSymbolicLink()) {
+        return [finding("plugin.submission.skill.agent.invalid_path", "Optional agent metadata must not be a symbolic link.", { path: skillPath })];
+    }
+    if (!agentDetails.isFile()) {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a regular file.", { path: packagePath(rootPath, agentPath) })];
+    }
+    let canonicalRoot;
+    let canonicalSkill;
+    let canonicalAgent;
+    try {
+        [canonicalRoot, canonicalSkill, canonicalAgent] = await Promise.all([realpath(rootPath), realpath(skillRoot), realpath(agentPath)]);
+    }
+    catch {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a readable regular file.", { path: packagePath(rootPath, agentPath) })];
+    }
+    if (!isWithin(canonicalRoot, canonicalAgent) || !isWithin(canonicalSkill, canonicalAgent)) {
+        return [finding("plugin.submission.skill.agent.invalid_path", "Optional agent metadata resolves outside its skill.", { path: skillPath })];
+    }
+    const source = await readSafeUtf8(agentPath, maxAgentBytes, budget);
+    if (source.kind === "budget") {
+        return [budgetFinding(source.nextBytes)];
+    }
+    if (source.kind === "invalid") {
+        return [finding("plugin.submission.skill.agent.invalid_file", "Optional agent metadata must be a bounded UTF-8 regular file.", { path: packagePath(rootPath, agentPath), limit: maxAgentBytes })];
+    }
+    const parsed = parseSafeYaml(source.source);
+    if ("error" in parsed) {
+        return [finding(parsed.error === "yaml" ? "plugin.submission.skill.agent.invalid_yaml" : "plugin.submission.skill.agent.invalid_shape", "Optional agent metadata must be a safe YAML mapping.", { path: packagePath(rootPath, agentPath) })];
+    }
+    const metadata = parsed.value;
+    if (rejectUnknownKeys(metadata, agentKeys) || !isRecord(metadata.interface) || rejectUnknownKeys(metadata.interface, interfaceKeys)
+        || !supportedText(metadata.interface.display_name) || !supportedText(metadata.interface.short_description)) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an unsupported shape.", { path: packagePath(rootPath, agentPath) })];
+    }
+    if (metadata.interface.brand_color !== undefined && (typeof metadata.interface.brand_color !== "string" || !/^#[0-9A-Fa-f]{6}$/u.test(metadata.interface.brand_color))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid brand color.", { path: packagePath(rootPath, agentPath), field: "brand_color" })];
+    }
+    if (metadata.interface.default_prompt !== undefined && !supportedText(metadata.interface.default_prompt)) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent metadata has an invalid default prompt.", { path: packagePath(rootPath, agentPath), field: "default_prompt" })];
+    }
+    if (metadata.policy !== undefined && (!isRecord(metadata.policy) || rejectUnknownKeys(metadata.policy, policyKeys)
+        || (metadata.policy.products !== undefined && (!Array.isArray(metadata.policy.products) || metadata.policy.products.length === 0
+            || new Set(metadata.policy.products).size !== metadata.policy.products.length
+            || metadata.policy.products.some((product) => product !== "CHAT" && product !== "CODEX")))
+        || (metadata.policy.allow_implicit_invocation !== undefined && typeof metadata.policy.allow_implicit_invocation !== "boolean"))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent policy has an unsupported shape.", { path: packagePath(rootPath, agentPath), field: "policy" })];
+    }
+    if (metadata.dependencies !== undefined && (!isRecord(metadata.dependencies) || rejectUnknownKeys(metadata.dependencies, dependencyKeys)
+        || !Array.isArray(metadata.dependencies.tools) || metadata.dependencies.tools.length === 0
+        || metadata.dependencies.tools.some((tool) => !isToolDescriptor(tool)))) {
+        return [finding("plugin.submission.skill.agent.invalid_shape", "Optional agent dependencies have an unsupported shape.", { path: packagePath(rootPath, agentPath), field: "dependencies" })];
+    }
+    for (const field of ["icon_small", "icon_large"]) {
+        const value = metadata.interface[field];
+        if (value === undefined)
+            continue;
+        const iconFinding = await validateIconPath(rootPath, canonicalRoot, skillRoot, skillPath, field, value);
+        if (iconFinding)
+            return [iconFinding];
+    }
+    return [];
+}
+export async function validateSubmissionSkillMetadata(discoveredPackage, targetType) {
+    const { manifest, rootPath } = discoveredPackage;
+    if (manifest.skills === undefined) {
+        return targetType === "skills-only"
+            ? { findings: [finding("plugin.submission.skill.required", "Skills-only submissions require a valid skill.")], skillCount: 0 }
+            : { findings: [], skillCount: 0 };
+    }
+    if (manifest.skills !== "./skills" && manifest.skills !== "./skills/") {
+        return { findings: [finding("plugin.submission.skill.invalid_manifest", "Skills must be declared as the root ./skills directory.", { field: "skills" })], skillCount: 0 };
+    }
+    const skillsPath = path.resolve(rootPath, manifest.skills);
+    const safe = await safeDirectory(rootPath, skillsPath);
+    if (!safe) {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory must be canonically contained in the package.", { path: "skills" })], skillCount: 0 };
+    }
+    const findings = [];
+    const identities = new Set();
+    let skillCount = 0;
+    const budget = { bytes: 0 };
+    let entries;
+    try {
+        entries = await opendir(skillsPath);
+    }
+    catch {
+        return { findings: [finding("plugin.submission.skill.invalid_path", "Skills directory cannot be inspected safely.", { path: "skills" })], skillCount: 0 };
+    }
+    let entryCount = 0;
+    let skillDirectoryCount = 0;
+    for await (const entry of entries) {
+        entryCount += 1;
+        if (entryCount > maxDirectoryEntries) {
+            findings.push(finding("plugin.submission.skill.too_many", "Skills directory exceeds the submission preflight entry limit.", { count: entryCount, limit: maxDirectoryEntries }));
+            break;
+        }
+        if (entry.name.startsWith(".") || !entry.isDirectory())
+            continue;
+        skillDirectoryCount += 1;
+        if (skillDirectoryCount > maxSkillDirectories) {
+            findings.push(finding("plugin.submission.skill.too_many", "Skills directory exceeds the submission preflight skill limit.", { count: skillDirectoryCount, limit: maxSkillDirectories }));
+            break;
+        }
+        const skillRoot = path.join(skillsPath, entry.name);
+        const skillFile = path.join(skillRoot, "SKILL.md");
+        const relativeSkillPath = packagePath(rootPath, skillFile);
+        let canonicalSkill;
+        try {
+            canonicalSkill = await realpath(skillRoot);
+            if (!isWithin(safe.canonicalSkills, canonicalSkill))
+                throw new Error("unsafe skill root");
+        }
+        catch {
+            findings.push(finding("plugin.submission.skill.invalid_path", "Skill directory resolves outside the declared skills directory.", { path: packagePath(rootPath, skillRoot) }));
+            continue;
+        }
+        try {
+            const details = await lstat(skillFile);
+            if (details.isSymbolicLink()) {
+                findings.push(finding("plugin.submission.skill.invalid_path", "Skill entrypoint must not be a symbolic link.", { path: relativeSkillPath }));
+                continue;
+            }
+            if (!details.isFile() || !isWithin(canonicalSkill, await realpath(skillFile))) {
+                findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a contained regular file.", { path: relativeSkillPath }));
+                continue;
+            }
+        }
+        catch {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a contained regular file.", { path: relativeSkillPath }));
+            continue;
+        }
+        const source = await readSafeUtf8(skillFile, maxSkillBytes, budget);
+        if (source.kind === "budget") {
+            findings.push(budgetFinding(source.nextBytes));
+            break;
+        }
+        if (source.kind === "invalid") {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint must be a bounded UTF-8 regular file.", { path: relativeSkillPath, limit: maxSkillBytes }));
+            continue;
+        }
+        const split = splitSkillFile(source.source);
+        if (!split) {
+            findings.push(finding("plugin.submission.skill.invalid_file", "Skill entrypoint requires delimited frontmatter and a nonempty body.", { path: relativeSkillPath }));
+            continue;
+        }
+        const parsed = parseSafeYaml(split.frontmatter);
+        if ("error" in parsed) {
+            findings.push(finding(parsed.error === "yaml" ? "plugin.submission.skill.invalid_yaml" : "plugin.submission.skill.invalid_shape", "Skill frontmatter must be a safe YAML mapping.", { path: relativeSkillPath }));
+            continue;
+        }
+        const name = parsed.value.name;
+        const description = parsed.value.description;
+        const normalizedName = typeof name === "string" ? name.normalize("NFKC").trim() : "";
+        const pluginName = typeof manifest.name === "string" ? manifest.name.normalize("NFKC").trim() : "";
+        if (!supportedText(name) || !supportedText(description, 1024) || normalizedName.length === 0
+            || `${pluginName}:${normalizedName}`.length > 64 || identities.has(normalizedName)) {
+            findings.push(finding("plugin.submission.skill.identity", "Skill identity metadata is invalid or duplicated.", { path: relativeSkillPath, limit: 64 }));
+            continue;
+        }
+        identities.add(normalizedName);
+        skillCount += 1;
+        const agentFindings = await validateAgentFile(rootPath, skillRoot, packagePath(rootPath, skillRoot), budget);
+        findings.push(...agentFindings);
+        if (agentFindings.some((item) => item.id === "plugin.submission.skill.budget_exceeded"))
+            break;
+    }
+    if (targetType === "skills-only" && skillCount === 0 && !findings.some((item) => item.id === "plugin.submission.skill.required")) {
+        findings.push(finding("plugin.submission.skill.required", "Skills-only submissions require at least one valid skill.", { count: 0 }));
+    }
+    if (targetType === "mcp-backed" && skillCount === 0 && findings.length === 0) {
+        findings.push(finding("plugin.submission.skill.invalid_file", "Declared skills must include at least one valid immediate skill entrypoint.", { path: "skills" }));
+    }
+    return { findings, skillCount };
+}

package/dist/core/validate-plugin.js

@@ -2,6 +2,9 @@ import { readFile, readdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { discoverPackage } from "./discover-package.js";
+import { normalizeMcpConfig } from "./mcp-config-normalizer.js";
+import { validatePluginComponents } from "./plugin-components.js";
+import { validatePluginHooks } from "./plugin-hooks.js";
 import { inspectRemoteMcpUrl } from "./remote-url-policy.js";
 import { probeRuntime, remoteReliabilityGatePassed } from "./runtime-probe.js";
 function buildFailure(id, message, impact, suggestedFix, evidence) {
@@ -24,6 +27,9 @@ function buildWarning(id, message, impact, suggestedFix, evidence) {
         ...(evidence ? { evidence } : {})
     };
 }
+function hasInvalidComponentPath(findings, field) {
+    return findings.some((finding) => finding.id === "plugin.manifest.invalid_path" && finding.evidence?.field === field);
+}
 function remoteUrlIssueFindingId(issue) {
     return issue === "insecure_non_loopback"
         ? "plugin.security.insecure_http_url"
@@ -223,9 +229,11 @@ function validateRequiredManifestFields(discoveredPackage) {
 }
 async function validateSkillsDirectory(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (manifest.skills === undefined) {
         return [];
     }
+    if (typeof manifest.skills !== "string")
+        return [];
     const skillsPath = path.resolve(rootPath, manifest.skills);
     if (!isPathWithinRoot(rootPath, skillsPath)) {
         return [
@@ -233,7 +241,7 @@ async function validateSkillsDirectory(discoveredPackage) {
                 manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
                 field: "skills",
                 configuredPath: manifest.skills,
-                resolvedPath: skillsPath
+                resolvedPath: relativePackagePath(rootPath, skillsPath)
             })
         ];
     }
@@ -246,13 +254,13 @@ async function validateSkillsDirectory(discoveredPackage) {
             manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
             field: "skills",
             configuredPath: manifest.skills,
-            resolvedPath: skillsPath
+            resolvedPath: relativePackagePath(rootPath, skillsPath)
         })
     ];
 }
 async function validateSkillDefinitions(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.skills) {
+    if (typeof manifest.skills !== "string") {
         return [];
     }
     const skillsPath = path.resolve(rootPath, manifest.skills);
@@ -319,7 +327,7 @@ async function validateSkillDefinitions(discoveredPackage) {
 }
 async function validateMcpConfig(discoveredPackage) {
     const { manifest, rootPath } = discoveredPackage;
-    if (!manifest.mcpServers) {
+    if (typeof manifest.mcpServers !== "string") {
         return [];
     }
     const mcpConfigPath = path.resolve(rootPath, manifest.mcpServers);
@@ -353,20 +361,28 @@ async function validateMcpConfig(discoveredPackage) {
             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}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "json" })
         ];
     }
-    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}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
-        ];
-    }
-    const servers = parsedConfig.mcpServers;
-    if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
+    const normalizedConfig = normalizeMcpConfig(parsedConfig);
+    if (!normalizedConfig.ok) {
+        if (normalizedConfig.reason === "ambiguous_shape") {
+            return [
+                buildFailure("plugin.mcp.ambiguous_shape", "The referenced `.mcp.json` file uses an ambiguous MCP config layout.", "Codex cannot safely choose between multiple wrapper layouts when they appear in one configuration file.", "Use exactly one supported layout: a direct server map, `mcp_servers`, or `mcpServers`.", { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
+            ];
+        }
+        if (normalizedConfig.field === "server" && normalizedConfig.invalidServerNames) {
+            return normalizedConfig.invalidServerNames.map((serverName) => 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.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "server"
+            }));
+        }
         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}\`.`, {
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a valid MCP server map.", "Without valid server entries, Codex cannot discover the bundled MCP server definitions.", `Use a direct server map, \`mcp_servers\`, or \`mcpServers\` in \`${mcpConfigPath}\`.`, {
                 configPath: relativePackagePath(rootPath, mcpConfigPath),
-                field: "mcpServers"
+                field: normalizedConfig.field
             })
         ];
     }
+    const servers = normalizedConfig.servers;
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
@@ -433,11 +449,17 @@ export async function validatePlugin(targetPath, options = {}) {
             findings: withFindingFingerprints([await buildMissingManifestFailure(rootPath)], rootPath)
         };
     }
+    const componentFindings = await validatePluginComponents(discoveredPackage);
+    const hookFindings = await validatePluginHooks(discoveredPackage);
+    const hasInvalidSkillsPath = hasInvalidComponentPath(componentFindings, "skills");
+    const hasInvalidMcpPath = hasInvalidComponentPath(componentFindings, "mcpServers");
     const staticFindings = [
         ...validateRequiredManifestFields(discoveredPackage),
-        ...(await validateSkillsDirectory(discoveredPackage)),
-        ...(await validateSkillDefinitions(discoveredPackage)),
-        ...(await validateMcpConfig(discoveredPackage))
+        ...componentFindings,
+        ...hookFindings,
+        ...(hasInvalidSkillsPath ? [] : await validateSkillsDirectory(discoveredPackage)),
+        ...(hasInvalidSkillsPath ? [] : await validateSkillDefinitions(discoveredPackage)),
+        ...(hasInvalidMcpPath ? [] : await validateMcpConfig(discoveredPackage))
     ];
     const staticFailed = staticFindings.some((finding) => finding.severity === "fail");
     const runtimeResult = options.runtime && !staticFailed

package/dist/domain/types.d.ts

@@ -55,7 +55,41 @@ export interface PluginManifest {
     description?: string;
     skills?: string;
     mcpServers?: string;
+    author?: unknown;
+    homepage?: unknown;
+    repository?: unknown;
+    license?: unknown;
+    keywords?: unknown;
+    apps?: unknown;
+    hooks?: PluginHooks;
+    interface?: unknown;
+}
+export declare const pluginHookEvents: readonly ["PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "UserPromptSubmit", "SubagentStop", "Stop", "SessionStart", "SubagentStart", "SessionEnd"];
+export type PluginHookEvent = (typeof pluginHookEvents)[number];
+export interface PluginHookCommandHandler {
+    type: "command";
+    command: string;
+    commandWindows?: string;
+    timeout?: number;
+    statusMessage?: string;
+    additionalContextLimit?: number;
+    async?: boolean;
+}
+export interface PluginHookUnsupportedHandler {
+    type: "prompt" | "agent";
+    async?: boolean;
+    [key: string]: unknown;
+}
+export type PluginHookHandler = PluginHookCommandHandler | PluginHookUnsupportedHandler;
+export interface PluginHookMatcherGroup {
+    matcher?: string;
+    hooks: PluginHookHandler[];
+}
+export interface PluginHookConfig {
+    description?: string;
+    hooks: Partial<Record<PluginHookEvent, PluginHookMatcherGroup[]>>;
 }
+export type PluginHooks = string | string[] | PluginHookConfig | PluginHookConfig[];
 export interface DiscoveredPackage {
     rootPath: string;
     manifestPath: string;

package/dist/domain/types.js

@@ -1 +1,13 @@
-export {};
+export const pluginHookEvents = [
+    "PreToolUse",
+    "PermissionRequest",
+    "PostToolUse",
+    "PreCompact",
+    "PostCompact",
+    "UserPromptSubmit",
+    "SubagentStop",
+    "Stop",
+    "SessionStart",
+    "SubagentStart",
+    "SessionEnd"
+];

package/dist/index.d.ts

@@ -14,6 +14,11 @@ export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest, type BuildExternalValidationCorpusOptions, type ExternalCorpusCaseResult, type ExternalCorpusClassificationCounts, type ExternalCorpusFindingReview, type ExternalCorpusManifest, type ExternalCorpusMode, type ExternalCorpusProfile, type ExternalCorpusSourceType, type ExternalValidationCorpusReport, type FindingReviewClassification } from "./core/external-validation-corpus.js";
 export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, loadCorpusMetricsManifest, reconcileCorpusMetricFindings, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText, type BuildCorpusMetricsDiffOptions, type BuildCorpusMetricsOptions, type CorpusMetricCounts, type CorpusMetricCountDeltas, type CorpusMetricFinding, type CorpusMetricFindingReview, type CorpusMetricReconciliation, type CorpusMetricsManifest, type CorpusMetricSource, type CorpusMetricThresholdCheck, type CorpusMetricThresholds, type CorpusMetricValues, type CorpusMetricValueComparison, type CorpusQualityMetricsDiffReport, type CorpusQualityMetricsDiffTarget, type CorpusQualityMetricsReport, type CorpusQualityMetricsTargetResult } from "./core/corpus-quality-metrics.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson, type DoctorOutputContract, type OutputContractRule, type OutputContractSchema } from "./core/output-contract.js";
+export { submissionRuleset, submissionManualChecks } from "./core/submission-ruleset.js";
+export { buildSubmissionPreflight, type SubmissionCheck, type SubmissionFinding, type SubmissionManualCheck, type SubmissionPreflightReport } from "./core/submission-preflight.js";
+export { validateSubmissionAssets, type SubmissionAssetResult } from "./core/submission-assets.js";
+export { validateSubmissionSkillMetadata, type SubmissionSkillMetadataResult } from "./core/submission-skill-metadata.js";
+export { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport, type BuildDoctorValidationCorpusOptions, type DoctorValidationCorpusReport, type ValidationCorpusCaseDefinition, type ValidationCorpusCaseResult } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis, type PackageAnalysis, type PackageAnalysisOptions, type PackageAnalysisStage, type PackageAnalysisTiming } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson, type BuildDoctorPerformanceReportOptions, type DoctorPerformanceReport, type DoctorPerformanceStage, type DoctorPerformanceStageName } from "./core/performance-report.js";

package/dist/index.js

@@ -14,6 +14,11 @@ export { buildDoctorAttestation, renderDoctorAttestation, renderDoctorAttestatio
 export { buildExternalValidationCorpusReport, ExternalCorpusManifestError, loadExternalCorpusManifest } from "./core/external-validation-corpus.js";
 export { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport, CorpusMetricsDiffError, CorpusMetricsManifestError, loadCorpusMetricsManifest, reconcileCorpusMetricFindings, renderCorpusQualityMetricsDiffJson, renderCorpusQualityMetricsDiffMarkdown, renderCorpusQualityMetricsDiffText, renderCorpusQualityMetricsJson, renderCorpusQualityMetricsMarkdown, renderCorpusQualityMetricsText } from "./core/corpus-quality-metrics.js";
 export { buildDoctorOutputContract, renderDoctorOutputContract, renderDoctorOutputContractJson } from "./core/output-contract.js";
+export { submissionRuleset, submissionManualChecks } from "./core/submission-ruleset.js";
+export { buildSubmissionPreflight } from "./core/submission-preflight.js";
+export { validateSubmissionAssets } from "./core/submission-assets.js";
+export { validateSubmissionSkillMetadata } from "./core/submission-skill-metadata.js";
+export { renderSubmissionPreflightJson, renderSubmissionPreflightMarkdown, renderSubmissionPreflightText, submissionPreflightExitCode } from "./reporting/render-submission-report.js";
 export { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
 export { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./core/package-analysis.js";
 export { buildDoctorPerformanceReport, renderDoctorPerformanceReport, renderDoctorPerformanceReportJson } from "./core/performance-report.js";