@curdx/flow 2.0.19 → 2.0.21

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.19"
+    "version": "2.0.21"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "curdx-flow",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "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/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to CurdX-Flow will be documented here.
 
+## [2.0.21] - 2026-04-23
+
+### Fixed
+
+- `cli/install-workflow.js` + `cli/install-self-update.js` — after `npm install -g @curdx/flow@latest`, the self-update restart spawned a bare `curdx-flow`, which fails under `npx` (PATH not guaranteed) or when the global bin dir isn't on PATH, surfacing as `sh: curdx-flow: command not found`. `checkAndUpdateSelf` now returns the absolute entry path of the freshly installed package, and the restart re-launches with `process.execPath` + that absolute script path. No PATH dependency, no shell involvement. Two new unit tests assert the spawn contract.
+- `README.zh.md` — corrected the `smart-ralph` credit URL. The previously listed `Nibzard/smart-ralph` 404s; the repo matching the described feature set ("Spec-driven + Ralph Wiggum loop + Claude Code plugin") is `tzachbon/smart-ralph`.
+
 ## [Unreleased]
 
 ### Fixed

package/README.zh.md

@@ -124,7 +124,7 @@ claude --plugin-dir ./curdx-flow
 CurdX-Flow 是蒸馏，不是原创。深深致谢：
 
 - [**andrej-karpathy-skills**](https://github.com/forrestchang/andrej-karpathy-skills) — 4 原则
-- [**smart-ralph**](https://github.com/Nibzard/smart-ralph) — 规格引擎 + stop-hook 循环
+- [**smart-ralph**](https://github.com/tzachbon/smart-ralph) — 规格引擎 + stop-hook 循环
 - [**superpowers**](https://github.com/obra/superpowers) — Subagent 纪律 + TDD + 两阶段审查
 - [**BMAD-METHOD**](https://github.com/bmad-code-org/BMAD-METHOD) — 协作流程 + 对抗审查
 - [**get-shit-done**](https://github.com/ryangentry/get-shit-done) — 波形执行 + 决策锁定 + 多源审计

package/cli/doctor-workflow.js

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  claudeVersion,
+  color,
+  ensureClaudeMemRuntimes,
+  listMcps,
+  listPluginMarketplaces,
+  listPlugins,
+  log,
+  readUserMcpConfig,
+  runSync,
+} from "./utils.js";
+
+export function createDoctorContext(args = []) {
+  return {
+    verbose: args.includes("--verbose") || args.includes("-v"),
+  };
+}
+
+export async function readProjectState(cwd = process.cwd()) {
+  const flowDir = path.join(cwd, ".flow");
+  try {
+    const stat = await fs.stat(flowDir);
+    if (!stat.isDirectory()) {
+      return { exists: false, activeSpec: null };
+    }
+
+    try {
+      const activeSpec = await fs.readFile(path.join(flowDir, ".active-spec"), "utf-8");
+      return { exists: true, activeSpec: activeSpec.trim() };
+    } catch {
+      return { exists: true, activeSpec: null };
+    }
+  } catch {
+    return { exists: false, activeSpec: null };
+  }
+}
+
+export async function collectDoctorData(
+  {
+    cwd = process.cwd(),
+  } = {},
+  {
+    claudeVersionImpl = claudeVersion,
+    listPluginsImpl = listPlugins,
+    listPluginMarketplacesImpl = listPluginMarketplaces,
+    listMcpsImpl = listMcps,
+    readUserMcpConfigImpl = readUserMcpConfig,
+    ensureClaudeMemRuntimesImpl = ensureClaudeMemRuntimes,
+    readProjectStateImpl = readProjectState,
+  } = {}
+) {
+  const claudeVersionValue = claudeVersionImpl();
+  const plugins = claudeVersionValue ? listPluginsImpl() : [];
+  const marketplaces = claudeVersionValue ? listPluginMarketplacesImpl() : [];
+  const mcps = claudeVersionValue ? listMcpsImpl() : [];
+  const userMcpConfig = claudeVersionValue ? readUserMcpConfigImpl() : new Map();
+  const runtimeStatus = plugins.some(
+    (plugin) => plugin.name === "claude-mem" && plugin.status === "enabled"
+  )
+    ? ensureClaudeMemRuntimesImpl()
+    : null;
+
+  return {
+    claudeVersionValue,
+    nodeVersion: process.version,
+    plugins,
+    marketplaces,
+    mcps,
+    userMcpConfig,
+    runtimeStatus,
+    cwd,
+    projectState: await readProjectStateImpl(cwd),
+  };
+}
+
+export function renderReportLines(lines, { logImpl = log } = {}) {
+  for (const line of lines) {
+    if (line.level === "ok") {
+      logImpl.ok(line.text);
+    } else if (line.level === "warn") {
+      logImpl.warn(line.text);
+    } else if (line.level === "err") {
+      logImpl.err(line.text);
+    } else {
+      logImpl.info(line.text);
+    }
+
+    for (const detail of line.details || []) {
+      console.log(color.dim(`     → ${detail}`));
+    }
+  }
+}
+
+export function printDoctorSummary(
+  report,
+  { logImpl = log, exitImpl = process.exit } = {}
+) {
+  console.log();
+  if (report.errors > 0) {
+    console.log(color.red(`Summary: ${report.errors} error(s), ${report.warnings} warning(s)`));
+    console.log(color.dim("Fix errors and re-run curdx-flow doctor"));
+    exitImpl(1);
+    return;
+  }
+
+  if (report.warnings > 0) {
+    console.log(color.yellow(`Summary: ${report.warnings} warning(s). Usable, but worth addressing.`));
+    return;
+  }
+
+  console.log(color.green("Summary: all healthy ✓"));
+}
+
+export function printVerboseDoctorDetails({ runSyncImpl = runSync } = {}) {
+  console.log(`\n${color.bold("Details:")}`);
+  console.log(color.dim("  Plugins raw:"));
+  console.log(runSyncImpl("claude", ["plugin", "list"]).stdout);
+}

package/cli/doctor.js

@@ -2,115 +2,35 @@
  * 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,
-  listPluginMarketplaces,
-  listMcps,
-  ensureClaudeMemRuntimes,
-  readUserMcpConfig,
 } from "./utils.js";
 import { buildDoctorReport } from "./lib/doctor-report.js";
+import {
+  collectDoctorData,
+  createDoctorContext,
+  printDoctorSummary,
+  printVerboseDoctorDetails,
+  renderReportLines,
+} from "./doctor-workflow.js";
 
 export async function doctor(args = []) {
-  const verbose = args.includes("--verbose") || args.includes("-v");
-  const claudeVersionValue = claudeVersion();
-  const plugins = claudeVersionValue ? listPlugins() : [];
-  const marketplaces = claudeVersionValue ? listPluginMarketplaces() : [];
-  const mcps = claudeVersionValue ? listMcps() : [];
-  const userMcpConfig = claudeVersionValue ? readUserMcpConfig() : new Map();
-  const runtimeStatus = plugins.some((plugin) => plugin.name === "claude-mem" && plugin.status === "enabled")
-    ? ensureClaudeMemRuntimes()
-    : null;
+  const context = createDoctorContext(args);
 
   log.title("🏥 CurdX-Flow Health Check");
 
-  const report = buildDoctorReport({
-    claudeVersionValue,
-    nodeVersion: process.version,
-    plugins,
-    marketplaces,
-    mcps,
-    userMcpConfig,
-    runtimeStatus,
-    cwd: process.cwd(),
-    projectState: await readProjectState(),
-  });
+  const doctorData = await collectDoctorData();
+  const report = buildDoctorReport(doctorData);
 
-  renderLines(report.lines);
+  renderReportLines(report.lines);
   for (const section of report.sections) {
     console.log(`\n${color.bold(section.title)}`);
-    renderLines(section.lines);
-  }
-
-  printSummary(report);
-  if (verbose && claudeVersionValue) {
-    printVerboseDetails();
-  }
-}
-
-async function readProjectState() {
-  const cwd = process.cwd();
-  const flowDir = path.join(cwd, ".flow");
-  try {
-    const stat = await fs.stat(flowDir);
-    if (!stat.isDirectory()) {
-      return { exists: false, activeSpec: null };
-    }
-
-    try {
-      const activeSpec = await fs.readFile(path.join(flowDir, ".active-spec"), "utf-8");
-      return { exists: true, activeSpec: activeSpec.trim() };
-    } catch {
-      return { exists: true, activeSpec: null };
-    }
-  } catch {
-    return { exists: false, activeSpec: null };
-  }
-}
-
-function renderLines(lines) {
-  for (const line of lines) {
-    if (line.level === "ok") {
-      log.ok(line.text);
-    } else if (line.level === "warn") {
-      log.warn(line.text);
-    } else if (line.level === "err") {
-      log.err(line.text);
-    } else {
-      log.info(line.text);
-    }
-
-    for (const detail of line.details || []) {
-      console.log(color.dim(`     → ${detail}`));
-    }
+    renderReportLines(section.lines);
   }
-}
 
-function printSummary(report) {
-  console.log();
-  if (report.errors > 0) {
-    console.log(color.red(`Summary: ${report.errors} error(s), ${report.warnings} warning(s)`));
-    console.log(color.dim("Fix errors and re-run curdx-flow doctor"));
-    process.exit(1);
+  printDoctorSummary(report);
+  if (context.verbose && doctorData.claudeVersionValue) {
+    printVerboseDoctorDetails();
   }
-
-  if (report.warnings > 0) {
-    console.log(color.yellow(`Summary: ${report.warnings} warning(s). Usable, but worth addressing.`));
-    return;
-  }
-
-  console.log(color.green("Summary: all healthy ✓"));
-}
-
-function printVerboseDetails() {
-  console.log(`\n${color.bold("Details:")}`);
-  console.log(color.dim("  Plugins raw:"));
-  console.log(runSync("claude", ["plugin", "list"]).stdout);
 }

package/cli/install-curdx-plugin.js

@@ -5,6 +5,46 @@ import {
   removePluginMarketplace,
 } from "./lib/claude-ops.js";
 
+const CURDX_FLOW_INSTALL_ENTRY = {
+  scope: "user",
+  installSpec: "curdx-flow@curdx-flow-marketplace",
+};
+
+export function resolveCurdxFlowInstallPlan({ prevCurdxFlow, shippedVersion }) {
+  if (prevCurdxFlow && shippedVersion && prevCurdxFlow.version === shippedVersion) {
+    return {
+      intro: `curdx-flow already at v${prevCurdxFlow.version}, re-registering...`,
+      success: `curdx-flow re-registered at v${shippedVersion}`,
+    };
+  }
+
+  if (prevCurdxFlow && shippedVersion) {
+    return {
+      intro: `curdx-flow v${prevCurdxFlow.version} → v${shippedVersion}, installing...`,
+      success: `curdx-flow upgraded to v${shippedVersion}`,
+    };
+  }
+
+  if (prevCurdxFlow) {
+    return {
+      intro: `curdx-flow v${prevCurdxFlow.version} detected, re-registering...`,
+      success: "curdx-flow re-registered",
+    };
+  }
+
+  if (shippedVersion) {
+    return {
+      intro: null,
+      success: `curdx-flow v${shippedVersion} installed`,
+    };
+  }
+
+  return {
+    intro: null,
+    success: "curdx-flow installed",
+  };
+}
+
 export async function addCurdxMarketplace({ marketplaceSource, marketplaceLabel, useOffline }) {
   log.blank();
   log.step(2, 5, `Adding curdx-flow marketplace from ${marketplaceLabel}...`);
@@ -24,72 +64,33 @@ export async function addCurdxMarketplace({ marketplaceSource, marketplaceLabel,
   }
 }
 
-export async function installCurdxFlowPlugin({ prevCurdxFlow, shippedVersion }) {
-  log.blank();
-  log.step(3, 5, "Installing curdx-flow plugin...");
+export async function installCurdxFlowPlugin(
+  { prevCurdxFlow, shippedVersion },
+  {
+    installPluginImpl = installPlugin,
+    exitImpl = process.exit,
+    logImpl = log,
+  } = {}
+) {
+  logImpl.blank();
+  logImpl.step(3, 5, "Installing curdx-flow plugin...");
 
   // Use the pre-Step-2 snapshot — by this point `claude plugin marketplace
   // remove` has already evicted the plugin, so listPlugins() here would
   // always return undefined for curdx-flow and we'd mis-report "installed"
   // when we actually upgraded (the bug reported by @wdx's beta.14 log).
-  const already = prevCurdxFlow;
+  const plan = resolveCurdxFlowInstallPlan({ prevCurdxFlow, shippedVersion });
 
-  if (already && shippedVersion && already.version === shippedVersion) {
-    // Step 2 removes and re-adds the marketplace to rebind it to the current
-    // source. Claude Code removes plugins installed from that marketplace as
-    // part of `marketplace remove`, so even a same-version install must be
-    // re-registered here.
-    log.info(
-      `curdx-flow already at v${already.version}, re-registering...`
-    );
-    const r = await installPlugin({
-      scope: "user",
-      installSpec: "curdx-flow@curdx-flow-marketplace",
-    });
-    if (r.code !== 0) {
-      log.err(`Install failed: ${resultOutput(r)}`);
-      process.exit(1);
-    }
-    log.ok(`curdx-flow re-registered at v${shippedVersion}`);
-  } else if (already && shippedVersion) {
-    log.info(
-      `curdx-flow v${already.version} → v${shippedVersion}, installing...`
-    );
-    const r = await installPlugin({
-      scope: "user",
-      installSpec: "curdx-flow@curdx-flow-marketplace",
-    });
-    if (r.code !== 0) {
-      log.err(`Install failed: ${resultOutput(r)}`);
-      process.exit(1);
-    }
-    log.ok(`curdx-flow upgraded to v${shippedVersion}`);
-  } else if (already) {
-    log.info(
-      `curdx-flow v${already.version} detected, re-registering...`
-    );
-    const r = await installPlugin({
-      scope: "user",
-      installSpec: "curdx-flow@curdx-flow-marketplace",
-    });
-    if (r.code !== 0) {
-      log.err(`Install failed: ${resultOutput(r)}`);
-      process.exit(1);
-    }
-    log.ok("curdx-flow re-registered");
-  } else {
-    const r = await installPlugin({
-      scope: "user",
-      installSpec: "curdx-flow@curdx-flow-marketplace",
-    });
-    if (r.code !== 0) {
-      log.err(`Install failed: ${resultOutput(r)}`);
-      process.exit(1);
-    }
-    if (shippedVersion) {
-      log.ok(`curdx-flow v${shippedVersion} installed`);
-    } else {
-      log.ok("curdx-flow installed");
-    }
+  if (plan.intro) {
+    logImpl.info(plan.intro);
+  }
+
+  const result = await installPluginImpl(CURDX_FLOW_INSTALL_ENTRY);
+  if (result.code !== 0) {
+    logImpl.err(`Install failed: ${resultOutput(result)}`);
+    exitImpl(1);
+    return;
   }
+
+  logImpl.ok(plan.success);
 }

package/cli/install-self-update.js

@@ -3,6 +3,98 @@ import { join } from "node:path";
 
 import { log, run, runSync, VERSION } from "./utils.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;
+}
+
 /**
  * Check for CLI updates and auto-update if available.
  * @returns {Promise<{updated: boolean, version?: string}>}
@@ -31,9 +123,7 @@ export async function checkAndUpdateSelf() {
       return { updated: false };
     }
 
-    // Existing behavior used simple string comparison; keep it unchanged for
-    // this structural refactor.
-    if (latestVersion > currentVersion) {
+    if (isVersionNewer(latestVersion, currentVersion)) {
       log.info(`New version available: v${currentVersion} → v${latestVersion}`);
       log.info("Updating CLI...");
 
@@ -43,7 +133,11 @@ export async function checkAndUpdateSelf() {
 
       if (updateRes.code === 0) {
         log.ok(`CLI updated to v${latestVersion}`);
-        return { updated: true, version: latestVersion };
+        return {
+          updated: true,
+          version: latestVersion,
+          entryPath: join(installedPath, "bin", "curdx-flow.js"),
+        };
       }
 
       log.warn("CLI update failed, continuing with current version");