Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

feat(mods): doctor reports which claude runs, mods-by-default from 2.1.287, stale/mixed installs (ADR-404)

ruvc84c559189b3
diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts
index 2639567183..d88295c2ba 100644
--- a/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts
+++ b/v3/@claude-flow/cli/__tests__/mods/mods-cli.test.ts
@@ -10,6 +10,7 @@ import { join } from 'node:path';
import { installMod, uninstallMod, withModEnabled, withModRemoved, ENABLE_ENV, MOD_PLUGIN_ID } from '../../src/mods/install.js';
import { projectionOf, syncPolicyProjection, PROJECTION_RELATIVE } from '../../src/mods/policy-projection.js';
import { probeMods } from '../../src/mods/probe.js';
+import { findClaudeInstalls, judgeInstalls, versionLess } from '../../src/mods/claude-installs.js';
import { modsCommand } from '../../src/commands/mods.js';
import { setPolicyMode, upsertPolicyRule } from '../../src/services/policy-runtime.js';
import { parseProjection } from '../../../../../plugins/ruflo-mods/hooks/guard/policy';
@@ -26,7 +27,7 @@ afterEach(() => {
});
const read = (p: string) => JSON.parse(readFileSync(p, 'utf8'));
const finding = (name: string, env: NodeJS.ProcessEnv = {}, managedPath = join(home, 'none.json')) =>
- probeMods({ projectRoot: root, home, env, managedPath }).find((f) => f.name === name)!;
+ probeMods({ projectRoot: root, home, env, managedPath, installs: [] }).find((f) => f.name === name)!;
describe('ADR-404 mods install / uninstall', () => {
it('enables the plugin, the marketplace and the early-access switch in settings.local.json', () => {
@@ -173,3 +174,44 @@ describe('ADR-404 mods probe and doctor', () => {
expect(read(join(root, '.claude', 'settings.local.json'))).toEqual({});
});
});
+
+describe('ADR-404 claude installs', () => {
+ const at = (path: string, version: string | null) => ({ path, version });
+
+ it('mods on by default from 2.1.287; the env var for 2.1.277..2.1.286; older predates mods', () => {
+ expect(judgeInstalls([at('/home/u/.local/bin/claude', '2.1.287')], false)).toMatchObject({ status: 'pass' });
+ expect(judgeInstalls([at('/c', '2.1.282')], false)).toMatchObject({ status: 'warn', message: expect.stringContaining('need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)') });
+ expect(judgeInstalls([at('/c', '2.1.282')], true)).toMatchObject({ status: 'pass' });
+ expect(judgeInstalls([at('/c', '2.1.107')], true)).toMatchObject({ status: 'warn', message: expect.stringContaining('predates mods') });
+ expect(judgeInstalls([], false).status).toBe('warn');
+ });
+
+ it('flags a mixed install: a stale claude first on PATH, or beside the current one', () => {
+ const shadowed = judgeInstalls([at('/usr/bin/claude', '2.1.107'), at('/home/u/.local/bin/claude', '2.1.287')], false);
+ expect(shadowed.status).toBe('warn');
+ expect(shadowed.message).toContain('predates mods');
+ expect(shadowed.message).toContain('also installed: /home/u/.local/bin/claude (2.1.287)');
+ const beside = judgeInstalls([at('/home/u/.local/bin/claude', '2.1.287'), at('/usr/bin/claude', '2.1.107')], false);
+ expect(beside).toMatchObject({ status: 'warn', message: expect.stringContaining('a stale one can shadow') });
+ });
+
+ it('versionLess compares numerically', () => {
+ expect(versionLess('2.1.107', '2.1.287')).toBe(true);
+ expect(versionLess('2.1.287', '2.1.287')).toBe(false);
+ expect(versionLess('2.10.0', '2.9.9')).toBe(false);
+ });
+
+ it('finds every claude on PATH in order, de-duplicated by real path', () => {
+ const a = mkdtempSync(join(tmpdir(), 'ruflo-mods-path-a-'));
+ const b = mkdtempSync(join(tmpdir(), 'ruflo-mods-path-b-'));
+ try {
+ writeFileSync(join(a, 'claude'), '');
+ writeFileSync(join(b, 'claude'), '');
+ const found = findClaudeInstalls({ PATH: [a, b, a].join(':') }, join(a, 'nohome'), (p) => (p.startsWith(a) ? '2.1.107' : '2.1.287'));
+ expect(found).toEqual([at(join(a, 'claude'), '2.1.107'), at(join(b, 'claude'), '2.1.287')]);
+ } finally {
+ rmSync(a, { recursive: true, force: true });
+ rmSync(b, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/src/mods/claude-installs.ts b/v3/@claude-flow/cli/src/mods/claude-installs.ts
new file mode 100644
index 0000000000..3523d805e9
--- /dev/null
+++ b/v3/@claude-flow/cli/src/mods/claude-installs.ts
@@ -0,0 +1,94 @@
+/**
+ * Which Claude Code binaries a shell would find, and whether the one it runs
+ * can load mods (ADR-404). Mods are on by default from Claude Code 2.1.287;
+ * from 2.1.277 they load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1; older
+ * builds predate them. A server-side rollout switch can still hold them off
+ * on any version (reported separately). A stale install earlier on PATH
+ * (a 2.1.107 npm-global beside a current native one, say) silently decides.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+export const MODS_DEFAULT_ON = '2.1.287';
+export const MODS_FIRST = '2.1.277';
+
+export interface ClaudeInstall {
+ path: string;
+ version: string | null;
+}
+
+export type VersionOf = (path: string) => string | null;
+
+const parse = (v: string) => v.split('.').map((n) => Number(n));
+/** a < b for dotted numeric versions. */
+export function versionLess(a: string, b: string): boolean {
+ const x = parse(a);
+ const y = parse(b);
+ for (let i = 0; i < Math.max(x.length, y.length); i++) {
+ if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) < (y[i] ?? 0);
+ }
+ return false;
+}
+
+/** `claude --version` of one binary, bounded; null when it cannot say. */
+export const defaultVersionOf: VersionOf = (path) => {
+ try {
+ const out = execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+ return out.match(/\d+\.\d+\.\d+/)?.[0] ?? null;
+ } catch {
+ return null;
+ }
+};
+
+/** Every `claude` on PATH, in PATH order (the first is what runs), plus ~/.local/bin. */
+export function findClaudeInstalls(env: NodeJS.ProcessEnv, home: string, versionOf: VersionOf = defaultVersionOf): ClaudeInstall[] {
+ const names = process.platform === 'win32' ? ['claude.exe', 'claude.cmd', 'claude'] : ['claude'];
+ const dirs = [...(env.PATH ?? '').split(delimiter).filter(Boolean), join(home, '.local', 'bin')];
+ const seen = new Set<string>();
+ const installs: ClaudeInstall[] = [];
+ for (const dir of dirs) {
+ for (const name of names) {
+ const path = join(dir, name);
+ let real: string;
+ try {
+ if (!existsSync(path) || !statSync(path).isFile()) continue;
+ real = realpathSync(path);
+ } catch {
+ continue;
+ }
+ if (seen.has(real)) continue;
+ seen.add(real);
+ installs.push({ path, version: versionOf(path) });
+ }
+ }
+ return installs;
+}
+
+export interface InstallsFinding {
+ status: 'pass' | 'warn';
+ message: string;
+ fix?: string;
+}
+
+/** The doctor's reading of what `claude` resolves to and what else is installed. */
+export function judgeInstalls(installs: readonly ClaudeInstall[], enableEnvSet: boolean): InstallsFinding {
+ if (installs.length === 0) return { status: 'warn', message: 'no claude binary on PATH', fix: 'install Claude Code >= 2.1.287' };
+ const [first] = installs;
+ const others = installs.slice(1).filter((i) => i.version !== first!.version);
+ const mixed = others.length
+ ? `; also installed: ${others.map((i) => `${i.path} (${i.version ?? 'unknown'})`).join(', ')}. The first on PATH runs; a stale one can shadow a current one.`
+ : '';
+ const runs = `${first!.path} (${first!.version ?? 'version unknown'})`;
+ if (!first!.version) return { status: 'warn', message: `claude resolves to ${runs}${mixed}` };
+ if (!versionLess(first!.version, MODS_DEFAULT_ON)) {
+ return { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods on by default${mixed}` };
+ }
+ if (!versionLess(first!.version, MODS_FIRST)) {
+ return enableEnvSet
+ ? { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}` }
+ : { status: 'warn', message: `claude resolves to ${runs}: below ${MODS_DEFAULT_ON}, mods need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON}, or export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` };
+ }
+ return { status: 'warn', message: `claude resolves to ${runs}: predates mods (< ${MODS_FIRST}); classic hooks handle every event${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON} and remove the stale install from PATH` };
+}
diff --git a/v3/@claude-flow/cli/src/mods/probe.ts b/v3/@claude-flow/cli/src/mods/probe.ts
index 841b1a6b05..dc1da5305e 100644
--- a/v3/@claude-flow/cli/src/mods/probe.ts
+++ b/v3/@claude-flow/cli/src/mods/probe.ts
@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from 'node:fs';
import { homedir, platform } from 'node:os';
import { join, resolve } from 'node:path';
+import { findClaudeInstalls, judgeInstalls, type ClaudeInstall } from './claude-installs.js';
import { ENABLE_ENV, MOD_PLUGIN_ID, readRecord, readSettingsFile, settingsFileFor } from './install.js';
import { PROJECTION_RELATIVE } from './policy-projection.js';
@@ -48,6 +49,8 @@ export interface ProbeInputs {
home?: string;
env?: NodeJS.ProcessEnv;
managedPath?: string;
+ /** Claude Code binaries on PATH; discovered (each `--version` run) when absent. */
+ installs?: ClaudeInstall[];
}
export function probeMods(inputs: ProbeInputs): Finding[] {
@@ -78,6 +81,9 @@ export function probeMods(inputs: ProbeInputs): Finding[] {
return false;
}
});
+
+ // 2a. Which Claude Code runs, and whether a stale install shadows it.
+ findings.push({ name: 'claude installs', ...judgeInstalls(inputs.installs ?? findClaudeInstalls(env, home), envOn || settingsOn) });
// Observed on Claude Code 2.1.282 (ADR-404): the server-side rollout switch
// decides. Served on, an installed mod loaded with ENABLE_ENV unset; served
// off, it did not load with ENABLE_ENV=1. The variable is reported, never