@curdx/flow 2.0.0-beta.8 → 2.0.0

package/cli/protocols.js

@@ -5,43 +5,41 @@
  * 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";
+import { fileURLToPath } from "node:url";
+
+// 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 =
   "<!-- BEGIN curdx-flow protocols (auto-managed; do not edit between sentinels) -->";
 const SENTINEL_END = "<!-- END curdx-flow protocols -->";
 
-// Protocol block is itself in English — it's instructions for the model,
-// not user-facing prose. User chat output is still Chinese per the rule below.
-const PROTOCOL_BODY = `
-## Global Protocols (curdx-flow)
-
-All operations MUST strictly follow these system constraints:
-
-### Language separation
-- **Tool / persistence layer = English**: commit messages, code, comments, file names, function names, PR descriptions, CLI log output, error messages thrown by code, and any artifact persisted to the repository or shown in a developer terminal.
-- **Conversational layer = Simplified Chinese**: chat replies, explanations and reasoning shown directly to the human in a conversation interface (e.g. Claude Code chat).
-
-Rationale: English in the persistence/tool layer aligns with developer-tool industry norms (npm/git/cargo are all English) and keeps the codebase internationally collaborable. Chinese in the conversational layer matches the user's language preference. Mixing the two (e.g. Chinese commit messages, Chinese CLI log output) is a violation.
-
-### Discovery & reasoning
-- **Library / framework / API questions**: query \`context7\` MCP first. Do not rely on training memory.
-- **Planning / design / architecture review / epic decomposition**: use \`sequential-thinking\` MCP with at least 5 thoughts.
-- **Cross-session memory**: query \`claude-mem\` MCP at task start when available.
-
-### Three red lines (inherited from pua)
-1. **Closed loop**: claiming "done"? Provide evidence (build output / passing tests / curl result).
-2. **Fact-driven**: before saying "probably an env issue", verify it. Unverified attribution = blame-shifting.
-3. **Exhaust everything**: before saying "I cannot", complete the systematic 4-stage debugging.
-
-> Source: curdx-flow CLI installer (\`curdx-flow install\`). Remove with: \`curdx-flow uninstall --purge\`.
-`;
+// Protocol body lives in a sibling markdown file so it keeps markdown tooling
+// (preview, lint, prettier) and avoids backtick-escaping noise inside a JS
+// template literal. The body itself is English — it's instructions for the
+// model, not user-facing prose.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROTOCOL_BODY = readFileSync(
+  join(__dirname, "protocols-body.md"),
+  "utf-8"
+).trim();
 
