π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(hooks): resolve globally-installed ruflo before falling back to npx (#3368) (#4368)
rUv3da60761f90d
diff --git a/.claude/helpers/hook-handler.cjs b/.claude/helpers/hook-handler.cjsindex 0cfe3d99e1..2b25605ff0 100755--- a/.claude/helpers/hook-handler.cjs+++ b/.claude/helpers/hook-handler.cjs@@ -24,9 +24,10 @@ const helpersDir = __dirname;const helperRoot = path.resolve(helpersDir, '..', '..');// Resolve an installed @claude-flow/cli (or ruflo) bin β mirrors-// statusline-generator.ts's resolveCliBin() candidate list. Used only to-// spawn the detached funnel-refresh helper below; failures are silent (no-// candidate found just means the refresh never fires this session).+// statusline-generator.ts's resolveCliBin() candidate list, then looks for a+// global install (resolveGlobalCliBin() below, #3368). Used only to spawn the+// detached funnel-refresh helper below; failures are silent (no candidate+// found just means the refresh falls back to npx).//// Verifies dist/src/index.js exists alongside bin/cli.js, not just the bin// itself β Claude Code's own plugin marketplace mechanism installs by@@ -39,7 +40,17 @@ const helperRoot = path.resolve(helpersDir, '..', '..');// first every time and spawnDetachedFunnelRefresh() below had no fallback,// so the promo/disclosure row could never populate for any marketplace// install, on any OS.+// session-restore asks up to three times (first-run enable, then the two+// refreshes). The answer cannot change inside one short-lived hook process,+// so resolve once: `undefined` means "not looked up yet", null means "no+// local or global CLI β use npx".+let cliBinCache;function resolveCliBinForHook() {+ if (cliBinCache === undefined) cliBinCache = resolveCliBinUncached();+ return cliBinCache;+}++function resolveCliBinUncached() {try {const home = os.homedir();const candidates = [@@ -53,16 +64,219 @@ function resolveCliBinForHook() {path.join(helpersDir, '..', '..', 'bin', 'cli.js'),];for (const p of candidates) {- try {- if (fs.existsSync(p) && fs.existsSync(path.join(path.dirname(p), '..', 'dist', 'src', 'index.js'))) {- return p;- }- } catch (e) { /* try next candidate */ }+ if (isRunnableCli(p)) return p;}+ return resolveGlobalCliBin();} catch (e) { /* ignore */ }return null;}+function isRunnableCli(p) {+ try {+ return fs.existsSync(p) && fs.existsSync(path.join(path.dirname(p), '..', 'dist', 'src', 'index.js'));+ } catch (e) { return false; }+}++// #3368: a global install β the README's `npm install -g ruflo@latest` β keeps+// the CLI at <prefix>/lib/node_modules/ruflo/node_modules/@claude-flow/cli,+// which none of the project-relative candidates above cover, so on those+// machines every refresh fell back to npx: a second, separately cached copy+// of the CLI that follows the registry's latest rather than the version the+// user pinned (the same npx-cache skew as #3306), and that cannot start+// offline on a cold cache.+//+// Three lookups, fs calls only (no child process), reached only after every+// candidate above missed:+// 1. npm's global prefix, resolved the way npm resolves it+// (npmGlobalPrefix() below). First because it does not depend on PATH:+// a hook inherits the host process's PATH, which need not contain the+// prefix's bin/ even when the user's interactive shell does (observed:+// the Claude Code process spawning hooks lacked ~/.npm-global/bin while+// a login zsh on the same machine had it).+// 2. `ruflo`, then `claude-flow`, on PATH β the order plugins/ruflo-core/+// scripts/ruflo-hook.cjs uses β for globals npm did not install (yarn+// classic, bun). Only a symlinked bin counts, and only when it lands in+// a package that declares one of the three known names, so a wrapper+// script or a version-manager shim (Volta) is never mistaken for an+// install. The <dir>/node_modules/<name> layout npm uses on Windows,+// where ruflo.cmd sits beside node_modules\ruflo (what resolveNpmShim()+// in ruflo-hook.cjs maps), is only consulted on win32: on POSIX every+// manager symlinks, and probing it there would follow a Windows install+// exposed to WSL through the appended Windows PATH.+// Relative PATH entries (`.` or an empty entry) are skipped, so a bare+// `./ruflo` in the working directory is never picked up.+// 3. ~/.npm-global, npm's documented no-sudo prefix, when 1 and 2 both+// missed: the prefix setting may live where this hook's node never+// reads it, and a wrapper script on PATH is skipped by 2.+// `env`/`platform`/`execPath` are parameters so any layout is testable+// from any OS.+function resolveGlobalCliBin(env = process.env, platform = process.platform, execPath = process.execPath) {+ const prefix = npmGlobalPrefix(env, platform, execPath);+ if (prefix) {+ const hit = cliUnderPrefix(prefix, platform);+ if (hit) return hit;+ }+ const dirs = String(env.PATH || env.Path || '').split(platform === 'win32' ? ';' : ':');+ const exts = platform === 'win32' ? ['.cmd', ''] : [''];+ for (const name of ['ruflo', 'claude-flow']) {+ for (const dir of dirs) {+ if (!dir || !path.isAbsolute(dir)) continue;+ for (const ext of exts) {+ const shim = path.join(dir, name + ext);+ if (!fs.existsSync(shim)) continue;+ const roots = [];+ try {+ if (fs.lstatSync(shim).isSymbolicLink()) {+ const root = path.dirname(path.dirname(fs.realpathSync(shim)));+ if (isKnownPackageRoot(root)) roots.push(root);+ }+ } catch (e) { /* unreadable link β fall back to the layout roots */ }+ if (platform === 'win32') {+ roots.push(path.join(dir, 'node_modules', name));+ if (name === 'claude-flow') roots.push(path.join(dir, 'node_modules', '@claude-flow', 'cli'));+ }+ for (const root of roots) {+ const hit = cliInPackage(root);+ if (hit) return hit;+ }+ }+ }+ }+ // Last resort: ~/.npm-global, the prefix npm's own docs recommend for+ // global installs without sudo ("Resolving EACCES permissions errors").+ // The setting that points npm there can live where this hook's node never+ // looks (another node's builtin npmrc, or a wrapper script that sets it+ // per call), and a `ruflo` wrapper script on PATH is skipped above by+ // design. Without this, such a machine fell back to npx @latest on every+ // hook. Checked only after the configured prefix and PATH both miss, so it+ // can never override either.+ const home = env.HOME || env.USERPROFILE;+ if (home && path.isAbsolute(home)) {+ const hit = cliUnderPrefix(path.join(home, '.npm-global'), platform);+ if (hit) return hit;+ }+ return null;+}++// The CLI of a global install under an npm prefix: <prefix>/lib/node_modules+// on POSIX, <prefix>\node_modules on Windows, trying the three published+// package names in order.+function cliUnderPrefix(prefix, platform) {+ const modules = platform === 'win32'+ ? path.join(prefix, 'node_modules')+ : path.join(prefix, 'lib', 'node_modules');+ for (const pkg of ['ruflo', 'claude-flow', path.join('@claude-flow', 'cli')]) {+ const hit = cliInPackage(path.join(modules, pkg));+ if (hit) return hit;+ }+ return null;+}++// A bin on PATH only counts as an install when the package it points into+// declares one of the three published names. This is a narrower check than+// resolveNpmShim() in ruflo-hook.cjs, which never reads `name`: that one takes+// the package name from the shim's own filename, then validates package.json's+// `bin` entry and that its realpath stays inside the package. Here the bin has+// already been resolved to a package root, so the manifest `name` is what+// identifies it.+function isKnownPackageRoot(root) {+ try {+ const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8')).name;+ return name === 'ruflo' || name === 'claude-flow' || name === '@claude-flow/cli';+ } catch (e) { return false; }+}++// Map an installed ruflo / claude-flow / @claude-flow/cli package root to the+// CLI it runs: <root>/bin/cli.js (@claude-flow/cli itself),+// <root>/v3/@claude-flow/cli/bin/cli.js (the claude-flow umbrella bundles+// it), or @claude-flow/cli in the node_modules npm nests inside <root> β+// or, for the flat layout yarn classic and bun use, in the node_modules+// folder that holds <root> itself. That is the dependency edge+// ruflo/bin/ruflo.js's findCliPath() follows. The search stops at that one+// enclosing node_modules: walking further up would reach unrelated trees,+// such as a stray ~/node_modules left by an `npm i` in a home directory.+// Every hit must still pass isRunnableCli().+function cliInPackage(root) {+ if (!fs.existsSync(root)) return null;+ const candidates = [+ path.join(root, 'bin', 'cli.js'),+ path.join(root, 'v3', '@claude-flow', 'cli', 'bin', 'cli.js'),+ path.join(root, 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ ];+ for (let dir = path.dirname(root), i = 0; i < 4 && dir !== path.dirname(dir); i++, dir = path.dirname(dir)) {+ if (path.basename(dir) === 'node_modules') {+ candidates.push(path.join(dir, '@claude-flow', 'cli', 'bin', 'cli.js'));+ break;+ }+ }+ return candidates.find(isRunnableCli) || null;+}++// npm's global prefix without spawning npm (`npm prefix -g` measured 70-80 ms+// per call, paid on every SessionStart that gets this far). Same precedence+// npm applies:+// 1. npm_config_prefix in the environment (npm accepts either case);+// 2. `prefix=` in the user npmrc ($npm_config_userconfig, else ~/.npmrc),+// where `npm config set prefix ~/.npm-global` (the npm docs' fix for+// EACCES on global installs) writes it;+// 3. `prefix=` in npm's builtin npmrc (<npm package>/npmrc), found through+// the `npm` link beside node: Homebrew writes `prefix = /opt/homebrew`+// there (its process.execPath is the Cellar path, so step 4 alone would+// be wrong), and the Node.js Windows installer ships+// `prefix=${APPDATA}\npm`;+// 4. npm's default: $PREFIX, else the directory above node's bin/ (POSIX)+// or node.exe's own directory (Windows).+// Values follow npm's ini handling for the cases that decide a path: a+// quoted value is taken literally, an unquoted `;`/`#` starts a comment,+// keys below a `[section]` header are ignored, `${VAR}` expands when the+// variable is set (and `${VAR?}` to empty when it is not) but otherwise+// stays literal like npm β which leaves the value relative, so the+// isAbsolute() check below rejects it instead of pointing at the drive root.+// Not emulated: escaped characters and npm's other ini corner cases; each of+// those produces a miss, never a wrong CLI. The npmrc is read into memory,+// but only the value of its last top-level `prefix =` line is kept: no other+// line (an `_authToken`, say) is returned, stored or logged.+function npmGlobalPrefix(env = process.env, platform = process.platform, execPath = process.execPath) {+ const home = (platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();+ const readPrefix = (file) => {+ let value = null;+ try {+ for (const line of fs.readFileSync(file, 'utf-8').split(/\r?\n/)) {+ if (/^\s*\[/.test(line)) break; // only the top-level section applies+ const m = /^\s*prefix\s*=\s*(.*?)\s*$/.exec(line);+ if (m) value = m[1]; // last one wins, as in npm's ini parser+ }+ } catch (e) { /* no such npmrc */ }+ return value;+ };+ const nodeDir = path.dirname(execPath);+ // npm's builtin npmrc sits in npm's own package dir. On Windows that is+ // node_modules\npm beside node.exe; elsewhere follow the `npm` link beside+ // node (<npm>/bin/npm-cli.js) β on Homebrew it points out of the node keg+ // to /opt/homebrew/lib/node_modules/npm.+ let builtinRc = path.join(nodeDir, 'node_modules', 'npm', 'npmrc');+ if (platform !== 'win32') {+ try {+ builtinRc = path.join(path.dirname(path.dirname(fs.realpathSync(path.join(nodeDir, 'npm')))), 'npmrc');+ } catch (e) { /* no npm beside node */ }+ }+ const raw = env.npm_config_prefix || env.NPM_CONFIG_PREFIX+ || readPrefix(env.npm_config_userconfig || env.NPM_CONFIG_USERCONFIG || path.join(home, '.npmrc'))+ || readPrefix(builtinRc)+ || env.PREFIX+ || (platform === 'win32' ? nodeDir : path.dirname(nodeDir));+ let value = String(raw).trim();+ const quoted = /^(["'])([\s\S]*)\1$/.exec(value);+ if (quoted) value = quoted[2];+ else value = value.replace(/(^|[^\\])[;#].*$/, '$1').trim();+ value = value+ .replace(/\$\{([^}?]+)(\?)?\}/g, (whole, name, optional) => (+ env[name] !== undefined ? env[name] : (optional ? '' : whole)+ ))+ .replace(/^~(?=$|[\\/])/, home);+ return path.isAbsolute(value) ? path.resolve(value) : null;+}+// Fire-and-forget doesn't work when the CALLER is itself a short-lived// subprocess (confirmed live: two consecutive statusline renders 5s apart// both saw an empty funnel-messages-cache, because the async HTTPS fetch@@ -74,8 +288,8 @@ function resolveCliBinForHook() {// chance to write the cache. Never awaited here β must not add to// SessionStart's own timeout budget.//-// No usable local candidate (resolveCliBinForHook() returned null) falls-// back to npx: this call is detached/unref'd, so a slower npx cold-start+// No usable local or global candidate (resolveCliBinForHook() returned null)+// falls back to npx: this call is detached/unref'd, so a slower npx cold-start// costs nothing perceptible β unlike the statusline's own synchronous// render path, where local-first exists purely for per-render latency.// `--prefer-offline` avoids a registry round trip for the tarball when@@ -1060,4 +1274,7 @@ if (require.main === module) {// Which sibling helpers loaded (all CommonJS, shipped as .cjs β #3555).const loadedHelpers = { router: !!router, session: !!session, memory: !!memory, intelligence: !!intelligence };-module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers, ownedByMod, MOD_OWNABLE_EVENTS, resolveCliBinForHook, cliSpawnArgs, helperRoot, scanSessionStartSettingsForRisk, srFormatRiskFindingsForAutomaticBoot, srScanSettingsForRisk, srScanCommandStringForRisk, srScanAllowRuleForRisk, SR_DANGEROUS_COMMAND_WORDS, SR_SHELL_EXEC_WORDS, SR_DOWNLOADER_WORDS, SR_STANDALONE_RISK_PATTERNS };+// resolveGlobalCliBin/npmGlobalPrefix are exported for+// hook-handler-global-cli.test.ts; resolveCliBinForHook for anyone checking+// what a given machine resolves to without running a hook (#3368).+module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers, ownedByMod, MOD_OWNABLE_EVENTS, resolveCliBinForHook, resolveGlobalCliBin, npmGlobalPrefix, cliSpawnArgs, helperRoot, scanSessionStartSettingsForRisk, srFormatRiskFindingsForAutomaticBoot, srScanSettingsForRisk, srScanCommandStringForRisk, srScanAllowRuleForRisk, SR_DANGEROUS_COMMAND_WORDS, SR_SHELL_EXEC_WORDS, SR_DOWNLOADER_WORDS, SR_STANDALONE_RISK_PATTERNS };diff --git a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.jsonindex e4a2977eb7..6aa8aad0f0 100644--- a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json+++ b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json@@ -1,14 +1,14 @@{"manifest": {- "version": "3.57.1",+ "version": "3.59.12","files": {"auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",- "hook-handler.cjs": "bc12b3cae92d5a7c8deef699fa00d0ef07b57625c18dbeac4387f15725b8e09f",+ "hook-handler.cjs": "24502a3bcb78770971147940515c992e35b6736ae14ee2dc54e07d4cdef6a1d8","intelligence.cjs": "1d981d6c6a35d70a66450e96458e26169e0cede11523ea246a2c129c197a5b4e","statusline.cjs": "d72417ecb38634011a19f095a30e07b9929e6f97663520172ece9be7491b2eaa","router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"}},- "signature": "6ArQqTEyowza1Ku34wtreG6UuyiY7XPdn99FyFK4LVAN8xvgFr+LzlfnP/Gk3wLd2ZhG0oBAELAUS00TuFOLBA==",+ "signature": "3W2msAbKXT6nAWSCviEGsLg0KdwT5VcWkBTndXg9RgKY56YkGiwjE8sL0eBI/m5iaGbdHqUOQVbibaBNJkdQAg==","algorithm": "ed25519"}diff --git a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjsindex 0cfe3d99e1..2b25605ff0 100755--- a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs+++ b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs@@ -24,9 +24,10 @@ const helpersDir = __dirname;const helperRoot = path.resolve(helpersDir, '..', '..');// Resolve an installed @claude-flow/cli (or ruflo) bin β mirrors-// statusline-generator.ts's resolveCliBin() candidate list. Used only to-// spawn the detached funnel-refresh helper below; failures are silent (no-// candidate found just means the refresh never fires this session).+// statusline-generator.ts's resolveCliBin() candidate list, then looks for a+// global install (resolveGlobalCliBin() below, #3368). Used only to spawn the+// detached funnel-refresh helper below; failures are silent (no candidate+// found just means the refresh falls back to npx).//// Verifies dist/src/index.js exists alongside bin/cli.js, not just the bin// itself β Claude Code's own plugin marketplace mechanism installs by@@ -39,7 +40,17 @@ const helperRoot = path.resolve(helpersDir, '..', '..');// first every time and spawnDetachedFunnelRefresh() below had no fallback,// so the promo/disclosure row could never populate for any marketplace// install, on any OS.+// session-restore asks up to three times (first-run enable, then the two+// refreshes). The answer cannot change inside one short-lived hook process,+// so resolve once: `undefined` means "not looked up yet", null means "no+// local or global CLI β use npx".+let cliBinCache;function resolveCliBinForHook() {+ if (cliBinCache === undefined) cliBinCache = resolveCliBinUncached();+ return cliBinCache;+}++function resolveCliBinUncached() {try {const home = os.homedir();const candidates = [@@ -53,16 +64,219 @@ function resolveCliBinForHook() {path.join(helpersDir, '..', '..', 'bin', 'cli.js'),];for (const p of candidates) {- try {- if (fs.existsSync(p) && fs.existsSync(path.join(path.dirname(p), '..', 'dist', 'src', 'index.js'))) {- return p;- }- } catch (e) { /* try next candidate */ }+ if (isRunnableCli(p)) return p;}+ return resolveGlobalCliBin();} catch (e) { /* ignore */ }return null;}+function isRunnableCli(p) {+ try {+ return fs.existsSync(p) && fs.existsSync(path.join(path.dirname(p), '..', 'dist', 'src', 'index.js'));+ } catch (e) { return false; }+}++// #3368: a global install β the README's `npm install -g ruflo@latest` β keeps+// the CLI at <prefix>/lib/node_modules/ruflo/node_modules/@claude-flow/cli,+// which none of the project-relative candidates above cover, so on those+// machines every refresh fell back to npx: a second, separately cached copy+// of the CLI that follows the registry's latest rather than the version the+// user pinned (the same npx-cache skew as #3306), and that cannot start+// offline on a cold cache.+//+// Three lookups, fs calls only (no child process), reached only after every+// candidate above missed:+// 1. npm's global prefix, resolved the way npm resolves it+// (npmGlobalPrefix() below). First because it does not depend on PATH:+// a hook inherits the host process's PATH, which need not contain the+// prefix's bin/ even when the user's interactive shell does (observed:+// the Claude Code process spawning hooks lacked ~/.npm-global/bin while+// a login zsh on the same machine had it).+// 2. `ruflo`, then `claude-flow`, on PATH β the order plugins/ruflo-core/+// scripts/ruflo-hook.cjs uses β for globals npm did not install (yarn+// classic, bun). Only a symlinked bin counts, and only when it lands in+// a package that declares one of the three known names, so a wrapper+// script or a version-manager shim (Volta) is never mistaken for an+// install. The <dir>/node_modules/<name> layout npm uses on Windows,+// where ruflo.cmd sits beside node_modules\ruflo (what resolveNpmShim()+// in ruflo-hook.cjs maps), is only consulted on win32: on POSIX every+// manager symlinks, and probing it there would follow a Windows install+// exposed to WSL through the appended Windows PATH.+// Relative PATH entries (`.` or an empty entry) are skipped, so a bare+// `./ruflo` in the working directory is never picked up.+// 3. ~/.npm-global, npm's documented no-sudo prefix, when 1 and 2 both+// missed: the prefix setting may live where this hook's node never+// reads it, and a wrapper script on PATH is skipped by 2.+// `env`/`platform`/`execPath` are parameters so any layout is testable+// from any OS.+function resolveGlobalCliBin(env = process.env, platform = process.platform, execPath = process.execPath) {+ const prefix = npmGlobalPrefix(env, platform, execPath);+ if (prefix) {+ const hit = cliUnderPrefix(prefix, platform);+ if (hit) return hit;+ }+ const dirs = String(env.PATH || env.Path || '').split(platform === 'win32' ? ';' : ':');+ const exts = platform === 'win32' ? ['.cmd', ''] : [''];+ for (const name of ['ruflo', 'claude-flow']) {+ for (const dir of dirs) {+ if (!dir || !path.isAbsolute(dir)) continue;+ for (const ext of exts) {+ const shim = path.join(dir, name + ext);+ if (!fs.existsSync(shim)) continue;+ const roots = [];+ try {+ if (fs.lstatSync(shim).isSymbolicLink()) {+ const root = path.dirname(path.dirname(fs.realpathSync(shim)));+ if (isKnownPackageRoot(root)) roots.push(root);+ }+ } catch (e) { /* unreadable link β fall back to the layout roots */ }+ if (platform === 'win32') {+ roots.push(path.join(dir, 'node_modules', name));+ if (name === 'claude-flow') roots.push(path.join(dir, 'node_modules', '@claude-flow', 'cli'));+ }+ for (const root of roots) {+ const hit = cliInPackage(root);+ if (hit) return hit;+ }+ }+ }+ }+ // Last resort: ~/.npm-global, the prefix npm's own docs recommend for+ // global installs without sudo ("Resolving EACCES permissions errors").+ // The setting that points npm there can live where this hook's node never+ // looks (another node's builtin npmrc, or a wrapper script that sets it+ // per call), and a `ruflo` wrapper script on PATH is skipped above by+ // design. Without this, such a machine fell back to npx @latest on every+ // hook. Checked only after the configured prefix and PATH both miss, so it+ // can never override either.+ const home = env.HOME || env.USERPROFILE;+ if (home && path.isAbsolute(home)) {+ const hit = cliUnderPrefix(path.join(home, '.npm-global'), platform);+ if (hit) return hit;+ }+ return null;+}++// The CLI of a global install under an npm prefix: <prefix>/lib/node_modules+// on POSIX, <prefix>\node_modules on Windows, trying the three published+// package names in order.+function cliUnderPrefix(prefix, platform) {+ const modules = platform === 'win32'+ ? path.join(prefix, 'node_modules')+ : path.join(prefix, 'lib', 'node_modules');+ for (const pkg of ['ruflo', 'claude-flow', path.join('@claude-flow', 'cli')]) {+ const hit = cliInPackage(path.join(modules, pkg));+ if (hit) return hit;+ }+ return null;+}++// A bin on PATH only counts as an install when the package it points into+// declares one of the three published names. This is a narrower check than+// resolveNpmShim() in ruflo-hook.cjs, which never reads `name`: that one takes+// the package name from the shim's own filename, then validates package.json's+// `bin` entry and that its realpath stays inside the package. Here the bin has+// already been resolved to a package root, so the manifest `name` is what+// identifies it.+function isKnownPackageRoot(root) {+ try {+ const name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8')).name;+ return name === 'ruflo' || name === 'claude-flow' || name === '@claude-flow/cli';+ } catch (e) { return false; }+}++// Map an installed ruflo / claude-flow / @claude-flow/cli package root to the+// CLI it runs: <root>/bin/cli.js (@claude-flow/cli itself),+// <root>/v3/@claude-flow/cli/bin/cli.js (the claude-flow umbrella bundles+// it), or @claude-flow/cli in the node_modules npm nests inside <root> β+// or, for the flat layout yarn classic and bun use, in the node_modules+// folder that holds <root> itself. That is the dependency edge+// ruflo/bin/ruflo.js's findCliPath() follows. The search stops at that one+// enclosing node_modules: walking further up would reach unrelated trees,+// such as a stray ~/node_modules left by an `npm i` in a home directory.+// Every hit must still pass isRunnableCli().+function cliInPackage(root) {+ if (!fs.existsSync(root)) return null;+ const candidates = [+ path.join(root, 'bin', 'cli.js'),+ path.join(root, 'v3', '@claude-flow', 'cli', 'bin', 'cli.js'),+ path.join(root, 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ ];+ for (let dir = path.dirname(root), i = 0; i < 4 && dir !== path.dirname(dir); i++, dir = path.dirname(dir)) {+ if (path.basename(dir) === 'node_modules') {+ candidates.push(path.join(dir, '@claude-flow', 'cli', 'bin', 'cli.js'));+ break;+ }+ }+ return candidates.find(isRunnableCli) || null;+}++// npm's global prefix without spawning npm (`npm prefix -g` measured 70-80 ms+// per call, paid on every SessionStart that gets this far). Same precedence+// npm applies:+// 1. npm_config_prefix in the environment (npm accepts either case);+// 2. `prefix=` in the user npmrc ($npm_config_userconfig, else ~/.npmrc),+// where `npm config set prefix ~/.npm-global` (the npm docs' fix for+// EACCES on global installs) writes it;+// 3. `prefix=` in npm's builtin npmrc (<npm package>/npmrc), found through+// the `npm` link beside node: Homebrew writes `prefix = /opt/homebrew`+// there (its process.execPath is the Cellar path, so step 4 alone would+// be wrong), and the Node.js Windows installer ships+// `prefix=${APPDATA}\npm`;+// 4. npm's default: $PREFIX, else the directory above node's bin/ (POSIX)+// or node.exe's own directory (Windows).+// Values follow npm's ini handling for the cases that decide a path: a+// quoted value is taken literally, an unquoted `;`/`#` starts a comment,+// keys below a `[section]` header are ignored, `${VAR}` expands when the+// variable is set (and `${VAR?}` to empty when it is not) but otherwise+// stays literal like npm β which leaves the value relative, so the+// isAbsolute() check below rejects it instead of pointing at the drive root.+// Not emulated: escaped characters and npm's other ini corner cases; each of+// those produces a miss, never a wrong CLI. The npmrc is read into memory,+// but only the value of its last top-level `prefix =` line is kept: no other+// line (an `_authToken`, say) is returned, stored or logged.+function npmGlobalPrefix(env = process.env, platform = process.platform, execPath = process.execPath) {+ const home = (platform === 'win32' ? env.USERPROFILE : env.HOME) || os.homedir();+ const readPrefix = (file) => {+ let value = null;+ try {+ for (const line of fs.readFileSync(file, 'utf-8').split(/\r?\n/)) {+ if (/^\s*\[/.test(line)) break; // only the top-level section applies+ const m = /^\s*prefix\s*=\s*(.*?)\s*$/.exec(line);+ if (m) value = m[1]; // last one wins, as in npm's ini parser+ }+ } catch (e) { /* no such npmrc */ }+ return value;+ };+ const nodeDir = path.dirname(execPath);+ // npm's builtin npmrc sits in npm's own package dir. On Windows that is+ // node_modules\npm beside node.exe; elsewhere follow the `npm` link beside+ // node (<npm>/bin/npm-cli.js) β on Homebrew it points out of the node keg+ // to /opt/homebrew/lib/node_modules/npm.+ let builtinRc = path.join(nodeDir, 'node_modules', 'npm', 'npmrc');+ if (platform !== 'win32') {+ try {+ builtinRc = path.join(path.dirname(path.dirname(fs.realpathSync(path.join(nodeDir, 'npm')))), 'npmrc');+ } catch (e) { /* no npm beside node */ }+ }+ const raw = env.npm_config_prefix || env.NPM_CONFIG_PREFIX+ || readPrefix(env.npm_config_userconfig || env.NPM_CONFIG_USERCONFIG || path.join(home, '.npmrc'))+ || readPrefix(builtinRc)+ || env.PREFIX+ || (platform === 'win32' ? nodeDir : path.dirname(nodeDir));+ let value = String(raw).trim();+ const quoted = /^(["'])([\s\S]*)\1$/.exec(value);+ if (quoted) value = quoted[2];+ else value = value.replace(/(^|[^\\])[;#].*$/, '$1').trim();+ value = value+ .replace(/\$\{([^}?]+)(\?)?\}/g, (whole, name, optional) => (+ env[name] !== undefined ? env[name] : (optional ? '' : whole)+ ))+ .replace(/^~(?=$|[\\/])/, home);+ return path.isAbsolute(value) ? path.resolve(value) : null;+}+// Fire-and-forget doesn't work when the CALLER is itself a short-lived// subprocess (confirmed live: two consecutive statusline renders 5s apart// both saw an empty funnel-messages-cache, because the async HTTPS fetch@@ -74,8 +288,8 @@ function resolveCliBinForHook() {// chance to write the cache. Never awaited here β must not add to// SessionStart's own timeout budget.//-// No usable local candidate (resolveCliBinForHook() returned null) falls-// back to npx: this call is detached/unref'd, so a slower npx cold-start+// No usable local or global candidate (resolveCliBinForHook() returned null)+// falls back to npx: this call is detached/unref'd, so a slower npx cold-start// costs nothing perceptible β unlike the statusline's own synchronous// render path, where local-first exists purely for per-render latency.// `--prefer-offline` avoids a registry round trip for the tarball when@@ -1060,4 +1274,7 @@ if (require.main === module) {// Which sibling helpers loaded (all CommonJS, shipped as .cjs β #3555).const loadedHelpers = { router: !!router, session: !!session, memory: !!memory, intelligence: !!intelligence };-module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers, ownedByMod, MOD_OWNABLE_EVENTS, resolveCliBinForHook, cliSpawnArgs, helperRoot, scanSessionStartSettingsForRisk, srFormatRiskFindingsForAutomaticBoot, srScanSettingsForRisk, srScanCommandStringForRisk, srScanAllowRuleForRisk, SR_DANGEROUS_COMMAND_WORDS, SR_SHELL_EXEC_WORDS, SR_DOWNLOADER_WORDS, SR_STANDALONE_RISK_PATTERNS };+// resolveGlobalCliBin/npmGlobalPrefix are exported for+// hook-handler-global-cli.test.ts; resolveCliBinForHook for anyone checking+// what a given machine resolves to without running a hook (#3368).+module.exports = { runWithTimeout, INTELLIGENCE_TIMEOUT_MS, loadedHelpers, ownedByMod, MOD_OWNABLE_EVENTS, resolveCliBinForHook, resolveGlobalCliBin, npmGlobalPrefix, cliSpawnArgs, helperRoot, scanSessionStartSettingsForRisk, srFormatRiskFindingsForAutomaticBoot, srScanSettingsForRisk, srScanCommandStringForRisk, srScanAllowRuleForRisk, SR_DANGEROUS_COMMAND_WORDS, SR_SHELL_EXEC_WORDS, SR_DOWNLOADER_WORDS, SR_STANDALONE_RISK_PATTERNS };diff --git a/v3/@claude-flow/cli/__tests__/hook-handler-global-cli.test.ts b/v3/@claude-flow/cli/__tests__/hook-handler-global-cli.test.tsnew file mode 100644index 0000000000..dc1b546f8b--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/hook-handler-global-cli.test.ts@@ -0,0 +1,394 @@+/**+ * hook-handler.cjs must find a globally-installed CLI before falling back to+ * npx (#3368).+ *+ * `npm install -g ruflo` (the README's global install) puts the CLI at+ * <prefix>/lib/node_modules/ruflo/node_modules/@claude-flow/cli, which none+ * of resolveCliBinForHook()'s project-relative candidates cover. Every+ * SessionStart on such a machine therefore spawned+ * `npx --prefer-offline --prefix <helper root> @claude-flow/cli hooks refresh-*`: a second copy of+ * the CLI that follows the registry's latest instead of the pinned version,+ * and cannot start offline on a cold npx cache.+ *+ * Each end-to-end case builds a fake install layout in a temp dir, puts an+ * `npx` trap first on PATH (it only logs its argv; the real npx is never+ * reachable), runs the hook exactly as Claude Code's SessionStart does, and+ * asserts which binary the two detached refreshes actually ran. The+ * "resolves" cases fail on the unfixed helper (both refreshes hit the npx+ * trap); the "still" cases pin behaviour the fix must not change.+ *+ * Hermetic: every case points HOME at an empty dir and sets npm's prefix+ * explicitly (npm_config_prefix, or a sandbox ~/.npmrc), so the host's own+ * npm config and global installs can never leak into a result.+ */+import { describe, it, expect, afterAll } from 'vitest';+import { spawnSync } from 'node:child_process';+import { createRequire } from 'node:module';+import {+ chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync,+ realpathSync, rmSync, symlinkSync, writeFileSync,+} from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const here = path.dirname(fileURLToPath(import.meta.url));+// The shipped copy; hook-handler-artifact-parity.test.ts keeps the repo's+// dogfood copy byte-identical to it.+const HOOK_HANDLER = path.resolve(here, '../.claude/helpers/hook-handler.cjs');++const sandboxes: string[] = [];+afterAll(() => {+ for (const dir of sandboxes) rmSync(dir, { recursive: true, force: true });+});++interface Sandbox { root: string; home: string; project: string; hook: string; trap: string; noPrefix: string }++function sandbox(): Sandbox {+ // realpath: macOS tmpdir() is a symlink (/var -> /private/var), and the+ // resolver reports realpath'd locations.+ const root = realpathSync(mkdtempSync(path.join(tmpdir(), 'hook-global-cli-')));+ sandboxes.push(root);+ const home = path.join(root, 'home'); // empty: no ~/.npmrc, no ~/.claude/plugins checkout+ const project = path.join(root, 'project');+ const helpers = path.join(project, '.claude', 'helpers');+ const trap = path.join(root, 'trap');+ const noPrefix = path.join(root, 'empty-npm-prefix');+ for (const d of [home, helpers, trap, noPrefix]) mkdirSync(d, { recursive: true });+ const hook = path.join(helpers, 'hook-handler.cjs');+ copyFileSync(HOOK_HANDLER, hook);+ writeFileSync(path.join(trap, 'npx'), '#!/bin/sh\nprintf "%s\\n" "$*" >> "$NPX_LOG"\n');+ chmodSync(path.join(trap, 'npx'), 0o755);+ return { root, home, project, hook, trap, noPrefix };+}++function write(file: string, content: string, mode?: number) {+ mkdirSync(path.dirname(file), { recursive: true });+ writeFileSync(file, content);+ if (mode) chmodSync(file, mode);+}++/** A built @claude-flow/cli whose bin/cli.js records how it was invoked. */+function fakeCli(dir: string, { built = true } = {}): string {+ const bin = path.join(dir, 'bin', 'cli.js');+ write(path.join(dir, 'package.json'), '{"name":"@claude-flow/cli","version":"3.42.4"}');+ write(bin,+ "require('fs').appendFileSync(process.env.CLI_LOG, " ++ "JSON.stringify({ bin: __filename, args: process.argv.slice(2) }) + '\\n');\n", 0o755);+ if (built) write(path.join(dir, 'dist', 'src', 'index.js'), 'export {};\n');+ return bin;+}++/** A package with a bin entry, linked from binDir the way npm/yarn/bun link it. */+function linkedPackage(pkgDir: string, name: string, entry: string, binDir: string) {+ write(path.join(pkgDir, 'package.json'), JSON.stringify({ name }));+ if (!existsSync(path.join(pkgDir, entry))) write(path.join(pkgDir, entry), '// entry\n', 0o755);+ mkdirSync(binDir, { recursive: true });+ const command = name === 'ruflo' ? 'ruflo' : 'claude-flow';+ symlinkSync(path.relative(binDir, path.join(pkgDir, entry)), path.join(binDir, command));+}++/** `npm install -g ruflo` under `prefix`: bin/ruflo -> lib/node_modules/ruflo, CLI nested. */+function npmGlobalRuflo(prefix: string, opts?: { built?: boolean }): string {+ const pkg = path.join(prefix, 'lib', 'node_modules', 'ruflo');+ const cli = fakeCli(path.join(pkg, 'node_modules', '@claude-flow', 'cli'), opts);+ linkedPackage(pkg, 'ruflo', 'bin/ruflo.js', path.join(prefix, 'bin'));+ return cli;+}++type Env = Record<string, string | undefined>;++async function runSessionRestore(sb: Sandbox, pathDirs: string[], env: Env = {}) {+ const npxLog = path.join(sb.root, 'npx.log');+ const cliLog = path.join(sb.root, 'cli.log');+ const fullEnv: Env = {+ HOME: sb.home,+ USERPROFILE: sb.home,+ PATH: [sb.trap, ...pathDirs].join(path.delimiter),+ npm_config_prefix: sb.noPrefix, // overridden (or removed) per case+ RUFLO_NO_AUTO_ENABLE: '1',+ NPX_LOG: npxLog,+ CLI_LOG: cliLog,+ ...env,+ };+ for (const k of Object.keys(fullEnv)) if (fullEnv[k] === undefined) delete fullEnv[k];+ const run = spawnSync(process.execPath, [sb.hook, 'session-restore'], {+ cwd: sb.project, input: '', encoding: 'utf8', timeout: 15_000, env: fullEnv as NodeJS.ProcessEnv,+ });+ expect(run.status).toBe(0);+ const read = (f: string) => (existsSync(f) ? readFileSync(f, 'utf8').trim().split('\n').filter(Boolean) : []);+ // Both refreshes are detached + unref'd; wait for them to record.+ for (let waited = 0; waited < 10_000; waited += 50) {+ if (read(npxLog).length + read(cliLog).length >= 2) break;+ await new Promise((r) => setTimeout(r, 50));+ }+ return { npx: read(npxLog), cli: read(cliLog).map((l) => JSON.parse(l) as { bin: string; args: string[] }) };+}++type Result = Awaited<ReturnType<typeof runSessionRestore>>;++function expectRanCli(result: Result, bin: string) {+ expect(result.npx, 'no refresh may fall back to npx').toEqual([]);+ expect(result.cli.map((c) => c.bin)).toEqual([bin, bin]);+ expect(result.cli.map((c) => c.args)).toEqual(expect.arrayContaining([+ ['hooks', 'refresh-funnel', '--quiet'],+ ['hooks', 'refresh-advisor', '--quiet'],+ ]));+}++// The npx fallback resolves from the helper's own install root, which for+// the sandbox's project-level helper is the project (cliSpawnArgs()).+function expectFellBackToNpx(result: Result, sb: Sandbox) {+ expect(result.cli).toEqual([]);+ expect(result.npx.sort()).toEqual([+ `--prefer-offline --prefix ${sb.project} @claude-flow/cli hooks refresh-advisor --quiet`,+ `--prefer-offline --prefix ${sb.project} @claude-flow/cli hooks refresh-funnel --quiet`,+ ]);+}++// Symlinks and a /bin/sh trap: these are the POSIX layouts. The Windows npm+// layout is covered below through resolveGlobalCliBin() directly.+describe.skipIf(process.platform === 'win32')('hook-handler.cjs β global CLI before npx (#3368)', () => {+ describe('via npm\'s global prefix', () => {+ it('resolves `npm i -g ruflo` with the prefix set in ~/.npmrc and its bin/ NOT on PATH (the reported setup)', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const prefix = path.join(sb.root, 'npm-global');+ const cli = npmGlobalRuflo(prefix);+ write(path.join(sb.home, '.npmrc'), `prefix=${prefix}\n`);+ expectRanCli(await runSessionRestore(sb, [], { npm_config_prefix: undefined }), cli);+ });++ it('resolves `npm i -g claude-flow` (umbrella bundles v3/@claude-flow/cli; its own bin/cli.js has no dist)', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const prefix = path.join(sb.root, 'npm-global');+ const pkg = path.join(prefix, 'lib', 'node_modules', 'claude-flow');+ const cli = fakeCli(path.join(pkg, 'v3', '@claude-flow', 'cli'));+ write(path.join(pkg, 'bin', 'cli.js'), '// umbrella proxy; must not be picked (no dist beside it)\n', 0o755);+ expectRanCli(await runSessionRestore(sb, [], { npm_config_prefix: prefix }), cli);+ });++ it('resolves `npm i -g @claude-flow/cli` (the package is the CLI itself)', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const prefix = path.join(sb.root, 'npm-global');+ const cli = fakeCli(path.join(prefix, 'lib', 'node_modules', '@claude-flow', 'cli'));+ expectRanCli(await runSessionRestore(sb, [], { NPM_CONFIG_PREFIX: prefix, npm_config_prefix: undefined }), cli);+ });+ });++ describe('via PATH', () => {+ it('resolves a `ruflo` on PATH installed under a prefix npm is no longer configured for', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const other = path.join(sb.root, 'other-prefix');+ const cli = npmGlobalRuflo(other);+ expectRanCli(await runSessionRestore(sb, [path.join(other, 'bin')]), cli);+ });++ it('resolves a yarn/bun global (dependency hoisted beside ruflo, not nested)', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const globalDir = path.join(sb.root, 'bun', 'install', 'global', 'node_modules');+ const cli = fakeCli(path.join(globalDir, '@claude-flow', 'cli'));+ linkedPackage(path.join(globalDir, 'ruflo'), 'ruflo', 'bin/ruflo.js', path.join(sb.root, 'bun', 'bin'));+ expectRanCli(await runSessionRestore(sb, [path.join(sb.root, 'bun', 'bin')]), cli);+ });+ });++ describe('via ~/.npm-global (npm\'s documented no-sudo prefix)', () => {+ it('resolves ~/.npm-global when no npmrc points there and the only `ruflo` on PATH is a wrapper script', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const cli = npmGlobalRuflo(path.join(sb.home, '.npm-global'));+ // A wrapper that pins node and runs the install directly: a regular+ // file, so the PATH lookup skips it by design.+ const wrapBin = path.join(sb.root, 'wrapper-bin');+ write(path.join(wrapBin, 'ruflo'), '#!/bin/sh\nexec node "$HOME/.npm-global/lib/node_modules/ruflo/bin/ruflo.js" "$@"\n', 0o755);+ expectRanCli(await runSessionRestore(sb, [wrapBin]), cli);+ });+ });++ describe('unchanged behaviour', () => {+ it('still prefers a project-local install over a global one', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const local = fakeCli(path.join(sb.project, 'node_modules', '@claude-flow', 'cli'));+ const prefix = path.join(sb.root, 'npm-global');+ npmGlobalRuflo(prefix);+ expectRanCli(await runSessionRestore(sb, [path.join(prefix, 'bin')], { npm_config_prefix: prefix }), local);+ });++ it('still falls back to npx when the global CLI has no compiled dist', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const prefix = path.join(sb.root, 'npm-global');+ npmGlobalRuflo(prefix, { built: false });+ expectFellBackToNpx(await runSessionRestore(sb, [path.join(prefix, 'bin')], { npm_config_prefix: prefix }), sb);+ });++ it('still falls back to npx when there is no global install at all', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ expectFellBackToNpx(await runSessionRestore(sb, []), sb);+ });++ it('never trusts a relative PATH entry, so a bare `./ruflo` is not picked up', { timeout: 30_000 }, async () => {+ const sb = sandbox();+ const pkg = path.join(sb.project, 'vendor', 'ruflo');+ fakeCli(path.join(pkg, 'node_modules', '@claude-flow', 'cli'));+ linkedPackage(pkg, 'ruflo', 'bin/ruflo.js', sb.project); // ./ruflo in the project root+ expectFellBackToNpx(await runSessionRestore(sb, ['.']), sb);+ });+ });+});++describe('hook-handler.cjs β resolveGlobalCliBin() / npmGlobalPrefix() units (#3368)', () => {+ // Load a sandbox copy: it has no router/session/intelligence siblings to+ // side-effect on require, and require() never runs main() (require.main guard).+ function load(sb: Sandbox) {+ return createRequire(import.meta.url)(sb.hook) as {+ resolveGlobalCliBin: (env: Env, platform?: string, execPath?: string) => string | null;+ npmGlobalPrefix: (env: Env, platform?: string, execPath?: string) => string | null;+ };+ }++ // npm on Windows puts ruflo.cmd (plus sh/ps1 shims) straight into the+ // prefix, beside node_modules\ruflo, with no lib/ level and nothing to+ // realpath. Same layout resolveNpmShim() in ruflo-hook.cjs maps.+ it('maps the Windows npm layout via the prefix and via ruflo.cmd on PATH', () => {+ const sb = sandbox();+ const { resolveGlobalCliBin } = load(sb);+ const prefix = path.join(sb.root, 'AppData', 'Roaming', 'npm');+ write(path.join(prefix, 'ruflo.cmd'), '@ECHO off\r\n');+ const cli = fakeCli(path.join(prefix, 'node_modules', 'ruflo', 'node_modules', '@claude-flow', 'cli'));+ const base = { USERPROFILE: sb.home };+ expect(resolveGlobalCliBin({ ...base, npm_config_prefix: prefix }, 'win32')).toBe(cli);+ expect(resolveGlobalCliBin({ ...base, npm_config_prefix: sb.noPrefix, Path: prefix }, 'win32')).toBe(cli);+ expect(resolveGlobalCliBin({ ...base, npm_config_prefix: sb.noPrefix, PATH: sb.home }, 'win32')).toBeNull();+ });++ it('reads the prefix the way npm does: env over ~/.npmrc, last line wins, ~ and ${VAR} expanded', () => {+ const sb = sandbox();+ const { npmGlobalPrefix } = load(sb);+ const npmrc = path.join(sb.home, '.npmrc');+ const env = { HOME: sb.home, BASE: '/opt/base' };+ write(npmrc, '; comment\n//registry.npmjs.org/:_authToken=secret\nprefix=/first\nprefix = ~/.npm-global\n');+ expect(npmGlobalPrefix(env, 'darwin')).toBe(path.join(sb.home, '.npm-global'));+ expect(npmGlobalPrefix({ ...env, npm_config_prefix: '/from-env' }, 'darwin')).toBe(path.resolve('/from-env'));+ expect(npmGlobalPrefix({ ...env, NPM_CONFIG_PREFIX: '/from-env-upper' }, 'darwin')).toBe(path.resolve('/from-env-upper'));+ write(npmrc, 'prefix="${BASE}/npm"\r\n');+ expect(npmGlobalPrefix(env, 'darwin')).toBe(path.resolve('/opt/base/npm'));+ const custom = path.join(sb.root, 'custom-npmrc');+ write(custom, 'prefix=/via-userconfig\n');+ expect(npmGlobalPrefix({ ...env, npm_config_userconfig: custom }, 'darwin')).toBe(path.resolve('/via-userconfig'));+ expect(npmGlobalPrefix({ ...env, npm_config_prefix: 'relative/dir' }, 'darwin')).toBeNull();+ });++ it('keeps an undefined ${VAR} literal, as npm does, instead of anchoring the path at the root', () => {+ const sb = sandbox();+ const { npmGlobalPrefix } = load(sb);+ const env = { HOME: sb.home };+ write(path.join(sb.home, '.npmrc'), 'prefix=${NOT_SET}/npm-global\n');+ // Left literal the value is relative, so it is rejected β not turned into+ // "/npm-global" next to the drive root.+ expect(npmGlobalPrefix(env, 'darwin')).not.toBe(path.resolve('/npm-global'));+ expect(npmGlobalPrefix(env, 'darwin')).toBeNull();+ // `${VAR?}` is npm's "empty if unset" form.+ write(path.join(sb.home, '.npmrc'), 'prefix=/opt${NOT_SET?}/npm\n');+ expect(npmGlobalPrefix(env, 'darwin')).toBe(path.resolve('/opt/npm'));+ });++ it('ignores an inline comment and any key below a [section] header', () => {+ const sb = sandbox();+ const { npmGlobalPrefix } = load(sb);+ const env = { HOME: sb.home };+ write(path.join(sb.home, '.npmrc'), 'prefix=/opt/one ; trailing comment\n');+ expect(npmGlobalPrefix(env, 'darwin')).toBe(path.resolve('/opt/one'));+ write(path.join(sb.home, '.npmrc'), 'prefix=/opt/one\n[scope]\nprefix=/opt/sectioned\n');+ expect(npmGlobalPrefix(env, 'darwin')).toBe(path.resolve('/opt/one'));+ });++ // Steps 3 and 4 of npmGlobalPrefix(): the builtin npmrc in npm's own+ // package (Homebrew keeps npm outside the node keg, which is why+ // process.execPath alone is not enough) and npm's default prefix.+ it('follows the `npm` link beside node to npm\'s builtin npmrc (the Homebrew keg case)', () => {+ const sb = sandbox();+ const { npmGlobalPrefix, resolveGlobalCliBin } = load(sb);+ const keg = path.join(sb.root, 'Cellar', 'node', '26.8.2');+ const prefix = path.join(sb.root, 'brew-prefix');+ const npmPkg = path.join(prefix, 'lib', 'node_modules', 'npm');+ write(path.join(npmPkg, 'bin', 'npm-cli.js'), '// npm\n');+ write(path.join(keg, 'bin', 'node'), '// node\n', 0o755);+ symlinkSync(path.join(npmPkg, 'bin', 'npm-cli.js'), path.join(keg, 'bin', 'npm'));+ write(path.join(npmPkg, 'npmrc'), `prefix = ${prefix}\n`);+ const execPath = path.join(keg, 'bin', 'node');+ const env = { HOME: sb.home };+ expect(npmGlobalPrefix(env, 'darwin', execPath)).toBe(prefix);+ // β¦and the whole lookup finds a global install with no env hint and no PATH.+ const cli = npmGlobalRuflo(prefix);+ expect(resolveGlobalCliBin(env, 'darwin', execPath)).toBe(cli);+ });++ it('falls back to $PREFIX, then to the directory above node/bin, when no npmrc sets one', () => {+ const sb = sandbox();+ const { npmGlobalPrefix } = load(sb);+ const execPath = path.join(sb.root, 'nvm', 'v26', 'bin', 'node');+ write(execPath, '// node\n', 0o755);+ expect(npmGlobalPrefix({ HOME: sb.home }, 'darwin', execPath)).toBe(path.join(sb.root, 'nvm', 'v26'));+ expect(npmGlobalPrefix({ HOME: sb.home, PREFIX: path.join(sb.root, 'from-prefix-env') }, 'darwin', execPath))+ .toBe(path.join(sb.root, 'from-prefix-env'));+ });++ it('reads the Windows builtin npmrc beside node.exe and expands ${APPDATA}', () => {+ const sb = sandbox();+ const { npmGlobalPrefix } = load(sb);+ const nodeDir = path.join(sb.root, 'Program Files', 'nodejs');+ write(path.join(nodeDir, 'node_modules', 'npm', 'npmrc'), 'prefix=${APPDATA}\\npm\n');+ const appData = path.join(sb.root, 'AppData', 'Roaming');+ const execPath = path.join(nodeDir, 'node.exe');+ // Windows path separators only resolve on win32, so assert that the+ // ${APPDATA} expansion happened rather than the exact joined form.+ expect(npmGlobalPrefix({ USERPROFILE: sb.home, APPDATA: appData }, 'win32', execPath))+ .toContain(appData);+ // With APPDATA unset the value stays literal, so it is relative and rejected.+ expect(npmGlobalPrefix({ USERPROFILE: sb.home }, 'win32', execPath)).toBeNull();+ });++ // The PATH lookup only trusts a symlink into a package that names itself.+ it('ignores a `ruflo` on PATH that is a wrapper script or a version-manager shim', () => {+ const sb = sandbox();+ const { resolveGlobalCliBin } = load(sb);+ const env = { HOME: sb.home, npm_config_prefix: sb.noPrefix };+ // A built CLI sitting in a stray node_modules above the shim's target,+ // e.g. left by an `npm i @claude-flow/cli` in a home directory.+ fakeCli(path.join(sb.root, 'stray', 'node_modules', '@claude-flow', 'cli'));+ const binDir = path.join(sb.root, 'stray', 'volta', 'bin');+ mkdirSync(binDir, { recursive: true });+ write(path.join(sb.root, 'stray', 'volta', 'volta-shim'), '#!/bin/sh\n', 0o755);+ symlinkSync(path.join(sb.root, 'stray', 'volta', 'volta-shim'), path.join(binDir, 'ruflo'));+ expect(resolveGlobalCliBin({ ...env, PATH: binDir }, 'darwin')).toBeNull();+ });++ // WSL appends the Windows PATH, which includes %APPDATA%\npm β where npm+ // writes an extensionless `ruflo` sh shim beside node_modules\ruflo.+ it('does not apply the Windows folder layout on POSIX (WSL keeps its own CLI)', () => {+ const sb = sandbox();+ const { resolveGlobalCliBin } = load(sb);+ const winPrefix = path.join(sb.root, 'mnt', 'c', 'Users', 'me', 'AppData', 'Roaming', 'npm');+ write(path.join(winPrefix, 'ruflo'), '#!/bin/sh\n', 0o755); // npm's sh shim, not a symlink+ fakeCli(path.join(winPrefix, 'node_modules', 'ruflo', 'node_modules', '@claude-flow', 'cli'));+ const env = { HOME: sb.home, npm_config_prefix: sb.noPrefix, PATH: winPrefix };+ expect(resolveGlobalCliBin(env, 'linux')).toBeNull();+ expect(resolveGlobalCliBin(env, 'win32')).not.toBeNull();+ });++ it('uses ~/.npm-global only after the configured prefix and PATH both miss', () => {+ const sb = sandbox();+ const { resolveGlobalCliBin } = load(sb);+ const fallback = npmGlobalRuflo(path.join(sb.home, '.npm-global'));+ const configured = path.join(sb.root, 'configured-prefix');+ const preferred = npmGlobalRuflo(configured);+ expect(resolveGlobalCliBin({ HOME: sb.home, npm_config_prefix: configured, PATH: '' }, 'darwin')).toBe(preferred);+ expect(resolveGlobalCliBin({ HOME: sb.home, npm_config_prefix: sb.noPrefix, PATH: '' }, 'darwin')).toBe(fallback);+ });++ it('ignores a ~/.npm-global install whose CLI has no compiled dist', () => {+ const sb = sandbox();+ const { resolveGlobalCliBin } = load(sb);+ npmGlobalRuflo(path.join(sb.home, '.npm-global'), { built: false });+ expect(resolveGlobalCliBin({ HOME: sb.home, npm_config_prefix: sb.noPrefix, PATH: '' }, 'darwin')).toBeNull();+ });+});