@curdx/flow 2.0.0-beta.10 → 2.0.0-beta.11

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
-    "version": "2.0.0-beta.10"
+    "version": "2.0.0-beta.11"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.0-beta.10",
+  "version": "2.0.0-beta.11",
   "description": "Claude Code Discipline Layer — spec-driven workflow + goal-backward verification + Karpathy 4 principles enforced via gates. Stops Claude from faking \"done\" on non-trivial features.",
   "author": {
     "name": "wdx",

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to CurDX-Flow will be documented here.
 
 ## [Unreleased]
 
+### Added
+
+- `cli/doctor.js` now detects when a user-level MCP in `~/.claude.json` (typically `context7` added via `claude mcp add …`) duplicates a plugin-bundled MCP from `plugin.json` (`plugin:curdx-flow:context7`). The two run as independent processes and Claude routes tool calls unpredictably between them. Doctor surfaces the overlap, shows the user-level command (with any `--api-key` flag) alongside the plugin command, and prints the exact remediation: `export CONTEXT7_API_KEY=…` + `claude mcp remove context7`. Backed by `cli/utils.js:readUserMcpConfig()` + `findDuplicateMcps()` and 3 new tests in `test/utils.test.js`.
+- `docs/getting-started.md` gained an "Optional: use your paid context7 API key" section documenting the env-var path (upstream `@upstash/context7-mcp` natively reads `process.env.CONTEXT7_API_KEY`) and the cleanup command for users with a pre-existing user-level registration.
+
+## [2.0.0-beta.10] - 2026-04-21
+
+### Fixed
+
+- `cli/utils.js` — `listMcps` rewritten to handle the actual `claude mcp list` format captured from claude 2.1.117. The previous regex matched only a single kebab-case token before the first colon, so `plugin:curdx-flow:context7: npx ...` parsed as name=`plugin` and silently dropped the rest. New parser exports `{ name, plugin, fullName, status, command }` and is fixture-tested in `test/utils.test.js`.
+- `cli/doctor.js` — MCP presence check now accepts both standalone (`context7`) and plugin-bundled (`plugin:curdx-flow:context7`) registrations, with source in the status line. Fixes the same class of false-positive that bit `chrome-devtools` in beta.7. Also gated `--verbose` raw-plugin dump behind `claude` being on PATH, so it no longer runs a meaningless empty child when the CLI is absent.
+- `cli/install.js` — step counter was `1/4`..`4/4` but there are five steps; `Step 5: inject global protocols` was emitted via bare `console.log` so the progress display lied. All five steps now use `log.step(N, 5, ...)`. Also switched `⏳ Installing` and `✅ Install complete` glyphs to the `▸` / `✓` symbols used elsewhere in the project's `log.*` helpers.
+- `cli/uninstall.js` — same `⏳` → `▸` glyph normalisation.
+- `cli/protocols.js` + `cli/utils.js` + `cli/uninstall.js` — switched from `process.env.HOME || ""` to `os.homedir()`. `$HOME` is only guaranteed in interactive login shells; CI containers, some `docker exec` invocations, and non-login spawns can leave it empty, which resolved `GLOBAL_CLAUDE_MD` to `/.claude/CLAUDE.md` and broke `ensureRuntimeInPath` runtime candidate lookup.
+- `bin/curdx-flow.js` — `main()` was called unconditionally at module scope, so `import()` from a test would spawn the CLI, parse the test runner's argv, and `exit(1)`. Now guarded by the ESM direct-invocation idiom (`import.meta.url === pathToFileURL(process.argv[1]).href`). Added one real-import test.
+- `.claude-plugin/plugin.json` — `homepage` and `repository` pointed at `github.com/wdx/curdx-flow` but the authoritative remote is `github.com/curdx/curdx-flow`. Plugin-marketplace UI clicks previously 404'd. Aligned to the real owner.
+- `.github/workflows/npm-publish.yml` — bumped `actions/setup-node` from Node 20 to Node 22 LTS ahead of the 2026-06-02 Node 20 removal.
+- `scripts/release.sh` — lockstep bump of `plugin.json` + `marketplace.json` now parses both files in memory before writing either, with `git checkout -- package.json` auto-revert on failure. Previously the second file could fail to write while the first was already disk-committed.
+
+### Changed
+
+- `commands/start.md` — replaced the brittle `xargs`/`awk`/`sed` flag-parsing block with a model-directed parse that tolerates quoted strings in `$ARGUMENTS` (e.g. `my-feature "Fix user's login bug"` no longer hits `xargs: unmatched quote`).
+- `commands/init.md` — Step 5 used to say "Run `npx @curdx/flow doctor`" but the slash command runs inside Claude Code where a spawned CLI's output doesn't render cleanly. Reframed as "verify inline + suggest the user run the CLI in a separate terminal if they want the full report."
+- `commands/implement.md` — replaced `❌` emoji with `✗` to match the project's own `log.err` helper.
+- `docs/architecture.md` — Hook System section and CLI layout were **entirely fabricated** (listed non-existent hooks `pre-spec.sh` / `post-implement.sh` / `pre-verify.sh` / `post-review.sh` / `on-gate-fail.sh` and bogus paths `cli/bin/flow` / `cli/commands/install.js` / `cli/lib/…`). Rewritten to match the real `hooks/scripts/` layout (4 hooks: session-start / inject-karpathy / quick-mode-guard / stop-watcher) and real `bin/` + `cli/` paths including `cli/registry.js` and the `test/` directory.
+
+### Added
+
+- `test/utils.test.js` grew 5 fixture tests for the new `parseMcpList` against a captured `claude mcp list` output.
+- `test/cli-entrypoints.test.js` — 5 smoke tests that each dynamically-import `cli/doctor.js` / `cli/install.js` / `cli/upgrade.js` / `cli/uninstall.js` and assert the expected top-level function exports. Guards against the "deleted an import but forgot the consumer" class of regression at CI time. Plus one test that imports `bin/curdx-flow.js` now that it no longer runs `main()` at module load.
+
+### Removed (docs compliance)
+
+- Chinese trigger phrases from `skills/*/SKILL.md` descriptions (5 files). Keeping bilingual triggers violated the project's own language-separation rule (`CLAUDE.md`: "Documentation layer = English"). Semantic matching on the English phrases plus the model's own bilingual understanding covers the same invocation surface.
+
+## [2.0.0-beta.9] - 2026-04-21
+
 ### Fixed (P0)
 
 - `cli/utils.js` — `findRuntime()` referenced `existsSync` without importing it; any user whose `bun`/`uv` was not on PATH hit `ReferenceError` during install or doctor.
@@ -18,6 +55,10 @@ All notable changes to CurDX-Flow will be documented here.
 - `commands/start.md` and `commands/spec.md` now produce `.state.json` files that match `schemas/spec-state.schema.json` (field names: `spec_name` / `created` / `updated` / `version`; initial phase is `research`, not the undefined `created`).
 - All python heredocs inside hook scripts use quoted delimiters (`<<'PY'`) and read `STATE_FILE` via `os.environ`, closing a shell→python code-injection surface triggered by unusual spec names.
 
+### Added
+
+- First real test suite — `node --test`-based, 18 regression tests covering `cli/protocols.js`, `cli/registry.js`, and `cli/utils.js`. Wired into `package.json` `scripts.test` and the CI `publish` job so a failing test blocks `npm publish`.
+
 ### Removed
 
 - `hooks/scripts/fail-tracker.sh` and its `PostToolUseFailure` registration — the counter was written but never read by any consumer (the intended pua escalation was never implemented). Can be reintroduced when the consumer exists.

package/cli/doctor.js

@@ -12,6 +12,8 @@ import {
   listPlugins,
   listMcps,
   ensureClaudeMemRuntimes,
+  readUserMcpConfig,
+  findDuplicateMcps,
 } from "./utils.js";
 import { RECOMMENDED_PLUGINS } from "./registry.js";
 
@@ -102,6 +104,49 @@ export async function doctor(args = []) {
     }
   }
 
