codex-plugin-doctor 1.16.0 → 1.17.0

package/README.md

@@ -358,9 +358,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.16.0
+      - uses: Esquetta/CodexPluginDoctor@v1.17.0
         with:
-          version: "1.16.0"
+          version: "1.17.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/dep-audit.d.ts

@@ -0,0 +1,17 @@
+export interface DepAuditVulnerability {
+    name: string;
+    severity: "critical" | "high" | "moderate" | "low";
+    isDirect: boolean;
+    fixAvailable: boolean;
+    via: string[];
+}
+export interface DepAuditReport {
+    targetPath: string;
+    status: "pass" | "warn" | "fail";
+    vulnerabilities: DepAuditVulnerability[];
+    totalVulnerabilities: number;
+    auditJson: unknown;
+}
+export declare function buildDepAudit(targetPath: string): Promise<DepAuditReport>;
+export declare function renderDepAudit(report: DepAuditReport): string;
+export declare function renderDepAuditJson(report: DepAuditReport): string;

package/dist/core/dep-audit.js

@@ -0,0 +1,169 @@
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+function resolvePackageJson(targetPath) {
+    return path.resolve(targetPath, "package.json");
+}
+async function fileExists(filePath) {
+    try {
+        const details = await stat(filePath);
+        return details.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function runNpmAudit(cwd) {
+    return new Promise((resolve, reject) => {
+        execFile("npm", ["audit", "--json"], { cwd, shell: process.platform === "win32", timeout: 120_000 }, (error, stdout, stderr) => {
+            const parsed = (() => {
+                try {
+                    return JSON.parse(stdout);
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (parsed) {
+                resolve(parsed);
+            }
+            else {
+                reject(new Error(stderr.trim() || error?.message || "npm audit failed"));
+            }
+        });
+    });
+}
+function extractVulnerabilities(auditJson) {
+    const result = [];
+    if (!auditJson || typeof auditJson !== "object") {
+        return result;
+    }
+    const data = auditJson;
+    const vulns = data.vulnerabilities;
+    if (!vulns) {
+        return result;
+    }
+    for (const [name, entry] of Object.entries(vulns)) {
+        if (!entry || typeof entry !== "object") {
+            continue;
+        }
+        const vuln = entry;
+        const severity = vuln.severity;
+        const isDirect = Boolean(vuln.isDirect);
+        const fixAvailable = Boolean(vuln.fixAvailable);
+        const via = Array.isArray(vuln.via) ? vuln.via.map((v) => (typeof v === "string" ? v : "unknown")) : [];
+        if (severity === "critical" || severity === "high" || severity === "moderate" || severity === "low") {
+            result.push({
+                name,
+                severity,
+                isDirect,
+                fixAvailable,
+                via
+            });
+        }
+    }
+    return result;
+}
+function computeStatus(vulnerabilities) {
+    if (vulnerabilities.length === 0) {
+        return "pass";
+    }
+    const hasCritical = vulnerabilities.some((v) => v.severity === "critical");
+    const hasHigh = vulnerabilities.some((v) => v.severity === "high");
+    if (hasCritical) {
+        return "fail";
+    }
+    if (hasHigh) {
+        return "fail";
+    }
+    return "warn";
+}
+export async function buildDepAudit(targetPath) {
+    const resolvedPath = path.resolve(targetPath);
+    const packageJsonPath = resolvePackageJson(resolvedPath);
+    if (!(await fileExists(packageJsonPath))) {
+        return {
+            targetPath: resolvedPath,
+            status: "pass",
+            vulnerabilities: [],
+            totalVulnerabilities: 0,
+            auditJson: null
+        };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    }
+    catch {
+        return {
+            targetPath: resolvedPath,
+            status: "warn",
+            vulnerabilities: [],
+            totalVulnerabilities: 0,
+            auditJson: { error: "Failed to parse package.json" }
+        };
+    }
+    const hasDeps = pkg.dependencies || pkg.devDependencies;
+    if (!hasDeps) {
+        return {
+            targetPath: resolvedPath,
+            status: "pass",
+            vulnerabilities: [],
+            totalVulnerabilities: 0,
+            auditJson: { message: "No runtime dependencies to audit" }
+        };
+    }
+    let auditJson;
+    try {
+        auditJson = await runNpmAudit(resolvedPath);
+    }
+    catch (error) {
+        return {
+            targetPath: resolvedPath,
+            status: "warn",
+            vulnerabilities: [],
+            totalVulnerabilities: 0,
+            auditJson: { error: error.message }
+        };
+    }
+    const vulnerabilities = extractVulnerabilities(auditJson);
+    const status = computeStatus(vulnerabilities);
+    return {
+        targetPath: resolvedPath,
+        status,
+        vulnerabilities,
+        totalVulnerabilities: vulnerabilities.length,
+        auditJson
+    };
+}
+export function renderDepAudit(report) {
+    const lines = [
+        "Dependency Vulnerability Audit",
+        "=============================",
+        `Path: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Vulnerabilities: ${report.totalVulnerabilities}`,
+        ""
+    ];
+    if (report.vulnerabilities.length === 0) {
+        lines.push("No known vulnerabilities found.");
+        return lines.join("\n");
+    }
+    for (const vuln of report.vulnerabilities) {
+        const tag = vuln.severity === "critical" ? "CRITICAL" :
+            vuln.severity === "high" ? "HIGH" :
+                vuln.severity === "moderate" ? "MODERATE" : "LOW";
+        lines.push(`${tag.padEnd(10)} ${vuln.name}`, `          Direct: ${vuln.isDirect ? "yes" : "no"}`, `          Fix available: ${vuln.fixAvailable ? "yes" : "no"}`, vuln.via.length > 0 ? `          Via: ${vuln.via.join(", ")}` : "", "");
+    }
+    return lines.join("\n");
+}
+export function renderDepAuditJson(report) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        targetPath: report.targetPath,
+        status: report.status,
+        totalVulnerabilities: report.totalVulnerabilities,
+        vulnerabilities: report.vulnerabilities,
+        audit: report.auditJson
+    }, null, 2);
+}

package/dist/core/init-git-hooks.d.ts

@@ -0,0 +1,8 @@
+export interface InitGitHooksResult {
+    rootPath: string;
+    hookPaths: string[];
+    preExisting: string[];
+}
+export declare function initGitHooks(targetPath: string, options?: {
+    force?: boolean;
+}): Promise<InitGitHooksResult>;

package/dist/core/init-git-hooks.js

@@ -0,0 +1,77 @@
+import { chmod, mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+const preCommitHook = [
+    "#!/usr/bin/env sh",
+    "# Generated by codex-plugin-doctor init git-hooks",
+    "# Validates the plugin package before every commit.",
+    "",
+    "echo \"Codex Plugin Doctor: running pre-commit validation...\"",
+    "",
+    "npx --yes codex-plugin-doctor check . --profile ci",
+    "",
+    "if [ $? -ne 0 ]; then",
+    "  echo \"\"",
+    "  echo \"Plugin validation failed. Commit blocked.\"",
+    "  echo \"Run 'codex-plugin-doctor check .' to see full diagnostics.\"",
+    "  exit 1",
+    "fi",
+    ""
+].join("\n");
+const prePushHook = [
+    "#!/usr/bin/env sh",
+    "# Generated by codex-plugin-doctor init git-hooks",
+    "# Validates the plugin package before every push.",
+    "",
+    "echo \"Codex Plugin Doctor: running pre-push validation...\"",
+    "",
+    "npx --yes codex-plugin-doctor check . --profile ci --runtime",
+    "",
+    "if [ $? -ne 0 ]; then",
+    "  echo \"\"",
+    "  echo \"Plugin validation failed. Push blocked.\"",
+    "  echo \"Run 'codex-plugin-doctor check . --runtime' to see full diagnostics.\"",
+    "  exit 1",
+    "fi",
+    ""
+].join("\n");
+async function fileExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeHook(hookPath, content, force) {
+    const exists = await fileExists(hookPath);
+    if (exists && !force) {
+        return false;
+    }
+    await writeFile(hookPath, content, "utf8");
+    if (process.platform !== "win32") {
+        await chmod(hookPath, 0o755);
+    }
+    return exists;
+}
+export async function initGitHooks(targetPath, options = {}) {
+    const rootPath = path.resolve(targetPath);
+    const hooksDir = path.join(rootPath, ".git", "hooks");
+    const force = options.force ?? false;
+    await mkdir(hooksDir, { recursive: true });
+    const hookPaths = [];
+    const preExisting = [];
+    const preCommitPath = path.join(hooksDir, "pre-commit");
+    const prePushPath = path.join(hooksDir, "pre-push");
+    const wasPreCommitExisting = await writeHook(preCommitPath, preCommitHook, force);
+    hookPaths.push(preCommitPath);
+    if (wasPreCommitExisting) {
+        preExisting.push(preCommitPath);
+    }
+    const wasPrePushExisting = await writeHook(prePushPath, prePushHook, force);
+    hookPaths.push(prePushPath);
+    if (wasPrePushExisting) {
+        preExisting.push(prePushPath);
+    }
+    return { rootPath, hookPaths, preExisting };
+}

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

@@ -0,0 +1,13 @@
+export interface WatchPluginOptions {
+    targetPath: string;
+    debounceMs?: number;
+    runtime?: boolean;
+    jsonOutput?: boolean;
+    outputPath?: string | null;
+}
+export interface WatchPluginResult {
+    targetPath: string;
+    validations: number;
+    failures: number;
+}
+export declare function watchPlugin(options: WatchPluginOptions): Promise<WatchPluginResult>;

package/dist/core/watch-plugin.js

@@ -0,0 +1,87 @@
+import { watch } from "node:fs";
+import path from "node:path";
+import { validatePlugin } from "./validate-plugin.js";
+function renderWatchValidation(result, iteration, jsonOutput) {
+    if (jsonOutput) {
+        const report = {
+            schemaVersion: "1.0.0",
+            iteration,
+            timestamp: new Date().toISOString(),
+            targetPath: result.targetPath,
+            status: result.status,
+            findingsCount: result.findings.length,
+            findings: result.findings
+        };
+        return JSON.stringify(report, null, 2);
+    }
+    const icon = result.status === "pass" ? "PASS" : "FAIL";
+    return [
+        `[#${String(iteration).padStart(3, "0")}] ${icon}  ${result.targetPath}`,
+        `      findings: ${result.findings.length} (${result.status})`,
+        result.findings.length > 0
+            ? result.findings.map((f) => `        ${f.severity === "fail" ? "FAIL" : "WARN"}  ${f.id}: ${f.message}`).join("\n")
+            : ""
+    ].filter(Boolean).join("\n");
+}
+export async function watchPlugin(options) {
+    const { targetPath, debounceMs = 300, runtime = false, jsonOutput = false, outputPath = null } = options;
+    const resolvedPath = path.resolve(targetPath);
+    let validations = 0;
+    let failures = 0;
+    let timer = null;
+    let pending = false;
+    const runValidation = async (iteration) => {
+        const result = await validatePlugin(resolvedPath, { runtime });
+        validations += 1;
+        if (result.status !== "pass") {
+            failures += 1;
+        }
+        const output = renderWatchValidation(result, iteration, jsonOutput);
+        if (outputPath) {
+            const { writeFile } = await import("node:fs/promises");
+            await writeFile(outputPath, output, "utf8");
+        }
+        else {
+            process.stdout.write(`${output}\n\n`);
+        }
+    };
+    return new Promise((resolve, _reject) => {
+        let iteration = 0;
+        const schedule = () => {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            if (pending) {
+                return;
+            }
+            pending = true;
+            timer = setTimeout(async () => {
+                pending = false;
+                timer = null;
+                iteration += 1;
+                await runValidation(iteration);
+            }, debounceMs);
+        };
+        const watcher = watch(resolvedPath, { recursive: true }, (_eventType, filename) => {
+            if (!filename || filename.includes("node_modules") || filename.startsWith(".git")) {
+                return;
+            }
+            schedule();
+        });
+        watcher.on("error", (error) => {
+            process.stderr.write(`Watch error: ${error.message}\n`);
+        });
+        const handleExit = () => {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            watcher.close();
+            resolve({ targetPath: resolvedPath, validations, failures });
+        };
+        process.on("SIGINT", handleExit);
+        process.on("SIGTERM", handleExit);
+        process.on("SIGHUP", handleExit);
+        process.stdout.write(`Watching ${resolvedPath} for changes (debounce: ${debounceMs}ms, runtime: ${runtime ? "enabled" : "disabled"})...\nPress Ctrl+C to stop.\n\n`);
+        schedule();
+    });
+}

package/dist/index.d.ts

@@ -19,4 +19,7 @@ export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorIn
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson, type EcosystemAuditReport } from "./audit/ecosystem-audit.js";
 export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames, type PolicyPackName } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson, type GenericMcpDoctorReport } from "./mcp/generic-mcp-doctor.js";
