@curdx/flow 3.0.0 → 3.2.0

package/bin/curdx-flow.js

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-/**
- * curdx-flow CLI entry
- *
- * Usage:
- *   npx @curdx/flow <command> [args]
- *
- * The CLI only handles install-time and lifecycle operations that must
- * happen outside Claude Code. Anything a user does while Claude Code is
- * running (init a project, start a spec, run the workflow, etc.) is a
- * slash command: /curdx-flow:init, /curdx-flow:start, and so on.
- *
- * Commands:
- *   install    Install curdx-flow plugin + optional recommended plugins
- *   doctor     Check health (claude CLI, plugin, MCPs, recommended plugins)
- *   upgrade    Update curdx-flow + recommended plugins to latest
- *   uninstall  Remove curdx-flow plugin (and optionally recommended / artifacts)
- *   --version / -v
- *   --help / -h  (CLI usage summary — use /curdx-flow:help in Claude Code
- *                 for the full command/workflow reference)
- */
-
-import { fileURLToPath } from "node:url";
-import { realpathSync } from "node:fs";
-
-import { runCli } from "../cli/router.js";
-
-// Only execute main() when invoked directly (`node bin/curdx-flow.js ...`
-// or via the npm bin shim at node_modules/.bin/<name>). When the file is
-// imported by tests or tooling, we want the module graph to load without
-// side-effects.
-//
-// CRITICAL: compare RESOLVED real paths. npm installs the bin as a symlink
-// (node_modules/.bin/curdx-flow → ../@curdx/flow/bin/curdx-flow.js), so
-// process.argv[1] is the symlink path while import.meta.url resolves to
-// the real file. Comparing them directly (the pre-beta.13 behavior)
-// silently skipped main() for every single npx / global-install user,
-// producing a completely broken CLI that exited with no output. Regression
-// caught by user report + reproduced in CI via test/cli-entrypoints.test.js.
-function isInvokedDirectly() {
-  if (!process.argv[1]) return false;
-  try {
-    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
-  } catch {
-    // argv[1] is not a real filesystem path (e.g. `node -e` eval forms or
-    // a worker pipe). Treat as "not invoked directly" — the caller is
-    // doing something non-standard.
-    return false;
-  }
-}
-
-if (isInvokedDirectly()) {
-  runCli();
-}

package/cli/README.md

