codex-plugin-doctor 1.16.0 → 1.18.0

package/README.md

@@ -232,12 +232,18 @@ codex-plugin-doctor doctor clients
 codex-plugin-doctor doctor --update-check
 codex-plugin-doctor audit --installed
 codex-plugin-doctor audit --installed --security --compat
-codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
-codex-plugin-doctor audit --installed --security --compat --cache
-codex-plugin-doctor audit --installed --changed --cache
-codex-plugin-doctor mcp .
-codex-plugin-doctor mcp . --json
-codex-plugin-doctor mcp . --json --output mcp-doctor.json
+codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
+codex-plugin-doctor audit --installed --security --compat --cache
+codex-plugin-doctor audit --installed --changed --cache
+codex-plugin-doctor audit deps .
+codex-plugin-doctor audit deps . --json --output dependency-audit.json
+codex-plugin-doctor watch .
+codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500
+codex-plugin-doctor init-git-hooks .
+codex-plugin-doctor init-git-hooks . --json
+codex-plugin-doctor mcp .
+codex-plugin-doctor mcp . --json
+codex-plugin-doctor mcp . --json --output mcp-doctor.json
 codex-plugin-doctor init my-plugin
 codex-plugin-doctor init my-mcp --template mcp-stdio
 codex-plugin-doctor init remote-mcp --template mcp-http
@@ -294,9 +300,15 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
-`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
-
-`--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
+`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
+
+`audit deps <path>` runs `npm audit --json` for the target package and normalizes dependency vulnerability results into a stable `schemaVersion: "1.0.0"` report. Use `--json --output dependency-audit.json` when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload.
+
+`watch <path>` continuously validates a plugin package after file changes. Use `--debounce-ms <ms>` to tune noisy repositories, `--runtime` when runtime probes are required, and `--json --output watch-latest.json` when another process should consume the latest validation snapshot.
+
+`init-git-hooks [path]` installs generated pre-commit and pre-push hooks that run Codex Plugin Doctor validation before local commits and pushes. Add `--force` to overwrite existing hooks and `--json` when setup automation needs the written hook paths.
+
+`--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
 
 `mcp <path>` diagnoses generic MCP packages that may not have a Codex plugin manifest. It looks for `.mcp.json` or a manifest `mcpServers` reference, validates the top-level `mcpServers` object and server transports, adds MCP command-surface security findings, and includes the all-client compatibility matrix in the same report.
 
@@ -358,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.16.0
+      - uses: Esquetta/CodexPluginDoctor@v1.18.0
         with:
-          version: "1.16.0"
+          version: "1.18.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/output-contract.js

@@ -34,11 +34,27 @@ const publicSchemaDefinitions = [
         command: "codex-plugin-doctor audit --installed --json",
         required: ["schemaVersion", "generatedAt", "summary", "items"]
     },
+    {
+        id: "doctor.audit.deps.json",
+        command: "codex-plugin-doctor audit deps <path> --json",
+        required: ["schemaVersion", "targetPath", "status", "totalVulnerabilities", "vulnerabilities", "audit"]
+    },
     {
         id: "doctor.fix.plan.json",
         command: "codex-plugin-doctor fix <path> --dry-run --json",
         required: ["schemaVersion", "targetPath", "mode", "actions"]
     },
+    {
+        id: "doctor.watch.validation.json",
+        command: "codex-plugin-doctor watch <path> --json",
+        required: ["schemaVersion", "iteration", "timestamp", "targetPath", "status", "findingsCount", "findings"]
+    },
+    {
+        id: "doctor.git.hooks.json",
+        command: "codex-plugin-doctor init-git-hooks <path> --json",
+        outputKind: "doctor.git.hooks",
+        required: ["schemaVersion", "kind", "rootPath", "hookPaths", "preExisting"]
+    },
     {
         id: "doctor.history.json",
         command: "codex-plugin-doctor history <history.jsonl> --json",

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] [--json]\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,61 @@ 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 jsonOutput = initFlags.includes("--json");
+        const result = await initGitHooks(targetPath, { force });
+        if (jsonOutput) {
+            io.writeStdout(JSON.stringify({
+                schemaVersion: "1.0.0",
+                kind: "doctor.git.hooks",
+                rootPath: result.rootPath,
+                hookPaths: result.hookPaths,
+                preExisting: result.preExisting
+            }, null, 2));
+            return 0;
+        }
+        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 +1382,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.18.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",