@curdx/flow 2.0.7 → 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.4"
+    "version": "2.0.9"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.6",
+  "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/install-paths.js

@@ -13,6 +13,11 @@ export const LOCAL_MARKETPLACE_MANIFEST = join(
   ".claude-plugin",
   "marketplace.json"
 );
+export const LOCAL_PLUGIN_MANIFEST = join(
+  PKG_ROOT,
+  ".claude-plugin",
+  "plugin.json"
+);
 
 export function shouldUseOfflineInstall({ forceOnline }) {
   return !forceOnline && existsSync(LOCAL_MARKETPLACE_MANIFEST);
@@ -30,8 +35,16 @@ export function getMarketplaceLabel(useOffline) {
 
 export function readShippedVersion() {
   try {
-    const mf = JSON.parse(readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8"));
-    return mf?.metadata?.version || null;
+    const plugin = JSON.parse(readFileSync(LOCAL_PLUGIN_MANIFEST, "utf-8"));
+    if (plugin?.version) return plugin.version;
+  } catch {
+    // Fall back to the marketplace manifest below. Online installs or old
+    // package layouts may not have a local plugin manifest available.
+  }
+
+  try {
+    const marketplace = JSON.parse(readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8"));
+    return marketplace?.metadata?.version || null;
   } catch {
     // marketplace not local (online install) or unreadable
     return null;

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),
+  };
+}