codex-plugin-doctor 0.1.1 → 0.1.3

package/README.md

@@ -71,9 +71,11 @@ Global install from npm:
 
 ```bash
 npm install -g codex-plugin-doctor
-codex-plugin-doctor check .
+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.
+
 Run from source:
 
 ```bash
@@ -139,6 +141,8 @@ x plugin.security.hard_coded_secret
 
 ## Useful Commands
 
+Run these from a Codex plugin package root:
+
 ```bash
 codex-plugin-doctor check .
 codex-plugin-doctor check . --json
@@ -150,6 +154,12 @@ codex-plugin-doctor check . --runtime
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+To self-test this repository after cloning it:
+
+```bash
+codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animations
+```
+
 ## Repository Layout
 
 ```text

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/package.json

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