@curdx/flow 1.1.1

package/cli/doctor.js

@@ -0,0 +1,155 @@
+/**
+ * doctor command — external health check (no need to enter Claude Code).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  color,
+  log,
+  runSync,
+  claudeVersion,
+  listPlugins,
+  listMcps,
+  ensureClaudeMemRuntimes,
+} from "./utils.js";
+
+export async function doctor(args = []) {
+  const verbose = args.includes("--verbose") || args.includes("-v");
+
+  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++;
+  }
+
+  // ---------- 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++;
+  }
+
+  // ---------- MCPs ----------
+  console.log(`\n${color.bold("MCP Servers:")}`);
+  const mcps = cv ? listMcps() : [];
+  const expectedMcps = ["context7", "sequential-thinking", "chrome-devtools"];
+  for (const m of expectedMcps) {
+    const found = mcps.find((x) => x.name === m);
+    if (found) {
+      log.ok(`${m.padEnd(22)} ${color.dim("auto-loaded")}`);
+    } else {
+      if (curdx) {
+        log.warn(`${m.padEnd(22)} not shown in claude mcp list (restart Claude Code may fix)`);
+        warnings++;
+      } else {
+        log.info(`${m.padEnd(22)} waiting for curdx-flow install`);
+      }
+    }
+  }
+
+  // ---------- Recommended plugins ----------
+  console.log(`\n${color.bold("Recommended plugins:")}`);
+  const recommended = [
+    { name: "pua", installCmd: "claude plugin install pua@pua-skills" },
+    { name: "claude-mem", installCmd: "claude plugin install claude-mem@thedotmack" },
+    { name: "frontend-design", installCmd: "claude plugin install frontend-design@claude-plugins-official" },
+  ];
+  let claudeMemEnabled = false;
+  for (const r of recommended) {
+    const p = plugins.find((x) => x.name === r.name);
+    if (p && p.status === "enabled") {
+      log.ok(`${r.name.padEnd(22)} ${color.dim(`v${p.version}`)}`);
+      if (r.name === "claude-mem") claudeMemEnabled = true;
+    } 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: curdx-flow install --all)")}`);
+      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++;
+      }
+    }
+  }
+
+  // ---------- 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 ----------
+  console.log();
+  if (errors > 0) {
+    console.log(color.red(`Summary: ${errors} error(s), ${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) {
+    console.log(`\n${color.bold("Details:")}`);
+    console.log(color.dim(`  Plugins raw:`));
+    console.log(runSync("claude", ["plugin", "list"]).stdout);
+  }
+}

package/cli/init.js

@@ -0,0 +1,296 @@
+/**
+ * init command — external version of /curdx-flow:init.
+ * Creates .flow/ structure in target directory.
+ *
+ * Uses templates from plugin cache if available, falls back to embedded templates.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import {
+  color,
+  log,
+  confirm,
+  pluginCacheDir,
+  has,
+  runSync,
+} from "./utils.js";
+
+export async function init(args = []) {
+  const force = args.includes("--force");
+  const target = args.find((a) => !a.startsWith("--")) || process.cwd();
+  const absTarget = path.resolve(target);
+
+  log.title(`📦 Initialize CurDX-Flow project`);
+  console.log(`   Target: ${color.cyan(absTarget)}`);
+
+  // ---------- Check target exists ----------
+  try {
+    const stat = await fs.stat(absTarget);
+    if (!stat.isDirectory()) {
+      log.err(`Target is not a directory: ${absTarget}`);
+      process.exit(1);
+    }
+  } catch {
+    log.err(`Directory does not exist: ${absTarget}`);
+    process.exit(1);
+  }
+
+  // ---------- Check existing .flow/ ----------
+  const flowDir = path.join(absTarget, ".flow");
+  if (existsSync(flowDir)) {
+    if (!force) {
+      log.warn(`.flow/ already exists`);
+      const ok = await confirm("Overwrite existing .flow/?", false);
+      if (!ok) {
+        log.info("Cancelled");
+        return;
+      }
+    }
+  }
+
+  // ---------- Find templates ----------
+  const tmplDir = await findLatestTemplatesDir();
+
+  // ---------- Create directory structure ----------
+  log.step(1, 4, "Creating .flow/ directory structure...");
+  const dirs = [
+    ".flow",
+    ".flow/specs",
+    ".flow/_epics",
+    ".flow/checkpoints",
+    ".flow/threads",
+    ".flow/seeds",
+  ];
+  for (const d of dirs) {
+    await fs.mkdir(path.join(absTarget, d), { recursive: true });
+  }
+  log.ok("Directories created");
+
+  // ---------- Generate files from templates ----------
+  log.step(2, 4, "Generating core files...");
+  const today = new Date().toISOString().slice(0, 10);
+  const userName = gitConfig("user.name") || "you";
+  const projectName = path.basename(absTarget);
+
+  const files = [
+    { tmpl: "PROJECT.md.tmpl", out: "PROJECT.md" },
+    { tmpl: "CONTEXT.md.tmpl", out: "CONTEXT.md" },
+    { tmpl: "STATE.md.tmpl", out: "STATE.md" },
+    { tmpl: "ROADMAP.md.tmpl", out: "ROADMAP.md" },
+    { tmpl: "config.json.tmpl", out: "config.json" },
+  ];
+
+  for (const f of files) {
+    const outPath = path.join(flowDir, f.out);
+    if (existsSync(outPath) && !force) {
+      log.info(`   ${f.out} already exists, skipping`);
+      continue;
+    }
+
+    let content;
+    if (tmplDir) {
+      try {
+        content = await fs.readFile(path.join(tmplDir, f.tmpl), "utf-8");
+      } catch {
+        content = embeddedTemplate(f.tmpl);
+      }
+    } else {
+      content = embeddedTemplate(f.tmpl);
+    }
+
+    // Placeholder replacement
+    content = content
+      .replace(/\{\{PROJECT_NAME\}\}/g, projectName)
+      .replace(/\{\{CREATED_DATE\}\}/g, today)
+      .replace(/\{\{USER_NAME\}\}/g, userName);
+
+    await fs.writeFile(outPath, content, "utf-8");
+    log.ok(`   .flow/${f.out}`);
+  }
+
+  // ---------- Update .gitignore ----------
+  log.step(3, 4, "Updating .gitignore...");
+  const giPath = path.join(absTarget, ".gitignore");
+  const giAdd = [
+    "",
+    "# CurDX-Flow runtime (auto-generated, do not commit)",
+    ".flow/checkpoints/",
+    ".flow/threads/",
+    ".flow/seeds/",
+    ".flow/.active-spec",
+    ".flow/specs/*/.state.json",
+    ".flow/specs/*/.progress.md",
+    ".flow/_epics/*/.epic-state.json",
+  ].join("\n");
+
+  let existingGi = "";
+  try {
+    existingGi = await fs.readFile(giPath, "utf-8");
+  } catch {
+    // no .gitignore yet
+  }
+
+  if (!existingGi.includes("CurDX-Flow")) {
+    await fs.writeFile(giPath, existingGi + giAdd + "\n", "utf-8");
+    log.ok(".gitignore appended with CurDX-Flow ignores");
+  } else {
+    log.info(".gitignore already has CurDX-Flow rules, skipping");
+  }
+
+  // ---------- Done ----------
+  log.blank();
+  log.step(4, 4, "Done");
+  log.ok(`CurDX-Flow project initialized: ${color.cyan(absTarget)}`);
+
+  console.log(`\n${color.bold("Next steps:")}\n`);
+  console.log(`  1. Edit ${color.cyan(".flow/PROJECT.md")} — fill in the project vision (~5 min)`);
+  console.log(`  2. Edit ${color.cyan(".flow/CONTEXT.md")} — your preferences`);
+  console.log(`  3. Enter Claude Code:`);
+  console.log(`     ${color.cyan("cd " + absTarget)}`);
+  console.log(`     ${color.cyan("claude")}`);
+  console.log(`     ${color.cyan("/curdx-flow:start my-feature \"<description>\"")}`);
+  console.log();
+}
+
+// ---------- Helpers ----------
+
+/**
+ * Find the latest installed templates directory in plugin cache.
+ * Returns null if plugin not installed.
+ */
+async function findLatestTemplatesDir() {
+  const pluginBase = pluginCacheDir();
+  try {
+    const versions = await fs.readdir(pluginBase);
+    // Pick last (lexicographically — semver works for simple cases)
+    const sorted = versions.sort();
+    for (let i = sorted.length - 1; i >= 0; i--) {
+      const tmplDir = path.join(pluginBase, sorted[i], "templates");
+      if (existsSync(tmplDir)) return tmplDir;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function gitConfig(key) {
+  if (!has("git")) return null;
+  const r = runSync("git", ["config", "--get", key]);
+  return r.code === 0 ? r.stdout.trim() : null;
+}
+
+/**
+ * Embedded fallback templates — used when plugin cache not available.
+ * Keep these minimal; rich templates live in templates/*.tmpl.
+ *
+ * Note: these embedded templates are English. Users who want Chinese
+ * project state can edit the resulting files (or set lang preference
+ * in CONTEXT.md and use the rich templates from the plugin cache).
+ */
+function embeddedTemplate(name) {
+  const today = "{{CREATED_DATE}}";
+  const project = "{{PROJECT_NAME}}";
+  const user = "{{USER_NAME}}";
+
+  switch (name) {
+    case "PROJECT.md.tmpl":
+      return `# ${project}
+
+> CurDX-Flow project vision
+
+## One-line description
+TODO: in one sentence — what is the project, who is it for, what problem does it solve
+
+## Why this exists
+TODO:
+
+## Core users
+TODO:
+
+## Success criteria (verifiable metrics)
+1. TODO:
+2. TODO:
+
+## Tech stack
+TODO:
+
+## Out of scope (Scope Guard)
+- ✗ TODO:
+
+---
+
+_Generated by curdx-flow init on ${today}. Maintainer: ${user}_
+`;
+
+    case "CONTEXT.md.tmpl":
+      return `# ${project} — User preferences
+
+## Code style
+- Indentation: TODO
+- Quotes: TODO
+- Naming: TODO
+
+## Communication preferences
+- Language: en
+- Verbosity: balanced
+
+## Tooling preferences
+- Package manager: TODO
+
+---
+
+_Generated by curdx-flow init on ${today}_
+`;
+
+    case "STATE.md.tmpl":
+      return `# ${project} — Cross-session state
+
+## Key decisions (Decisions)
+None yet.
+
+## Blockers
+None yet.
+
+---
+
+_Initialized on ${today}_
+`;
+
+    case "ROADMAP.md.tmpl":
+      return `# ${project} — Roadmap
+
+## Current version: v0.1 (MVP)
+
+**Goal**: TODO
+
+### Success criteria
+- [ ] TODO
+
+---
+
+_Initialized on ${today}_
+`;
+
+    case "config.json.tmpl":
+      return `{
+  "version": "1.0",
+  "mode": "standard",
+  "execution": {
+    "strategy": "auto",
+    "max_parallel": 5
+  },
+  "gates": {
+    "always_on": ["karpathy-gate", "verification-gate"],
+    "standard_mode": ["tdd-gate", "coverage-audit-gate"]
+  },
+  "created": "${today}"
+}
+`;
+
+    default:
+      return `# ${name}\n\n(template not found)\n`;
+  }
+}

package/cli/install.js

@@ -0,0 +1,213 @@
+/**
+ * install command — install curdx-flow plugin + optional recommended plugins.
+ */
+
+import {
+  color,
+  log,
+  run,
+  has,
+  claudeVersion,
+  listPlugins,
+  multiSelect,
+  ensureClaudeMemRuntimes,
+} from "./utils.js";
+import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+
+// Recommended plugins with their marketplace source + install identifier
+const RECOMMENDED = [
+  {
+    name: "pua",
+    marketplace: "tanweai/pua",
+    installSpec: "pua@pua-skills",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    marketplace: "thedotmack/claude-mem",
+    installSpec: "claude-mem@thedotmack",
+    hint: "automatic cross-session memory",
+  },
+  {
+    name: "frontend-design",
+    marketplace: null, // already in default marketplace claude-plugins-official
+    installSpec: "frontend-design@claude-plugins-official",
+    hint: "Anthropic official UI skill",
+  },
+];
+
+export async function install(args = []) {
+  const all = args.includes("--all");
+  const noDeps = args.includes("--no-deps");
+
+  log.title("🚀 CurDX-Flow Installer");
+
+  // ---------- Step 1: Check claude CLI ----------
+  log.step(1, 4, "Checking claude CLI...");
+  const ver = claudeVersion();
+  if (!ver) {
+    log.err("claude CLI not found. Install Claude Code from https://code.claude.com first.");
+    process.exit(1);
+  }
+  log.ok(`claude CLI found (${ver})`);
+
+  // ---------- Step 2: Add marketplace ----------
+  log.blank();
+  log.step(2, 4, "Adding curdx-flow marketplace...");
+  const addRes = await run("claude", ["plugin", "marketplace", "add", "curdx/curdx-flow"], {
+    silent: true,
+  });
+  if (addRes.code !== 0 && !addRes.stderr.includes("already")) {
+    // Not a fatal error if already added
+    log.warn(`marketplace add output: ${addRes.stderr.trim() || addRes.stdout.trim()}`);
+  } else {
+    log.ok("curdx-flow-marketplace added");
+  }
+
+  // ---------- Step 3: Install curdx-flow plugin ----------
+  log.blank();
+  log.step(3, 4, "Installing curdx-flow plugin (3 MCPs will auto-start)...");
+  const installed = listPlugins();
+  const already = installed.find((p) => p.name === "curdx-flow");
+  if (already) {
+    log.ok(`curdx-flow already installed (v${already.version}, ${already.status})`);
+  } else {
+    const r = await run(
+      "claude",
+      ["plugin", "install", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.err(`Install failed: ${r.stderr.trim() || r.stdout.trim()}`);
+      process.exit(1);
+    }
+    log.ok("curdx-flow installed");
+  }
+
+  // ---------- Step 4: Recommended plugins ----------
+  log.blank();
+  log.step(4, 4, "Recommended plugins");
+
+  if (noDeps) {
+    log.info("Skipping recommended plugins (--no-deps)");
+    printNextSteps();
+    return;
+  }
+
+  let toInstall;
+  if (all) {
+    toInstall = RECOMMENDED.map((r) => r.name);
+    log.info("--all mode: installing all recommended");
+  } else {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    const choices = RECOMMENDED.map((r) => ({
+      label: `${color.bold(r.name)}${currentlyInstalled.has(r.name) ? color.green(" (installed)") : ""}`,
+      value: r.name,
+      hint: r.hint,
+    }));
+    const defaults = RECOMMENDED
+      .map((r, i) => (currentlyInstalled.has(r.name) ? -1 : i))
+      .filter((i) => i >= 0);
+
+    toInstall = await multiSelect("Which recommended plugins to install?", choices, defaults);
+  }
+
+  if (!toInstall || toInstall.length === 0) {
+    log.info("No recommended plugins selected, skipping");
+    printNextSteps();
+    return;
+  }
+
+  // Install each
+  for (const pluginName of toInstall) {
+    const rec = RECOMMENDED.find((r) => r.name === pluginName);
+    log.blank();
+    console.log(`  ${color.cyan("⏳")} Installing ${color.bold(rec.name)}...`);
+
+    // 1. Add marketplace (if needed)
+    if (rec.marketplace) {
+      const ma = await run(
+        "claude",
+        ["plugin", "marketplace", "add", rec.marketplace],
+        { silent: true }
+      );
+      if (ma.code !== 0 && !ma.stderr.includes("already")) {
+        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+        // Don't abort — may already exist
+      }
+    }
+
+    // 2. Install
+    const ir = await run("claude", ["plugin", "install", rec.installSpec], {
+      silent: true,
+    });
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${rec.name} installed`);
+
+      // 3. Post-install hook for claude-mem: its .mcp.json hard-codes `bun`,
+      // but ~/.bun/bin is not on PATH when Claude Code spawns the MCP server.
+      // Auto-create a PATH-visible symlink to fix it.
+      if (rec.name === "claude-mem") {
+        const r = ensureClaudeMemRuntimes();
+        for (const [name, res] of Object.entries(r)) {
+          if (res.status === "linked") {
+            console.log(
+              `  ${color.green("✓")} ${name} → PATH symlink created ${color.dim(`(${res.link} → ${res.path})`)}`
+            );
+          } else if (res.status === "missing") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} not installed ${color.dim("(claude-mem will auto-install on first run; or run: curdx-flow doctor)")}`
+            );
+          } else if (res.status === "path-unwritable") {
+            console.log(
+              `  ${color.yellow("⚠")} ${name} installed ${color.dim(`(${res.path}) but no writable PATH location — add export PATH=\"${res.path.split("/").slice(0,-1).join("/")}:$PATH\" to your shell rc`)}`
+            );
+          }
+          // status === "ok" → already on PATH, stay silent
+        }
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${rec.name} install failed: ${ir.stderr.trim().split("\n").pop()}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin install ${rec.installSpec}`
+        )
+      );
+    }
+  }
+
+  // ---------- Step 5: inject global protocols ----------
+  log.blank();
+  console.log(color.dim("Injecting global protocols into ~/.claude/CLAUDE.md..."));
+  try {
+    const r = injectGlobalProtocols();
+    if (r.action === "created") {
+      log.ok(`Global protocols injected ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
+    } else if (r.action === "upgraded") {
+      log.ok(`Global protocols upgraded ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
+    } else {
+      log.info(`Global protocols up to date ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
+    }
+  } catch (err) {
+    log.warn(`Protocol injection failed: ${err.message} ${color.dim("(non-blocking)")}`);
+  }
+
+  printNextSteps();
+}
+
+function printNextSteps() {
+  console.log(`\n${color.bold("✅ Install complete")}\n`);
+  console.log(`${color.bold("Next steps")}:\n`);
+  console.log(`  ${color.dim("# Verify health")}`);
+  console.log(`  curdx-flow doctor\n`);
+  console.log(`  ${color.dim("# Initialize .flow/ in your project")}`);
+  console.log(`  cd ~/your-project && curdx-flow init\n`);
+  console.log(`  ${color.dim("# Start using it (inside Claude Code)")}`);
+  console.log(`  ${color.cyan("claude")}`);
+  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<describe what to build>\"")}\n`);
+  console.log(
+    `${color.bold("Learn more")}: https://github.com/curdx/curdx-flow/blob/main/docs/getting-started.md\n`
+  );
+}