+  // ---------- Duplicate user-level / plugin-level MCPs ----------
+  // Context: the bundled context7 + sequential-thinking MCPs (registered
+  // via plugin.json) show up as `plugin:curdx-flow:<name>`. If the user
+  // also added `<name>` manually via `claude mcp add …` at some earlier
+  // point (common with context7 + a personal API key), both instances
+  // run side-by-side. That's not a correctness bug — tool namespaces
+  // differ — but it doubles MCP processes and makes API-key routing
+  // unpredictable. Surface the duplicates + concrete remediation.
+  if (cv) {
+    const userCfg = readUserMcpConfig();
+    const duplicates = findDuplicateMcps(mcps, userCfg);
+    if (duplicates.length > 0) {
+      console.log(`\n${color.bold("Duplicate MCP servers (user-level vs plugin-bundled):")}`);
+      for (const d of duplicates) {
+        const userArgs = (d.userConfig.args || []).join(" ");
+        const hasApiKey = userArgs.includes("api-key") || userArgs.includes("ctx7sk");
+        log.warn(
+          `${d.name.padEnd(22)} registered BOTH in ~/.claude.json AND via plugin:${d.pluginEntry.plugin}`
+        );
+        console.log(
+          color.dim(`     user-level : ${d.userConfig.command || "?"} ${userArgs}`)
+        );
+        console.log(
+          color.dim(`     plugin     : ${d.pluginEntry.command || "?"}`)
+        );
+        if (hasApiKey && d.name === "context7") {
+          console.log(
+            color.dim(
+              `     → Fix: export CONTEXT7_API_KEY=<your-key> in your shell rc,\n` +
+                `              then: claude mcp remove ${d.name}\n` +
+                `              (plugin MCP will inherit the env var — no key is lost)`
+            )
+          );
+        } else {
+          console.log(
+            color.dim(`     → Fix: claude mcp remove ${d.name}`)
+          );
+        }
+        warnings++;
+      }
+    }
+  }
+
   // ---------- Runtime PATH guards (only if claude-mem is installed) ----------
   if (claudeMemEnabled) {
     console.log(`\n${color.bold("Runtime (claude-mem dependencies):")}`);

package/cli/utils.js

@@ -215,6 +215,52 @@ export function listPlugins() {
   return plugins;
 }
 
+/**
+ * Read the user-level MCP registrations from ~/.claude.json. These are the
+ * MCPs the user added manually via `claude mcp add …` — distinct from
+ * plugin-bundled MCPs (which live in plugin.json).
+ *
+ * Returns a Map keyed by server name with the raw config object. Returns
+ * an empty Map if the file is missing / unreadable / has no mcpServers
+ * section — all of which are normal states and not errors.
+ */
+export function readUserMcpConfig() {
+  try {
+    const path = join(HOME, ".claude.json");
+    if (!existsSync(path)) return new Map();
+    const cfg = JSON.parse(readFileSync(path, "utf-8"));
+    const servers = cfg?.mcpServers || {};
+    return new Map(Object.entries(servers));
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Given the output of listMcps() and a user-level MCP config map, find
+ * MCPs that are registered BOTH as user-level AND as plugin-bundled.
+ * The plugin-bundled form shows up as `plugin:<plugin>:<name>` in
+ * listMcps output, so a user-level "context7" and a plugin-level
+ * "plugin:curdx-flow:context7" are a duplicate pair.
+ *
+ * Returns array of { name, userConfig, pluginEntry }.
+ */
+export function findDuplicateMcps(mcps, userConfig) {
+  const duplicates = [];
+  for (const m of mcps) {
+    // Only look at plugin-prefixed entries — they're the reference for
+    // what's bundled. Check if user has their own non-prefixed version.
+    if (m.plugin && userConfig.has(m.name)) {
+      duplicates.push({
+        name: m.name,
+        userConfig: userConfig.get(m.name),
+        pluginEntry: m,
+      });
+    }
+  }
+  return duplicates;
+}
+
 /**
  * List MCP servers registered with the `claude` CLI. Returns array of
  *   { name, plugin, fullName, status, command }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.0-beta.10",
+  "version": "2.0.0-beta.11",
   "description": "CLI installer for CurDX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {