@curdx/flow 2.0.8 → 2.0.9

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "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/bin/curdx-flow.js

@@ -23,113 +23,7 @@
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 
-import { install } from "../cli/install.js";
-import { doctor } from "../cli/doctor.js";
-import { upgrade } from "../cli/upgrade.js";
-import { uninstall } from "../cli/uninstall.js";
-import { VERSION, color } from "../cli/utils.js";
-
-const args = process.argv.slice(2);
-const cmd = args[0];
-const rest = args.slice(1);
-
-function printHelp() {
-  console.log(`
-${color.bold("curdx-flow")} ${color.dim(`v${VERSION}`)}
-CurdX-Flow installer & helper for Claude Code
-
-${color.bold("USAGE")}
-  npx @curdx/flow <command> [options]
-
-${color.bold("COMMANDS")}
-  ${color.cyan("install")}   Install curdx-flow plugin + optional recommended plugins
-            --all            Install all recommended (skip prompt)
-            --no-deps        Only install curdx-flow, skip recommendations
-            --online         Fetch plugin from GitHub instead of using the
-                             local npm package (slower; default is offline
-                             when the plugin body is bundled)
-
-  ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
-
-  ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest
-
-  ${color.cyan("uninstall")} Remove curdx-flow plugin (and optionally recommended / artifacts)
-            -y, --yes           Skip confirmation, keep recommended + .flow/
-            --keep-recommended  Don't ask about pua/claude-mem/frontend-design
-            --purge             Also remove ~/.local/bin/bun, ~/.local/bin/uv symlinks
-
-${color.bold("OPTIONS")}
-  -v, --version       Print version
-  -h, --help          Show this CLI usage summary
-
-${color.dim("For the full command / workflow reference (including all slash")}
-${color.dim("commands like /curdx-flow:start, /curdx-flow:spec, …) run:")}
-  ${color.cyan("/curdx-flow:help")}  ${color.dim("(inside Claude Code)")}
-
-${color.bold("EXAMPLES")}
-  ${color.dim("# First-time install with recommended plugins")}
-  npx @curdx/flow install --all
-
-  ${color.dim("# Check what's installed")}
-  npx @curdx/flow doctor
-
-  ${color.dim("# Update everything")}
-  npx @curdx/flow upgrade
-
-${color.bold("INITIALIZING A PROJECT")}
-  Once curdx-flow is installed, initialize your project inside Claude Code:
-
-    ${color.cyan("claude")}
-    ${color.cyan("/curdx-flow:init")}
-    ${color.cyan("/curdx-flow:start my-feature \"<description>\"")}
-
-${color.bold("LEARN MORE")}
-  https://github.com/curdx/curdx-flow
-`);
-}
-
-async function main() {
-  // Version flags
-  if (cmd === "--version" || cmd === "-v") {
-    console.log(VERSION);
-    return;
-  }
-
-  // Help flags (standard CLI convention: -h / --help / no args)
-  if (!cmd || cmd === "--help" || cmd === "-h") {
-    printHelp();
-    return;
-  }
-
-  // Route
-  try {
-    switch (cmd) {
-      case "install":
-        await install(rest);
-        break;
-      case "doctor":
-        await doctor(rest);
-        break;
-      case "upgrade":
-        await upgrade(rest);
-        break;
-      case "uninstall":
-      case "remove":
-        await uninstall(rest);
-        break;
-      default:
-        console.error(color.red(`Unknown command: ${cmd}`));
-        console.error(`Run ${color.cyan("npx @curdx/flow --help")} for CLI usage.`);
-        process.exit(1);
-    }
-  } catch (err) {
-    console.error(color.red(`\n✗ ${err.message || err}`));
-    if (process.env.CURDX_DEBUG) {
-      console.error(err.stack || "");
-    }
-    process.exit(1);
-  }
-}
+import { runCli } from "../cli/router.js";
 
 // Only execute main() when invoked directly (`node bin/curdx-flow.js ...`
 // or via the npm bin shim at node_modules/.bin/<name>). When the file is
@@ -156,5 +50,5 @@ function isInvokedDirectly() {
 }
 
 if (isInvokedDirectly()) {
-  main();
+  runCli();
 }

package/cli/help.js

