@axiomatic-labs/claudeflow 2.13.25 → 2.13.26

package/lib/install.js

@@ -334,6 +334,7 @@ function ensureGlobalCli(version) {
         autoInstalled: !needsUpgrade,
         upgraded: needsUpgrade,
         fromVersion: installedVersion || undefined,
+        shellPath: verifyShellCanFindCli(),
       };
     }
     return {
@@ -368,6 +369,67 @@ function readGlobalCliVersion() {
   }
 }
 
+// Returns { ok: boolean | null, binPath?: string, shellRcFile?: string,
+//   nvmDetected?: boolean, suggestedFix?: string }
+//
+// Distinguishes "package installed globally" from "package findable from
+// the user's interactive shell". Catches the common nvm-lazy-load setup
+// where `npm install -g` writes a binary the shell can't see until nvm
+// is sourced — typically discovered only when the user opens a fresh
+// terminal and types `claudeflow` and gets "command not found".
+function verifyShellCanFindCli() {
+  // Skip on Windows; lazy-load + nvm-windows behave differently and the
+  // login-shell trick below is brittle there.
+  if (process.platform === 'win32') return { ok: null };
+
+  const shellPath = process.env.SHELL;
+  if (!shellPath || !fs.existsSync(shellPath)) return { ok: null };
+
+  // Run a non-inherited interactive login shell — that's the closest
+  // simulation of "user opens a new terminal" without polluting the
+  // current process.
+  let foundOnUserPath = null;
+  try {
+    const out = execSync(`${shellPath} -lic 'command -v claudeflow 2>/dev/null'`, {
+      encoding: 'utf8',
+      timeout: 6000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    foundOnUserPath = out.length > 0;
+  } catch {
+    // Some shells exit non-zero when `command -v` finds nothing — treat
+    // that as "not found" rather than as an inconclusive check.
+    foundOnUserPath = false;
+  }
+
+  if (foundOnUserPath) return { ok: true };
+
+  // Resolve where the binary actually lives so the warning is concrete.
+  let binPath = null;
+  try {
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8', timeout: 5000 }).trim();
+    binPath = path.join(prefix, 'bin', 'claudeflow');
+  } catch {}
+
+  const home = process.env.HOME || '';
+  const nvmDetected = !!process.env.NVM_DIR
+    || fs.existsSync(path.join(home, '.nvm', 'nvm.sh'));
+  const isZsh = shellPath.endsWith('/zsh');
+  const shellRcFile = isZsh ? '~/.zshrc' : (shellPath.endsWith('/bash') ? '~/.bashrc' : '~/.profile');
+
+  // Wrapper-function fix that mirrors the user's existing nvm lazy-load
+  // pattern (e.g., npx, node, npm). Single line, paste into rcFile, done.
+  const wrapperFix = `claudeflow() { unset -f claudeflow; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; claudeflow "$@"; }`;
+
+  return {
+    ok: false,
+    binPath,
+    shellRcFile,
+    nvmDetected,
+    suggestedFix: wrapperFix,
+  };
+}
+
 function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled: false }) {
   const MANIFESTS = ['package.json', 'pyproject.toml', 'Gemfile', 'go.mod', 'Cargo.toml', 'composer.json'];
   const SKIP_DIRS = new Set(['node_modules', 'vendor', '__pycache__', 'dist', 'build', '.next', '.nuxt', '.output', '.claude']);
@@ -401,7 +463,27 @@ function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled:
       `  ${ui.DIM}✓ Upgraded global ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} CLI${cliStatus.fromVersion ? ` from ${cliStatus.fromVersion}` : ''}.${ui.RESET}`
     );
     console.log('');
