@curdx/flow 2.1.0 → 2.2.3

package/cli/doctor.js

@@ -8,6 +8,7 @@ import {
 } from "./utils.js";
 import { buildDoctorReport } from "./lib/doctor-report.js";
 import {
+  applyDoctorFixes,
   collectDoctorData,
   createDoctorContext,
   printDoctorSummary,
@@ -21,6 +22,13 @@ export async function doctor(args = []) {
   log.title("🏥 CurdX-Flow Health Check");
 
   const doctorData = await collectDoctorData();
+  if (context.fix) {
+    log.info("Applying safe fixes...");
+    const fixes = await applyDoctorFixes(doctorData);
+    if (fixes.length === 0) {
+      log.info("No automatic fixes available for the current environment");
+    }
+  }
   const report = buildDoctorReport(doctorData);
 
   renderReportLines(report.lines);

package/cli/help.js

@@ -17,6 +17,8 @@ ${color.bold("COMMANDS")}
                              when the plugin body is bundled)
 
   ${color.cyan("doctor")}    Check health (claude CLI, plugin, MCPs, recommended)
+            --fix            Apply safe runtime fixes (bun/uv PATH symlinks)
+            --verbose        Show raw plugin list details
 
   ${color.cyan("upgrade")}   Update curdx-flow and recommended plugins to latest
 

package/cli/install-companions.js

@@ -11,6 +11,9 @@
  *   install-context7-config.js    — context7 API-key prompt (private to required)
  */
 
-export { installRequiredPlugins } from "./install-required-plugins.js";
+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-required-plugins.js

@@ -8,15 +8,28 @@ import { REQUIRED_PLUGINS } from "./registry.js";
 import { color, log, resultLastLine } from "./utils.js";
 import { installContext7Config } from "./install-context7-config.js";
 
-export async function installRequiredPlugins({ yes, language, config }) {
-  log.blank();
-  log.info("Installing required Claude Code plugins...");
+export async function addRequiredPluginMarketplaces({ logWarnings = true } = {}) {
   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")) {
+    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) {

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.

package/cli/lib/claude.js

@@ -14,20 +14,51 @@ export function claudeVersion() {
   return m ? m[1] : res.stdout.trim().split("\n")[0];
 }
 
+function normalizePluginError(error) {
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    return error.message || error.code || JSON.stringify(error);
+  }
+  return String(error);
+}
+
+export function parsePluginListJson(output) {
+  const trimmed = String(output || "").trim();
+  if (!trimmed.startsWith("[")) {
+    return null;
+  }
+
+  const arr = JSON.parse(trimmed);
+  return arr.map((p) => {
+    const id = String(p.id || p.name || "");
+    const errors = Array.isArray(p.errors)
+      ? p.errors.map(normalizePluginError).filter(Boolean)
+      : [];
+    const enabled = p.enabled !== false;
+
+    return {
+      id,
+      name: id.split("@")[0],
+      marketplaceId: id.split("@")[1] || undefined,
+      version: p.version,
+      status: errors.length > 0 ? "failed" : enabled ? "enabled" : "disabled",
+      scope: p.scope,
+      errors,
+      raw: JSON.stringify(p),
+    };
+  });
+}
+
 export function listPlugins() {
   const j = runSync("claude", ["plugin", "list", "--json"]);
-  if (j.code === 0 && j.stdout.trim().startsWith("[")) {
+  if (j.code === 0) {
     try {
-      const arr = JSON.parse(j.stdout);
-      return arr.map((p) => ({
-        id: String(p.id || ""),
-        name: String(p.id || "").split("@")[0],
-        marketplaceId: String(p.id || "").split("@")[1] || undefined,
-        version: p.version,
-        status: p.enabled === false ? "disabled" : "enabled",
-        scope: p.scope,
-        raw: JSON.stringify(p),
-      }));
+      const plugins = parsePluginListJson(j.stdout);
+      if (plugins) {
+        return plugins;
+      }
     } catch {
       // JSON parse failed; fall through to legacy text parser.
     }

package/cli/lib/doctor-report.js

@@ -4,6 +4,117 @@ import {
   findPluginByRegistryEntry,
   hasMarketplace,
 } from "./claude.js";
+import { isVersionAtLeast } from "./semver.js";
+
+export const MIN_CLAUDE_VERSION = "2.1.110";
+
+function pluginErrorDetails(plugin) {
+  return Array.isArray(plugin?.errors) ? plugin.errors : [];
+}
+
+function projectSettingsWarningDetails(warning) {
+  if (warning?.scope === "local") {
+    if (warning.kind === "invalid-local-setting") {
+      return [
+        "settings.local.json is the highest-precedence repo-scoped settings surface on this machine",
+        "fix the JSON shape or remove the local override if Claude behaves unexpectedly",
+      ];
+    }
+
+    if (warning.kind === "required-plugin-disabled") {
+      return [
+        "settings.local.json overrides project and user plugin preferences on this machine",
+        "remove the false entry or enable the required companion plugin locally",
+      ];
+    }
+
+    if (warning.kind === "flow-runtime-blocker") {
+      return [
+        "settings.local.json has higher precedence than .claude/settings.json and can break CurDX-Flow only on this machine",
+        "remove the local blocker or add explicit exceptions for curdx-flow workflows",
+      ];
+    }
+
+    return [
+      "settings.local.json overrides shared project settings on this machine",
+      "fix or remove the local override if Claude behaves differently from the rest of the team",
+    ];
+  }
+
+  if (!warning?.kind) {
+    return [
+      "project settings are shared with collaborators",
+      "prefer deny rules for .env/secrets and avoid bypassPermissions defaults",
+    ];
+  }
+
+  if (warning.kind === "ignored-project-setting" || warning.kind === "managed-only-setting") {
+    return [
+      "Claude Code will ignore this at project scope or only honor it from managed settings",
+      "move it to user settings, settings.local.json, or managed settings as appropriate",
+    ];
+  }
+
+  if (warning.kind === "invalid-project-setting") {
+    return [
+      "Claude Code expects this setting to follow the official settings.json shape",
+      "fix the value shape or remove the key from shared project settings",
+    ];
+  }
+
+  if (warning.kind === "required-plugin-disabled") {
+    return [
+      "project enabledPlugins has higher precedence than user plugin preferences",
+      "remove the false entry or enable the required companion plugin for this project",
+    ];
+  }
+
+  if (
+    warning.kind === "shared-script-setting" ||
+    warning.kind === "shared-env-setting" ||
+    warning.kind === "shared-mcp-auto-approve" ||
+    warning.kind === "shared-hook-policy" ||
+    warning.kind === "shared-sandbox-policy"
+  ) {
+    return [
+      "project settings are shared with collaborators",
+      "avoid shared settings that run scripts, inject env vars, narrow hooks, or change sandbox behavior for every collaborator",
+    ];
+  }
+
+  if (warning.kind === "skill-shell-disabled") {
+    return [
+      "Claude Code replaces inline skill shell output with a disabled placeholder when this policy is active",
+      "keep it only if your team intentionally bans dynamic shell-backed skill content",
+    ];
+  }
+
+  if (warning.kind === "low-effort-project-setting") {
+    return [
+      "project effortLevel applies to main-thread planning and review turns",
+      "prefer high/xhigh for CurDX-Flow planning and verification-heavy workflows",
+    ];
+  }
+
+  if (warning.kind === "flow-runtime-blocker") {
+    return [
+      "CurDX-Flow relies on Claude Code hooks, Agent dispatch, AskUserQuestion, Monitor plus Bash/Read/Edit tooling, and sonnet/opus model aliases",
+      "move restrictive policy to a narrower scope or add explicit exceptions for curdx-flow workflows",
+    ];
+  }
+
+  if (warning.kind === "deprecated-setting") {
+    return [
+      "deprecated settings are still accepted for compatibility but should be migrated",
+      "prefer the current official replacement before the old key is removed",
+    ];
+  }
+
+  return [
+    "project settings are shared with collaborators",
+    "prefer deny rules for .env/secrets and avoid bypassPermissions defaults",
+  ];
+}
 
 export function buildDoctorReport({
   claudeVersionValue,
@@ -13,8 +124,12 @@ export function buildDoctorReport({
   mcps = [],
   userMcpConfig,
   runtimeStatus,
+  runtimeEnvironment,
   cwd,
   projectState,
+  projectMcpConfig,
+  projectTeamConfig,
+  projectClaudeSettings,
 }) {
   const lines = [];
   const sections = [];
@@ -37,6 +152,17 @@ export function buildDoctorReport({
 
   if (claudeVersionValue) {
     pushLine(lines, "ok", `claude CLI            ${claudeVersionValue}`);
+    if (!isVersionAtLeast(claudeVersionValue, MIN_CLAUDE_VERSION)) {
+      pushLine(
+        lines,
+        "warn",
+        `claude CLI            ${claudeVersionValue} below recommended ${MIN_CLAUDE_VERSION}`,
+        [
+          "curdx-flow uses modern Claude Code plugin dependency resolution and plugin bin/ PATH support",
+          "run: claude update",
+        ]
+      );
+    }
   } else {
     pushLine(lines, "err", "claude CLI            not found (install Claude Code)");
   }
@@ -47,7 +173,12 @@ export function buildDoctorReport({
     if (curdx.status === "enabled") {
       pushLine(lines, "ok", `curdx-flow            v${curdx.version} (enabled)`);
     } else {
-      pushLine(lines, "err", `curdx-flow            v${curdx.version} (${curdx.status})`);
+      pushLine(
+        lines,
+        "err",
+        `curdx-flow            v${curdx.version} (${curdx.status})`,
+        pluginErrorDetails(curdx)
+      );
     }
   } else {
     pushLine(lines, "warn", "curdx-flow            not installed → run curdx-flow install");
@@ -67,7 +198,12 @@ export function buildDoctorReport({
     if (plugin && plugin.status === "enabled") {
       pushSectionLine(requiredSection, "ok", `${entry.name.padEnd(22)} v${plugin.version || "unknown"}`);
     } else if (plugin && plugin.status === "failed") {
-      pushSectionLine(requiredSection, "err", `${entry.name.padEnd(22)} load failed`);
+      pushSectionLine(
+        requiredSection,
+        "err",
+        `${entry.name.padEnd(22)} load failed`,
+        pluginErrorDetails(plugin)
+      );
     } else {
       pushSectionLine(
         requiredSection,
@@ -120,7 +256,12 @@ export function buildDoctorReport({
       pushSectionLine(recommendedSection, "ok", `${entry.name.padEnd(22)} v${plugin.version}`);
       if (entry.postInstall === "claude-mem-runtimes") claudeMemEnabled = true;
     } else if (plugin && plugin.status === "failed") {
-      pushSectionLine(recommendedSection, "err", `${entry.name.padEnd(22)} load failed`);
+      pushSectionLine(
+        recommendedSection,
+        "err",
+        `${entry.name.padEnd(22)} load failed`,
+        pluginErrorDetails(plugin)
+      );
     } else {
       pushSectionLine(
         recommendedSection,
@@ -133,16 +274,22 @@ export function buildDoctorReport({
 
   const duplicates = findDuplicateMcps(mcps, userMcpConfig);
   if (duplicates.length > 0) {
-    const duplicateSection = createSection("Legacy plugin-bundled MCPs still present:");
+    const duplicateSection = createSection("Duplicate MCP registrations:");
     for (const duplicate of duplicates) {
+      const details = duplicate.pluginEntry.plugin === "curdx-flow"
+        ? [
+          "migration: claude plugin update curdx-flow@curdx-flow-marketplace",
+          "then restart Claude Code",
+        ]
+        : [
+          `remove the duplicate user-level server if plugin:${duplicate.pluginEntry.plugin} should own it`,
+          `run: claude mcp remove --scope user ${duplicate.name}`,
+        ];
       pushSectionLine(
         duplicateSection,
         "warn",
         `${duplicate.name.padEnd(22)} both user-level AND plugin:${duplicate.pluginEntry.plugin} active`,
-        [
-          "migration: claude plugin update curdx-flow@curdx-flow-marketplace",
-          "then restart Claude Code",
-        ]
+        details
       );
     }
   }
@@ -152,6 +299,16 @@ export function buildDoctorReport({
     for (const [name, status] of Object.entries(runtimeStatus)) {
       if (status.status === "ok") {
         pushSectionLine(runtimeSection, "ok", `${name.padEnd(22)} visible on PATH`);
+      } else if (status.status === "linkable") {
+        pushSectionLine(
+          runtimeSection,
+          "warn",
+          `${name.padEnd(22)} installed but not on PATH`,
+          [
+            `detected at ${status.path}`,
+            "run: npx @curdx/flow doctor --fix",
+          ]
+        );
       } else if (status.status === "linked") {
         pushSectionLine(runtimeSection, "ok", `${name.padEnd(22)} auto-linked ${status.link} → ${status.path}`);
       } else if (status.status === "missing") {
@@ -167,12 +324,27 @@ export function buildDoctorReport({
           runtimeSection,
           "err",
           `${name.padEnd(22)} installed but not on PATH`,
-          [`add export PATH="${dir}:$PATH" to your shell rc`]
+          [
+            `add export PATH="${dir}:$PATH" to your shell rc`,
+            "then rerun: npx @curdx/flow doctor",
+          ]
         );
       }
     }
   }
 
+  if (runtimeEnvironment?.entries?.length > 0) {
+    const runtimeEnvSection = createSection("Runtime environment:");
+    for (const entry of runtimeEnvironment.entries) {
+      pushSectionLine(
+        runtimeEnvSection,
+        entry.level || "info",
+        entry.text,
+        entry.details || []
+      );
+    }
+  }
+
   const localProjectSection = createSection("Local project:");
   if (projectState?.exists) {
     pushSectionLine(localProjectSection, "ok", `.flow/                ${cwd}`);
@@ -185,5 +357,127 @@ export function buildDoctorReport({
     pushSectionLine(localProjectSection, "info", ".flow/                not a curdx-flow project (run: curdx-flow init)");
   }
 
+  const projectMcpSection = createSection("Project MCP config:");
+  if (projectMcpConfig?.misplacedExists) {
+    pushSectionLine(
+      projectMcpSection,
+      projectMcpConfig.exists ? "warn" : "err",
+      `.claude/.mcp.json      ignored by Claude Code`,
+      [
+        "project MCP config must live at repo root as .mcp.json",
+        "move .claude/.mcp.json → .mcp.json, then reopen /mcp or rerun doctor",
+      ]
+    );
+  }
+
+  if (projectMcpConfig?.exists) {
+    if (projectMcpConfig.invalid) {
+      pushSectionLine(
+        projectMcpSection,
+        "err",
+        `.mcp.json            invalid JSON`,
+        [
+          projectMcpConfig.parseError,
+          "fix the JSON syntax, then run /mcp or npx @curdx/flow doctor again",
+        ]
+      );
+    } else if (projectMcpConfig.shapeError) {
+      pushSectionLine(
+        projectMcpSection,
+        "err",
+        `.mcp.json            unsupported shape`,
+        [
+          projectMcpConfig.shapeError,
+          'expected: { "mcpServers": { "<name>": { ... } } }',
+        ]
+      );
+    } else {
+      pushSectionLine(
+        projectMcpSection,
+        "ok",
+        `.mcp.json            ${projectMcpConfig.serverCount} server(s) declared`
+      );
+
+      for (const warning of projectMcpConfig.relativePathWarnings || []) {
+        pushSectionLine(
+          projectMcpSection,
+          "warn",
+          `${warning.serverName.padEnd(22)} relative path in ${warning.field}`,
+          [
+            `value: ${warning.value}`,
+            "Claude Code resolves relative MCP paths against the launch directory, not .mcp.json",
+            "use an absolute path or a PATH executable such as npx / uvx",
+            "debug: claude --debug mcp",
+          ]
+        );
+      }
+    }
+  } else if (!projectMcpConfig?.misplacedExists) {
+    pushSectionLine(projectMcpSection, "info", ".mcp.json            not present");
+  }
+
+  const projectTeamsSection = createSection("Project agent teams:");
+  if (projectTeamConfig?.exists) {
+    pushSectionLine(
+      projectTeamsSection,
+      "warn",
+      `.claude/teams/teams.json ignored by Claude Code`,
+      [
+        "official agent-teams docs say project directories do not have a recognized team config surface",
+        "remove the file or move team configuration to the supported user-level agent-teams runtime",
+      ]
+    );
+  } else {
+    pushSectionLine(projectTeamsSection, "info", ".claude/teams/teams.json not present");
+  }
+
+  const projectSettingsSection = createSection("Project Claude settings:");
+  if (projectClaudeSettings?.exists) {
+    if (projectClaudeSettings.invalid) {
+      pushSectionLine(
+        projectSettingsSection,
+        "err",
+        `.claude/settings.json invalid JSON`,
+        [projectClaudeSettings.parseError]
+      );
+    } else if ((projectClaudeSettings.warnings || []).length > 0) {
+      pushSectionLine(projectSettingsSection, "warn", ".claude/settings.json needs review");
+      for (const warning of projectClaudeSettings.warnings) {
+        pushSectionLine(
+          projectSettingsSection,
+          "warn",
+          warning.message,
+          projectSettingsWarningDetails(warning)
+        );
+      }
+    } else {
+      pushSectionLine(projectSettingsSection, "ok", ".claude/settings.json conservative");
+    }
+  } else {
+    pushSectionLine(projectSettingsSection, "info", ".claude/settings.json not present");
+  }
+
+  if (projectClaudeSettings?.localExists) {
+    pushSectionLine(projectSettingsSection, "info", ".claude/settings.local.json present (local overrides)");
+    if (projectClaudeSettings.localInvalid) {
+      pushSectionLine(
+        projectSettingsSection,
+        "err",
+        ".claude/settings.local.json invalid JSON",
+        [projectClaudeSettings.localParseError]
+      );
+    } else if ((projectClaudeSettings.localWarnings || []).length > 0) {
+      pushSectionLine(projectSettingsSection, "warn", ".claude/settings.local.json affects the local runtime");
+      for (const warning of projectClaudeSettings.localWarnings) {
+        pushSectionLine(
+          projectSettingsSection,
+          "warn",
+          warning.message,
+          projectSettingsWarningDetails(warning)
+        );
+      }
+    }
+  }
+
   return { lines, sections, errors, warnings };
 }