@@ -0,0 +1,56 @@
+import { VERSION, color } from "./utils.js";
+
+export function printHelp() {
+  console.log(`
+${color.bold("curdx-flow")} ${color.dim(`v${VERSION}`)}
+CurdX-Flow installer & helper for Claude Code
+
+${color.bold("USAGE")}
+  npx @curdx/flow <command> [options]
+
+${color.bold("COMMANDS")}
+  ${color.cyan("install")}   Install curdx-flow plugin + optional recommended plugins
+            --all            Install all recommended (skip prompt)
+            --no-deps        Only install curdx-flow, skip recommendations
+            --online         Fetch plugin from GitHub instead of using the
+                             local npm package (slower; default is offline
+                             when the plugin body is bundled)
+
+  ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
+
+  ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest
+
+  ${color.cyan("uninstall")} Remove curdx-flow plugin (and optionally recommended / artifacts)
+            -y, --yes           Skip confirmation, keep recommended + .flow/
+            --keep-recommended  Don't ask about pua/claude-mem/frontend-design
+            --purge             Also remove ~/.local/bin/bun, ~/.local/bin/uv symlinks
+
+${color.bold("OPTIONS")}
+  -v, --version       Print version
+  -h, --help          Show this CLI usage summary
+
+${color.dim("For the full command / workflow reference (including all slash")}
+${color.dim("commands like /curdx-flow:start, /curdx-flow:spec, …) run:")}
+  ${color.cyan("/curdx-flow:help")}  ${color.dim("(inside Claude Code)")}
+
+${color.bold("EXAMPLES")}
+  ${color.dim("# First-time install with recommended plugins")}
+  npx @curdx/flow install --all
+
+  ${color.dim("# Check what's installed")}
+  npx @curdx/flow doctor
+
+  ${color.dim("# Update everything")}
+  npx @curdx/flow upgrade
+
+${color.bold("INITIALIZING A PROJECT")}
+  Once curdx-flow is installed, initialize your project inside Claude Code:
+
+    ${color.cyan("claude")}
+    ${color.cyan("/curdx-flow:init")}
+    ${color.cyan("/curdx-flow:start my-feature \"<description>\"")}
+
+${color.bold("LEARN MORE")}
+  https://github.com/curdx/curdx-flow
+`);
+}

package/cli/lib/claude.js

@@ -0,0 +1,141 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { has, runSync } from "./process.js";
+
+const HOME = homedir();
+
+export function claudeVersion() {
+  if (!has("claude")) return null;
+  const res = runSync("claude", ["--version"]);
+  if (res.code !== 0) return null;
+  const m = res.stdout.match(/(\d+\.\d+\.\d+)/);
+  return m ? m[1] : res.stdout.trim().split("\n")[0];
+}
+
+export function listPlugins() {
+  const j = runSync("claude", ["plugin", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      const arr = JSON.parse(j.stdout);
+      return arr.map((p) => ({
+        id: String(p.id || ""),
+        name: String(p.id || "").split("@")[0],
+        marketplaceId: String(p.id || "").split("@")[1] || undefined,
+        version: p.version,
+        status: p.enabled === false ? "disabled" : "enabled",
+        scope: p.scope,
+        raw: JSON.stringify(p),
+      }));
+    } catch {
+      // JSON parse failed; fall through to legacy text parser.
+    }
+  }
+
+  const res = runSync("claude", ["plugin", "list"]);
+  if (res.code !== 0) return [];
+  const plugins = [];
+  const blocks = res.stdout.split(/\n\s*❯\s*/).slice(1);
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const id = lines[0].trim();
+    const name = id.split("@")[0];
+    const version = (block.match(/Version:\s*(\S+)/) || [])[1];
+    const status = block.includes("✔")
+      ? "enabled"
+      : block.includes("✘")
+        ? "failed"
+        : "unknown";
+    plugins.push({
+      id,
+      name,
+      marketplaceId: id.split("@")[1],
+      version,
+      status,
+      raw: block,
+    });
+  }
+  return plugins;
+}
+
+export function listPluginMarketplaces() {
+  const j = runSync("claude", ["plugin", "marketplace", "list", "--json"]);
+  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+    try {
+      return JSON.parse(j.stdout);
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+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();
+  }
+}
+
+export function findDuplicateMcps(mcps, userConfig) {
+  const duplicates = [];
+  for (const m of mcps) {
+    if (m.plugin && userConfig.has(m.name)) {
+      duplicates.push({
+        name: m.name,
+        userConfig: userConfig.get(m.name),
+        pluginEntry: m,
+      });
+    }
+  }
+  return duplicates;
+}
+
+export function listMcps() {
+  const res = runSync("claude", ["mcp", "list"]);
+  if (res.code !== 0) return [];
+  return parseMcpList(res.stdout);
+}
+
+export function parseMcpList(output) {
+  const mcps = [];
+  for (const raw of output.split("\n")) {
+    const line = raw.trimEnd();
+    if (!line) continue;
+    if (line.startsWith("Checking") || line.startsWith("checking")) continue;
+
+    const statusSplit = line.lastIndexOf(" - ");
+    if (statusSplit === -1) continue;
+    const statusRaw = line.slice(statusSplit + 3).trim();
+    const beforeStatus = line.slice(0, statusSplit);
+    const nameSplit = beforeStatus.indexOf(": ");
+    if (nameSplit === -1) continue;
+    const fullName = beforeStatus.slice(0, nameSplit).trim();
+    const command = beforeStatus.slice(nameSplit + 2).trim();
+
+    let plugin = null;
+    let name = fullName;
+    if (fullName.startsWith("plugin:")) {
+      const parts = fullName.split(":");
+      if (parts.length >= 3) {
+        plugin = parts[1];
+        name = parts.slice(2).join(":");
+      }
+    }
+
+    const status = /Connected|✓/.test(statusRaw)
+      ? "connected"
+      : /Failed|✗/.test(statusRaw)
+        ? "failed"
+        : "unknown";
+
+    mcps.push({ name, plugin, fullName, status, command });
+  }
+  return mcps;
+}