-  } else if (!cliStatus.available) {
+  }
+
+  // Shell PATH warning — if the global package was installed but the
+  // user's interactive shell can't find the binary (typical with
+  // nvm lazy-load), emit a concrete fix.
+  if (cliStatus.shellPath && cliStatus.shellPath.ok === false) {
+    const sp = cliStatus.shellPath;
+    console.log(`  ${ui.YELLOW}⚠ ${ui.BOLD}claudeflow${ui.RESET}${ui.YELLOW} CLI installed but NOT on your shell PATH.${ui.RESET}`);
+    if (sp.binPath) {
+      console.log(`    ${ui.DIM}Binary lives at: ${sp.binPath}${ui.RESET}`);
+    }
+    if (sp.nvmDetected) {
+      console.log(`    ${ui.DIM}Likely cause: nvm lazy-load. Add this to ${sp.shellRcFile}, then reopen terminal:${ui.RESET}`);
+      console.log(`    ${ui.CYAN}${sp.suggestedFix}${ui.RESET}`);
+    } else {
+      console.log(`    ${ui.DIM}Add the npm prefix bin directory to your PATH in ${sp.shellRcFile}.${ui.RESET}`);
+    }
+    console.log('');
+  }
+
+  if (!cliStatus.available) {
     console.log(`  ${ui.DIM}To get the ${ui.CYAN}claudeflow${ui.RESET}${ui.DIM} shell command, run:${ui.RESET}`);
     console.log(`    ${ui.CYAN}npm i -g @axiomatic-labs/claudeflow${ui.RESET}`);
     if (cliStatus.error && cliStatus.error !== 'skipped') {
@@ -434,14 +516,21 @@ function showGettingStarted(cwd, cliStatus = { available: false, autoInstalled:
   }
 
   console.log('');
-  console.log(`  ${ui.BOLD}Commands:${ui.RESET}`);
+  console.log(`  ${ui.BOLD}Slash commands (inside Claude Code):${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-install${ui.RESET}        ${ui.DIM}Route setup automatically for new or existing projects${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-build${ui.RESET}          ${ui.DIM}Execute an approved spec for larger or higher-risk changes${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-design-tokens${ui.RESET}  ${ui.DIM}Create design reference from a site or screenshot${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-create-ui${ui.RESET}      ${ui.DIM}Build pages from visual references${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-checkpoints${ui.RESET}    ${ui.DIM}Auto-save work with git checkpoints${ui.RESET}`);
   console.log(`  ${ui.CYAN}/claudeflow-add-skill${ui.RESET}      ${ui.DIM}Add new technology skills (e.g. /claudeflow-add-skill stripe)${ui.RESET}`);
-  console.log(`  ${ui.CYAN}/claudeflow-add-tools${ui.RESET}     ${ui.DIM}Discover and install MCP servers + CLI tools${ui.RESET}`);
+  console.log(`  ${ui.CYAN}/claudeflow-add-tools${ui.RESET}      ${ui.DIM}Discover and install MCP servers + CLI tools${ui.RESET}`);
+  console.log('');
+  console.log(`  ${ui.BOLD}Shell commands (outside Claude Code):${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow${ui.RESET}                 ${ui.DIM}Start Claude Code with this project's claudeflow context${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow panel${ui.RESET}           ${ui.DIM}Open the local web dashboard — toggle hooks, reminders, enforcement${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow doctor${ui.RESET}          ${ui.DIM}Diagnose CDP-port and lockfile issues; ${ui.CYAN}--fix${ui.RESET}${ui.DIM} to auto-repair${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow install${ui.RESET}         ${ui.DIM}Refresh the template + global CLI in this project${ui.RESET}`);
+  console.log(`  ${ui.CYAN}claudeflow version${ui.RESET}         ${ui.DIM}Show installed framework + CLI versions${ui.RESET}`);
   console.log('');
   console.log(`  ${ui.DIM}Docs: https://claudeflow.dev${ui.RESET}`);
   console.log('');
@@ -1107,4 +1196,6 @@ module.exports = Object.assign(run, {
   mergeClaudeSettings,
   commandExists,
   readGlobalCliVersion,
+  verifyShellCanFindCli,
+  showGettingStarted,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.13.25",
+  "version": "2.13.26",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"