@claude-flow/cli 3.25.6 → 3.26.0

package/dist/src/init/helper-refresh.d.ts

@@ -1,5 +1,10 @@
 export declare const HELPERS_STAMP_FILE = ".helpers-version";
-/** ruflo-owned helpers that carry hook logic and must track the package version. */
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
 export declare const CRITICAL_HELPERS: string[];
 /** Installed @claude-flow/cli version — the value the helpers are stamped with. */
 export declare function getInstalledCliVersion(): string;
@@ -9,8 +14,34 @@ export declare function getInstalledCliVersion(): string;
  * stamp read + string compare (sub-ms); the copy runs at most once per version
  * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
  * existing hook-handler.cjs — never creates files in an unrelated directory).
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) against THIS project directory
+ * would see its own older version != the project's newer stamp and silently
+ * overwrite hand-fixed `hook-handler.cjs`/`intelligence.cjs` with its own
+ * older, already-superseded bundled copies. Comparing with `semver.gt`
+ * instead of `!==` makes that impossible: an older or equal installed
+ * version is always a no-op, regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
+ * THIS repo's actual current `.claude/helpers` + its real Ed25519 signature —
+ * fine for production (that coupling to the real source IS the point), but
+ * it means a test exercising that path for real would only pass when this
+ * repo's manifest happens to be currently re-signed, which is a separately-
+ * gated, occasionally-stale publish-time step. `sourceDirOverride` +
+ * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash →
+ * copy logic without depending on that.
  */
