context-doctor 0.13.2 → 0.13.4

package/README.md

@@ -34,6 +34,8 @@ Findings (4)
 npx context-doctor install
 ```
 
+`install` configures every app it detects and does not stop at the first problem: a corrupt Claude Desktop config still gets you Claude Code and Cursor. It does not pretend either. Any target that failed is named with a ✗ line, the summary reads "Done with N problem(s)" instead of "Done.", and the **exit code is 1**, so dotfiles and onboarding scripts can react. A broken config file is never overwritten; fix it and re-run.
+
 That single command is also all it takes to **set up context-doctor on anyone else's machine**. Prefer a global install, or want the unreleased `main`? Both work (Node 20+):
 
 ```bash
@@ -383,6 +385,8 @@ npm publish              # prompts for the npm 2FA code
 git push --follow-tags
 ```
 
+**What the npm download number measures.** `install` writes `npx -y context-doctor-mcp` into MCP configs, and npx re-fetches the tarball whenever a new version exists. So every release is downloaded once by every active install within about a day, and the daily count is almost entirely those refreshes: on this package, release days run ~170 downloads and non-release days ~27. Read it as "size of the active installed base × number of releases", not as new users — a quiet week with no releases will look like a decline while nothing has changed. Two corollaries: the release-day figure is a live count of machines running context-doctor, and a broken release reaches all of them automatically, which is why `prepublishOnly` runs the full test suite. npm's stats also lag by several days and occasionally record a day as zero; a zero on a release day is a gap in their pipeline, not in usage.
+
 Known gotcha: if `npm publish` fails with **`404 Not Found - PUT …/context-doctor`** on a package that clearly exists, the real cause is an **expired npm login token** — npm reports unauthenticated publishes as a 404, not a 401. Check with `npm whoami`; if that errors, run `npm login` and publish again.
 
 Also keep the MCP server version in `src/mcp.ts` in sync with `package.json`, and remember `dist/` is committed — run `npm run build` before committing so the CI dist-sync check passes.

package/dist/cli.js

@@ -359,7 +359,10 @@ function main() {
         return;
     }
     if (args.command === "install") {
-        runInstall();
+        // Partial success is still installed, but not silent: any failed target
+        // makes the exit code non-zero so automation can react.
+        if (runInstall().failures.length > 0)
+            process.exitCode = 1;
         return;
     }
     if (args.command === "uninstall") {

package/dist/doctor.js

@@ -50,6 +50,23 @@ function checkMcpEntry(appName, configPath) {
         return { label: appName, status: "fail", detail: `${configPath} is not valid JSON (${e.message})` };
     }
 }
+/**
+ * For a hook command, the path that must exist for it to run — or null when it
+ * resolves through PATH (`node`, `npx`) and there is nothing to check here.
+ *
+ * Forms written by install: `node "<cli.js>" hook`, `"<binary>" hook`,
+ * `npx -y context-doctor hook`.
+ */
+function hookBinaryMissing(command) {
+    const quoted = [...command.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+    const first = command.trim().split(/\s+/)[0]?.replace(/^"|"$/g, "") ?? "";
+    const candidates = quoted.length > 0 ? quoted : /[\\/]/.test(first) ? [first] : [];
+    for (const path of candidates) {
+        if (!existsSync(path))
+            return path;
+    }
+    return null;
+}
 /** Spawn our own MCP server and run the initialize handshake over stdio. */
 function checkMcpHandshake() {
     const label = "MCP server handshake";
@@ -96,10 +113,20 @@ export async function runDoctor() {
     if (existsSync(settingsPath)) {
         try {
             const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-            const registered = JSON.stringify(settings.hooks?.UserPromptSubmit ?? []).includes("context-doctor");
-            checks.push(registered
-                ? { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json" }
-                : { label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
+            const entries = settings.hooks?.UserPromptSubmit ?? [];
+            const ours = entries.map((e) => e.hooks?.[0]?.command ?? "").find((c) => /context-doctor|cli\.js"?\s+hook/.test(c));
+            if (!ours) {
+                checks.push({ label: "Every-prompt hook", status: "fail", detail: "not registered — run: context-doctor install" });
+            }
+            else {
+                // "Registered" is not "working": a hook whose binary has been deleted
+                // (an npx cache sweep, a Node upgrade) fails silently on every prompt,
+                // and this check used to report it as fine.
+                const missing = hookBinaryMissing(ours);
+                checks.push(missing
+                    ? { label: "Every-prompt hook", status: "fail", detail: `registered, but ${missing} no longer exists — re-run: context-doctor install` }
+                    : { label: "Every-prompt hook", status: "ok", detail: "registered in ~/.claude/settings.json; command resolves" });
+            }
         }
         catch (e) {
             checks.push({ label: "Every-prompt hook", status: "fail", detail: `settings.json unreadable (${e.message})` });

package/dist/install.d.ts

@@ -20,5 +20,20 @@ export declare function npxLauncher(platformName: string): {
     command: string;
     args: string[];
 };
-export declare function runInstall(): void;
+/** Outcome of an install run, so the CLI can set a truthful exit code. */
+export interface InstallResult {
+    /** Detected targets that could not be configured, with the reason. */
+    failures: string[];
+}
+/**
+ * Install into every detected app.
+ *
+ * A failure in one app must not stop the others: someone with a corrupt
+ * Claude Desktop config still wants Claude Code and Cursor wired. But it
+ * must not be reported as success either — automation (dotfiles, CI,
+ * onboarding scripts) reads the exit code, and a "Done." with exit 0 over a
+ * failed target is a lie that surfaces later as "the tools never showed up".
+ * So: keep going, summarize, and return the failures for a non-zero exit.
+ */
+export declare function runInstall(): InstallResult;
 export declare function runUninstall(): void;

package/dist/install.js

@@ -89,6 +89,13 @@ function binOnPath(name) {
     for (const dir of (process.env.PATH ?? "").split(delimiter)) {
         if (!dir)
             continue;
+        // npx prepends its OWN cache's .bin to PATH while it runs the command. So
+        // during `npx -y context-doctor install`, the first "global binary" on
+        // PATH is inside _npx — the garbage-collected directory this lookup exists
+        // to avoid. That hole put a cache path in the hook of every user who
+        // followed the README's headline command.
+        if (isEphemeralPath(dir))
+            continue;
         for (const ext of exts) {
             const candidate = join(dir, name + ext);
             if (existsSync(candidate))
@@ -97,6 +104,10 @@ function binOnPath(name) {
     }
     return null;
 }
+/** Paths npm may delete at any time: the npx cache and the npm cache itself. */
+function isEphemeralPath(path) {
+    return /[\\/]_npx[\\/]/.test(path) || /[\\/]\.npm[\\/]/.test(path) || /[\\/]npm-cache[\\/]/i.test(path);
+}
 /**
  * Shell command used for the Claude Code every-prompt hook.
  *
@@ -113,8 +124,7 @@ function binOnPath(name) {
 function hookCommand() {
     const selfDir = dirname(fileURLToPath(import.meta.url));
     const localCli = join(selfDir, "cli.js");
-    const ephemeral = selfDir.includes("_npx");
-    if (!ephemeral && existsSync(localCli))
+    if (!isEphemeralPath(selfDir + sep) && existsSync(localCli))
         return `node "${localCli}" hook`;
     const global = binOnPath("context-doctor");
     if (global)
@@ -204,6 +214,16 @@ function installSkill() {
     copyFileSync(skillSource, join(skillDest, "SKILL.md"));
     return join(skillDest, "SKILL.md");
 }
+/**
+ * Install into every detected app.
+ *
+ * A failure in one app must not stop the others: someone with a corrupt
+ * Claude Desktop config still wants Claude Code and Cursor wired. But it
+ * must not be reported as success either — automation (dotfiles, CI,
+ * onboarding scripts) reads the exit code, and a "Done." with exit 0 over a
+ * failed target is a lie that surfaces later as "the tools never showed up".
+ * So: keep going, summarize, and return the failures for a non-zero exit.
+ */
 export function runInstall() {
     const entry = serverEntry();
     const found = targets().filter((t) => t.detect());
@@ -211,8 +231,9 @@ export function runInstall() {
         console.log("No supported AI apps detected (Claude Desktop, Claude Code, Cursor).");
         console.log("Manual setup — add to your app's MCP config:");
         console.log(JSON.stringify({ mcpServers: { "context-doctor": entry } }, null, 2));
-        return;
+        return { failures: [] };
     }
+    const failures = [];
     for (const target of found) {
         try {
             const config = readJson(target.configPath);
@@ -224,22 +245,44 @@ export function runInstall() {
         }
         catch (e) {
             console.error(`✗ ${target.name}: ${e.message}`);
+            failures.push(target.name);
         }
     }
-    const skillPath = installSkill();
-    if (skillPath)
-        console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
-    const hookPath = installHook();
-    if (hookPath) {
-        console.log(`✓ Claude Code every-prompt hook installed (${hookPath}) — heavy sessions get automatic hygiene guidance`);
-        // npx resolves the package on every single prompt; a global install makes
-        // the hook a plain exec instead, which is both faster and update-proof.
-        if (hookUsesNpx()) {
-            console.log("  note: the hook falls back to npx. For a faster, permanent hook: npm i -g context-doctor && context-doctor install");
+    try {
+        const skillPath = installSkill();
+        if (skillPath)
+            console.log(`✓ Agent Skill installed for Claude Code (${skillPath})`);
+    }
+    catch (e) {
+        console.error(`✗ Agent Skill: ${e.message}`);
+        failures.push("Agent Skill");
+    }
+    try {
+        const hookPath = installHook();
+        if (hookPath) {
+            console.log(`✓ Claude Code every-prompt hook installed (${hookPath}) — heavy sessions get automatic hygiene guidance`);
+            // npx resolves the package on every single prompt; a global install makes
+            // the hook a plain exec instead, which is both faster and update-proof.
+            if (hookUsesNpx()) {
+                console.log("  note: the hook falls back to npx. For a faster, permanent hook: npm i -g context-doctor && context-doctor install");
+            }
         }
     }
-    console.log("\nDone. Restart the apps to pick up the new tools, then try:");
-    console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+    catch (e) {
+        // An unreadable settings.json used to escape as a stack trace and abort
+        // the run; it is a failed target like any other.
+        console.error(`✗ Claude Code every-prompt hook: ${e.message}`);
+        failures.push("Claude Code hook");
+    }
+    if (failures.length > 0) {
+        console.log(`\nDone with ${failures.length} problem(s): ${failures.join(", ")}. See the ✗ lines above.`);
+        console.log("Everything else was installed. Exit code is 1 so scripts can tell; fix the file(s) and re-run install.");
+    }
+    else {
+        console.log("\nDone. Restart the apps to pick up the new tools, then try:");
+        console.log('  "What\'s eating my context?" — or paste a conversation and ask for a profile.');
+    }
+    return { failures };
 }
 export function runUninstall() {
     for (const target of targets().filter((t) => t.detect())) {

package/dist/mcp.js

@@ -37,7 +37,7 @@ const STRATEGY_IDS = ["dedupe", "trim-tool-results", "trim-tool-calls", "strip-b
  * recommended pattern.
  */
 function createServer() {
-    const server = new McpServer({ name: "context-doctor", version: "0.13.2" }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: "context-doctor", version: "0.13.4" }, { instructions: SERVER_INSTRUCTIONS });
     server.tool("profile_context", "Profile an LLM conversation or prompt: token breakdown by category, largest messages, and actionable findings about wasted context (duplicates, oversized tool results, base64 blobs, cache-unfriendly ordering). Accepts OpenAI/Anthropic conversation JSON or raw text. Call this immediately whenever the user asks about token usage, context size, LLM cost, or latency — and proactively offer it once a conversation grows long or accumulates large pasted content.", {
         conversation: z.string().describe("Conversation JSON (OpenAI or Anthropic format, or bare message array) or raw prompt text"),
         model: z.string().optional().describe("Target model name for context-window math, e.g. claude-sonnet-5 or gpt-4o"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-doctor",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Profile and optimize LLM context windows. See what's eating your tokens and fix it — works with Claude, GPT, Gemini, and any MCP-capable AI app.",
   "keywords": [
     "llm",
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "build": "tsc && node -e \"const fs=require('fs');['dist/cli.js','dist/mcp.js'].forEach(f=>fs.chmodSync(f,0o755))\"",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm test",
     "dev": "tsc --watch",
     "test": "npm run build && node --test dist/test/smoke.test.js dist/test/proxy.test.js dist/test/proxy-abort.test.js dist/test/hook.test.js dist/test/mcp-http.test.js dist/test/doctor.test.js dist/test/watch.test.js dist/test/chatgpt-export.test.js dist/test/config.test.js dist/test/dashboard.test.js dist/test/cursor.test.js dist/test/cache.test.js dist/test/session.test.js dist/test/accuracy.test.js dist/test/cache-stability.test.js dist/test/ledger.test.js"
   },