codex-plugin-doctor 1.58.0 → 1.59.0

package/dist/core/submission-preflight.js

@@ -0,0 +1,289 @@
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { validateSubmissionAssets } from "./submission-assets.js";
+import { submissionManualChecks, submissionRuleset } from "./submission-ruleset.js";
+import { validateSubmissionSkillMetadata } from "./submission-skill-metadata.js";
+const packageNamePattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const singleLineUnsupported = /[\u0000-\u001F\u007F\u2028\u2029\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/u;
+const multilineUnsupported = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u2028\u2029\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/u;
+const knownInterfaceFields = new Set([
+    "displayName", "shortDescription", "longDescription", "developerName", "category",
+    "capabilities", "websiteURL", "supportURL", "privacyPolicyURL", "termsOfServiceURL",
+    "brandColor", "brandColorDark", "defaultPrompt", "composerIcon", "logo", "screenshots"
+]);
+const maxSubmissionManifestBytes = 1024 * 1024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function finding(id, severity, message, evidence) {
+    return evidence === undefined ? { id, severity, message } : { id, severity, message, evidence };
+}
+function invalidField(field, evidence) {
+    return finding(`plugin.submission.interface.${field}`, "fail", "Listing field is invalid.", {
+        field,
+        ...evidence
+    });
+}
+function hasValidText(value, maximum, multiline = false) {
+    return typeof value === "string"
+        && value.trim().length > 0
+        && value.length <= maximum
+        && !(multiline ? multilineUnsupported : singleLineUnsupported).test(value);
+}
+function validateRequiredText(source, property, field, limit, multiline, findings) {
+    if (!hasValidText(source[property], limit, multiline)) {
+        findings.push(invalidField(field, { limit }));
+    }
+}
+function validatePackage(manifest, findings) {
+    const name = manifest.name;
+    if (typeof name !== "string" || name.length > submissionRuleset.limits.packageName || !packageNamePattern.test(name)) {
+        findings.push(finding("plugin.submission.package.name", "fail", "Package name is invalid.", {
+            field: "name", limit: submissionRuleset.limits.packageName
+        }));
+    }
+    const version = manifest.version;
+    if (typeof version !== "string" || version.length > submissionRuleset.limits.version || !semverPattern.test(version)) {
+        findings.push(finding("plugin.submission.package.version", "fail", "Package version is invalid.", {
+            field: "version", limit: submissionRuleset.limits.version
+        }));
+    }
+}
+function validateCapabilities(value, findings) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value) || value.length > submissionRuleset.limits.capabilities) {
+        findings.push(invalidField("capabilities", { limit: submissionRuleset.limits.capabilities }));
+    }
+    if (!Array.isArray(value)) {
+        return;
+    }
+    if (value.some((capability) => !hasValidText(capability, submissionRuleset.limits.capability))) {
+        findings.push(invalidField("capability", { limit: submissionRuleset.limits.capability }));
+    }
+}
+function normalizePrompt(prompt) {
+    return prompt.normalize("NFKC").trim().replace(/\s+/gu, " ");
+}
+function validateDefaultPrompt(value, findings) {
+    if (value === undefined) {
+        return;
+    }
+    const prompts = typeof value === "string" ? [value] : value;
+    if (!Array.isArray(prompts) || prompts.length > submissionRuleset.limits.starterPrompts) {
+        findings.push(invalidField("default_prompt", { limit: submissionRuleset.limits.starterPrompts }));
+        return;
+    }
+    const normalized = new Set();
+    const invalid = prompts.some((prompt) => {
+        if (!hasValidText(prompt, submissionRuleset.limits.starterPrompt) || prompt.includes("@")) {
+            return true;
+        }
+        const normalizedPrompt = normalizePrompt(prompt);
+        if (normalized.has(normalizedPrompt)) {
+            return true;
+        }
+        normalized.add(normalizedPrompt);
+        return false;
+    });
+    if (invalid) {
+        findings.push(invalidField("default_prompt", { limit: submissionRuleset.limits.starterPrompt }));
+    }
+}
+function isValidHttpsUrl(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > submissionRuleset.limits.url
+        || value.trim() !== value || singleLineUnsupported.test(value)) {
+        return false;
+    }
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "https:" && parsed.hostname.length > 0
+            && parsed.username.length === 0 && parsed.password.length === 0 && parsed.hash.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function validateListing(manifest, targetType) {
+    const findings = [];
+    validatePackage(manifest, findings);
+    const listing = manifest.interface;
+    if (!isRecord(listing)) {
+        findings.push(finding("plugin.submission.interface.required", "fail", "Listing interface mapping is required.", { field: "interface" }));
+        return findings;
+    }
+    validateRequiredText(listing, "displayName", "display_name", submissionRuleset.limits.displayName, false, findings);
+    validateRequiredText(listing, "shortDescription", "short_description", submissionRuleset.limits.shortDescription, false, findings);
+    validateRequiredText(listing, "longDescription", "long_description", submissionRuleset.limits.longDescription, true, findings);
+    validateRequiredText(listing, "developerName", "developer_name", submissionRuleset.limits.developerName, false, findings);
+    validateRequiredText(listing, "category", "category", 80, false, findings);
+    if (typeof listing.category === "string" && !submissionRuleset.categories.includes(listing.category)) {
+        findings.push(invalidField("category"));
+    }
+    validateCapabilities(listing.capabilities, findings);
+    validateDefaultPrompt(listing.defaultPrompt, findings);
+    if (targetType === "mcp-backed") {
+        for (const property of ["websiteURL", "supportURL", "privacyPolicyURL", "termsOfServiceURL"]) {
+            if (!isValidHttpsUrl(listing[property])) {
+                findings.push(finding("plugin.submission.interface.url", "fail", "Required listing URL is invalid.", {
+                    field: property, limit: submissionRuleset.limits.url
+                }));
+            }
+        }
+    }
+    for (const key of Object.keys(listing)) {
+        if (!knownInterfaceFields.has(key)) {
+            findings.push(finding("plugin.submission.interface.unknown_field", "warn", "Listing interface contains an unsupported field.", { field: key }));
+        }
+    }
+    return findings;
+}
+function isWithin(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+async function validateApp(rootPath, declaration) {
+    if (declaration === undefined) {
+        return [];
+    }
+    const invalid = () => [finding("plugin.submission.component.app", "fail", "App declaration must reference a contained parseable root file.", { path: ".app.json" })];
+    const invalidPath = () => [finding("plugin.submission.app.invalid_path", "fail", "App declaration resolves outside the package.", { path: ".app.json" })];
+    if (declaration !== "./.app.json") {
+        return invalid();
+    }
+    const candidatePath = path.resolve(rootPath, ".app.json");
+    try {
+        const [canonicalRoot, canonicalCandidate, details] = await Promise.all([
+            realpath(rootPath),
+            realpath(candidatePath),
+            stat(candidatePath)
+        ]);
+        if (!isWithin(canonicalRoot, canonicalCandidate)) {
+            return invalidPath();
+        }
+        if (!details.isFile() || details.size > 5 * 1024 * 1024) {
+            return invalid();
+        }
+        JSON.parse(await readFile(candidatePath, "utf8"));
+        return [];
+    }
+    catch {
+        return invalid();
+    }
+}
+function checkStatus(findings) {
+    if (findings.some((item) => item.severity === "fail")) {
+        return "fail";
+    }
+    return findings.some((item) => item.severity === "warn") ? "warn" : "pass";
+}
+function check(id, findings) {
+    return { id, status: checkStatus(findings), findingIds: findings.map((item) => item.id) };
+}
+function checklist(targetType) {
+    return submissionManualChecks.map((item) => ({
+        id: item.id,
+        label: item.label,
+        state: item.mcpOnly && targetType === "skills-only" ? "not_applicable" : "required"
+    }));
+}
+function invalidPackageReport() {
+    const findings = [finding("plugin.submission.package.invalid", "fail", "Plugin manifest is missing or invalid.")];
+    const checks = [check("listing", findings), check("components", []), check("assets", []), check("skills", [])];
+    return {
+        schemaVersion: "1.0.0",
+        rulesetVersion: submissionRuleset.version,
+        targetType: "skills-only",
+        status: "fail",
+        readiness: "blocked",
+        summary: { passed: 3, warnings: 0, blockers: 1, manualChecks: 3 },
+        checks,
+        findings,
+        manualChecklist: checklist("skills-only")
+    };
+}
+function oversizedPackageReport() {
+    const findings = [finding("plugin.submission.package.too_large", "fail", "Plugin manifest exceeds the submission preflight size limit.", {
+            path: ".codex-plugin/plugin.json", limit: maxSubmissionManifestBytes
+        })];
+    const checks = [check("listing", findings), check("components", []), check("assets", []), check("skills", [])];
+    return {
+        schemaVersion: "1.0.0",
+        rulesetVersion: submissionRuleset.version,
+        targetType: "skills-only",
+        status: "fail",
+        readiness: "blocked",
+        summary: { passed: 3, warnings: 0, blockers: 1, manualChecks: 3 },
+        checks,
+        findings,
+        manualChecklist: checklist("skills-only")
+    };
+}
+async function discoverSubmissionPackage(targetPath) {
+    const rootPath = path.resolve(targetPath);
+    const manifestPath = path.join(rootPath, ".codex-plugin", "plugin.json");
+    try {
+        const linkDetails = await lstat(manifestPath);
+        if (!linkDetails.isFile())
+            return null;
+        const details = await stat(manifestPath);
+        if (details.size > maxSubmissionManifestBytes)
+            return "too_large";
+        const content = new TextDecoder("utf-8", { fatal: true }).decode(await readFile(manifestPath));
+        return { rootPath, manifestPath, manifest: JSON.parse(content) };
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildSubmissionPreflight(targetPath) {
+    if (typeof targetPath !== "string") {
+        return invalidPackageReport();
+    }
+    const discovered = await discoverSubmissionPackage(targetPath);
+    if (discovered === "too_large") {
+        return oversizedPackageReport();
+    }
+    if (!discovered || !isRecord(discovered.manifest)) {
+        return invalidPackageReport();
+    }
+    const manifest = discovered.manifest;
+    const targetType = manifest.mcpServers !== undefined || manifest.apps !== undefined
+        ? "mcp-backed"
+        : "skills-only";
+    const listingFindings = validateListing(manifest, targetType);
+    const componentFindings = await validateApp(discovered.rootPath, manifest.apps);
+    const assetFindings = (await validateSubmissionAssets(discovered)).findings;
+    const skillFindings = (await validateSubmissionSkillMetadata(discovered, targetType)).findings;
+    const interfaceValue = manifest.interface;
+    if (targetType === "skills-only" && isRecord(interfaceValue) && interfaceValue.screenshots !== undefined) {
+        componentFindings.push(finding("plugin.submission.component.excluded", "fail", "Screenshots are excluded for skills-only submissions.", { field: "screenshots" }));
+    }
+    const findings = [...listingFindings, ...componentFindings, ...assetFindings, ...skillFindings];
+    const checks = [
+        check("listing", listingFindings),
+        check("components", componentFindings),
+        check("assets", assetFindings),
+        check("skills", skillFindings)
+    ];
+    const blockers = findings.filter((item) => item.severity === "fail").length;
+    const manualChecklist = checklist(targetType);
+    return {
+        schemaVersion: "1.0.0",
+        rulesetVersion: submissionRuleset.version,
+        targetType,
+        status: blockers > 0 ? "fail" : "pass",
+        readiness: blockers > 0 ? "blocked" : "manual_review_required",
+        summary: {
+            passed: checks.filter((item) => item.status === "pass").length,
+            warnings: findings.filter((item) => item.severity === "warn").length,
+            blockers,
+            manualChecks: manualChecklist.filter((item) => item.state === "required").length
+        },
+        checks,
+        findings,
+        manualChecklist
+    };
+}

package/dist/core/submission-ruleset.d.ts

@@ -0,0 +1,56 @@
+export declare const submissionRuleset: Readonly<{
+    version: "openai-directory-2026-08-15";
+    reviewedAt: "2026-08-15";
+    sources: readonly string[];
+    limits: Readonly<{
+        packageName: 64;
+        version: 64;
+        displayName: 30;
+        shortDescription: 30;
+        longDescription: 4000;
+        developerName: 80;
+        capabilities: 20;
+        capability: 120;
+        starterPrompts: 3;
+        starterPrompt: 128;
+        url: 1024;
+    }>;
+    categories: readonly string[];
+}>;
+export declare const submissionManualChecks: readonly (Readonly<{
+    id: "developer-business-identity";
+    label: "Developer and business identity";
+    mcpOnly: false;
+}> | Readonly<{
+    id: "attestations";
+    label: "Required attestations";
+    mcpOnly: false;
+}> | Readonly<{
+    id: "skill-safety-scan";
+    label: "Skill safety scan";
+    mcpOnly: false;
+}> | Readonly<{
+    id: "demo-video";
+    label: "Demo video";
+    mcpOnly: true;
+}> | Readonly<{
+    id: "tool-tests";
+    label: "Exactly 5 positive and 3 negative tool tests";
+    mcpOnly: true;
+}> | Readonly<{
+    id: "release-notes";
+    label: "Release notes";
+    mcpOnly: true;
+}> | Readonly<{
+    id: "production-domain-verification";
+    label: "Production domain verification and current tool scan";
+    mcpOnly: true;
+}> | Readonly<{
+    id: "tool-annotations";
+    label: "Tool annotations and justifications";
+    mcpOnly: true;
+}> | Readonly<{
+    id: "oauth-reviewer-credentials";
+    label: "OAuth reviewer credentials";
+    mcpOnly: true;
+}>)[];

package/dist/core/submission-ruleset.js

@@ -0,0 +1,38 @@
+export const submissionRuleset = Object.freeze({
+    version: "openai-directory-2026-08-15",
+    reviewedAt: "2026-08-15",
+    sources: Object.freeze([
+        "https://developers.openai.com/plugins/build/plugins",
+        "https://developers.openai.com/plugins/deploy/app-review",
+        "https://developers.openai.com/plugins/deploy/submission-errors"
+    ]),
+    limits: Object.freeze({
+        packageName: 64,
+        version: 64,
+        displayName: 30,
+        shortDescription: 30,
+        longDescription: 4000,
+        developerName: 80,
+        capabilities: 20,
+        capability: 120,
+        starterPrompts: 3,
+        starterPrompt: 128,
+        url: 1024
+    }),
+    categories: Object.freeze([
+        "Productivity", "Creativity", "Developer Tools", "Business & Operations",
+        "Data & Analytics", "Communication", "Education & Research", "Security",
+        "Finance", "Healthcare", "Travel", "Entertainment", "Other"
+    ])
+});
+export const submissionManualChecks = Object.freeze([
+    Object.freeze({ id: "developer-business-identity", label: "Developer and business identity", mcpOnly: false }),
+    Object.freeze({ id: "attestations", label: "Required attestations", mcpOnly: false }),
+    Object.freeze({ id: "skill-safety-scan", label: "Skill safety scan", mcpOnly: false }),
+    Object.freeze({ id: "demo-video", label: "Demo video", mcpOnly: true }),
+    Object.freeze({ id: "tool-tests", label: "Exactly 5 positive and 3 negative tool tests", mcpOnly: true }),
+    Object.freeze({ id: "release-notes", label: "Release notes", mcpOnly: true }),
+    Object.freeze({ id: "production-domain-verification", label: "Production domain verification and current tool scan", mcpOnly: true }),
+    Object.freeze({ id: "tool-annotations", label: "Tool annotations and justifications", mcpOnly: true }),
+    Object.freeze({ id: "oauth-reviewer-credentials", label: "OAuth reviewer credentials", mcpOnly: true })
+]);

package/dist/core/submission-skill-metadata.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoveredPackage } from "../domain/types.js";
+import type { SubmissionFinding } from "./submission-preflight.js";
+type TargetType = "skills-only" | "mcp-backed";
+export interface SubmissionSkillMetadataResult {
+    findings: SubmissionFinding[];
+    skillCount: number;
+}
+export declare function validateSubmissionSkillMetadata(discoveredPackage: DiscoveredPackage, targetType: TargetType): Promise<SubmissionSkillMetadataResult>;
+export {};