codex-plugin-doctor 0.1.2 → 0.1.4

package/README.md

@@ -71,11 +71,20 @@ Global install from npm:
 
 ```bash
 npm install -g codex-plugin-doctor
+codex-plugin-doctor --version
 codex-plugin-doctor check path/to/plugin-package
 ```
 
 Run `codex-plugin-doctor check .` from the root of a Codex plugin package that contains `.codex-plugin/plugin.json`. The Codex Plugin Doctor source repository is not itself a plugin package.
 
+If you already have Codex installed locally and do not know plugin paths, discover the installed plugin cache:
+
+```bash
+codex-plugin-doctor list --installed
+codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed github
+```
+
 Run from source:
 
 ```bash
@@ -144,6 +153,7 @@ x plugin.security.hard_coded_secret
 Run these from a Codex plugin package root:
 
 ```bash
+codex-plugin-doctor --version
 codex-plugin-doctor check .
 codex-plugin-doctor check . --json
 codex-plugin-doctor check . --json --output report.json
@@ -154,6 +164,15 @@ codex-plugin-doctor check . --runtime
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
+
+```bash
+codex-plugin-doctor list --installed
+codex-plugin-doctor check --installed
+codex-plugin-doctor check --installed github
+codex-plugin-doctor check --installed github --runtime --no-animations
+```
+
 To self-test this repository after cloning it:
 
 ```bash

package/dist/core/discover-installed-plugins.d.ts

@@ -0,0 +1,12 @@
+export interface InstalledPlugin {
+    name: string;
+    version?: string;
+    rootPath: string;
+    manifestPath: string;
+    relativePath: string;
+}
+export interface InstalledPluginDiscoveryOptions {
+    env?: Record<string, string | undefined>;
+}
+export declare function discoverInstalledPlugins(options?: InstalledPluginDiscoveryOptions): Promise<InstalledPlugin[]>;
+export declare function filterInstalledPlugins(plugins: InstalledPlugin[], query: string | null): InstalledPlugin[];

package/dist/core/discover-installed-plugins.js

@@ -0,0 +1,69 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function getCodexHomeCandidates(env) {
+    const candidates = env.CODEX_HOME
+        ? [env.CODEX_HOME]
+        : [path.join(os.homedir(), ".codex")];
+    return [...new Set(candidates.map((candidate) => path.resolve(candidate)))];
+}
+async function findManifestPaths(rootPath) {
+    const entries = await readdir(rootPath, { withFileTypes: true });
+    const manifestPaths = [];
+    for (const entry of entries) {
+        const entryPath = path.join(rootPath, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === ".codex-plugin") {
+                manifestPaths.push(path.join(entryPath, "plugin.json"));
+                continue;
+            }
+            manifestPaths.push(...(await findManifestPaths(entryPath)));
+        }
+    }
+    return manifestPaths;
+}
+export async function discoverInstalledPlugins(options = {}) {
+    const env = options.env ?? process.env;
+    const plugins = [];
+    for (const codexHome of getCodexHomeCandidates(env)) {
+        const cacheRoot = path.join(codexHome, "plugins", "cache");
+        if (!(await directoryExists(cacheRoot))) {
+            continue;
+        }
+        for (const manifestPath of await findManifestPaths(cacheRoot)) {
+            try {
+                const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+                const rootPath = path.dirname(path.dirname(manifestPath));
+                const relativePath = path.relative(cacheRoot, rootPath);
+                plugins.push({
+                    name: typeof manifest.name === "string" ? manifest.name : path.basename(rootPath),
+                    version: typeof manifest.version === "string" ? manifest.version : undefined,
+                    rootPath,
+                    manifestPath,
+                    relativePath
+                });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return plugins.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+export function filterInstalledPlugins(plugins, query) {
+    if (!query) {
+        return plugins;
+    }
+    const normalizedQuery = query.toLowerCase();
+    return plugins.filter((plugin) => [plugin.name, plugin.relativePath, plugin.rootPath]
+        .some((value) => value.toLowerCase().includes(normalizedQuery)));
+}

package/dist/core/validate-plugin.js

@@ -38,6 +38,26 @@ async function fileExists(targetPath) {
         return false;
     }
 }
+async function readPackageName(rootPath) {
+    const packageJsonPath = path.join(rootPath, "package.json");
+    try {
+        const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+        return typeof packageJson.name === "string" ? packageJson.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function buildMissingManifestFailure(rootPath) {
+    const packageName = await readPackageName(rootPath);
+    if (packageName === "codex-plugin-doctor") {
+        return buildFailure("plugin.manifest.missing", "This looks like the Codex Plugin Doctor source repo, not a Codex plugin package.", "Codex Plugin Doctor validates plugin package roots that contain `.codex-plugin/plugin.json`; the tool source repo intentionally does not expose that manifest.", "For a local self-test, run `codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations`. To check your own plugin, pass that plugin package root instead.");
+    }
+    if (packageName) {
+        return buildFailure("plugin.manifest.missing", "This directory has a `package.json`, but it does not look like a Codex plugin package.", "Codex cannot treat a normal project directory as a plugin package without the required `.codex-plugin/plugin.json` entry point.", "Run from a Codex plugin package root, or pass the path to a directory that contains `.codex-plugin/plugin.json`.");
+    }
+    return buildFailure("plugin.manifest.missing", "This directory does not look like a Codex plugin package.", "Codex cannot treat this directory as a plugin package without the required `.codex-plugin/plugin.json` manifest entry point.", "Create `.codex-plugin/plugin.json` with at least `name`, `version`, and `description`, or pass the path to an existing Codex plugin package.");
+}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -299,13 +319,12 @@ async function validateMcpConfig(discoveredPackage) {
 export async function validatePlugin(targetPath, options = {}) {
     const discoveredPackage = await discoverPackage(targetPath);
     if (!discoveredPackage) {
+        const rootPath = path.resolve(targetPath);
         return {
-            targetPath: path.resolve(targetPath),
+            targetPath: rootPath,
             status: "fail",
             exitCode: 1,
-            findings: [
-                buildFailure("plugin.manifest.missing", "Missing required `.codex-plugin/plugin.json` manifest.", "Codex cannot treat this directory as a plugin package without the required manifest entry point.", "Create `.codex-plugin/plugin.json` with at least `name`, `version`, and `description`.")
-            ]
+            findings: [await buildMissingManifestFailure(rootPath)]
         };
     }
     const runtimeResult = options.runtime

package/dist/run-cli.js

@@ -1,4 +1,5 @@
 import { writeFile } from "node:fs/promises";
+import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { runCheck } from "./index.js";
 import { renderJsonReport } from "./reporting/render-json-report.js";
 import { buildMarkdownReport } from "./reporting/render-markdown-report.js";
@@ -6,6 +7,7 @@ import { renderTextReport } from "./reporting/render-text-report.js";
 import { createLiveStatusRenderer } from "./terminal/live-status-renderer.js";
 import { determineOutputPolicy } from "./terminal/output-policy.js";
 import { getSpinner } from "./terminal/spinner-registry.js";
+import { packageVersion } from "./version.js";
 const defaultIo = {
     writeStdout(message) {
         process.stdout.write(`${message}\n`);
@@ -15,18 +17,60 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path> [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor --version");
+}
+function renderInstalledPlugins(plugins) {
+    const lines = [
+        "Installed Codex Plugins",
+        "======================="
+    ];
+    if (plugins.length === 0) {
+        lines.push("", "No installed Codex plugins found.");
+        return lines.join("\n");
+    }
+    for (const plugin of plugins) {
+        const version = plugin.version ? `@${plugin.version}` : "";
+        lines.push("", `- ${plugin.name}${version}`);
+        lines.push(`  Path: ${plugin.rootPath}`);
+        lines.push(`  Cache: ${plugin.relativePath}`);
+    }
+    return lines.join("\n");
 }
 export async function runCli(args, io = defaultIo, options = {}) {
     const [command, maybePath, ...remainingArgs] = args;
+    if (command === "--version" || command === "-v" || command === "version") {
+        io.writeStdout(packageVersion);
+        return 0;
+    }
+    const terminalContext = options.terminalContext ?? {
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        stderrIsTTY: Boolean(process.stderr.isTTY),
+        env: process.env
+    };
+    if (command === "list" && maybePath === "--installed") {
+        const installedPlugins = await discoverInstalledPlugins({
+            env: terminalContext.env
+        });
+        io.writeStdout(renderInstalledPlugins(installedPlugins));
+        return 0;
+    }
     if (command !== "check") {
         printUsage(io);
         return 2;
     }
-    const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
-    const normalizedFlags = maybePath && maybePath.startsWith("--")
-        ? [maybePath, ...remainingArgs]
+    const checkInstalled = maybePath === "--installed";
+    const installedFilter = checkInstalled && remainingArgs[0] && !remainingArgs[0].startsWith("--")
+        ? remainingArgs[0]
+        : null;
+    const flagsAfterInstalledFilter = checkInstalled && installedFilter
+        ? remainingArgs.slice(1)
         : remainingArgs;
+    const targetPath = maybePath && !maybePath.startsWith("--") ? maybePath : ".";
+    const normalizedFlags = checkInstalled
+        ? [maybePath, ...flagsAfterInstalledFilter]
+        : maybePath && maybePath.startsWith("--")
+            ? [maybePath, ...remainingArgs]
+            : remainingArgs;
     const jsonOutput = normalizedFlags.includes("--json");
     const markdownOutput = normalizedFlags.includes("--markdown");
     const runtimeProbeEnabled = normalizedFlags.includes("--runtime");
@@ -39,11 +83,6 @@ export async function runCli(args, io = defaultIo, options = {}) {
         io.writeStderr("Missing path after --output.");
         return 2;
     }
-    const terminalContext = options.terminalContext ?? {
-        stdoutIsTTY: Boolean(process.stdout.isTTY),
-        stderrIsTTY: Boolean(process.stderr.isTTY),
-        env: process.env
-    };
     const outputPolicy = determineOutputPolicy({
         jsonOutput,
         markdownOutput,
@@ -55,6 +94,36 @@ export async function runCli(args, io = defaultIo, options = {}) {
         env: terminalContext.env
     });
     const runCheckImpl = options.runCheckImpl ?? runCheck;
+    if (checkInstalled) {
+        const installedPlugins = filterInstalledPlugins(await discoverInstalledPlugins({ env: terminalContext.env }), installedFilter);
+        if (installedPlugins.length === 0) {
+            io.writeStderr(installedFilter
+                ? `No installed Codex plugins matched '${installedFilter}'.`
+                : "No installed Codex plugins found.");
+            return 1;
+        }
+        const results = [];
+        for (const plugin of installedPlugins) {
+            results.push(await runCheckImpl(plugin.rootPath, {
+                runtime: runtimeProbeEnabled,
+                runtimeTranscript: runtimeProbeEnabled && verboseRuntime
+                    ? (line) => io.writeStderr(line)
+                    : undefined
+            }));
+        }
+        const report = results
+            .map((result) => markdownOutput
+            ? buildMarkdownReport(result, { runtimeProbeEnabled })
+            : jsonOutput
+                ? renderJsonReport(result, { runtimeProbeEnabled })
+                : renderTextReport(result, { ascii: outputPolicy.style === "ascii" }))
+            .join("\n\n");
+        if (outputPath) {
+            await writeFile(outputPath, report, "utf8");
+        }
+        io.writeStdout(report);
+        return results.some((result) => result.exitCode === 1) ? 1 : 0;
+    }
     const renderer = outputPolicy.interactive
         && !verboseRuntime
         ? createLiveStatusRenderer(io, getSpinner(outputPolicy.style === "ascii" ? "ascii" : "doctor"))

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const packageVersion: string;

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+export const packageVersion = packageJson.version;

package/package.json

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