@curdx/flow 2.0.21 → 2.2.0

package/cli/install-companions.js

@@ -1,252 +1,19 @@
-import {
-  color,
-  ensureClaudeMemRuntimes,
-  listPlugins,
-  log,
-  multiselectClack,
-  note,
-  resultLastLine,
-  text,
-  writeConfig,
-} from "./utils.js";
-import { BUNDLED_MCPS, RECOMMENDED_PLUGINS, REQUIRED_PLUGINS } from "./registry.js";
-import { readUserMcpConfig } from "./utils.js";
-import {
-  addMcp,
-  addPluginMarketplace,
-  installPlugin,
-  removeMcp,
-} from "./lib/claude-ops.js";
-
-const RECOMMENDED = RECOMMENDED_PLUGINS;
-const CONTEXT7_COMMAND = "npx";
-const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
-
-export async function installRequiredPlugins({ yes, language, config }) {
-  log.blank();
-  log.info("Installing required Claude Code plugins...");
-  for (const plugin of REQUIRED_PLUGINS) {
-    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
-    const ma = await addPluginMarketplace(plugin);
-    if (ma.code !== 0 && !ma.stderr.includes("already")) {
-      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
-    }
-
-    const ir = await installPlugin(plugin);
-    if (ir.code === 0) {
-      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
-
-      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
-        await promptPluginConfig(plugin, language, config);
-      }
-    } else {
-      console.log(
-        `  ${color.red("✗")} ${plugin.name} install failed: ${resultLastLine(ir)}`
-      );
-      console.log(
-        color.dim(
-          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
-        )
-      );
-      console.log(
-        color.dim(
-          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
-        )
-      );
-    }
-  }
-}
-
-export async function registerBundledMcps() {
-  log.blank();
-  log.info("Registering required MCP servers (user-level)...");
-  const existingUserMcps = readUserMcpConfig();
-  for (const mcp of BUNDLED_MCPS) {
-    if (mcp.preserveExisting && existingUserMcps.has(mcp.name)) {
-      const existing = existingUserMcps.get(mcp.name);
-      log.info(
-        `  ${mcp.name.padEnd(22)} ${color.dim(`already registered (${(existing.args || []).join(" ")}) — preserving`)}`
-      );
-      continue;
-    }
-    const r = await addMcp(mcp);
-    if (r.code === 0) {
-      log.ok(`  ${mcp.name.padEnd(22)} ${color.dim("registered")}`);
-    } else if (r.stderr.includes("already exists")) {
-      log.info(`  ${mcp.name.padEnd(22)} ${color.dim("already exists — skipped")}`);
-    } else {
-      log.warn(
-        `  ${mcp.name.padEnd(22)} registration failed: ${resultLastLine(r)}`
-      );
-      log.info(
-        `     Run manually: claude mcp add --scope user ${mcp.name} -- ${mcp.command} ${mcp.args.join(" ")}`
-      );
-    }
-  }
-}
-
-export async function installRecommendedPlugins({ all, yes, language }) {
-  log.blank();
-  log.step(4, 5, "Recommended plugins");
-
-  let toInstall;
-  if (all) {
-    toInstall = RECOMMENDED.map((r) => r.name);
-    log.info("--all mode: installing all recommended");
-  } else if (yes) {
-    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
-    toInstall = RECOMMENDED
-      .filter((r) => !currentlyInstalled.has(r.name))
-      .map((r) => r.name);
-    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
-  } else {
-    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
-    const options = RECOMMENDED.map((r) => ({
-      value: r.name,
-      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
-      hint: r.hint,
-    }));
-    const initialValues = RECOMMENDED.map((r) => r.name);
-
-    toInstall = await multiselectClack({
-      message: language === "zh"
-        ? "选择要安装的推荐插件（空格切换，回车确认）"
-        : "Select recommended plugins to install (space to toggle, enter to confirm)",
-      options,
-      initialValues,
-      required: false,
-    });
-  }
-
-  if (!toInstall || toInstall.length === 0) {
-    log.info("No recommended plugins selected, skipping");
-    return false;
-  }
-
-  for (const pluginName of toInstall) {
-    const rec = RECOMMENDED.find((r) => r.name === pluginName);
-    log.blank();
-    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
-
-    if (rec.marketplaceSource) {
-      const ma = await addPluginMarketplace(rec);
-      if (ma.code !== 0 && !ma.stderr.includes("already")) {
-        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
-      }
-    }
-
-    const ir = await installPlugin(rec);
-    if (ir.code === 0) {
-      console.log(`  ${color.green("✓")} ${rec.name} installed`);
-
-      if (rec.postInstall === "claude-mem-runtimes") {
-        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`)}`
-            );
-          }
-        }
-      }
-    } else {
-      console.log(
-        `  ${color.red("✗")} ${rec.name} install failed: ${resultLastLine(ir)}`
-      );
-      console.log(
-        color.dim(
-          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
-        )
-      );
-    }
-  }
-  return true;
-}
-
-async function promptPluginConfig(plugin, language, config) {
-  if (plugin.name !== "context7-plugin") return;
-
-  log.blank();
-  await note(
-    language === "zh"
-      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
-      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
-    language === "zh" ? "配置 Context7" : "Configure Context7"
-  );
-
-  const apiKey = await text({
-    message: language === "zh"
-      ? "输入你的 Context7 API key（或按 Enter 跳过）"
-      : "Enter your Context7 API key (or press Enter to skip)",
-    placeholder: "ctx7sk-...",
-    validate: (value) => {
-      if (!value) return;
-      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
-        return language === "zh"
-          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
-          : "API key should start with ctx7sk- or ctx7_";
-      }
-    },
-  });
-
-  if (apiKey) {
-    config.context7ApiKey = apiKey;
-    writeConfig(config);
-
-    const r = await addMcp(buildContext7Mcp(apiKey));
-
-    if (r.code === 0) {
-      log.ok(
-        language === "zh"
-          ? "  Context7 API key 已配置"
-          : "  Context7 API key configured"
-      );
-    } else if (r.stderr.includes("already exists")) {
-      await removeMcp({ name: "context7" });
-      const r2 = await addMcp(buildContext7Mcp(apiKey));
-      if (r2.code === 0) {
-        log.ok(
-          language === "zh"
-            ? "  Context7 API key 已更新"
-            : "  Context7 API key updated"
-        );
-      }
-    } else {
-      log.warn(
-        language === "zh"
-          ? `  Context7 MCP 配置失败: ${resultLastLine(r)}`
-          : `  Context7 MCP configuration failed: ${resultLastLine(r)}`
-      );
-      log.info(
-        color.dim(
-          language === "zh"
-            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
-        )
-      );
-    }
-  } else {
-    log.info(
-      language === "zh"
-        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
-        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
-    );
-  }
-}
-
-function buildContext7Mcp(apiKey) {
-  return {
-    name: "context7",
-    env: [`CONTEXT7_API_KEY=${apiKey}`],
-    command: CONTEXT7_COMMAND,
-    args: CONTEXT7_ARGS,
-  };
-}
+/**
+ * Re-export barrel preserving the pre-Stage-7 import surface. New callers
+ * should import directly from the concern-specific modules below instead
+ * of going through this barrel. Kept in place so existing imports in
+ * cli/install.js and cli/install-workflow.js keep working unchanged.
+ *
+ * Concern split (see docs/refactor-plan.md Stage 7):
+ *   install-required-plugins.js   — required Claude Code companion plugins
+ *   install-bundled-mcps.js       — user-level MCP registration
+ *   install-recommended-plugins.js — optional recommended plugins
+ *   install-context7-config.js    — context7 API-key prompt (private to required)
+ */
+
+export {
+  addRequiredPluginMarketplaces,
+  installRequiredPlugins,
+} from "./install-required-plugins.js";
+export { registerBundledMcps } from "./install-bundled-mcps.js";
+export { installRecommendedPlugins } from "./install-recommended-plugins.js";

