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

package/cli/install.js

@@ -2,7 +2,7 @@
  * install command — install curdx-flow plugin + optional recommended plugins.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -17,6 +17,7 @@ import {
   ensureClaudeMemRuntimes,
 } from "./utils.js";
 import { injectGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
 // When installed via npm, this CLI file lives at <pkg-root>/cli/install.js.
 // The npm package bundles the full plugin body (.claude-plugin/, agents/,
@@ -28,27 +29,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = dirname(__dirname);
 const LOCAL_MARKETPLACE_MANIFEST = join(PKG_ROOT, ".claude-plugin", "marketplace.json");
 
-// 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",
-  },
-];
+// Recommended plugins: single source of truth is cli/registry.js.
+// See registry.js for the rationale — this list used to drift across
+// install/uninstall/upgrade/doctor, producing the chrome-devtools-mcp
+// orphan-plugin bug (installable but uninstallable).
+const RECOMMENDED = RECOMMENDED_PLUGINS;
 
 export async function install(args = []) {
   const all = args.includes("--all");
@@ -64,7 +49,7 @@ export async function install(args = []) {
   log.title("🚀 CurDX-Flow Installer");
 
   // ---------- Step 1: Check claude CLI ----------
-  log.step(1, 4, "Checking claude CLI...");
+  log.step(1, 5, "Checking claude CLI...");
   const ver = claudeVersion();
   if (!ver) {
     log.err("claude CLI not found. Install Claude Code from https://code.claude.com first.");
@@ -78,7 +63,7 @@ export async function install(args = []) {
   const marketplaceLabel = useOffline
     ? `local npm package (${PKG_ROOT})`
     : "GitHub curdx/curdx-flow";
-  log.step(2, 4, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
+  log.step(2, 5, `Adding curdx-flow marketplace from ${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
@@ -105,10 +90,38 @@ export async function install(args = []) {
 
   // ---------- Step 3: Install curdx-flow plugin ----------
   log.blank();
-  log.step(3, 4, "Installing curdx-flow plugin (3 MCPs will auto-start)...");
+  log.step(3, 5, "Installing curdx-flow plugin (2 MCPs will auto-start)...");
+  // Read the version the marketplace is shipping so we can decide whether an
+  // already-installed plugin needs an update (same name but stale version
+  // previously silently skipped the upgrade — caused the beta.1 → beta.7 drift).
+  let shippedVersion = null;
+  try {
+    const mf = JSON.parse(
+      readFileSync(LOCAL_MARKETPLACE_MANIFEST, "utf-8")
+    );
+    shippedVersion = mf?.metadata?.version || null;
+  } catch {
+    // marketplace not local (online install) or unreadable — fall through
+  }
+
   const installed = listPlugins();
   const already = installed.find((p) => p.name === "curdx-flow");
-  if (already) {
+  if (already && shippedVersion && already.version !== shippedVersion) {
+    log.info(
+      `curdx-flow installed at v${already.version}, marketplace ships v${shippedVersion} — updating...`
+    );
+    const r = await run(
+      "claude",
+      ["plugin", "update", "curdx-flow@curdx-flow-marketplace"],
+      { silent: true }
+    );
+    if (r.code !== 0) {
+      log.warn(`Update returned non-zero: ${r.stderr.trim() || r.stdout.trim()}`);
+      log.info(`If the version stays on v${already.version}, run: claude plugin uninstall curdx-flow@curdx-flow-marketplace && retry`);
+    } else {
+      log.ok(`curdx-flow updated to v${shippedVersion}`);
+    }
+  } else if (already) {
     log.ok(`curdx-flow already installed (v${already.version}, ${already.status})`);
   } else {
     const r = await run(
@@ -125,7 +138,7 @@ export async function install(args = []) {
 
   // ---------- Step 4: Recommended plugins ----------
   log.blank();
-  log.step(4, 4, "Recommended plugins");
+  log.step(4, 5, "Recommended plugins");
 
   if (noDeps) {
     log.info("Skipping recommended plugins (--no-deps)");
@@ -161,7 +174,7 @@ export async function install(args = []) {
   for (const pluginName of toInstall) {
     const rec = RECOMMENDED.find((r) => r.name === pluginName);
     log.blank();
-    console.log(`  ${color.cyan("⏳")} Installing ${color.bold(rec.name)}...`);
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
 
     // 1. Add marketplace (if needed)
     if (rec.marketplace) {
@@ -186,7 +199,7 @@ export async function install(args = []) {
       // 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") {
+      if (rec.postInstall === "claude-mem-runtimes") {
         const r = ensureClaudeMemRuntimes();
         for (const [name, res] of Object.entries(r)) {
           if (res.status === "linked") {
@@ -219,11 +232,13 @@ export async function install(args = []) {
 
   // ---------- Step 5: inject global protocols ----------
   log.blank();
-  console.log(color.dim("Injecting global protocols into ~/.claude/CLAUDE.md..."));
+  log.step(5, 5, "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 === "appended") {
+      log.ok(`Global protocols appended ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else if (r.action === "upgraded") {
       log.ok(`Global protocols upgraded ${color.dim(`(${GLOBAL_CLAUDE_MD})`)}`);
     } else {
@@ -237,15 +252,26 @@ export async function install(args = []) {
 }
 
 function printNextSteps() {
-  console.log(`\n${color.bold("✅ Install complete")}\n`);
+  // Detect whether the CLI is globally installed (curdx-flow on PATH) or
+  // the user ran us via npx. Tell them the right invocation each time.
+  const cliOnPath = has("curdx-flow");
+  const cliCmd = cliOnPath ? "curdx-flow" : "npx @curdx/flow";
+
+  console.log(`\n${color.bold(`${color.green("✓")} Install complete`)}\n`);
+  console.log(`${color.bold("Restart Claude Code")} so the plugin registers all its commands and hooks.\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(`  ${cliCmd} doctor\n`);
+  console.log(`  ${color.dim("# Inside any project, initialize and start a feature spec")}`);
+  console.log(`  ${color.cyan("cd ~/your-project")}`);
   console.log(`  ${color.cyan("claude")}`);
-  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<describe what to build>\"")}\n`);
+  console.log(`  ${color.cyan("/curdx-flow:init")}`);
+  console.log(`  ${color.cyan("/curdx-flow:start my-feature \"<one-line goal>\"")}\n`);
+  if (!cliOnPath) {
+    console.log(
+      `${color.dim("Tip: install the CLI globally for shorter commands —")} ${color.cyan("npm i -g @curdx/flow")}\n`
+    );
+  }
   console.log(
     `${color.bold("Learn more")}: https://github.com/curdx/curdx-flow/blob/main/docs/getting-started.md\n`
   );

package/cli/protocols.js

@@ -5,10 +5,23 @@
  * and reversible (uninstall removes it cleanly without touching user content).
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
 import { join, dirname } from "node:path";
-
-const HOME = process.env.HOME || "";
+import { homedir } from "node:os";
+
+// Use os.homedir() instead of process.env.HOME — HOME can be empty inside
+// non-login shells (CI containers, some spawned child envs), which would
+// resolve GLOBAL_CLAUDE_MD to "/.claude/CLAUDE.md" (filesystem root) and
+// cause mkdir/writeFileSync to fail with EACCES. homedir() falls back to
+// the effective user's passwd entry on POSIX and USERPROFILE on Windows.
+const HOME = homedir();
 export const GLOBAL_CLAUDE_MD = join(HOME, ".claude", "CLAUDE.md");
 
 const SENTINEL_BEGIN =
@@ -53,16 +66,56 @@ function readGlobalMd() {
 
 /**
  * Locate the sentinel block in the content.
- * Returns { start, end } indices into content, or null if not found.
+ * Returns { start, end } indices into content, `null` if neither sentinel is
+ * present, or throws if the block is corrupted (begin without matching end).
+ * The throw is intentional — previously the corrupted case silently returned
+ * null, so the next run would append a SECOND block, producing drift.
  */
 function findBlock(content) {
   const start = content.indexOf(SENTINEL_BEGIN);
-  if (start === -1) return null;
+  if (start === -1) {
+    // Also check for a dangling END without BEGIN — that is also corrupted.
+    if (content.indexOf(SENTINEL_END) !== -1) {
+      throw new Error(
+        `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: END sentinel found without BEGIN. ` +
+          `Manually inspect the file and remove the dangling END line, then re-run.`
+      );
+    }
+    return null;
+  }
   const endIdx = content.indexOf(SENTINEL_END, start);
-  if (endIdx === -1) return null;
+  if (endIdx === -1) {
+    throw new Error(
+      `Corrupted protocol block in ${GLOBAL_CLAUDE_MD}: BEGIN sentinel found without END. ` +
+        `Manually remove the orphan BEGIN line (or restore the END), then re-run.`
+    );
+  }
   return { start, end: endIdx + SENTINEL_END.length };
 }
 
+/**
+ * Write `content` to `path` atomically: write to a sibling temp file first,
+ * then rename. This prevents a half-written CLAUDE.md if the process is
+ * interrupted mid-write, and avoids races between concurrent install /
+ * uninstall invocations.
+ */
+function atomicWrite(path, content) {
+  const tmp = `${path}.curdx-flow.tmp.${process.pid}`;
+  try {
+    writeFileSync(tmp, content, "utf-8");
+    renameSync(tmp, path);
+  } catch (err) {
+    // Best-effort cleanup of the temp file; swallow errors here since we
+    // are already re-throwing the real failure.
+    try {
+      if (existsSync(tmp)) unlinkSync(tmp);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}
+
 /**
  * Inject (or upgrade) the protocol block in ~/.claude/CLAUDE.md.
  * @returns {{action:"created"|"upgraded"|"unchanged", path:string}}
@@ -81,8 +134,8 @@ export function injectGlobalProtocols() {
       ? (existing.endsWith("\n") ? "\n" : "\n\n")
       : "";
     const next = existing + sep + FULL_BLOCK + "\n";
-    writeFileSync(path, next, "utf-8");
-    return { action: existing.length === 0 ? "created" : "created", path };
+    atomicWrite(path, next);
+    return { action: existing.length === 0 ? "created" : "appended", path };
   }
 
   // Replace existing block (handle upgrade-in-place)
@@ -92,7 +145,7 @@ export function injectGlobalProtocols() {
   }
   const next =
     existing.slice(0, block.start) + FULL_BLOCK + existing.slice(block.end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "upgraded", path };
 }
 
@@ -119,6 +172,6 @@ export function removeGlobalProtocols() {
   }
 
   const next = existing.slice(0, start) + existing.slice(end);
-  writeFileSync(path, next, "utf-8");
+  atomicWrite(path, next);
   return { action: "removed", path };
 }

package/cli/registry.js

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for recommended companion plugins.
+ *
+ * Background: before this file existed, the list of recommended plugins lived
+ * in FOUR independent places (install.js, uninstall.js, upgrade.js,
+ * doctor.js). They drifted — chrome-devtools-mcp was added to install.js
+ * during the beta.8 MCP decoupling but forgotten in the other three,
+ * making it installable but uninstallable. This registry exists so adding
+ * or removing a plugin is a one-file change.
+ *
+ * Every consumer pulls what it needs via property access:
+ *   - install.js     → marketplace + installSpec + hint (+ optional postInstall)
+ *   - uninstall.js   → uninstallSpec
+ *   - upgrade.js     → installSpec (for `claude plugin update`) + marketplaceId
+ *   - doctor.js      → name + installSpec (for manual recovery hints)
+ */
+
+export const RECOMMENDED_PLUGINS = [
+  {
+    name: "pua",
+    marketplace: "tanweai/pua",
+    marketplaceId: "pua",
+    installSpec: "pua@pua-skills",
+    uninstallSpec: "pua@pua-skills",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    marketplace: "thedotmack/claude-mem",
+    marketplaceId: "thedotmack",
+    installSpec: "claude-mem@thedotmack",
+    uninstallSpec: "claude-mem@thedotmack",
+    hint: "automatic cross-session memory",
+    postInstall: "claude-mem-runtimes",
+  },
+  {
+    name: "frontend-design",
+    // Already in default marketplace claude-plugins-official, no add needed
+    marketplace: null,
+    marketplaceId: "claude-plugins-official",
+    installSpec: "frontend-design@claude-plugins-official",
+    uninstallSpec: "frontend-design@claude-plugins-official",
+    hint: "Anthropic official UI skill",
+  },
+  {
+    name: "chrome-devtools-mcp",
+    marketplace: "ChromeDevTools/chrome-devtools-mcp",
+    marketplaceId: "chrome-devtools-plugins",
+    installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    hint: "Chrome DevTools + Puppeteer (Google official)",
+  },
+];
+
+/**
+ * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
+ * plus the curdx-flow marketplace itself.
+ */
+export const MARKETPLACES_TO_REFRESH = [
+  "curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS
+    .filter((p) => p.marketplaceId && p.marketplaceId !== "claude-plugins-official")
+    .map((p) => p.marketplaceId),
+];
+
+/**
+ * Plugin install specs to update during `upgrade` — includes curdx-flow
+ * itself plus every recommended plugin.
+ */
+export const PLUGINS_TO_UPDATE = [
+  "curdx-flow@curdx-flow-marketplace",
+  ...RECOMMENDED_PLUGINS.map((p) => p.installSpec),
+];

package/cli/uninstall.js

@@ -4,6 +4,7 @@
 
 import { existsSync, lstatSync, unlinkSync, rmSync, readlinkSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 import {
   color,
@@ -15,18 +16,15 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
 
-const HOME = process.env.HOME || "";
+const HOME = homedir();
 
-// Keep aligned with install.js
-const RECOMMENDED = [
-  { name: "pua", uninstallSpec: "pua@pua-skills" },
-  { name: "claude-mem", uninstallSpec: "claude-mem@thedotmack" },
-  {
-    name: "frontend-design",
-    uninstallSpec: "frontend-design@claude-plugins-official",
-  },
-];
+// Pull uninstall-relevant subset from the single registry. See registry.js.
+const RECOMMENDED = RECOMMENDED_PLUGINS.map(({ name, uninstallSpec }) => ({
+  name,
+  uninstallSpec,
+}));
 
 // Symlinks created by install.js (only cleaned with --purge)
 const MANAGED_SYMLINKS = [
@@ -116,7 +114,7 @@ export async function uninstall(args = []) {
       for (const name of toRemove) {
         const rec = presentRecs.find((r) => r.name === name);
         log.blank();
-        console.log(`  ${color.cyan("⏳")} Uninstalling ${color.bold(rec.name)}...`);
+        console.log(`  ${color.cyan("▸")} Uninstalling ${color.bold(rec.name)}...`);
         const r = await run(
           "claude",
           ["plugin", "uninstall", rec.uninstallSpec],

package/cli/upgrade.js

@@ -3,13 +3,10 @@
  */
 
 import { color, log, run, listPlugins, claudeVersion } from "./utils.js";
-
-const PLUGINS_TO_UPDATE = [
-  "curdx-flow@curdx-flow-marketplace",
-  "pua@pua-skills",
-  "claude-mem@thedotmack",
-  "frontend-design@claude-plugins-official",
-];
+import {
+  PLUGINS_TO_UPDATE,
+  MARKETPLACES_TO_REFRESH,
+} from "./registry.js";
 
 export async function upgrade(args = []) {
   log.title("⬆️  CurDX-Flow upgrade");
@@ -19,10 +16,9 @@ export async function upgrade(args = []) {
     process.exit(1);
   }
 
-  // Refresh marketplaces first
+  // Refresh marketplaces first (derived from cli/registry.js)
   log.step(1, 2, "Refreshing marketplaces...");
-  const marketplaces = ["curdx-flow-marketplace", "pua", "thedotmack"];
-  for (const mp of marketplaces) {
+  for (const mp of MARKETPLACES_TO_REFRESH) {
     const r = await run(
       "claude",
       ["plugin", "marketplace", "update", mp],