@curdx/flow 2.0.17 → 2.0.18

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.17"
+    "version": "2.0.18"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.17",
+  "version": "2.0.18",
   "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/cli/doctor.js

@@ -4,6 +4,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
+
 import {
   color,
   log,
@@ -14,220 +15,102 @@ import {
   listMcps,
   ensureClaudeMemRuntimes,
   readUserMcpConfig,
-  findDuplicateMcps,
-  findPluginByRegistryEntry,
-  hasMarketplace,
 } from "./utils.js";
-import { BUNDLED_MCPS, REQUIRED_PLUGINS, RECOMMENDED_PLUGINS } from "./registry.js";
+import { buildDoctorReport } from "./lib/doctor-report.js";
 
 export async function doctor(args = []) {
   const verbose = args.includes("--verbose") || args.includes("-v");
+  const claudeVersionValue = claudeVersion();
+  const plugins = claudeVersionValue ? listPlugins() : [];
+  const marketplaces = claudeVersionValue ? listPluginMarketplaces() : [];
+  const mcps = claudeVersionValue ? listMcps() : [];
+  const userMcpConfig = claudeVersionValue ? readUserMcpConfig() : new Map();
+  const runtimeStatus = plugins.some((plugin) => plugin.name === "claude-mem" && plugin.status === "enabled")
+    ? ensureClaudeMemRuntimes()
+    : null;
 
   log.title("🏥 CurdX-Flow Health Check");
 
-  let errors = 0;
-  let warnings = 0;
-
-  // ---------- claude CLI ----------
-  const cv = claudeVersion();
-  if (cv) {
-    log.ok(`claude CLI            ${color.dim(cv)}`);
-  } else {
-    log.err("claude CLI            not found (install Claude Code)");
-    errors++;
+  const report = buildDoctorReport({
+    claudeVersionValue,
+    nodeVersion: process.version,
+    plugins,
+    marketplaces,
+    mcps,
+    userMcpConfig,
+    runtimeStatus,
+    cwd: process.cwd(),
+    projectState: await readProjectState(),
+  });
+
+  renderLines(report.lines);
+  for (const section of report.sections) {
+    console.log(`\n${color.bold(section.title)}`);
+    renderLines(section.lines);
   }
 
-  // ---------- Node ----------
-  log.ok(`Node                  ${color.dim(process.version)}`);
-
-  // ---------- curdx-flow plugin ----------
-  const plugins = cv ? listPlugins() : [];
-  const curdx = plugins.find((p) => p.name === "curdx-flow");
-  if (curdx) {
-    if (curdx.status === "enabled") {
-      log.ok(`curdx-flow            ${color.dim(`v${curdx.version} (enabled)`)}`);
-    } else {
-      log.err(`curdx-flow            v${curdx.version} (${curdx.status})`);
-      errors++;
-    }
-  } else {
-    log.warn("curdx-flow            not installed → run curdx-flow install");
-    warnings++;
+  printSummary(report);
+  if (verbose && claudeVersionValue) {
+    printVerboseDetails();
   }
+}
 
-  const marketplaces = cv ? listPluginMarketplaces() : [];
-
-  // ---------- Required plugins ----------
-  console.log(`\n${color.bold("Required plugins:")}`);
-  for (const r of REQUIRED_PLUGINS) {
-    const p = findPluginByRegistryEntry(plugins, r);
-    if (!hasMarketplace(marketplaces, r)) {
-      log.warn(
-        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
-      );
-      warnings++;
-    }
-    if (p && p.status === "enabled") {
-      log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version || "unknown"}`)}`);
-    } else if (p && p.status === "failed") {
-      log.err(`${r.name.padEnd(22)} load failed`);
-      errors++;
-    } else {
-      log.warn(
-        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
-      );
-      warnings++;
+async function readProjectState() {
+  const cwd = process.cwd();
+  const flowDir = path.join(cwd, ".flow");
+  try {
+    const stat = await fs.stat(flowDir);
+    if (!stat.isDirectory()) {
+      return { exists: false, activeSpec: null };
     }
-  }
 
-  // ---------- MCPs ----------
-  console.log(`\n${color.bold("MCP Servers (required by L2 mandatory tools):")}`);
-  const mcps = cv ? listMcps() : [];
-  for (const expected of BUNDLED_MCPS) {
-    const m = expected.name;
-    // Beta.12 onward: the required MCPs are registered at user-level
-    // (via `claude mcp add`), NOT plugin-bundled. Both still show up in
-    // `claude mcp list`. Accept a standalone user-level registration
-    // as the primary form, and warn if only a plugin-bundled copy exists
-    // (because that's the legacy layout that beta.11 had).
-    const userLevel = mcps.find((x) => x.name === m && x.plugin === null);
-    const pluginLevel = mcps.find((x) => x.name === m && x.plugin !== null);
-
-    if (userLevel) {
-      log.ok(`${m.padEnd(22)} ${color.dim("user-level (standard)")}`);
-    } else if (pluginLevel) {
-      log.warn(
-        `${m.padEnd(22)} registered via plugin:${pluginLevel.plugin} (legacy). ` +
-          `Run ${color.cyan("npx @curdx/flow install --all")} to migrate to user-level.`
-      );
-      warnings++;
-    } else {
-      if (curdx) {
-        log.warn(
-          `${m.padEnd(22)} missing. Run: ${color.cyan(`claude mcp add --scope user ${m} -- ${expected.command} ${expected.args.join(" ")}`)}`
-        );
-        warnings++;
-      } else {
-        log.info(`${m.padEnd(22)} waiting for curdx-flow install`);
-      }
+    try {
+      const activeSpec = await fs.readFile(path.join(flowDir, ".active-spec"), "utf-8");
+      return { exists: true, activeSpec: activeSpec.trim() };
+    } catch {
+      return { exists: true, activeSpec: null };
     }
+  } catch {
+    return { exists: false, activeSpec: null };
   }
+}
 
-  // ---------- Recommended plugins (single registry; see cli/registry.js) ----------
-  console.log(`\n${color.bold("Recommended plugins:")}`);
-  let claudeMemEnabled = false;
-  for (const r of RECOMMENDED_PLUGINS) {
-    const p = findPluginByRegistryEntry(plugins, r);
-    if (!hasMarketplace(marketplaces, r)) {
-      log.warn(
-        `${r.marketplaceId.padEnd(22)} marketplace missing ${color.dim(`(run: claude plugin marketplace add --scope ${r.scope} ${r.marketplaceSource})`)}`
-      );
-      warnings++;
-    }
-    if (p && p.status === "enabled") {
-      log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
-      if (r.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
-    } else if (p && p.status === "failed") {
-      log.err(`${r.name.padEnd(22)} load failed`);
-      errors++;
+function renderLines(lines) {
+  for (const line of lines) {
+    if (line.level === "ok") {
+      log.ok(line.text);
+    } else if (line.level === "warn") {
+      log.warn(line.text);
+    } else if (line.level === "err") {
+      log.err(line.text);
     } else {
-      log.warn(
-        `${r.name.padEnd(22)} not installed ${color.dim(`(run: claude plugin install --scope ${r.scope} ${r.installSpec})`)}`
-      );
-      warnings++;
+      log.info(line.text);
     }
-  }
-
-  // ---------- Legacy plugin-bundled MCP residue (beta.11 and earlier) ----------
-  // Beta.12 moved context7 + sequential-thinking to user-level registration.
-  // If both a user-level and a plugin-bundled copy are visible, the user
-  // was likely installed from an older beta.7-beta.11 that still had
-  // mcpServers in plugin.json and a `claude mcp update` hasn't refreshed
-  // the plugin cache yet. Point them at the migration command.
-  if (cv) {
-    const userCfg = readUserMcpConfig();
-    const duplicates = findDuplicateMcps(mcps, userCfg);
-    if (duplicates.length > 0) {
-      console.log(`\n${color.bold("Legacy plugin-bundled MCPs still present:")}`);
-      for (const d of duplicates) {
-        log.warn(
-          `${d.name.padEnd(22)} both user-level AND plugin:${d.pluginEntry.plugin} active`
-        );
-        console.log(
-          color.dim(
-            `     → Migration: ${color.cyan(`claude plugin update curdx-flow@curdx-flow-marketplace`)}\n` +
-              `                  then restart Claude Code. Beta.12+ removes plugin-bundled\n` +
-              `                  versions in favor of the user-level entry you already have.`
-          )
-        );
-        warnings++;
-      }
-    }
-  }
 
-  // ---------- Runtime PATH guards (only if claude-mem is installed) ----------
-  if (claudeMemEnabled) {
-    console.log(`\n${color.bold("Runtime (claude-mem dependencies):")}`);
-    const rt = ensureClaudeMemRuntimes();
-    for (const [name, res] of Object.entries(rt)) {
-      if (res.status === "ok") {
-        log.ok(`${name.padEnd(22)} ${color.dim("visible on PATH")}`);
-      } else if (res.status === "linked") {
-        log.ok(
-          `${name.padEnd(22)} ${color.dim(`auto-linked ${res.link} → ${res.path}`)}`
-        );
-      } else if (res.status === "missing") {
-        log.warn(
-          `${name.padEnd(22)} not installed ${color.dim("(claude-mem will auto-install on next Claude Code session)")}`
-        );
-        warnings++;
-      } else if (res.status === "path-unwritable") {
-        const dir = res.path.split("/").slice(0, -1).join("/");
-        log.err(
-          `${name.padEnd(22)} installed but not on PATH ${color.dim(`(add export PATH="${dir}:$PATH" to your shell rc)`)}`
-        );
-        errors++;
-      }
+    for (const detail of line.details || []) {
+      console.log(color.dim(`     → ${detail}`));
     }
   }
+}
 
-  // ---------- Project state ----------
-  console.log(`\n${color.bold("Local project:")}`);
-  const cwd = process.cwd();
-  const flowDir = path.join(cwd, ".flow");
-  try {
-    const stat = await fs.stat(flowDir);
-    if (stat.isDirectory()) {
-      log.ok(`.flow/                ${color.dim(cwd)}`);
-      // Check active spec
-      try {
-        const active = await fs.readFile(path.join(flowDir, ".active-spec"), "utf-8");
-        log.info(`Active spec           ${color.cyan(active.trim())}`);
-      } catch {
-        log.info("Active spec           (none)");
-      }
-    }
-  } catch {
-    log.info(`.flow/                not a curdx-flow project (run: curdx-flow init)`);
-  }
-
-  // ---------- Summary ----------
+function printSummary(report) {
   console.log();
-  if (errors > 0) {
-    console.log(color.red(`Summary: ${errors} error(s), ${warnings} warning(s)`));
+  if (report.errors > 0) {
+    console.log(color.red(`Summary: ${report.errors} error(s), ${report.warnings} warning(s)`));
     console.log(color.dim("Fix errors and re-run curdx-flow doctor"));
     process.exit(1);
-  } else if (warnings > 0) {
-    console.log(color.yellow(`Summary: ${warnings} warning(s). Usable, but worth addressing.`));
-  } else {
-    console.log(color.green("Summary: all healthy ✓"));
   }
 
-  if (verbose && cv) {
-    // Only call claude when it is actually on PATH; otherwise we spawn a
-    // child that fails silently and print a blank block.
-    console.log(`\n${color.bold("Details:")}`);
-    console.log(color.dim(`  Plugins raw:`));
-    console.log(runSync("claude", ["plugin", "list"]).stdout);
+  if (report.warnings > 0) {
+    console.log(color.yellow(`Summary: ${report.warnings} warning(s). Usable, but worth addressing.`));
+    return;
   }
+
+  console.log(color.green("Summary: all healthy ✓"));
+}
+
+function printVerboseDetails() {
+  console.log(`\n${color.bold("Details:")}`);
+  console.log(color.dim("  Plugins raw:"));
+  console.log(runSync("claude", ["plugin", "list"]).stdout);
 }

package/cli/install-companions.js

@@ -1,34 +1,38 @@
-import { color, ensureClaudeMemRuntimes, listPlugins, log, multiselectClack, note, resultLastLine, run, text, writeConfig } from "./utils.js";
+import {
+  color,
+  ensureClaudeMemRuntimes,
+  listPlugins,
+  log,
+  multiselectClack,
+  note,
+  resultLastLine,
+  text,
+  writeConfig,
+} from "./utils.js";
 import { BUNDLED_MCPS, RECOMMENDED_PLUGINS, REQUIRED_PLUGINS } from "./registry.js";
 import { readUserMcpConfig } from "./utils.js";
 import {
-  mcpAddArgs,
-  mcpRemoveArgs,
-  pluginInstallArgs,
-  pluginMarketplaceAddArgs,
-} from "./lib/claude-commands.js";
+  addMcp,
+  addPluginMarketplace,
+  installPlugin,
+  removeMcp,
+} from "./lib/claude-ops.js";
 
 const RECOMMENDED = RECOMMENDED_PLUGINS;
+const CONTEXT7_COMMAND = "npx";
+const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
 
 export async function installRequiredPlugins({ yes, language, config }) {
   log.blank();
   log.info("Installing required Claude Code plugins...");
   for (const plugin of REQUIRED_PLUGINS) {
     console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
-    const ma = await run(
-      "claude",
-      pluginMarketplaceAddArgs(plugin),
-      { silent: true }
-    );
+    const ma = await addPluginMarketplace(plugin);
     if (ma.code !== 0 && !ma.stderr.includes("already")) {
       log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
     }
 
-    const ir = await run(
-      "claude",
-      pluginInstallArgs(plugin),
-      { silent: true }
-    );
+    const ir = await installPlugin(plugin);
     if (ir.code === 0) {
       console.log(`  ${color.green("✓")} ${plugin.name} installed`);
 
@@ -65,11 +69,7 @@ export async function registerBundledMcps() {
       );
       continue;
     }
-    const r = await run(
-      "claude",
-      mcpAddArgs(mcp),
-      { silent: true }
-    );
+    const r = await addMcp(mcp);
     if (r.code === 0) {
       log.ok(`  ${mcp.name.padEnd(22)} ${color.dim("registered")}`);
     } else if (r.stderr.includes("already exists")) {
@@ -129,19 +129,13 @@ export async function installRecommendedPlugins({ all, yes, language }) {
     console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
 
     if (rec.marketplaceSource) {
-      const ma = await run(
-        "claude",
-        pluginMarketplaceAddArgs(rec),
-        { silent: true }
-      );
+      const ma = await addPluginMarketplace(rec);
       if (ma.code !== 0 && !ma.stderr.includes("already")) {
         log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
       }
     }
 
-    const ir = await run("claude", pluginInstallArgs(rec), {
-      silent: true,
-    });
+    const ir = await installPlugin(rec);
     if (ir.code === 0) {
       console.log(`  ${color.green("✓")} ${rec.name} installed`);
 
@@ -207,16 +201,7 @@ async function promptPluginConfig(plugin, language, config) {
     config.context7ApiKey = apiKey;
     writeConfig(config);
 
-    const r = await run(
-      "claude",
-      mcpAddArgs({
-        name: "context7",
-        env: [`CONTEXT7_API_KEY=${apiKey}`],
-        command: "npx",
-        args: ["-y", "@upstash/context7-mcp"],
-      }),
-      { silent: true }
-    );
+    const r = await addMcp(buildContext7Mcp(apiKey));
 
     if (r.code === 0) {
       log.ok(
@@ -225,17 +210,8 @@ async function promptPluginConfig(plugin, language, config) {
           : "  Context7 API key configured"
       );
     } else if (r.stderr.includes("already exists")) {
-      await run("claude", mcpRemoveArgs({ name: "context7" }), { silent: true });
-      const r2 = await run(
-        "claude",
-        mcpAddArgs({
-          name: "context7",
-          env: [`CONTEXT7_API_KEY=${apiKey}`],
-          command: "npx",
-          args: ["-y", "@upstash/context7-mcp"],
-        }),
-        { silent: true }
-      );
+      await removeMcp({ name: "context7" });
+      const r2 = await addMcp(buildContext7Mcp(apiKey));
       if (r2.code === 0) {
         log.ok(
           language === "zh"
@@ -252,8 +228,8 @@ async function promptPluginConfig(plugin, language, config) {
       log.info(
         color.dim(
           language === "zh"
-            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
-            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- npx -y @upstash/context7-mcp`
+            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
+            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
         )
       );
     }
@@ -265,3 +241,12 @@ async function promptPluginConfig(plugin, language, config) {
     );
   }
 }
+
+function buildContext7Mcp(apiKey) {
+  return {
+    name: "context7",
+    env: [`CONTEXT7_API_KEY=${apiKey}`],
+    command: CONTEXT7_COMMAND,
+    args: CONTEXT7_ARGS,
+  };
+}

package/cli/install-curdx-plugin.js

@@ -1,9 +1,9 @@
-import { color, log, resultOutput, run } from "./utils.js";
+import { color, log, resultOutput } from "./utils.js";
 import {
-  pluginInstallArgs,
-  pluginMarketplaceAddArgs,
-  pluginMarketplaceRemoveArgs,
-} from "./lib/claude-commands.js";
+  addPluginMarketplace,
+  installPlugin,
+  removePluginMarketplace,
+} from "./lib/claude-ops.js";
 
 export async function addCurdxMarketplace({ marketplaceSource, marketplaceLabel, useOffline }) {
   log.blank();
@@ -12,17 +12,9 @@ export async function addCurdxMarketplace({ marketplaceSource, marketplaceLabel,
   // Remove any existing marketplace with the same name so we get a clean
   // rebind to the chosen source. Errors are non-fatal (marketplace may
   // simply not exist yet).
-  await run(
-    "claude",
-    pluginMarketplaceRemoveArgs("curdx-flow-marketplace"),
-    { silent: true }
-  );
+  await removePluginMarketplace("curdx-flow-marketplace");
 
-  const addRes = await run(
-    "claude",
-    pluginMarketplaceAddArgs({ scope: "user", marketplaceSource }),
-    { silent: true }
-  );
+  const addRes = await addPluginMarketplace({ scope: "user", marketplaceSource });
   if (addRes.code !== 0 && !addRes.stderr.includes("already")) {
     log.warn(`marketplace add output: ${resultOutput(addRes)}`);
   } else {
@@ -50,14 +42,10 @@ export async function installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion })
     log.info(
       `curdx-flow already at v${already.version}, re-registering...`
     );
-    const r = await run(
-      "claude",
-      pluginInstallArgs({
-        scope: "user",
-        installSpec: "curdx-flow@curdx-flow-marketplace",
-      }),
-      { silent: true }
-    );
+    const r = await installPlugin({
+      scope: "user",
+      installSpec: "curdx-flow@curdx-flow-marketplace",
+    });
     if (r.code !== 0) {
       log.err(`Install failed: ${resultOutput(r)}`);
       process.exit(1);
@@ -67,14 +55,10 @@ export async function installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion })
     log.info(
       `curdx-flow v${already.version} → v${shippedVersion}, installing...`
     );
-    const r = await run(
-      "claude",
-      pluginInstallArgs({
-        scope: "user",
-        installSpec: "curdx-flow@curdx-flow-marketplace",
-      }),
-      { silent: true }
-    );
+    const r = await installPlugin({
+      scope: "user",
+      installSpec: "curdx-flow@curdx-flow-marketplace",
+    });
     if (r.code !== 0) {
       log.err(`Install failed: ${resultOutput(r)}`);
       process.exit(1);
@@ -84,28 +68,20 @@ export async function installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion })
     log.info(
       `curdx-flow v${already.version} detected, re-registering...`
     );
-    const r = await run(
-      "claude",
-      pluginInstallArgs({
-        scope: "user",
-        installSpec: "curdx-flow@curdx-flow-marketplace",
-      }),
-      { silent: true }
-    );
+    const r = await installPlugin({
+      scope: "user",
+      installSpec: "curdx-flow@curdx-flow-marketplace",
+    });
     if (r.code !== 0) {
       log.err(`Install failed: ${resultOutput(r)}`);
       process.exit(1);
     }
     log.ok("curdx-flow re-registered");
   } else {
-    const r = await run(
-      "claude",
-      pluginInstallArgs({
-        scope: "user",
-        installSpec: "curdx-flow@curdx-flow-marketplace",
-      }),
-      { silent: true }
-    );
+    const r = await installPlugin({
+      scope: "user",
+      installSpec: "curdx-flow@curdx-flow-marketplace",
+    });
     if (r.code !== 0) {
       log.err(`Install failed: ${resultOutput(r)}`);
       process.exit(1);

package/cli/lib/claude-ops.js

@@ -0,0 +1,47 @@
+import { run } from "./process.js";
+import {
+  mcpAddArgs,
+  mcpRemoveArgs,
+  pluginInstallArgs,
+  pluginMarketplaceAddArgs,
+  pluginMarketplaceRemoveArgs,
+  pluginMarketplaceUpdateArgs,
+  pluginUninstallArgs,
+  pluginUpdateArgs,
+} from "./claude-commands.js";
+
+async function runClaude(args, { runner = run, silent = true } = {}) {
+  return runner("claude", args, { silent });
+}
+
+export async function addPluginMarketplace(entry, options) {
+  return runClaude(pluginMarketplaceAddArgs(entry), options);
+}
+
+export async function updatePluginMarketplace(marketplaceId, options) {
+  return runClaude(pluginMarketplaceUpdateArgs(marketplaceId), options);
+}
+
+export async function removePluginMarketplace(marketplaceId, options) {
+  return runClaude(pluginMarketplaceRemoveArgs(marketplaceId), options);
+}
+
+export async function installPlugin(entry, options) {
+  return runClaude(pluginInstallArgs(entry), options);
+}
+
+export async function updatePlugin(spec, options) {
+  return runClaude(pluginUpdateArgs({ spec }), options);
+}
+
+export async function uninstallPlugin(entry, options) {
+  return runClaude(pluginUninstallArgs(entry), options);
+}
+
+export async function addMcp(entry, options) {
+  return runClaude(mcpAddArgs(entry), options);
+}
+
+export async function removeMcp(entry, options) {
+  return runClaude(mcpRemoveArgs(entry), options);
+}