package/cli/install-context7-config.js

@@ -0,0 +1,97 @@
+/**
+ * Context7 API-key configuration during install. Private to the
+ * required-plugins concern; not re-exported from install-companions.js.
+ */
+
+import { addMcp, removeMcp } from "./lib/claude-ops.js";
+import {
+  color,
+  log,
+  note,
+  resultLastLine,
+  text,
+  writeConfig,
+} from "./utils.js";
+
+const CONTEXT7_COMMAND = "npx";
+const CONTEXT7_ARGS = ["-y", "@upstash/context7-mcp"];
+
+export async function installContext7Config(plugin, language, config) {
+  if (plugin.name !== "context7-plugin") return;
+
+  log.blank();
+  await note(
+    language === "zh"
+      ? "Context7 需要 API key 才能使用。\n获取 API key: https://console.upstash.com/context7"
+      : "Context7 requires an API key to function.\nGet your API key at: https://console.upstash.com/context7",
+    language === "zh" ? "配置 Context7" : "Configure Context7"
+  );
+
+  const apiKey = await text({
+    message: language === "zh"
+      ? "输入你的 Context7 API key（或按 Enter 跳过）"
+      : "Enter your Context7 API key (or press Enter to skip)",
+    placeholder: "ctx7sk-...",
+    validate: (value) => {
+      if (!value) return;
+      if (!value.startsWith("ctx7sk-") && !value.startsWith("ctx7_")) {
+        return language === "zh"
+          ? "API key 应该以 ctx7sk- 或 ctx7_ 开头"
+          : "API key should start with ctx7sk- or ctx7_";
+      }
+    },
+  });
+
+  if (apiKey) {
+    config.context7ApiKey = apiKey;
+    writeConfig(config);
+
+    const r = await addMcp(buildContext7Mcp(apiKey));
+
+    if (r.code === 0) {
+      log.ok(
+        language === "zh"
+          ? "  Context7 API key 已配置"
+          : "  Context7 API key configured"
+      );
+    } else if (r.stderr.includes("already exists")) {
+      await removeMcp({ name: "context7" });
+      const r2 = await addMcp(buildContext7Mcp(apiKey));
+      if (r2.code === 0) {
+        log.ok(
+          language === "zh"
+            ? "  Context7 API key 已更新"
+            : "  Context7 API key updated"
+        );
+      }
+    } else {
+      log.warn(
+        language === "zh"
+          ? `  Context7 MCP 配置失败: ${resultLastLine(r)}`
+          : `  Context7 MCP configuration failed: ${resultLastLine(r)}`
+      );
+      log.info(
+        color.dim(
+          language === "zh"
+            ? `     手动运行: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
+            : `     Run manually: claude mcp add --scope user context7 --env CONTEXT7_API_KEY=${apiKey} -- ${CONTEXT7_COMMAND} ${CONTEXT7_ARGS.join(" ")}`
+        )
+      );
+    }
+  } else {
+    log.info(
+      language === "zh"
+        ? "  跳过 Context7 配置（稍后可运行 curdx-flow install 重新配置）"
+        : "  Skipped Context7 configuration (run curdx-flow install later to reconfigure)"
+    );
+  }
+}
+
+function buildContext7Mcp(apiKey) {
+  return {
+    name: "context7",
+    env: [`CONTEXT7_API_KEY=${apiKey}`],
+    command: CONTEXT7_COMMAND,
+    args: CONTEXT7_ARGS,
+  };
+}

package/cli/install-recommended-plugins.js

@@ -0,0 +1,104 @@
+/**
+ * Install optional recommended companion plugins. List source-of-truth:
+ * cli/registry.js RECOMMENDED_PLUGINS. Handles --all / --yes / interactive
+ * multiselect and the claude-mem bun/uv PATH symlink post-install step.
+ */
+
+import { addPluginMarketplace, installPlugin } from "./lib/claude-ops.js";
+import { RECOMMENDED_PLUGINS } from "./registry.js";
+import {
+  color,
+  ensureClaudeMemRuntimes,
+  listPlugins,
+  log,
+  multiselectClack,
+  resultLastLine,
+} from "./utils.js";
+
+const RECOMMENDED = RECOMMENDED_PLUGINS;
+
+export async function installRecommendedPlugins({ all, yes, language }) {
+  log.blank();
+  log.step(4, 5, "Recommended plugins");
+
+  let toInstall;
+  if (all) {
+    toInstall = RECOMMENDED.map((r) => r.name);
+    log.info("--all mode: installing all recommended");
+  } else if (yes) {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    toInstall = RECOMMENDED
+      .filter((r) => !currentlyInstalled.has(r.name))
+      .map((r) => r.name);
+    log.info(`--yes mode: installing ${toInstall.length} recommended plugins`);
+  } else {
+    const currentlyInstalled = new Set(listPlugins().map((p) => p.name));
+    const options = RECOMMENDED.map((r) => ({
+      value: r.name,
+      label: `${r.name}${currentlyInstalled.has(r.name) ? " (installed)" : ""}`,
+      hint: r.hint,
+    }));
+    const initialValues = RECOMMENDED.map((r) => r.name);
+
+    toInstall = await multiselectClack({
+      message: language === "zh"
+        ? "选择要安装的推荐插件（空格切换，回车确认）"
+        : "Select recommended plugins to install (space to toggle, enter to confirm)",
+      options,
+      initialValues,
+      required: false,
+    });
+  }
+
+  if (!toInstall || toInstall.length === 0) {
+    log.info("No recommended plugins selected, skipping");
+    return false;
+  }
+
+  for (const pluginName of toInstall) {
+    const rec = RECOMMENDED.find((r) => r.name === pluginName);
+    log.blank();
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(rec.name)}...`);
+
+    if (rec.marketplaceSource) {
+      const ma = await addPluginMarketplace(rec);
+      if (ma.code !== 0 && !ma.stderr.includes("already")) {
+        log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+      }
+    }
+
+    const ir = await installPlugin(rec);
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${rec.name} installed`);
+
+      if (rec.postInstall === "claude-mem-runtimes") {
+        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`)}`
+            );
+          }
+        }
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${rec.name} install failed: ${resultLastLine(ir)}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin install --scope ${rec.scope} ${rec.installSpec}`
+        )
+      );
+    }
+  }
+  return true;
+}