package/cli/lib/config.js

@@ -0,0 +1,24 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const CONFIG_DIR = join(homedir(), ".claude");
+const CONFIG_FILE = join(CONFIG_DIR, "curdx-flow-config.json");
+
+export function readConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+}

package/cli/lib/logging.js

@@ -0,0 +1,25 @@
+const isTTY = process.stdout.isTTY && process.env.TERM !== "dumb";
+const c = (code) => (s) => isTTY ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+
+export const color = {
+  red: c("31"),
+  green: c("32"),
+  yellow: c("33"),
+  blue: c("34"),
+  magenta: c("35"),
+  cyan: c("36"),
+  dim: c("2"),
+  bold: c("1"),
+  underline: c("4"),
+};
+
+export const log = {
+  info: (msg) => console.log(`${color.cyan("ℹ")}  ${msg}`),
+  ok: (msg) => console.log(`${color.green("✓")}  ${msg}`),
+  warn: (msg) => console.log(`${color.yellow("⚠")}  ${msg}`),
+  err: (msg) => console.error(`${color.red("✗")}  ${msg}`),
+  step: (n, total, msg) =>
+    console.log(`${color.dim(`[${n}/${total}]`)} ${msg}`),
+  blank: () => console.log(""),
+  title: (msg) => console.log(`\n${color.bold(msg)}\n`),
+};

package/cli/lib/process.js

@@ -0,0 +1,44 @@
+import { spawn, spawnSync } from "node:child_process";
+
+/**
+ * Run a command, stream output live. Returns { code, stdout, stderr }.
+ */
+export function run(cmd, args = [], opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: opts.silent ? ["ignore", "pipe", "pipe"] : "inherit",
+      env: { ...process.env, ...opts.env },
+      cwd: opts.cwd || process.cwd(),
+      shell: false,
+    });
+
+    let stdout = "";
+    let stderr = "";
+    if (opts.silent) {
+      child.stdout.on("data", (d) => (stdout += d.toString()));
+      child.stderr.on("data", (d) => (stderr += d.toString()));
+    }
+
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+    child.on("error", (err) =>
+      resolve({ code: -1, stdout: "", stderr: err.message })
+    );
+  });
+}
+
+/**
+ * Sync run — for quick checks (e.g. "which claude").
+ */
+export function runSync(cmd, args = []) {
+  const res = spawnSync(cmd, args, { encoding: "utf-8", shell: false });
+  return {
+    code: res.status ?? -1,
+    stdout: res.stdout ?? "",
+    stderr: res.stderr ?? "",
+  };
+}
+
+export function has(cmd) {
+  const res = runSync("which", [cmd]);
+  return res.code === 0 && res.stdout.trim().length > 0;
+}

package/cli/lib/prompts.js