+export { watchPlugin, type WatchPluginOptions, type WatchPluginResult } from "./core/watch-plugin.js";
+export { buildDepAudit, renderDepAudit, renderDepAuditJson, type DepAuditReport, type DepAuditVulnerability } from "./core/dep-audit.js";
+export { initGitHooks, type InitGitHooksResult } from "./core/init-git-hooks.js";
 export declare function runCheck(targetPath: string, options?: CheckOptions): Promise<CheckResult>;

package/dist/index.js

@@ -19,6 +19,9 @@ export { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorIn
 export { buildEcosystemAudit, renderEcosystemAudit, renderEcosystemAuditJson } from "./audit/ecosystem-audit.js";
 export { applyPolicyToDoctorConfig, applyPolicyToSecurityAudit, parsePolicyPack, policyEnablesRuntime, policyFailsOnWarnings, policyPackNames } from "./policy/policy-packs.js";
 export { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
+export { watchPlugin } from "./core/watch-plugin.js";
+export { buildDepAudit, renderDepAudit, renderDepAuditJson } from "./core/dep-audit.js";
+export { initGitHooks } from "./core/init-git-hooks.js";
 export async function runCheck(targetPath, options = {}) {
     return validatePlugin(targetPath, options);
 }

package/dist/run-cli.js

@@ -30,6 +30,9 @@ import { buildDoctorInspectorReport, renderDoctorInspectorReport, renderDoctorIn
 import { applyFixPlan, buildFixPlan, renderApplyFixResult, renderFixPlanJsonReport, renderFixPlan } from "./core/fix-plan.js";
 import { renderClientDoctor, renderEnvironmentDoctor, renderEnvironmentDoctorJson } from "./core/environment-doctor.js";
 import { initCiWorkflow } from "./core/init-ci.js";
+import { watchPlugin } from "./core/watch-plugin.js";
+import { buildDepAudit, renderDepAudit, renderDepAuditJson } from "./core/dep-audit.js";
+import { initGitHooks } from "./core/init-git-hooks.js";
 import { initPluginPackage, initPluginTemplates, isInitPluginTemplate } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
 import { buildGenericMcpDoctor, renderGenericMcpDoctor, renderGenericMcpDoctorJson } from "./mcp/generic-mcp-doctor.js";
@@ -73,7 +76,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--json] [--output <path>]\n       codex-plugin-doctor mcp <path> [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus|runtime-plan <path> [--json|--markdown] [--output <path>]|runtime-policy <path> [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--upload]|mcp <path>|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
 }
 const performanceStageNames = new Set([
     "validation",
@@ -1219,6 +1222,50 @@ export async function runCli(args, io = defaultIo, options = {}) {
         ].join("\n"));
         return 0;
     }
+    if (command === "init-git-hooks") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const initFlags = maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        const force = initFlags.includes("--force");
+        const result = await initGitHooks(targetPath, { force });
+        const overwritten = result.preExisting.length > 0
+            ? `\nOverwritten existing hooks: ${result.preExisting.join(", ")}`
+            : "";
+        io.writeStdout([
+            "Initialized Codex Plugin Doctor git hooks",
+            `Root: ${result.rootPath}`,
+            `Hooks: ${result.hookPaths.join(", ")}`,
+            overwritten
+        ].filter(Boolean).join("\n"));
+        return 0;
+    }
+    if (command === "watch") {
+        const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+        const watchFlags = maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
+        const runtime = watchFlags.includes("--runtime");
+        const jsonOutput = watchFlags.includes("--json");
+        const outputIndex = watchFlags.indexOf("--output");
+        const outputPath = outputIndex === -1 ? null : watchFlags[outputIndex + 1];
+        const debounceIndex = watchFlags.indexOf("--debounce-ms");
+        const debounceRaw = debounceIndex === -1 ? null : watchFlags[debounceIndex + 1];
+        const debounceMs = debounceRaw ? Number(debounceRaw) || 300 : 300;
+        if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+            io.writeStderr("Missing path after --output.");
+            return 2;
+        }
+        const result = await watchPlugin({
+            targetPath,
+            debounceMs,
+            runtime,
+            jsonOutput,
+            outputPath
+        });
+        io.writeStdout(`\nStopped watching ${result.targetPath}: ${result.validations} validations, ${result.failures} failures.`);
+        return result.failures > 0 ? 1 : 0;
+    }
     if (command === "fix") {
         if (!maybePath || maybePath.startsWith("--")) {
             io.writeStderr("Missing target path. Usage: codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)");
@@ -1324,10 +1371,32 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return report.exitCode;
     }
     if (command === "audit") {
+        if (maybePath === "deps") {
+            const targetPath = remainingArgs[0] && !remainingArgs[0].startsWith("--") ? remainingArgs[0] : ".";
+            const depsFlags = remainingArgs[0] && remainingArgs[0].startsWith("--")
+                ? remainingArgs
+                : remainingArgs.slice(1);
+            const jsonOutput = depsFlags.includes("--json");
+            const outputIndex = depsFlags.indexOf("--output");
+            const outputPath = outputIndex === -1 ? null : depsFlags[outputIndex + 1];
+            if (outputIndex !== -1 && (!outputPath || outputPath.startsWith("--"))) {
+                io.writeStderr("Missing path after --output.");
+                return 2;
+            }
+            const report = await buildDepAudit(targetPath);
+            const renderedReport = jsonOutput
+                ? renderDepAuditJson(report)
+                : renderDepAudit(report);
+            if (outputPath) {
+                await writeFile(outputPath, renderedReport, "utf8");
+            }
+            io.writeStdout(renderedReport);
+            return report.status === "fail" ? 1 : 0;
+        }
         const auditFlags = maybePath ? [maybePath, ...remainingArgs] : remainingArgs;
         const installed = auditFlags.includes("--installed");
         if (!installed) {
-            io.writeStderr("Usage: codex-plugin-doctor audit --installed [filter] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]");
+            io.writeStderr("Usage: codex-plugin-doctor audit --installed [filter] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--json] [--output <path>]");
             return 2;
         }
         const installedIndex = auditFlags.indexOf("--installed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",