package/cli/install-required-plugins.js

@@ -0,0 +1,57 @@
+/**
+ * Install required Claude Code companion plugins (today: context7-plugin).
+ * Post-install, dispatches Context7 API-key configuration if applicable.
+ */
+
+import { addPluginMarketplace, installPlugin } from "./lib/claude-ops.js";
+import { REQUIRED_PLUGINS } from "./registry.js";
+import { color, log, resultLastLine } from "./utils.js";
+import { installContext7Config } from "./install-context7-config.js";
+
+export async function addRequiredPluginMarketplaces({ logWarnings = true } = {}) {
+  for (const plugin of REQUIRED_PLUGINS) {
+    const ma = await addPluginMarketplace(plugin);
+    if (ma.code !== 0 && !ma.stderr.includes("already") && logWarnings) {
+      log.warn(`     marketplace add warning: ${ma.stderr.trim().split("\n")[0]}`);
+    }
+  }
+}
+
+export async function installRequiredPlugins({
+  yes,
+  language,
+  config,
+  skipMarketplaceAdd = false,
+}) {
+  log.blank();
+  log.info("Installing required Claude Code plugins...");
+  if (!skipMarketplaceAdd) {
+    await addRequiredPluginMarketplaces();
+  }
+  for (const plugin of REQUIRED_PLUGINS) {
+    console.log(`  ${color.cyan("▸")} Installing ${color.bold(plugin.name)}...`);
+
+    const ir = await installPlugin(plugin);
+    if (ir.code === 0) {
+      console.log(`  ${color.green("✓")} ${plugin.name} installed`);
+
+      if (plugin.requiresConfig && plugin.configType === "apiKey" && !yes) {
+        await installContext7Config(plugin, language, config);
+      }
+    } else {
+      console.log(
+        `  ${color.red("✗")} ${plugin.name} install failed: ${resultLastLine(ir)}`
+      );
+      console.log(
+        color.dim(
+          `     Run manually: claude plugin marketplace add --scope ${plugin.scope} ${plugin.marketplaceSource}`
+        )
+      );
+      console.log(
+        color.dim(
+          `     Then: claude plugin install --scope ${plugin.scope} ${plugin.installSpec}`
+        )
+      );
+    }
+  }
+}