-export declare function autoRefreshHelpersIfStale(cwd: string): Promise<{
+export declare function autoRefreshHelpersIfStale(cwd: string, opts?: {
+    sourceDirOverride?: string;
+    pubkeyPemOverride?: string;
+    versionOverride?: string;
+}): Promise<{
     refreshed: boolean;
     from?: string;
     to?: string;

package/dist/src/init/helper-refresh.js

@@ -17,11 +17,55 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
+import * as semver from 'semver';
 import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Walk up from `startDir` to the nearest ancestor whose `package.json` names
+ * `@claude-flow/cli` — depth-independent, unlike a hardcoded `'..','..',
+ * '..'`. That fixed count assumed this module always runs compiled, three
+ * levels under the package root (`dist/src/init/helper-refresh.js`); it
+ * silently breaks whenever the module runs from a different depth — e.g.
+ * loaded straight from `src/init/helper-refresh.ts` (one level shallower:
+ * ts-node, tsx, or a test runner that transforms TS in place rather than
+ * requiring a prior `tsc` build). When that happened here, BOTH
+ * `getInstalledCliVersion()` silently fell back to the placeholder `'0.0.0'`
+ * AND `findPackageHelpersDir()` silently failed to resolve the real package
+ * helpers dir — with no error surfaced, just wrong values propagating into
+ * version-comparison and refresh-source-selection logic. Real ceiling on the
+ * walk (`maxUp`) so a package.json-less filesystem can't loop forever.
+ */
+function findPackageRoot(startDir, maxUp = 6) {
+    let dir = startDir;
+    for (let i = 0; i < maxUp; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+            if (pkg && pkg.name === '@claude-flow/cli')
+                return dir;
+        }
+        catch { /* no package.json here, or unreadable — keep climbing */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return null;
+}
 export const HELPERS_STAMP_FILE = '.helpers-version';
-/** ruflo-owned helpers that carry hook logic and must track the package version. */
-export const CRITICAL_HELPERS = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
+export const CRITICAL_HELPERS = [
+    'auto-memory-hook.mjs',
+    'hook-handler.cjs',
+    'intelligence.cjs',
+    // statusline.cjs is here so the funnel disclosure row (ADR-301) reaches
+    // existing installs on the next `ruflo` command, not only fresh `ruflo init`.
+    'statusline.cjs',
+];
 /** Installed @claude-flow/cli version — the value the helpers are stamped with. */
 export function getInstalledCliVersion() {
     try {
@@ -30,9 +74,11 @@ export function getInstalledCliVersion() {
         return String(pkg.version || '0.0.0');
     }
     catch {
-        // dist/src/init → package root
+        const root = findPackageRoot(__dirname);
+        if (!root)
+            return '0.0.0';
         try {
-            const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', 'package.json'), 'utf-8'));
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
             return String(pkg.version || '0.0.0');
         }
         catch {
@@ -49,7 +95,9 @@ function findPackageHelpersDir() {
         candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
     }
     catch { /* not resolvable */ }
-    candidates.push(path.resolve(__dirname, '..', '..', '..', '.claude', 'helpers'));
+    const root = findPackageRoot(__dirname);
+    if (root)
+        candidates.push(path.join(root, '.claude', 'helpers'));
     for (const c of candidates) {
         if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
             return c;
@@ -67,13 +115,16 @@ function findPackageHelpersDir() {
  * fallback needs no manifest — that content comes from the CLI's own compiled
  * code, which is already the trust root.
  */
-async function writeCriticalHelpers(helpersDir, version) {
-    const source = findPackageHelpersDir();
+async function writeCriticalHelpers(helpersDir, version, opts = {}) {
+    const source = opts.sourceDirOverride ?? findPackageHelpersDir();
     if (source) {
-        // 1. Verify the signed manifest against the baked public key.
+        // 1. Verify the signed manifest against the baked public key (or, in
+        // tests, an injected throwaway key — see autoRefreshHelpersIfStale's
+        // opts.pubkeyPemOverride doc comment for why that injection point
+        // exists at all).
         let trusted = null;
         try {
-            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'));
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'), opts.pubkeyPemOverride);
         }
         catch {
             trusted = null;
@@ -118,10 +169,19 @@ async function writeCriticalHelpers(helpersDir, version) {
     // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
     // OWN compiled generators (the trust root; no external file to verify).
     const gen = await import('./helpers-generator.js');
+    const statusGen = await import('./statusline-generator.js');
     const files = {
         'hook-handler.cjs': gen.generateHookHandler(),
         'intelligence.cjs': gen.generateIntelligenceStub(),
         'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+        // Fallback needs the same generator inputs `ruflo init` uses. We match the
+        // hardcoded default (maxAgents 15) because the fallback fires when the
+        // installed package is unresolvable — no way to read the user's project
+        // config from here. Fresh `ruflo init` still generates a per-project value.
+        'statusline.cjs': statusGen.generateStatuslineScript({
+            statusline: { enabled: true, style: 'compact' },
+            runtime: { maxAgents: 15 },
+        }),
     };
     let wrote = false;
     for (const [name, content] of Object.entries(files)) {
@@ -147,13 +207,35 @@ async function writeCriticalHelpers(helpersDir, version) {
  * stamp read + string compare (sub-ms); the copy runs at most once per version
  * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
  * existing hook-handler.cjs — never creates files in an unrelated directory).
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) against THIS project directory
+ * would see its own older version != the project's newer stamp and silently
+ * overwrite hand-fixed `hook-handler.cjs`/`intelligence.cjs` with its own
+ * older, already-superseded bundled copies. Comparing with `semver.gt`
+ * instead of `!==` makes that impossible: an older or equal installed
+ * version is always a no-op, regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
+ * THIS repo's actual current `.claude/helpers` + its real Ed25519 signature —
+ * fine for production (that coupling to the real source IS the point), but
+ * it means a test exercising that path for real would only pass when this
+ * repo's manifest happens to be currently re-signed, which is a separately-
+ * gated, occasionally-stale publish-time step. `sourceDirOverride` +
+ * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash →
+ * copy logic without depending on that.
  */
-export async function autoRefreshHelpersIfStale(cwd) {
+export async function autoRefreshHelpersIfStale(cwd, opts = {}) {
     try {
         const helpersDir = path.join(cwd, '.claude', 'helpers');
         if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
             return { refreshed: false };
-        const version = getInstalledCliVersion();
+        const version = opts.versionOverride ?? getInstalledCliVersion();
         let stamped = '';
         try {
             stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
@@ -161,7 +243,15 @@ export async function autoRefreshHelpersIfStale(cwd) {
         catch { /* pre-feature: unstamped */ }
         if (stamped === version)
             return { refreshed: false }; // up to date — fast path
-        const res = await writeCriticalHelpers(helpersDir, version);
+        if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
+            // Stamped version is already >= what this binary reports — refreshing
+            // would silently DOWNGRADE the project's helpers. Skip, untouched.
+            return { refreshed: false };
+        }
+        const res = await writeCriticalHelpers(helpersDir, version, {
+            sourceDirOverride: opts.sourceDirOverride,
+            pubkeyPemOverride: opts.pubkeyPemOverride,
+        });
         // A blocked refresh is a SECURITY signal (tampered source/manifest) — surface
         // it, don't advance the stamp, and leave the project's existing helpers intact.
         if (res.blocked)

package/dist/src/init/helpers-generator.js

@@ -448,6 +448,7 @@ export function generateHookHandler() {
         '',
         "const path = require('path');",
         "const fs = require('fs');",
+        "const os = require('os');",
         '',
         'const helpersDir = __dirname;',
         '',
@@ -537,6 +538,57 @@ export function generateHookHandler() {
         '    } else {',
         "      console.log('[INFO] Router not available, using default routing');",
         '    }',
+        '',
+        '    // Rate-limit -> sponsored-capacity nudge (ADR-312/313). Fires here,',
+        '    // client-side, BEFORE the API call this prompt would make - so it',
+        '    // still reaches the transcript even if that call then fails from the',
+        '    // rate limit. Cheap local file reads only; never a network call or a',
+        '    // child process, so it cannot add latency to prompt submission.',
+        '    try {',
+        "      var rlFunnelEnv = process.env.RUFLO_FUNNEL;",
+        '      var rlDisabledByEnv = rlFunnelEnv !== undefined && /^(0|false|off|no)$/i.test(String(rlFunnelEnv).trim());',
+        "      var rlCiVars = ['CI', 'GITHUB_ACTIONS', 'GITLAB_CI', 'CIRCLECI', 'TRAVIS', 'BUILDKITE', 'JENKINS_URL', 'TEAMCITY_VERSION', 'TF_BUILD'];",
+        '      var rlIsCi = rlCiVars.some(function (v) {',
+        '        var val = process.env[v];',
+        "        return val !== undefined && val !== '' && val !== '0' && String(val).toLowerCase() !== 'false';",
+        '      });',
+        "      var rlHome = path.join(os.homedir(), '.ruflo');",
+        '      var rlUserDisabled = false;',
+        '      try {',
+        "        var rlUserCfg = JSON.parse(fs.readFileSync(path.join(rlHome, 'funnel.json'), 'utf8'));",
+        '        rlUserDisabled = !!(rlUserCfg && rlUserCfg.enabled === false);',
+        '      } catch (e) { /* absent/malformed = not disabled */ }',
+        '      var rlProjectDisabled = false;',
+        '      try {',
+        "        var rlProjCfg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'claude-flow.config.json'), 'utf8'));",
+        '        rlProjectDisabled = !!(rlProjCfg && rlProjCfg.funnel && rlProjCfg.funnel.enabled === false);',
+        '      } catch (e) { /* absent/malformed = not disabled */ }',
+        '',
+        '      if (!rlDisabledByEnv && !rlIsCi && !rlUserDisabled && !rlProjectDisabled) {',
+        '        var rlStatus = null;',
+        "        try { rlStatus = JSON.parse(fs.readFileSync(path.join(rlHome, 'rate-limit-status.json'), 'utf8')); } catch (e) { /* not flagged */ }",
+        '        var rlIsLimited = false;',
+        '        if (rlStatus && rlStatus.limited) {',
+        '          if (rlStatus.since) {',
+        '            var rlSinceMs = Date.parse(rlStatus.since);',
+        '            rlIsLimited = isNaN(rlSinceMs) ? true : (Date.now() - rlSinceMs) < 6 * 60 * 60 * 1000;',
+        '          } else {',
+        '            rlIsLimited = true;',
+        '          }',
+        '        }',
+        '        if (rlIsLimited) {',
+        '          var rlConsented = false;',
+        '          try {',
+        "            var rlConsentFile = JSON.parse(fs.readFileSync(path.join(rlHome, 'consent.json'), 'utf8'));",
+        "            var rlReceipt = rlConsentFile && rlConsentFile['sponsored-downtime'];",
+        '            rlConsented = !!(rlReceipt && rlReceipt.granted === true && rlReceipt.at !== null && rlReceipt.policyVersion === 1);',
+        '          } catch (e) { /* not consented */ }',
+        '          if (!rlConsented) {',
+        "            console.log('[COGNITUM] Hit your Claude usage limit? Free sponsored capacity is available at cognitum.one/meta-llm -- run: ruflo proxy sponsor-enable --yes');",
+        '          }',
+        '        }',
+        '      }',
+        '    } catch (e) { /* nudge must never break the hook */ }',
         '  },',
         '',
         "  'pre-bash': () => {",