-const FULL_BLOCK = `${SENTINEL_BEGIN}\n${PROTOCOL_BODY.trim()}\n${SENTINEL_END}`;
+const FULL_BLOCK = `${SENTINEL_BEGIN}\n${PROTOCOL_BODY}\n${SENTINEL_END}`;
 
 /**
  * Read existing CLAUDE.md content; return "" if missing.
@@ -53,16 +51,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 +119,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 +130,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 +157,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,123 @@
+/**
+ * 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     → marketplaceSource + installSpec + hint (+ optional postInstall)
+ *   - uninstall.js   → uninstallSpec + uninstallArgs + marketplaceId
+ *   - upgrade.js     → updateSpec + marketplaceId
+ *   - doctor.js      → id + installSpec (for health checks and recovery hints)
+ */
+
+export const RECOMMENDED_PLUGINS = [
+  {
+    name: "pua",
+    id: "pua@pua-skills",
+    marketplaceSource: "tanweai/pua",
+    marketplaceId: "pua-skills",
+    installSpec: "pua@pua-skills",
+    uninstallSpec: "pua@pua-skills",
+    updateSpec: "pua@pua-skills",
+    scope: "user",
+    hint: "no-give-up + three red lines",
+  },
+  {
+    name: "claude-mem",
+    id: "claude-mem@thedotmack",
+    marketplaceSource: "thedotmack/claude-mem",
+    marketplaceId: "thedotmack",
+    installSpec: "claude-mem@thedotmack",
+    uninstallSpec: "claude-mem@thedotmack",
+    updateSpec: "claude-mem@thedotmack",
+    uninstallArgs: ["--keep-data"],
+    scope: "user",
+    hint: "automatic cross-session memory",
+    postInstall: "claude-mem-runtimes",
+  },
+  {
+    name: "frontend-design",
+    id: "frontend-design@claude-plugins-official",
+    marketplaceSource: "anthropics/claude-plugins-official",
+    marketplaceId: "claude-plugins-official",
+    installSpec: "frontend-design@claude-plugins-official",
+    uninstallSpec: "frontend-design@claude-plugins-official",
+    updateSpec: "frontend-design@claude-plugins-official",
+    scope: "user",
+    hint: "Anthropic official UI skill",
+  },
+  {
+    name: "chrome-devtools-mcp",
+    id: "chrome-devtools-mcp@chrome-devtools-plugins",
+    marketplaceSource: "ChromeDevTools/chrome-devtools-mcp",
+    marketplaceId: "chrome-devtools-plugins",
+    installSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    uninstallSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    updateSpec: "chrome-devtools-mcp@chrome-devtools-plugins",
+    scope: "user",
+    hint: "Chrome DevTools + Puppeteer (Google official)",
+  },
+];
+
+export const REQUIRED_PLUGINS = [
+  {
+    name: "context7-plugin",
+    id: "context7-plugin@context7-marketplace",
+    marketplaceSource: "upstash/context7",
+    marketplaceId: "context7-marketplace",
+    installSpec: "context7-plugin@context7-marketplace",
+    uninstallSpec: "context7-plugin@context7-marketplace",
+    updateSpec: "context7-plugin@context7-marketplace",
+    scope: "user",
+    hint: "official Context7 plugin (MCP + skill + docs-researcher agent + /context7:docs)",
+    requiresConfig: true,
+    configType: "apiKey",
+  },
+];
+
+/**
+ * MCP servers that curdx-flow depends on for its core discipline rules and
+ * still registers directly. Starting beta.12 these are registered at
+ * USER-LEVEL via `claude mcp add` instead of plugin.json bundling, so:
+ *
+ *   - Tool names stay standard (mcp__sequential-thinking__*)
+ *     — matching every agent's and knowledge doc's hardcoded references.
+ *
+ * Context7 is installed via Upstash's official Claude Code plugin instead
+ * of direct `claude mcp add`: context7-plugin@context7-marketplace includes
+ * the MCP server, skill, docs-researcher agent, and /context7:docs command.
+ */
+export const BUNDLED_MCPS = [
+  {
+    name: "sequential-thinking",
+    command: "npx",
+    args: ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+    purpose: "structured reasoning for design / review (L2 Mandatory Tool)",
+    preserveExisting: true,
+  },
+];
+
+/**
+ * Marketplaces to refresh during `upgrade`. Derived from RECOMMENDED_PLUGINS
+ * plus the curdx-flow marketplace itself.
+ */
+export const MARKETPLACES_TO_REFRESH = [
+  "curdx-flow-marketplace",
+  ...REQUIRED_PLUGINS.map((p) => p.marketplaceId),
+  ...RECOMMENDED_PLUGINS.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",
+  ...REQUIRED_PLUGINS.map((p) => p.updateSpec),
+  ...RECOMMENDED_PLUGINS.map((p) => p.updateSpec),
+];

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,25 @@ import {
   listPlugins,
 } from "./utils.js";
 import { removeGlobalProtocols, GLOBAL_CLAUDE_MD } from "./protocols.js";
