@curdx/flow 2.2.0 → 2.2.4

package/cli/lib/doctor-report.js

@@ -12,6 +12,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,
   nodeVersion,
@@ -20,8 +124,12 @@ export function buildDoctorReport({
   mcps = [],
   userMcpConfig,
   runtimeStatus,
+  runtimeEnvironment,
   cwd,
   projectState,
+  projectMcpConfig,
+  projectTeamConfig,
+  projectClaudeSettings,
 }) {
   const lines = [];
   const sections = [];
@@ -191,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") {
@@ -206,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}`);
@@ -224,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 };
 }

package/cli/lib/doctor-runtime-environment.js

@@ -0,0 +1,196 @@
+const ENV_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max", "auto"];
+const PINNED_MODEL_ENV_FAMILIES = [
+  {
+    modelVar: "ANTHROPIC_DEFAULT_OPUS_MODEL",
+    capsVar: "ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES",
+    label: "Opus",
+  },
+  {
+    modelVar: "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    capsVar: "ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES",
+    label: "Sonnet",
+  },
+  {
+    modelVar: "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    capsVar: "ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES",
+    label: "Haiku",
+  },
+  {
+    modelVar: "ANTHROPIC_CUSTOM_MODEL_OPTION",
+    capsVar: "ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES",
+    label: "Custom model option",
+  },
+];
+
+function envFlagEnabled(value) {
+  if (value === true || value === 1) return true;
+  if (typeof value !== "string") return false;
+  return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+
+function normalizedEnvValue(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function stripExtendedContextSuffix(modelId) {
+  return modelId.replace(/\[1m\]$/i, "");
+}
+
+function looksProviderSpecificModelId(modelId) {
+  const normalized = stripExtendedContextSuffix(modelId);
+  if (normalized.includes(":") || normalized.includes("/")) return true;
+  if (/^(?:us\.)?anthropic\./i.test(normalized)) return true;
+  if (!/^claude-(?:opus|sonnet|haiku)-/i.test(normalized)) return true;
+  return false;
+}
+
+function positiveIntegerFromEnv(value) {
+  const normalized = normalizedEnvValue(value);
+  if (!normalized) return null;
+  if (!/^[0-9]+$/.test(normalized)) return Number.NaN;
+  const parsed = Number(normalized);
+  return parsed > 0 ? parsed : Number.NaN;
+}
+
+export function inspectRuntimeEnvironment(env = process.env) {
+  const entries = [];
+  const inCi = envFlagEnabled(env.CI);
+
+  if (envFlagEnabled(env.CLAUDE_CODE_SIMPLE)) {
+    entries.push({
+      level: "err",
+      text: "CLAUDE_CODE_SIMPLE     enabled (bare/simple mode)",
+      details: [
+        "official docs: this disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md",
+        "CurDX-Flow cannot load correctly in this mode; unset it before launching Claude Code",
+      ],
+    });
+  }
+
+  if (envFlagEnabled(env.CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT)) {
+    entries.push({
+      level: "warn",
+      text: "CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT enabled",
+      details: [
+        "official docs: discovery still works, but Claude runs with the minimal system prompt and collapsed tool descriptions",
+        "CurDX-Flow may still load, but planning/review behavior can degrade versus the normal Claude Code prompt",
+      ],
+    });
+  }
+
+  const effortLevel = normalizedEnvValue(env.CLAUDE_CODE_EFFORT_LEVEL);
+  if (effortLevel && !ENV_EFFORT_LEVELS.includes(effortLevel)) {
+    entries.push({
+      level: "warn",
+      text: `CLAUDE_CODE_EFFORT_LEVEL invalid (${effortLevel})`,
+      details: [
+        `expected one of: ${ENV_EFFORT_LEVELS.join(", ")}`,
+        "invalid effort env values can make sessions harder to reason about; remove or correct it",
+      ],
+    });
+  } else if (effortLevel === "low" || effortLevel === "medium") {
+    entries.push({
+      level: "warn",
+      text: `CLAUDE_CODE_EFFORT_LEVEL ${effortLevel}`,
+      details: [
+        "this takes precedence over /effort and settings effortLevel",
+        "CurDX-Flow planning, verification, and review-heavy turns usually work better at high or xhigh",
+      ],
+    });
+  } else if (effortLevel) {
+    entries.push({
+      level: "info",
+      text: `CLAUDE_CODE_EFFORT_LEVEL ${effortLevel}`,
+      details: [
+        "session effort is pinned through the environment for this process",
+      ],
+    });
+  }
+
+  if (envFlagEnabled(env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS)) {
+    entries.push({
+      level: "info",
+      text: "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled",
+      details: [
+        "official docs: this enables experimental team surfaces such as SendMessage / TeamCreate / TeamDelete",
+        "CurDX-Flow does not depend on these runtime-gated tools, but this explains why teammate features may appear in this session",
+      ],
+    });
+  }
+
+  const syncPluginInstall = envFlagEnabled(env.CLAUDE_CODE_SYNC_PLUGIN_INSTALL);
+  const syncPluginInstallTimeout = positiveIntegerFromEnv(
+    env.CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS
+  );
+  const pluginSeedDir = normalizedEnvValue(env.CLAUDE_CODE_PLUGIN_SEED_DIR);
+
+  if (normalizedEnvValue(env.CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS)) {
+    if (Number.isNaN(syncPluginInstallTimeout)) {
+      entries.push({
+        level: "warn",
+        text: "CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS invalid",
+        details: [
+          "expected a positive integer timeout in milliseconds",
+          "invalid timeout values can make headless plugin-install behavior harder to reason about",
+        ],
+      });
+    } else if (!syncPluginInstall) {
+      entries.push({
+        level: "warn",
+        text: "CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS set without CLAUDE_CODE_SYNC_PLUGIN_INSTALL",
+        details: [
+          "official docs: the timeout only applies when synchronous plugin installation is enabled",
+          "set CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 or remove the timeout override",
+        ],
+      });
+    }
+  }
+
+  if (pluginSeedDir) {
+    entries.push({
+      level: "info",
+      text: "CLAUDE_CODE_PLUGIN_SEED_DIR configured",
+      details: [
+        `seed dir: ${pluginSeedDir}`,
+        "official docs: pre-populated plugin seeds let containers and CI start with marketplaces/plugins already available",
+      ],
+    });
+  }
+
+  if (inCi && !syncPluginInstall && !pluginSeedDir) {
+    entries.push({
+      level: "warn",
+      text: "CI environment without synchronous or seeded plugin availability",
+      details: [
+        "prefer claude --bare -p for CI so runs do not inherit local hooks, skills, plugins, MCP discovery, or CLAUDE.md unexpectedly",
+        "official docs: in non-interactive/headless mode, marketplace plugins may install in the background and miss the first turn",
+        "set CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 for headless runs that depend on plugin availability on turn one",
+        "or pre-populate plugins with CLAUDE_CODE_PLUGIN_SEED_DIR in containers/CI images",
+        "if the run needs project assets in bare mode, pass them explicitly with --plugin-dir, --settings, or --mcp-config",
+      ],
+    });
+  }
+
+  for (const family of PINNED_MODEL_ENV_FAMILIES) {
+    const modelId = normalizedEnvValue(env[family.modelVar]);
+    if (!modelId) continue;
+
+    const caps = normalizedEnvValue(env[family.capsVar]);
+    if (!looksProviderSpecificModelId(modelId) || caps) continue;
+
+    entries.push({
+      level: "warn",
+      text: `${family.modelVar} uses a provider-specific/custom model id`,
+      details: [
+        `${family.label} pinned to: ${modelId}`,
+        `${family.capsVar} is unset`,
+        "official docs: custom/provider model IDs can disable Claude Code feature detection for effort and thinking",
+        `declare ${family.capsVar} when pinning custom Bedrock / Vertex / Foundry / gateway model IDs`,
+      ],
+    });
+  }
+
+  return { entries };
+}

package/cli/lib/frontmatter.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+
+function formatYamlErrors(errors) {
+  return errors.map((error) => error.message).join("; ");
+}
+
+export function extractFrontmatterBlock(text, sourceLabel = "frontmatter") {
+  const match = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    throw new Error(`${sourceLabel}: missing YAML frontmatter`);
+  }
+
+  return match[1];
+}
+
+export function parseFrontmatterBlock(block, sourceLabel = "frontmatter") {
+  const document = YAML.parseDocument(block, {
+    strict: true,
+    uniqueKeys: true,
+  });
+
+  if (document.errors.length > 0) {
+    throw new Error(`${sourceLabel}: invalid YAML (${formatYamlErrors(document.errors)})`);
+  }
+
+  const value = document.toJS();
+  if (value == null) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${sourceLabel}: frontmatter must parse to an object`);
+  }
+
+  return value;
+}
+
+export function readFrontmatter(filePath) {
+  const text = readFileSync(filePath, "utf-8");
+  const block = extractFrontmatterBlock(text, filePath);
+  return parseFrontmatterBlock(block, filePath);
+}
+
+export function readFrontmatterFields(filePath) {
+  return Object.keys(readFrontmatter(filePath));
+}

package/cli/lib/json-schema.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import Ajv from "ajv";
+
+const ajv = new Ajv({
+  allErrors: true,
+  allowUnionTypes: true,
+  strict: false,
+});
+
+const validatorCache = new Map();
+
+function formatParams(params = {}) {
+  if (params.missingProperty) return ` missingProperty=${params.missingProperty}`;
+  if (params.additionalProperty) return ` additionalProperty=${params.additionalProperty}`;
+  return "";
+}
+
+export function readJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf-8"));
+}
+
+export function formatAjvErrors(errors = []) {
+  return errors.map((error) => {
+    const where = error.instancePath || error.schemaPath || "(root)";
+    return `${where}: ${error.message}${formatParams(error.params)}`;
+  });
+}
+
+function getSchemaValidator(schemaPath) {
+  const absPath = resolve(schemaPath);
+  if (validatorCache.has(absPath)) return validatorCache.get(absPath);
+
+  const schema = readJsonFile(absPath);
+  const validate = ajv.compile(schema);
+  const entry = { absPath, schema, validate };
+  validatorCache.set(absPath, entry);
+  return entry;
+}
+
+export function validateAgainstSchemaFile(schemaPath, data) {
+  const { validate } = getSchemaValidator(schemaPath);
+  const valid = Boolean(validate(data));
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(validate.errors),
+  };
+}
+
+export function validateSchemaFile(schemaPath) {
+  const schema = readJsonFile(resolve(schemaPath));
+  const valid = ajv.validateSchema(schema);
+  return {
+    valid,
+    errors: valid ? [] : formatAjvErrors(ajv.errors),
+  };
+}