@@ -0,0 +1,135 @@
+import { createInterface } from "node:readline";
+
+import { color } from "./logging.js";
+
+let _clack = null;
+
+async function getClack() {
+  if (!_clack) {
+    _clack = await import("@clack/prompts");
+  }
+  return _clack;
+}
+
+async function handleCancel(value, message = "Operation cancelled") {
+  const clack = await getClack();
+  if (clack.isCancel(value)) {
+    clack.cancel(message);
+    process.exit(0);
+  }
+  return false;
+}
+
+export async function select(options) {
+  const clack = await getClack();
+  const result = await clack.select({
+    message: options.message,
+    options: options.options,
+    initialValue: options.initialValue,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+export async function multiselectClack(options) {
+  const clack = await getClack();
+  const result = await clack.multiselect({
+    message: options.message,
+    options: options.options,
+    initialValues: options.initialValues || [],
+    required: options.required !== undefined ? options.required : false,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+export async function text(options) {
+  const clack = await getClack();
+  const result = await clack.text({
+    message: options.message,
+    placeholder: options.placeholder,
+    defaultValue: options.defaultValue,
+    validate: options.validate,
+  });
+  await handleCancel(result);
+  return result;
+}
+
+export async function spinner() {
+  const clack = await getClack();
+  return clack.spinner();
+}
+
+export async function intro(message) {
+  const clack = await getClack();
+  clack.intro(message);
+}
+
+export async function outro(message) {
+  const clack = await getClack();
+  clack.outro(message);
+}
+
+export async function note(message, title) {
+  const clack = await getClack();
+  clack.note(message, title);
+}
+
+export function confirm(message, defaultYes = true) {
+  return new Promise((resolve) => {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    const hint = defaultYes ? "[Y/n]" : "[y/N]";
+    rl.question(`${color.cyan("?")}  ${message} ${color.dim(hint)} `, (ans) => {
+      rl.close();
+      const v = ans.trim().toLowerCase();
+      if (v === "") return resolve(defaultYes);
+      resolve(v === "y" || v === "yes");
+    });
+  });
+}
+
+export function multiSelect(message, choices, defaults = null) {
+  return new Promise((resolve) => {
+    const defaultSet = new Set(defaults ?? choices.map((_, i) => i));
+    console.log(`${color.cyan("?")}  ${message}`);
+    choices.forEach((ch, i) => {
+      const checked = defaultSet.has(i)
+        ? color.green("[x]")
+        : color.dim("[ ]");
+      console.log(
+        `   ${checked} ${color.bold(String(i + 1))}. ${ch.label}${ch.hint ? color.dim(` — ${ch.hint}`) : ""}`
+      );
+    });
+    console.log(
+      color.dim(
+        "   (comma-separated selection, e.g. 1,3  |  a=all  |  n=none  |  Enter=default)"
+      )
+    );
+
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(`   > `, (ans) => {
+      rl.close();
+      const v = ans.trim().toLowerCase();
+      let selected;
+      if (v === "") {
+        selected = [...defaultSet];
+      } else if (v === "a" || v === "all") {
+        selected = choices.map((_, i) => i);
+      } else if (v === "n" || v === "none") {
+        selected = [];
+      } else {
+        selected = v
+          .split(/[,\s]+/)
+          .map((x) => parseInt(x, 10) - 1)
+          .filter((i) => Number.isInteger(i) && i >= 0 && i < choices.length);
+      }
+      resolve(selected.map((i) => choices[i].value));
+    });
+  });
+}

package/cli/lib/runtime.js

@@ -0,0 +1,89 @@
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  symlinkSync,
+  unlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { has } from "./process.js";
+
+const HOME = homedir();
+
+const BUN_CANDIDATES = [
+  join(HOME, ".bun", "bin", "bun"),
+  "/opt/homebrew/bin/bun",
+  "/usr/local/bin/bun",
+  "/home/linuxbrew/.linuxbrew/bin/bun",
+];
+
+const UV_CANDIDATES = [
+  join(HOME, ".local", "bin", "uv"),
+  join(HOME, ".cargo", "bin", "uv"),
+  "/opt/homebrew/bin/uv",
+  "/usr/local/bin/uv",
+];
+
+const SYMLINK_TARGET_DIRS = [
+  join(HOME, ".local", "bin"),
+  join(HOME, ".npm-global", "bin"),
+];
+
+function findRuntime(candidates) {
+  for (const p of candidates) if (existsSync(p)) return p;
+  return null;
+}
+
+function findSymlinkDir() {
+  const pathDirs = (process.env.PATH || "").split(":").filter(Boolean);
+  for (const d of SYMLINK_TARGET_DIRS) {
+    if (pathDirs.includes(d)) {
+      try {
+        if (!existsSync(d)) mkdirSync(d, { recursive: true });
+        return d;
+      } catch {
+        // continue
+      }
+    }
+  }
+  return null;
+}
+
+export function ensureRuntimeInPath(cmd, candidates) {
+  if (has(cmd)) return { status: "ok" };
+
+  const realPath = findRuntime(candidates);
+  if (!realPath) return { status: "missing" };
+
+  const linkDir = findSymlinkDir();
+  if (!linkDir) return { status: "path-unwritable", path: realPath };
+
+  const linkPath = join(linkDir, cmd);
+  if (existsSync(linkPath)) {
+    try {
+      const stat = lstatSync(linkPath);
+      if (stat.isSymbolicLink() && readlinkSync(linkPath) === realPath) {
+        return { status: "ok", path: realPath, link: linkPath };
+      }
+      unlinkSync(linkPath);
+    } catch {
+      // ignore
+    }
+  }
+  try {
+    symlinkSync(realPath, linkPath);
+    return { status: "linked", path: realPath, link: linkPath };
+  } catch {
+    return { status: "path-unwritable", path: realPath };
+  }
+}
+
+export function ensureClaudeMemRuntimes() {
+  return {
+    bun: ensureRuntimeInPath("bun", BUN_CANDIDATES),
+    uv: ensureRuntimeInPath("uv", UV_CANDIDATES),
+  };
+}

package/cli/lib/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Read version dynamically from package.json so `curdx-flow --version` always
+// reflects the installed package version.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgJson = JSON.parse(
+  readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8")
+);
+
+export const VERSION = pkgJson.version;

package/cli/router.js

@@ -0,0 +1,49 @@
+import { doctor } from "./doctor.js";
+import { install } from "./install.js";
+import { uninstall } from "./uninstall.js";
+import { upgrade } from "./upgrade.js";
+import { printHelp } from "./help.js";
+import { VERSION, color } from "./utils.js";
+
+export async function runCli(args = process.argv.slice(2)) {
+  const cmd = args[0];
+  const rest = args.slice(1);
+
+  if (cmd === "--version" || cmd === "-v") {
+    console.log(VERSION);
+    return;
+  }
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    printHelp();
+    return;
+  }
+
+  try {
+    switch (cmd) {
+      case "install":
+        await install(rest);
+        break;
+      case "doctor":
+        await doctor(rest);
+        break;
+      case "upgrade":
+        await upgrade(rest);
+        break;
+      case "uninstall":
+      case "remove":
+        await uninstall(rest);
+        break;
+      default:
+        console.error(color.red(`Unknown command: ${cmd}`));
+        console.error(`Run ${color.cyan("npx @curdx/flow --help")} for CLI usage.`);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(color.red(`\n✗ ${err.message || err}`));
+    if (process.env.CURDX_DEBUG) {
+      console.error(err.stack || "");
+    }
+    process.exit(1);
+  }
+}

package/cli/utils.js

@@ -1,606 +1,32 @@
 /**
  * Shared utilities for curdx-flow CLI.
- */
-
-import { spawn, spawnSync } from "node:child_process";
-import { createInterface } from "node:readline";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-import { homedir } from "node:os";
-
-// Read version dynamically from package.json so `curdx-flow --version` always
-// reflects the installed package version (avoids drift after npm version bumps).
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgJson = JSON.parse(
-  readFileSync(join(__dirname, "..", "package.json"), "utf-8")
-);
-export const VERSION = pkgJson.version;
-
-// ---------- Color helpers (no chalk dep) ----------
-const isTTY = process.stdout.isTTY && process.env.TERM !== "dumb";
-const c = (code) => (s) => isTTY ? `\x1b[${code}m${s}\x1b[0m` : String(s);
-
-export const color = {
-  red: c("31"),
-  green: c("32"),
-  yellow: c("33"),
-  blue: c("34"),
-  magenta: c("35"),
-  cyan: c("36"),
-  dim: c("2"),
-  bold: c("1"),
-  underline: c("4"),
-};
-
-// ---------- Logging helpers ----------
-export const log = {
-  info: (msg) => console.log(`${color.cyan("ℹ")}  ${msg}`),
-  ok: (msg) => console.log(`${color.green("✓")}  ${msg}`),
-  warn: (msg) => console.log(`${color.yellow("⚠")}  ${msg}`),
-  err: (msg) => console.error(`${color.red("✗")}  ${msg}`),
-  step: (n, total, msg) =>
-    console.log(`${color.dim(`[${n}/${total}]`)} ${msg}`),
-  blank: () => console.log(""),
-  title: (msg) => console.log(`\n${color.bold(msg)}\n`),
-};
-
-// ---------- Run shell command ----------
-/**
- * Run a command, stream output live. Returns { code, stdout, stderr }.
- */
-export function run(cmd, args = [], opts = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, {
-      stdio: opts.silent ? ["ignore", "pipe", "pipe"] : "inherit",
-      env: { ...process.env, ...opts.env },
-      cwd: opts.cwd || process.cwd(),
-      shell: false,
-    });
-
-    let stdout = "";
-    let stderr = "";
-    if (opts.silent) {
-      child.stdout.on("data", (d) => (stdout += d.toString()));
-      child.stderr.on("data", (d) => (stderr += d.toString()));
-    }
-
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-    child.on("error", (err) => resolve({ code: -1, stdout: "", stderr: err.message }));
-  });
-}
-
-/**
- * Sync run — for quick checks (e.g. "which claude").
- */
-export function runSync(cmd, args = []) {
-  const res = spawnSync(cmd, args, { encoding: "utf-8", shell: false });
-  return {
-    code: res.status ?? -1,
-    stdout: res.stdout ?? "",
-    stderr: res.stderr ?? "",
-  };
-}
-
-// ---------- Check if a command exists ----------
-export function has(cmd) {
-  const res = runSync("which", [cmd]);
-  return res.code === 0 && res.stdout.trim().length > 0;
-}
-
-// ---------- @clack/prompts wrappers ----------
-let _clack = null;
-
-/**
- * Lazy-load @clack/prompts (ESM module)
- */
-async function getClack() {
-  if (!_clack) {
-    _clack = await import("@clack/prompts");
-  }
-  return _clack;
-}
-
-/**
- * Handle user cancellation gracefully
- */
-async function handleCancel(value, message = "Operation cancelled") {
-  const clack = await getClack();
-  if (clack.isCancel(value)) {
-    clack.cancel(message);
-    process.exit(0);
-  }
-  return false;
-}
-
-/**
- * Single-select prompt with arrow key navigation
- * @param {Object} options
- * @param {string} options.message - Question to ask
- * @param {Array} options.options - Array of {value, label, hint?}
- * @param {any} [options.initialValue] - Default selected value
- * @returns {Promise<any>} Selected value
- */
-export async function select(options) {
-  const clack = await getClack();
-  const result = await clack.select({
-    message: options.message,
-    options: options.options,
-    initialValue: options.initialValue,
-  });
-  await handleCancel(result);
-  return result;
-}
-
-/**
- * Multi-select prompt with checkboxes (arrow keys + space to toggle)
- * @param {Object} options
- * @param {string} options.message - Question to ask
- * @param {Array} options.options - Array of {value, label, hint?}
- * @param {Array} [options.initialValues] - Default selected values
- * @param {boolean} [options.required] - Whether at least one must be selected
- * @returns {Promise<Array>} Array of selected values
- */
-export async function multiselectClack(options) {
-  const clack = await getClack();
-  const result = await clack.multiselect({
-    message: options.message,
-    options: options.options,
-    initialValues: options.initialValues || [],
-    required: options.required !== undefined ? options.required : false,
-  });
-  await handleCancel(result);
-  return result;
-}
-
-/**
- * Text input prompt with validation
- * @param {Object} options
- * @param {string} options.message - Question to ask
- * @param {string} [options.placeholder] - Placeholder text
- * @param {string} [options.defaultValue] - Default value
- * @param {Function} [options.validate] - Validation function (return string for error, undefined for success)
- * @returns {Promise<string>} User input
- */
-export async function text(options) {
-  const clack = await getClack();
-  const result = await clack.text({
-    message: options.message,
-    placeholder: options.placeholder,
-    defaultValue: options.defaultValue,
-    validate: options.validate,
-  });
-  await handleCancel(result);
-  return result;
-}
-
-/**
- * Spinner for async operations
- * @returns {Promise<Object>} Spinner controller
- */
-export async function spinner() {
-  const clack = await getClack();
-  return clack.spinner();
-}
-
-/**
- * Display intro message
- */
-export async function intro(message) {
-  const clack = await getClack();
-  clack.intro(message);
-}
-
-/**
- * Display outro message
- */
-export async function outro(message) {
-  const clack = await getClack();
-  clack.outro(message);
-}
-
-/**
- * Display a note/info box
- */
-export async function note(message, title) {
-  const clack = await getClack();
-  clack.note(message, title);
-}
-
-// ---------- Config file helpers ----------
-const CONFIG_DIR = join(homedir(), ".claude");
-const CONFIG_FILE = join(CONFIG_DIR, "curdx-flow-config.json");
-
-/**
- * Read curdx-flow config from ~/.claude/curdx-flow-config.json
- */
-export function readConfig() {
-  if (!existsSync(CONFIG_FILE)) {
-    return {};
-  }
-  try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Write curdx-flow config to ~/.claude/curdx-flow-config.json
- */
-export function writeConfig(config) {
-  if (!existsSync(CONFIG_DIR)) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
-  }
-  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
-}
-
-// ---------- Interactive prompts (readline, legacy) ----------
-/**
- * Ask user a yes/no question. Default applies on empty input.
- */
-export function confirm(message, defaultYes = true) {
-  return new Promise((resolve) => {
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    const hint = defaultYes ? "[Y/n]" : "[y/N]";
-    rl.question(`${color.cyan("?")}  ${message} ${color.dim(hint)} `, (ans) => {
-      rl.close();
-      const v = ans.trim().toLowerCase();
-      if (v === "") return resolve(defaultYes);
-      resolve(v === "y" || v === "yes");
-    });
-  });
-}
-
-/**
- * Multi-select (checkbox-style via comma-separated input).
- * Returns array of selected values.
- */
-export function multiSelect(message, choices, defaults = null) {
-  return new Promise((resolve) => {
-    const defaultSet = new Set(
-      defaults ?? choices.map((_, i) => i)
-    );
-    console.log(`${color.cyan("?")}  ${message}`);
-    choices.forEach((ch, i) => {
-      const checked = defaultSet.has(i)
-        ? color.green("[x]")
-        : color.dim("[ ]");
-      console.log(`   ${checked} ${color.bold(String(i + 1))}. ${ch.label}${ch.hint ? color.dim(` — ${ch.hint}`) : ""}`);
-    });
-    console.log(
-      color.dim(
-        "   (comma-separated selection, e.g. 1,3  |  a=all  |  n=none  |  Enter=default)"
-      )
-    );
-
-    const rl = createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    rl.question(`   > `, (ans) => {
-      rl.close();
-      const v = ans.trim().toLowerCase();
-      let selected;
-      if (v === "") {
-        selected = [...defaultSet];
-      } else if (v === "a" || v === "all") {
-        selected = choices.map((_, i) => i);
-      } else if (v === "n" || v === "none") {
-        selected = [];
-      } else {
-        selected = v
-          .split(/[,\s]+/)
-          .map((x) => parseInt(x, 10) - 1)
-          .filter((i) => Number.isInteger(i) && i >= 0 && i < choices.length);
-      }
-      resolve(selected.map((i) => choices[i].value));
-    });
-  });
-}
-
-// ---------- Claude CLI helpers ----------
-/** Get claude CLI version, or null if not installed. */
-export function claudeVersion() {
-  if (!has("claude")) return null;
-  const res = runSync("claude", ["--version"]);
-  if (res.code !== 0) return null;
-  // Output like "2.1.114 (Claude Code)"
-  const m = res.stdout.match(/(\d+\.\d+\.\d+)/);
-  return m ? m[1] : res.stdout.trim().split("\n")[0];
-}
-
-/**
- * List installed plugins. Prefers the structured `claude plugin list --json`
- * output (stable machine-readable format; confirmed present in claude
- * 2.1.117+). Falls back to parsing the human-readable stream-text output
- * for older CLI versions, but warns that parser is brittle.
  *
- * Returns array of { id, name, marketplaceId, version, status, scope }.
- */
-export function listPlugins() {
-  // Preferred: structured JSON output.
-  const j = runSync("claude", ["plugin", "list", "--json"]);
-  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
-    try {
-      const arr = JSON.parse(j.stdout);
-      return arr.map((p) => ({
-        // id has form "name@marketplace" — name is stable for dedup/lookup.
-        id: String(p.id || ""),
-        name: String(p.id || "").split("@")[0],
-        marketplaceId: String(p.id || "").split("@")[1] || undefined,
-        version: p.version,
-        status: p.enabled === false ? "disabled" : "enabled",
-        scope: p.scope,
-        raw: JSON.stringify(p),
-      }));
-    } catch {
-      // JSON parse failed — fall through to legacy text parser.
-    }
-  }
-
-  // Legacy fallback: parse the human-readable format.
-  //   ❯ curdx-flow@curdx-flow-marketplace
-  //     Version: 1.1.1
-  //     Status: ✔ enabled
-  // Fragile — matches unicode markers. Kept only for older claude CLIs.
-  const res = runSync("claude", ["plugin", "list"]);
-  if (res.code !== 0) return [];
-  const plugins = [];
-  const blocks = res.stdout.split(/\n\s*❯\s*/).slice(1);
-  for (const block of blocks) {
-    const lines = block.split("\n");
-    const id = lines[0].trim();
-    const name = id.split("@")[0];
-    const version = (block.match(/Version:\s*(\S+)/) || [])[1];
-    const status = block.includes("✔")
-      ? "enabled"
-      : block.includes("✘")
-        ? "failed"
-        : "unknown";
-    plugins.push({ id, name, marketplaceId: id.split("@")[1], version, status, raw: block });
-  }
-  return plugins;
-}
-
-/**
- * List configured Claude Code plugin marketplaces.
- * Returns array of { name, source, repo, path } when `--json` is supported.
- */
-export function listPluginMarketplaces() {
-  const j = runSync("claude", ["plugin", "marketplace", "list", "--json"]);
-  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
-    try {
-      return JSON.parse(j.stdout);
-    } catch {
-      return [];
-    }
-  }
-  return [];
-}
-
-/**
- * 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 }
- * where `plugin` is set when the MCP came from a plugin (real name is
- * `plugin:<plugin>:<mcp>`), `name` is the trailing segment, and `fullName`
- * is the original as reported by claude.
- *
- * Fixture captured from `claude mcp list` (2.1.117):
- *   Checking MCP server health…
- *
- *   plugin:curdx-flow:context7: npx -y @upstash/context7-mcp@latest - ✓ Connected
- *   context7: npx -y @upstash/context7-mcp --api-key ... - ✓ Connected
- *   claude.ai Gmail: https://gmailmcp... - ✓ Connected
- *
- * `claude mcp list --json` does not exist on 2.1.117 (verified), so this
- * parser is the primary path. It is fixture-tested in test/utils.test.js
- * so format regressions get caught in CI.
- */
-export function listMcps() {
-  const res = runSync("claude", ["mcp", "list"]);
-  if (res.code !== 0) return [];
-  return parseMcpList(res.stdout);
-}
-
-/** Exported for testing against a fixed input. */
-export function parseMcpList(output) {
-  const mcps = [];
-  for (const raw of output.split("\n")) {
-    const line = raw.trimEnd();
-    if (!line) continue;
-    // skip the health-check header line
-    if (line.startsWith("Checking") || line.startsWith("checking")) continue;
-    // Expected format: "<fullName>: <command-or-url> - <status>"
-    // fullName may itself contain colons when prefixed with "plugin:<p>:<m>".
-    // Match from the end to find the status sentinel " - ", then split off
-    // the name at the first ": " after the identifier prefix.
-    const statusSplit = line.lastIndexOf(" - ");
-    if (statusSplit === -1) continue;
-    const statusRaw = line.slice(statusSplit + 3).trim();
-    const beforeStatus = line.slice(0, statusSplit);
-    // Find the first ": " that separates name from command. Note the space
-    // after the colon — this disambiguates from the colons inside
-    // "plugin:foo:bar".
-    const nameSplit = beforeStatus.indexOf(": ");
-    if (nameSplit === -1) continue;
-    const fullName = beforeStatus.slice(0, nameSplit).trim();
-    const command = beforeStatus.slice(nameSplit + 2).trim();
-
-    let plugin = null;
-    let name = fullName;
-    if (fullName.startsWith("plugin:")) {
-      const parts = fullName.split(":");
-      if (parts.length >= 3) {
-        plugin = parts[1];
-        name = parts.slice(2).join(":");
-      }
-    }
-
-    const status = /Connected|✓/.test(statusRaw)
-      ? "connected"
-      : /Failed|✗/.test(statusRaw)
-        ? "failed"
-        : "unknown";
-
-    mcps.push({ name, plugin, fullName, status, command });
-  }
-  return mcps;
-}
-
-// ---------- Runtime PATH guards (bun / uv) ----------
-// claude-mem hard-codes `command: "bun"` in its .mcp.json, but bun installs to
-// ~/.bun/bin which is not on PATH when Claude Code spawns MCP servers
-// (macOS non-interactive shells do not source .zshrc). This module provides
-// detection + self-healing: create a symlink to the user-level bun install
-// in a PATH-visible directory.
-
-// Note: existsSync, mkdirSync, symlinkSync, lstatSync, unlinkSync, readlinkSync, homedir, join
-// are already imported at the top of this file.
-
-// os.homedir() is sourced from the OS-level user record and works even
-// when $HOME is empty (non-login shells, some CI containers). See the
-// same rationale in cli/protocols.js.
-const HOME = homedir();
-
-/** Candidate bun install locations (priority order) */
-const BUN_CANDIDATES = [
-  join(HOME, ".bun", "bin", "bun"),
-  "/opt/homebrew/bin/bun",
-  "/usr/local/bin/bun",
-  "/home/linuxbrew/.linuxbrew/bin/bun",
-];
-
-/** Candidate uv install locations */
-const UV_CANDIDATES = [
-  join(HOME, ".local", "bin", "uv"),
-  join(HOME, ".cargo", "bin", "uv"),
-  "/opt/homebrew/bin/uv",
-  "/usr/local/bin/uv",
-];
-
-/** PATH-visible directories where symlinks can be created (priority order; use if exists, else try to create) */
-const SYMLINK_TARGET_DIRS = [
-  join(HOME, ".local", "bin"),
-  join(HOME, ".npm-global", "bin"),
-];
-
-/** Find the absolute path of a runtime that actually exists */
-function findRuntime(candidates) {
-  for (const p of candidates) if (existsSync(p)) return p;
-  return null;
-}
-
-/** Whether the current PATH can resolve this command */
-function inPath(cmd) {
-  return has(cmd);
-}
-
-/** Find a writable PATH-visible directory for symlink creation */
-function findSymlinkDir() {
-  const pathDirs = (process.env.PATH || "").split(":").filter(Boolean);
-  for (const d of SYMLINK_TARGET_DIRS) {
-    if (pathDirs.includes(d)) {
-      try {
-        if (!existsSync(d)) mkdirSync(d, { recursive: true });
-        return d;
-      } catch {
-        // continue
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * Ensure cmd is resolvable on PATH. If it is installed but not visible
- * on PATH, create a symlink automatically.
- * @returns {{status:"ok"|"linked"|"missing"|"path-unwritable", path?:string, link?:string}}
- */
-export function ensureRuntimeInPath(cmd, candidates) {
-  if (inPath(cmd)) return { status: "ok" };
-
-  const realPath = findRuntime(candidates);
-  if (!realPath) return { status: "missing" };
-
-  const linkDir = findSymlinkDir();
-  if (!linkDir) return { status: "path-unwritable", path: realPath };
-
-  const linkPath = join(linkDir, cmd);
-  // If it already exists and points to the same target, return idempotently
-  if (existsSync(linkPath)) {
-    try {
-      const stat = lstatSync(linkPath);
-      if (stat.isSymbolicLink() && readlinkSync(linkPath) === realPath) {
-        return { status: "ok", path: realPath, link: linkPath };
-      }
-      // Old symlink/file points elsewhere — overwrite
-      unlinkSync(linkPath);
-    } catch {
-      // ignore
-    }
-  }
-  try {
-    symlinkSync(realPath, linkPath);
-    return { status: "linked", path: realPath, link: linkPath };
-  } catch (err) {
-    return { status: "path-unwritable", path: realPath };
-  }
-}
-
-/** One-shot: ensure both bun and uv (claude-mem's runtimes) are resolvable on PATH */
-export function ensureClaudeMemRuntimes() {
-  return {
-    bun: ensureRuntimeInPath("bun", BUN_CANDIDATES),
-    uv: ensureRuntimeInPath("uv", UV_CANDIDATES),
-  };
-}
+ * This module is kept as the stable public import surface for existing CLI
+ * commands. Implementations live under cli/lib/ so each concern stays small.
+ */
+
+export { VERSION } from "./lib/version.js";
+export { color, log } from "./lib/logging.js";
+export { has, run, runSync } from "./lib/process.js";
+export {
+  confirm,
+  intro,
+  multiSelect,
+  multiselectClack,
+  note,
+  outro,
+  select,
+  spinner,
+  text,
+} from "./lib/prompts.js";
+export { readConfig, writeConfig } from "./lib/config.js";
+export {
+  claudeVersion,
+  findDuplicateMcps,
+  listMcps,
+  listPluginMarketplaces,
+  listPlugins,
+  parseMcpList,
+  readUserMcpConfig,
+} from "./lib/claude.js";
+export { ensureClaudeMemRuntimes, ensureRuntimeInPath } from "./lib/runtime.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@curdx/flow",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "CLI installer for CurdX-Flow — AI engineering workflow meta-framework for Claude Code",
   "type": "module",
   "bin": {