@@ -1,104 +0,0 @@
-# curdx-flow CLI
-
-One-shot installer + external diagnostics + external init. Requires Node.js 18+ and Claude Code v2.1.110+.
-
-## Quick Start
-
-```bash
-# Interactive install (pick recommended plugins)
-npx github:curdx/curdx-flow install
-
-# Or install everything automatically
-npx github:curdx/curdx-flow install --all
-
-# Health check
-npx @curdx/flow doctor
-
-# Update all plugins
-npx @curdx/flow upgrade
-```
-
-## Commands
-
-### `install [--all] [--no-deps]`
-
-Steps:
-1. Verify the `claude` CLI is installed
-2. `claude plugin marketplace add --scope user curdx/curdx-flow`
-3. Pre-register required companion marketplaces so plugin dependencies can resolve
-4. `claude plugin install --scope user curdx-flow@curdx-flow-marketplace`
-5. Install required companion plugin: **context7-plugin@context7-marketplace**
-6. Register required user-level MCP: **sequential-thinking**
-7. Interactively (or automatically) install recommended plugins: **pua**, **claude-mem**, **frontend-design**, **chrome-devtools-mcp**
-
-| Flag | Purpose |
-|------|---------|
-| `--all` | Install all recommended plugins, no prompt |
-| `--no-deps` | Install only curdx-flow itself |
-
-### `doctor [--verbose] [--fix] [--json]`
-
-External diagnostics: claude CLI / curdx-flow / required MCPs / recommended plugins / current directory `.flow/` state.
-
-`--fix` applies the safe automatic repairs the CLI can perform without guessing — currently the `bun` / `uv` PATH symlinks used by `claude-mem`. Everything else remains diagnostic-only.
-
-`--json` emits the full health result as machine-readable JSON for CI, wrappers, or external diagnostics. It includes `contractVersion`, `metadata.appliedFixes`, settings inspection scope metadata, the rendered report structure, and raw `doctorData`, including CurDX-Flow plugin option precedence, file-based managed settings, and runtime env projection.
-
-`doctor` also compares the plugin body shipped with the current CLI/package against the `curdx-flow` version Claude actually has installed, so local development and release validation do not silently run against stale plugin cache state.
-
-When the CLI is running from a git checkout, `doctor` also reports whether that source repo is dirty. This catches the common plugin-development trap where Claude is still running the previously installed cache while your local checkout has uninstalled edits.
-
-### Project initialization (not a CLI command)
-
-Project initialization is a Claude Code slash command, not a CLI one. After `install`, open your project in Claude Code and run:
-
-```
-claude
-/curdx-flow:init
-```
-
-This keeps the CLI scoped to install-time and lifecycle operations only — anything the user does while Claude Code is running stays inside Claude Code.
-
-### `upgrade`
-
-`claude plugin marketplace update` + `claude plugin update --scope user` for every installed curdx-flow-related plugin.
-
-After updating, `upgrade` also reconciles retired Context7 install artifacts:
-
-- removes the old user-level `context7` MCP if the official `context7-plugin` already owns it
-- removes any stale `context7ApiKey` entry from `~/.claude/curdx-flow-config.json`
-
-### `uninstall [-y] [--keep-recommended] [--purge]`
-
-Inverse of `install`. By default removes only the curdx-flow plugin. Recommended plugins are kept unless selected interactively. With `--purge`, also removes third-party marketplaces, the `~/.local/bin/bun` / `~/.local/bin/uv` symlinks created by install, and any retired Context7 user-level MCP / stored API key left behind by older CurDX-Flow releases.
-
-## Why a CLI?
-
-The **core workflow** still lives inside Claude Code (`/curdx-flow:*` commands). The CLI provides:
-
-- **One-line install**: Docker/CI friendly (`RUN npx github:curdx/curdx-flow install --all`)
-- **External diagnostics**: check health without entering Claude Code
-- **Batch deployment**: write a script for your team — `for host in ...; do ssh $host npx github:curdx/curdx-flow install; done`
-
-## Small-dependency design
-
-- Pure ES Modules (Node 18+)
-- Tiny runtime dependency surface (`@clack/prompts`, `picocolors`)
-- No `commander` / `inquirer` / `execa`
-- Fast `npx` and offline-capable plugin install
-
-## Local development
-
-```bash
-# clone
-git clone https://github.com/curdx/curdx-flow
-cd curdx-flow
-
-# run directly
-node bin/curdx-flow.js --help
-node bin/curdx-flow.js doctor
-```
-
-## License
-
-MIT

package/cli/doctor-workflow.js