package/cli/lib/runtime.js

@@ -52,15 +52,18 @@ function findSymlinkDir() {
   return null;
 }
 
-export function ensureRuntimeInPath(cmd, candidates) {
+function getRuntimeStatus(cmd, candidates, { repair = false } = {}) {
   if (has(cmd)) return { status: "ok" };
-
   const realPath = findRuntime(candidates);
   if (!realPath) return { status: "missing" };
 
   const linkDir = findSymlinkDir();
   if (!linkDir) return { status: "path-unwritable", path: realPath };
 
+  if (!repair) {
+    return { status: "linkable", path: realPath, link: join(linkDir, cmd) };
+  }
+
   const linkPath = join(linkDir, cmd);
   if (existsSync(linkPath)) {
     try {
@@ -81,6 +84,21 @@ export function ensureRuntimeInPath(cmd, candidates) {
   }
 }
 
+export function inspectRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: false });
+}
+
+export function ensureRuntimeInPath(cmd, candidates) {
+  return getRuntimeStatus(cmd, candidates, { repair: true });
+}
+
+export function inspectClaudeMemRuntimes() {
+  return {
+    bun: inspectRuntimeInPath("bun", BUN_CANDIDATES),
+    uv: inspectRuntimeInPath("uv", UV_CANDIDATES),
+  };
+}
+
 export function ensureClaudeMemRuntimes() {
   return {
     bun: ensureRuntimeInPath("bun", BUN_CANDIDATES),

package/cli/lib/semver.js

@@ -93,3 +93,17 @@ export function isVersionNewer(latestVersion, currentVersion) {
 export function isVersionAtLeast(version, minimumVersion) {
   return compareVersions(version, minimumVersion) >= 0;
 }
+
+export function deriveNpmDistTag(version) {
+  const { prerelease } = parseVersion(version);
+
+  if (prerelease.length === 0) {
+    return "latest";
+  }
+
+  const namedChannel = prerelease.find(
+    (token) => typeof token === "string" && token.length > 0
+  );
+
+  return namedChannel || "prerelease";
+}