+import { REQUIRED_PLUGINS, RECOMMENDED_PLUGINS, BUNDLED_MCPS } 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, uninstallArgs, marketplaceId, scope }) => ({
+  name,
+  uninstallSpec,
+  uninstallArgs: uninstallArgs || [],
+  marketplaceId,
+  scope,
+}));
+const REQUIRED = REQUIRED_PLUGINS.map(({ name, uninstallSpec, uninstallArgs, marketplaceId, scope }) => ({
+  name,
+  uninstallSpec,
+  uninstallArgs: uninstallArgs || [],
+  marketplaceId,
+  scope,
+}));
 
 // Symlinks created by install.js (only cleaned with --purge)
 const MANAGED_SYMLINKS = [
@@ -70,7 +78,7 @@ export async function uninstall(args = []) {
   } else {
     const r = await run(
       "claude",
-      ["plugin", "uninstall", "curdx-flow@curdx-flow-marketplace"],
+      ["plugin", "uninstall", "--scope", "user", "curdx-flow@curdx-flow-marketplace"],
       { silent: true }
     );
     if (r.code === 0) {
@@ -116,10 +124,10 @@ 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],
+          ["plugin", "uninstall", "--scope", rec.scope, ...rec.uninstallArgs, rec.uninstallSpec],
           { silent: true }
         );
         if (r.code === 0) {
@@ -133,9 +141,71 @@ export async function uninstall(args = []) {
     }
   }
 
+  // ---------- Step 4.5: optionally remove user-level MCPs ----------
+  // Starting beta.12, the install command registers context7 +
+  // sequential-thinking at user-level (not plugin-bundled). Ask before
+  // removing because the user may have customised args (e.g. --api-key)
+  // or still be using these MCPs outside curdx-flow.
+  log.blank();
+  log.info("Required MCP servers (context7, sequential-thinking)");
+  if (keepRecommended || yes) {
+    log.info(
+      color.dim("--yes or --keep-recommended: keeping user-level MCPs (remove manually with `claude mcp remove <name>`)")
+    );
+  } else {
+    const removeMcps = await confirm(
+      `Remove user-level MCPs registered by install (${BUNDLED_MCPS.map((m) => m.name).join(", ")})? ${color.dim("(keeps them if other tools depend on them)")}`,
+      false
+    );
+    if (removeMcps) {
+      for (const mcp of BUNDLED_MCPS) {
+        const r = await run("claude", ["mcp", "remove", mcp.name], {
+          silent: true,
+        });
+        if (r.code === 0) {
+          log.ok(`  ${mcp.name.padEnd(22)} removed`);
+        } else {
+          log.info(`  ${mcp.name.padEnd(22)} ${color.dim("not present or already removed")}`);
+        }
+      }
+    } else {
+      log.info("Keeping user-level MCPs");
+    }
+  }
+
+  // ---------- Step 4.75: uninstall required companion plugins ----------
+  log.blank();
+  log.info("Required companion plugins");
+  if (yes) {
+    log.info(
+      color.dim("--yes mode: keeping required companion plugins (use --purge to remove them)")
+    );
+  } else {
+    const removeRequired = await confirm(
+      `Remove required companion plugins (${REQUIRED.map((p) => p.name).join(", ")})? ${color.dim("(keeps shared tools available if other workflows depend on them)")}`,
+      false
+    );
+    if (removeRequired) {
+      for (const plugin of REQUIRED) {
+        const r = await run(
+          "claude",
+          ["plugin", "uninstall", "--scope", plugin.scope, ...plugin.uninstallArgs, plugin.uninstallSpec],
+          { silent: true }
+        );
+        if (r.code === 0) {
+          log.ok(`  ${plugin.name.padEnd(22)} uninstalled`);
+        } else {
+          log.info(`  ${plugin.name.padEnd(22)} ${color.dim("not present or already removed")}`);
+        }
+      }
+    } else {
+      log.info("Keeping required companion plugins");
+    }
+  }
+
   // ---------- Step 5: cleanup symlinks (only with --purge) ----------
   log.blank();
-  log.step(3, 4, "Runtime symlinks");
+  log.step(3, 4, "Runtime symlinks and marketplaces");
   if (!purge) {
     log.info(
       color.dim("Keeping ~/.local/bin/bun, ~/.local/bin/uv (use --purge to remove)")
@@ -144,6 +214,27 @@ export async function uninstall(args = []) {
       color.dim("Reason: these bun/uv binaries may be used by other tools — confirm before deleting")
     );
   } else {
+    const marketplaceIds = [
+      ...new Set(
+        RECOMMENDED
+          .concat(REQUIRED)
+          .map((r) => r.marketplaceId)
+          .filter((id) => id && id !== "claude-plugins-official")
+      ),
+    ];
+    for (const marketplaceId of marketplaceIds) {
+      const r = await run(
+        "claude",
+        ["plugin", "marketplace", "remove", marketplaceId],
+        { silent: true }
+      );
+      if (r.code === 0) {
+        log.ok(`Removed marketplace ${marketplaceId}`);
+      } else if (!r.stderr.includes("not found")) {
+        log.warn(`Failed to remove marketplace ${marketplaceId}: ${r.stderr.trim().split("\n").pop()}`);
+      }
+    }
+
     for (const link of MANAGED_SYMLINKS) {
       if (!existsSync(link) && !isBrokenSymlink(link)) {
         continue;

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],
@@ -51,7 +47,7 @@ export async function upgrade(args = []) {
       continue;
     }
 
-    const r = await run("claude", ["plugin", "update", spec], { silent: true });
+    const r = await run("claude", ["plugin", "update", "--scope", "user", spec], { silent: true });
     if (r.code === 0) {
       const updated = r.stdout.includes("updated from");
       if (updated) {