@@ -1,483 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { removeMcp } from "./lib/claude-ops.js";
-import { readProjectClaudeSettings } from "./lib/doctor-claude-settings.js";
-import { CONFIG_FILE, readConfig, writeConfig } from "./lib/config.js";
-import { inspectRuntimeEnvironment } from "./lib/doctor-runtime-environment.js";
-import {
-  claudeVersion,
-  color,
-  ensureClaudeMemRuntimes,
-  inspectClaudeMemRuntimes,
-  listMcps,
-  listPluginMarketplaces,
-  listPlugins,
-  log,
-  readUserMcpConfig,
-  runSync,
-} from "./utils.js";
-
-export { readProjectClaudeSettings };
-export { inspectRuntimeEnvironment };
-
-const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
-export const DOCTOR_JSON_CONTRACT_VERSION = 2;
-export const DOCTOR_SETTINGS_INSPECTION = Object.freeze({
-  pluginOptionScopesInspected: ["managed-file", "user", "project", "local"],
-  pluginOptionScopesNotInspected: ["managed-server", "managed-mdm", "cli"],
-});
-
-export function createDoctorContext(args = []) {
-  return {
-    fix: args.includes("--fix"),
-    json: args.includes("--json"),
-    verbose: args.includes("--verbose") || args.includes("-v"),
-  };
-}
-
-function isUrlLike(value) {
-  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
-}
-
-function isWindowsAbsolutePath(value) {
-  return /^[A-Za-z]:[\\/]/.test(value);
-}
-
-function looksLikeRelativePathToken(value) {
-  if (typeof value !== "string") return false;
-  const token = value.trim();
-  if (!token) return false;
-
-  if (token.startsWith("./") || token.startsWith("../")) return true;
-  if (!/[\\/]/.test(token)) return false;
-
-  if (
-    token.startsWith("/") ||
-    token.startsWith("~/") ||
-    token.startsWith("${") ||
-    token.startsWith("@") ||
-    token.startsWith("--") ||
-    isUrlLike(token) ||
-    isWindowsAbsolutePath(token)
-  ) {
-    return false;
-  }
-
-  return (
-    /\.(?:[cm]?js|mjs|ts|tsx|jsx|py|rb|sh|bash|zsh|fish|ps1|cmd|bat|exe)$/i.test(token) ||
-    /(^|[\\/])(?:scripts?|bin|dist|src|tools|vendor|node_modules|venv|\.venv)([\\/]|$)/i.test(token)
-  );
-}
-export async function readProjectMcpConfig(cwd = process.cwd()) {
-  const rootPath = path.join(cwd, ".mcp.json");
-  const misplacedPath = path.join(cwd, ".claude", ".mcp.json");
-
-  const state = {
-    exists: false,
-    misplacedExists: false,
-    invalid: false,
-    parseError: null,
-    shapeError: null,
-    serverCount: 0,
-    relativePathWarnings: [],
-  };
-
-  try {
-    const misplacedStat = await fs.stat(misplacedPath);
-    state.misplacedExists = misplacedStat.isFile();
-  } catch {
-    state.misplacedExists = false;
-  }
-
-  try {
-    const stat = await fs.stat(rootPath);
-    if (!stat.isFile()) return state;
-    state.exists = true;
-  } catch {
-    return state;
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(await fs.readFile(rootPath, "utf-8"));
-  } catch (error) {
-    state.invalid = true;
-    state.parseError = error.message;
-    return state;
-  }
-
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    state.shapeError = "root value must be a JSON object";
-    return state;
-  }
-
-  if (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers)) {
-    state.shapeError = 'missing top-level "mcpServers" object';
-    return state;
-  }
-
-  state.serverCount = Object.keys(parsed.mcpServers).length;
-
-  for (const [serverName, config] of Object.entries(parsed.mcpServers)) {
-    if (!config || typeof config !== "object" || Array.isArray(config)) continue;
-
-    if (looksLikeRelativePathToken(config.command)) {
-      state.relativePathWarnings.push({
-        serverName,
-        field: "command",
-        value: config.command,
-      });
-    }
-
-    const args = Array.isArray(config.args) ? config.args : [];
-    args.forEach((arg, index) => {
-      if (!looksLikeRelativePathToken(arg)) return;
-      state.relativePathWarnings.push({
-        serverName,
-        field: `args[${index}]`,
-        value: arg,
-      });
-    });
-  }
-
-  return state;
-}
-
-export async function readProjectTeamConfig(cwd = process.cwd()) {
-  const teamConfigPath = path.join(cwd, ".claude", "teams", "teams.json");
-  const state = {
-    exists: false,
-  };
-
-  try {
-    const stat = await fs.stat(teamConfigPath);
-    state.exists = stat.isFile();
-  } catch {
-    state.exists = false;
-  }
-
-  return state;
-}
-
-export async function readBundledPluginRuntimeDefaults(packageRoot = PACKAGE_ROOT) {
-  const pluginSettingsPath = path.join(packageRoot, "settings.json");
-  const pluginManifestPath = path.join(packageRoot, ".claude-plugin", "plugin.json");
-  const monitorsPath = path.join(packageRoot, "monitors", "monitors.json");
-  const packageJsonPath = path.join(packageRoot, "package.json");
-
-  const state = {
-    exists: false,
-    packageVersion: null,
-    pluginVersion: null,
-    sourceRepo: {
-      isGitRepo: false,
-      branch: null,
-      shortSha: null,
-      exactTag: null,
-      dirty: false,
-    },
-    defaultAgent: null,
-    subagentStatusLineCommand: null,
-    monitorCount: 0,
-    monitors: [],
-    userConfig: [],
-  };
-
-  let pluginSettings = null;
-  let pluginManifest = null;
-  let monitors = null;
-
-  try {
-    pluginSettings = JSON.parse(await fs.readFile(pluginSettingsPath, "utf-8"));
-  } catch {
-    pluginSettings = null;
-  }
-
-  try {
-    pluginManifest = JSON.parse(await fs.readFile(pluginManifestPath, "utf-8"));
-  } catch {
-    pluginManifest = null;
-  }
-
-  try {
-    const pkg = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
-    state.packageVersion = typeof pkg?.version === "string" ? pkg.version : null;
-  } catch {
-    state.packageVersion = null;
-  }
-
-  const gitRepoCheck = runSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: packageRoot });
-  if (gitRepoCheck.code === 0 && gitRepoCheck.stdout.trim() === "true") {
-    state.sourceRepo.isGitRepo = true;
-
-    const branch = runSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: packageRoot });
-    if (branch.code === 0) {
-      state.sourceRepo.branch = branch.stdout.trim() || null;
-    }
-
-    const shortSha = runSync("git", ["rev-parse", "--short", "HEAD"], { cwd: packageRoot });
-    if (shortSha.code === 0) {
-      state.sourceRepo.shortSha = shortSha.stdout.trim() || null;
-    }
-
-    const exactTag = runSync("git", ["describe", "--tags", "--exact-match", "HEAD"], { cwd: packageRoot });
-    if (exactTag.code === 0) {
-      state.sourceRepo.exactTag = exactTag.stdout.trim() || null;
-    }
-
-    const status = runSync("git", ["status", "--short"], { cwd: packageRoot });
-    if (status.code === 0) {
-      state.sourceRepo.dirty = status.stdout.trim().length > 0;
-    }
-  }
-
-  try {
-    monitors = JSON.parse(await fs.readFile(monitorsPath, "utf-8"));
-  } catch {
-    monitors = null;
-  }
-
-  if (!pluginSettings && !pluginManifest && !monitors) {
-    return state;
-  }
-
-  state.exists = true;
-  state.pluginVersion = typeof pluginManifest?.version === "string" ? pluginManifest.version : null;
-  state.defaultAgent = typeof pluginSettings?.agent === "string" ? pluginSettings.agent : null;
-  state.subagentStatusLineCommand =
-    typeof pluginSettings?.subagentStatusLine?.command === "string"
-      ? pluginSettings.subagentStatusLine.command
-      : null;
-
-  if (Array.isArray(monitors)) {
-    state.monitorCount = monitors.length;
-    state.monitors = monitors
-      .filter((entry) => entry && typeof entry === "object")
-      .map((entry) => ({
-        name: typeof entry.name === "string" ? entry.name : null,
-        when: typeof entry.when === "string" ? entry.when : "always",
-      }))
-      .filter((entry) => entry.name);
-  }
-
-  if (pluginManifest?.userConfig && typeof pluginManifest.userConfig === "object") {
-    state.userConfig = Object.entries(pluginManifest.userConfig)
-      .filter(([, value]) => value && typeof value === "object" && !Array.isArray(value))
-      .map(([key, value]) => ({
-        key,
-        type: value.type ?? null,
-        default: Object.prototype.hasOwnProperty.call(value, "default") ? value.default : undefined,
-        sensitive: value.sensitive === true,
-      }));
-  }
-
-  return state;
-}
-
-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,
-    inspectClaudeMemRuntimesImpl = inspectClaudeMemRuntimes,
-    inspectRuntimeEnvironmentImpl = inspectRuntimeEnvironment,
-    readProjectStateImpl = readProjectState,
-    readProjectMcpConfigImpl = readProjectMcpConfig,
-    readProjectTeamConfigImpl = readProjectTeamConfig,
-    readProjectClaudeSettingsImpl = readProjectClaudeSettings,
-    readBundledPluginRuntimeDefaultsImpl = readBundledPluginRuntimeDefaults,
-    readConfigImpl = readConfig,
-  } = {}
-) {
-  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"
-  )
-    ? inspectClaudeMemRuntimesImpl()
-    : null;
-
-  return {
-    claudeVersionValue,
-    nodeVersion: process.version,
-    plugins,
-    marketplaces,
-    mcps,
-    userMcpConfig,
-    runtimeStatus,
-    runtimeEnvironment: inspectRuntimeEnvironmentImpl(),
-    cwd,
-    projectState: await readProjectStateImpl(cwd),
-    projectMcpConfig: await readProjectMcpConfigImpl(cwd),
-    projectTeamConfig: await readProjectTeamConfigImpl(cwd),
-    projectClaudeSettings: await readProjectClaudeSettingsImpl(cwd),
-    bundledPluginRuntimeDefaults: await readBundledPluginRuntimeDefaultsImpl(),
-    legacyInstallState: {
-      configPath: CONFIG_FILE,
-      hasLegacyContext7ApiKey: Object.prototype.hasOwnProperty.call(readConfigImpl(), "context7ApiKey"),
-    },
-  };
-}
-
-export async function applyDoctorFixes(
-  doctorData,
-  {
-    ensureClaudeMemRuntimesImpl = ensureClaudeMemRuntimes,
-    removeMcpImpl = removeMcp,
-    readConfigImpl = readConfig,
-    writeConfigImpl = writeConfig,
-  } = {}
-) {
-  const fixes = [];
-  const context7PluginOwnsMcp = doctorData.mcps.some(
-    (entry) => entry.name === "context7" && entry.plugin === "context7-plugin"
-  );
-  const hasLegacyUserContext7Mcp =
-    doctorData.userMcpConfig instanceof Map && doctorData.userMcpConfig.has("context7");
-
-  if (context7PluginOwnsMcp && hasLegacyUserContext7Mcp) {
-    const result = await removeMcpImpl({ name: "context7" });
-    if (result.code === 0) {
-      doctorData.userMcpConfig.delete("context7");
-      doctorData.mcps = doctorData.mcps.filter(
-        (entry) => !(entry.name === "context7" && entry.plugin == null)
-      );
-      fixes.push({
-        kind: "legacy-context7-user-mcp-removed",
-      });
-    }
-  }
-
-  if (doctorData.legacyInstallState?.hasLegacyContext7ApiKey) {
-    const config = readConfigImpl();
-    if (Object.prototype.hasOwnProperty.call(config, "context7ApiKey")) {
-      delete config.context7ApiKey;
-      writeConfigImpl(config);
-      doctorData.legacyInstallState = {
-        ...doctorData.legacyInstallState,
-        hasLegacyContext7ApiKey: false,
-      };
-      fixes.push({
-        kind: "legacy-context7-api-key-removed",
-        configPath: CONFIG_FILE,
-      });
-    }
-  }
-
-  const claudeMemEnabled = doctorData.plugins.some(
-    (plugin) => plugin.name === "claude-mem" && plugin.status === "enabled"
-  );
-
-  if (!claudeMemEnabled) {
-    return fixes;
-  }
-
-  const runtimeStatus = ensureClaudeMemRuntimesImpl();
-  doctorData.runtimeStatus = runtimeStatus;
-  fixes.push({
-    kind: "claude-mem-runtimes",
-    runtimeStatus,
-  });
-  return fixes;
-}
-
-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 buildDoctorJsonPayload({
-  context = {},
-  doctorData,
-  fixes = [],
-  report,
-} = {}) {
-  return {
-    contractVersion: DOCTOR_JSON_CONTRACT_VERSION,
-    generatedAt: new Date().toISOString(),
-    context: {
-      fix: context.fix === true,
-      json: context.json === true,
-      verbose: context.verbose === true,
-    },
-    summary: {
-      errors: report?.errors || 0,
-      warnings: report?.warnings || 0,
-      healthy: (report?.errors || 0) === 0,
-    },
-    metadata: {
-      appliedFixes: fixes,
-      settingsInspection: DOCTOR_SETTINGS_INSPECTION,
-    },
-    doctorData,
-    report,
-  };
-}
-
-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);
-}