package/cli/install-self-update.js

@@ -2,98 +2,9 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 
 import { log, run, runSync, VERSION } from "./utils.js";
+import { compareVersions, isVersionNewer } from "./lib/semver.js";
 
-function normalizeVersionToken(token) {
-  return /^\d+$/.test(token) ? Number(token) : token;
-}
-
-function parseVersion(version) {
-  const normalized = String(version || "").trim().replace(/^v/i, "");
-  const [coreRaw = "0", prereleaseRaw] = normalized.split("-", 2);
-  const core = coreRaw.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const prerelease = prereleaseRaw
-    ? prereleaseRaw.split(/[.-]/).filter(Boolean).map(normalizeVersionToken)
-    : [];
-
-  return { core, prerelease };
-}
-
-function compareIdentifier(left, right) {
-  if (left === right) {
-    return 0;
-  }
-
-  const leftIsNumber = typeof left === "number";
-  const rightIsNumber = typeof right === "number";
-
-  if (leftIsNumber && rightIsNumber) {
-    return left > right ? 1 : -1;
-  }
-
-  if (leftIsNumber) {
-    return -1;
-  }
-
-  if (rightIsNumber) {
-    return 1;
-  }
-
-  return left > right ? 1 : -1;
-}
-
-export function compareVersions(leftVersion, rightVersion) {
-  const left = parseVersion(leftVersion);
-  const right = parseVersion(rightVersion);
-  const coreLength = Math.max(left.core.length, right.core.length);
-
-  for (let index = 0; index < coreLength; index += 1) {
-    const leftPart = left.core[index] ?? 0;
-    const rightPart = right.core[index] ?? 0;
-    if (leftPart !== rightPart) {
-      return leftPart > rightPart ? 1 : -1;
-    }
-  }
-
-  const leftHasPrerelease = left.prerelease.length > 0;
-  const rightHasPrerelease = right.prerelease.length > 0;
-
-  if (!leftHasPrerelease && !rightHasPrerelease) {
-    return 0;
-  }
-
-  if (!leftHasPrerelease) {
-    return 1;
-  }
-
-  if (!rightHasPrerelease) {
-    return -1;
-  }
-
-  const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
-  for (let index = 0; index < prereleaseLength; index += 1) {
-    const leftPart = left.prerelease[index];
-    const rightPart = right.prerelease[index];
-
-    if (leftPart === undefined) {
-      return -1;
-    }
-
-    if (rightPart === undefined) {
-      return 1;
-    }
-
-    const comparison = compareIdentifier(leftPart, rightPart);
-    if (comparison !== 0) {
-      return comparison;
-    }
-  }
-
-  return 0;
-}
-
-export function isVersionNewer(latestVersion, currentVersion) {
-  return compareVersions(latestVersion, currentVersion) > 0;
-}
+export { compareVersions, isVersionNewer };
 
 /**
  * Check for CLI updates and auto-update if available.

package/cli/install.js

@@ -3,6 +3,7 @@
  */
 
 import {
+  addRequiredPluginMarketplaces,
   installRequiredPlugins,
   registerBundledMcps,
 } from "./install-companions.js";
@@ -60,6 +61,11 @@ export async function install(args = []) {
 
   await addCurdxMarketplace(context);
 
+  // Claude Code resolves plugin dependencies during install. Register
+  // required companion marketplaces before installing curdx-flow so its
+  // cross-marketplace dependency on Context7 can be satisfied immediately.
+  await addRequiredPluginMarketplaces({ logWarnings: false });
+
   // ---------- Step 3: Install curdx-flow plugin ----------
   // Read the version the marketplace is shipping so we can decide whether an
   // already-installed plugin needs an update (same name but stale version
@@ -68,7 +74,12 @@ export async function install(args = []) {
   await installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion });
 
   // ---------- Step 3.5: Install required plugins + register user-level MCPs ----------
-  await installRequiredPlugins({ yes: context.yes, language, config });
+  await installRequiredPlugins({
+    yes: context.yes,
+    language,
+    config,
+    skipMarketplaceAdd: true,
+  });
 
   // Beta.12: direct MCPs migrated from plugin.json bundling. See cli/registry.js
   // for the rationale. Context7 now uses Upstash's official plugin instead.