claude-flow 3.48.0 → 3.50.0

package/v3/@claude-flow/cli/dist/src/mods/install.js

@@ -0,0 +1,135 @@
+/**
+ * `ruflo mods install|uninstall` (ADR-404): enable the ruflo-mods plugin for
+ * one project, opt-in, and take back exactly what was added.
+ *
+ * Writes three keys of a Claude Code settings file (`.claude/settings.local.json`
+ * by default, so the early-access feature is one person's choice, not the
+ * repository's): `enabledPlugins["ruflo-mods@ruflo"]`, the `ruflo` entry of
+ * `extraKnownMarketplaces` when absent, and `env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS`.
+ * What was added is recorded in `.claude-flow/mods/install.json`, so uninstall
+ * removes those and nothing a person set themselves. Classic hooks are never
+ * touched: they stay the fallback (the mod takes an event over at runtime only).
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+export const MOD_PLUGIN_ID = 'ruflo-mods@ruflo';
+export const MARKETPLACE_NAME = 'ruflo';
+export const MARKETPLACE_SOURCE = { source: { source: 'github', repo: 'ruvnet/ruflo' } };
+export const ENABLE_ENV = 'CLAUDE_CODE_ENABLE_FUNCTION_HOOKS';
+export const INSTALL_RECORD = join('.claude-flow', 'mods', 'install.json');
+export function settingsFileFor(projectRoot, scope) {
+    return join(resolve(projectRoot), '.claude', scope === 'local' ? 'settings.local.json' : 'settings.json');
+}
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/** Reads a settings file; absent is `{}`, anything unparseable throws (never overwritten). */
+export function readSettingsFile(path) {
+    if (!existsSync(path))
+        return {};
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!isRecord(parsed))
+        throw new Error(`${path} is not a JSON object`);
+    return parsed;
+}
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    renameSync(tmp, path);
+}
+/** The settings after install, and what install added (pure). */
+export function withModEnabled(settings) {
+    const next = { ...settings };
+    const plugins = isRecord(settings.enabledPlugins) ? { ...settings.enabledPlugins } : {};
+    const markets = isRecord(settings.extraKnownMarketplaces) ? { ...settings.extraKnownMarketplaces } : {};
+    const env = isRecord(settings.env) ? { ...settings.env } : {};
+    const added = {
+        plugin: plugins[MOD_PLUGIN_ID] !== true,
+        marketplace: !(MARKETPLACE_NAME in markets),
+        env: env[ENABLE_ENV] !== '1',
+    };
+    plugins[MOD_PLUGIN_ID] = true;
+    if (added.marketplace)
+        markets[MARKETPLACE_NAME] = MARKETPLACE_SOURCE;
+    env[ENABLE_ENV] = '1';
+    next.enabledPlugins = plugins;
+    next.extraKnownMarketplaces = markets;
+    next.env = env;
+    return { next, added };
+}
+/** The settings after uninstall: only what the record says install added (pure). */
+export function withModRemoved(settings, added) {
+    const next = { ...settings };
+    const drop = (key, name) => {
+        const section = next[key];
+        if (!isRecord(section))
+            return;
+        const copy = { ...section };
+        delete copy[name];
+        if (Object.keys(copy).length === 0)
+            delete next[key];
+        else
+            next[key] = copy;
+    };
+    if (added.plugin)
+        drop('enabledPlugins', MOD_PLUGIN_ID);
+    if (added.marketplace)
+        drop('extraKnownMarketplaces', MARKETPLACE_NAME);
+    if (added.env)
+        drop('env', ENABLE_ENV);
+    return next;
+}
+export function installMod(projectRoot, scope, dryRun = false) {
+    const settingsFile = settingsFileFor(projectRoot, scope);
+    const current = readSettingsFile(settingsFile);
+    const { next, added } = withModEnabled(current);
+    if (dryRun)
+        return { settingsFile, added, dryRun, next };
+    let backup;
+    if (existsSync(settingsFile)) {
+        backup = `${settingsFile}.bak-ruflo-mods-${Date.now()}`;
+        copyFileSync(settingsFile, backup);
+    }
+    writeJson(settingsFile, next);
+    const recordPath = join(resolve(projectRoot), INSTALL_RECORD);
+    const previous = readRecord(projectRoot);
+    // A second install keeps the first record's claims: what ruflo added once
+    // is still ruflo's to remove.
+    const merged = previous && previous.settingsFile === settingsFile
+        ? { plugin: previous.added.plugin || added.plugin, marketplace: previous.added.marketplace || added.marketplace, env: previous.added.env || added.env }
+        : added;
+    const record = { version: 1, settingsFile, installedAt: new Date().toISOString(), added: merged };
+    writeJson(recordPath, record);
+    return { settingsFile, backup, added: merged, dryRun, next };
+}
+export function readRecord(projectRoot) {
+    const path = join(resolve(projectRoot), INSTALL_RECORD);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return parsed && parsed.version === 1 && typeof parsed.settingsFile === 'string' && isRecord(parsed.added) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function uninstallMod(projectRoot, dryRun = false) {
+    const record = readRecord(projectRoot);
+    if (!record)
+        return { removed: false, dryRun };
+    // The record names the file; never follow it outside this project.
+    const root = resolve(projectRoot);
+    if (!resolve(record.settingsFile).startsWith(join(root, '.claude') + sep)) {
+        throw new Error(`install record names a settings file outside ${root}/.claude: ${record.settingsFile}`);
+    }
+    if (dryRun)
+        return { settingsFile: record.settingsFile, removed: true, dryRun };
+    if (existsSync(record.settingsFile)) {
+        writeJson(record.settingsFile, withModRemoved(readSettingsFile(record.settingsFile), record.added));
+    }
+    unlinkSync(join(root, INSTALL_RECORD));
+    return { settingsFile: record.settingsFile, removed: true, dryRun };
+}
+//# sourceMappingURL=install.js.map

package/v3/@claude-flow/cli/dist/src/mods/policy-projection.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The policy projection the ruflo mod reads (ADR-404).
+ *
+ * A hooks module may read at most 4 MiB and cannot import @claude-flow/security,
+ * while `.claude-flow/policy/state.json` carries the whole receipt ledger
+ * (tens of MB on a busy project). So every policy state write also writes a
+ * small file holding only what the mod's `tool.check` needs: the mode and the
+ * rules that name a `claude-code.` action explicitly. Legacy mode, or no such
+ * rule, removes the file, and the mod then adds no policy of its own.
+ *
+ * The projection never authorizes anything: the mod only tightens Claude
+ * Code's own verdict with it, so a deleted or stale projection returns to the
+ * no-mod baseline and can never loosen a call. It is not a ledger and holds
+ * no receipts; issue #3602 (the ledger anchor) is untouched by it.
+ */
+import type { PolicyRule, PolicyState } from '@claude-flow/security';
+export declare const PROJECTION_RELATIVE: string;
+export declare const CLAUDE_CODE_ACTION_PREFIX = "claude-code.";
+export interface PolicyProjection {
+    version: 1;
+    mode: PolicyState['mode'];
+    generatedAt: number;
+    rules: PolicyRule[];
+}
+/** Whether a rule names Claude Code tool calls explicitly (never via `*` or no actions). */
+export declare function targetsClaudeCode(rule: Pick<PolicyRule, 'actions'>): boolean;
+/** The projection of a state, or null when there is nothing to project. */
+export declare function projectionOf(state: Pick<PolicyState, 'mode' | 'rules'>, now?: number): PolicyProjection | null;
+export type ProjectionSync = {
+    action: 'written' | 'removed' | 'unchanged';
+    path: string;
+};
+/**
+ * Writes (atomically, owner-only) or removes the projection for a state.
+ * Throws on I/O failure; policy-runtime calls it after the state is safely
+ * written and keeps the state write's own result whatever happens here.
+ */
+export declare function syncPolicyProjection(projectRoot: string, state: Pick<PolicyState, 'mode' | 'rules'>): ProjectionSync;
+//# sourceMappingURL=policy-projection.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/policy-projection.js

@@ -0,0 +1,65 @@
+/**
+ * The policy projection the ruflo mod reads (ADR-404).
+ *
+ * A hooks module may read at most 4 MiB and cannot import @claude-flow/security,
+ * while `.claude-flow/policy/state.json` carries the whole receipt ledger
+ * (tens of MB on a busy project). So every policy state write also writes a
+ * small file holding only what the mod's `tool.check` needs: the mode and the
+ * rules that name a `claude-code.` action explicitly. Legacy mode, or no such
+ * rule, removes the file, and the mod then adds no policy of its own.
+ *
+ * The projection never authorizes anything: the mod only tightens Claude
+ * Code's own verdict with it, so a deleted or stale projection returns to the
+ * no-mod baseline and can never loosen a call. It is not a ledger and holds
+ * no receipts; issue #3602 (the ledger anchor) is untouched by it.
+ */
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export const PROJECTION_RELATIVE = join('.claude-flow', 'policy', 'claude-code.json');
+export const CLAUDE_CODE_ACTION_PREFIX = 'claude-code.';
+/** Whether a rule names Claude Code tool calls explicitly (never via `*` or no actions). */
+export function targetsClaudeCode(rule) {
+    return Array.isArray(rule.actions) && rule.actions.some((a) => typeof a === 'string' && a.startsWith(CLAUDE_CODE_ACTION_PREFIX));
+}
+/** The projection of a state, or null when there is nothing to project. */
+export function projectionOf(state, now = Date.now()) {
+    if (state.mode === 'legacy')
+        return null;
+    const rules = (Array.isArray(state.rules) ? state.rules : []).filter(targetsClaudeCode).map((rule) => ({
+        id: rule.id,
+        effect: rule.effect,
+        actions: [...rule.actions],
+        ...(rule.enabled !== undefined ? { enabled: rule.enabled } : {}),
+        ...(rule.priority !== undefined ? { priority: rule.priority } : {}),
+        ...(rule.resources ? { resources: [...rule.resources] } : {}),
+        ...(rule.principals ? { principals: [...rule.principals] } : {}),
+        ...(rule.identityTypes ? { identityTypes: [...rule.identityTypes] } : {}),
+        ...(rule.roles ? { roles: [...rule.roles] } : {}),
+        ...(rule.environments ? { environments: [...rule.environments] } : {}),
+        ...(rule.constraints ? { constraints: { ...rule.constraints } } : {}),
+    }));
+    if (rules.length === 0)
+        return null;
+    return { version: 1, mode: state.mode, generatedAt: now, rules };
+}
+/**
+ * Writes (atomically, owner-only) or removes the projection for a state.
+ * Throws on I/O failure; policy-runtime calls it after the state is safely
+ * written and keeps the state write's own result whatever happens here.
+ */
+export function syncPolicyProjection(projectRoot, state) {
+    const path = join(resolve(projectRoot), PROJECTION_RELATIVE);
+    const projection = projectionOf(state);
+    if (!projection) {
+        if (!existsSync(path))
+            return { action: 'unchanged', path };
+        unlinkSync(path);
+        return { action: 'removed', path };
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(projection, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, path);
+    return { action: 'written', path };
+}
+//# sourceMappingURL=policy-projection.js.map

package/v3/@claude-flow/cli/dist/src/mods/probe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What can be known, from outside a Claude Code session, about whether the
+ * ruflo mod will load and what it will own (ADR-404). Every finding names its
+ * source; nothing here claims a live load it did not see. The one direct
+ * evidence of a load is the heartbeat the mod writes at session start.
+ */
+import { type ClaudeInstall } from './claude-installs.js';
+export declare const HANDSHAKE_MARKER = "RUFLO_MODS_OWNS";
+export declare const HEARTBEAT_RELATIVE: string;
+export type Status = 'pass' | 'warn' | 'fail';
+export interface Finding {
+    name: string;
+    status: Status;
+    message: string;
+    fix?: string;
+}
+/** Managed settings, where an organization sets sec-default's options. */
+export declare function managedSettingsPath(os?: NodeJS.Platform): string;
+export interface ProbeInputs {
+    projectRoot: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    managedPath?: string;
+    /** Claude Code binaries on PATH; discovered (each `--version` run) when absent. */
+    installs?: ClaudeInstall[];
+}
+export declare function probeMods(inputs: ProbeInputs): Finding[];
+//# sourceMappingURL=probe.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/probe.js

@@ -0,0 +1,118 @@
+/**
+ * What can be known, from outside a Claude Code session, about whether the
+ * ruflo mod will load and what it will own (ADR-404). Every finding names its
+ * source; nothing here claims a live load it did not see. The one direct
+ * evidence of a load is the heartbeat the mod writes at session start.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+import { findClaudeInstalls, judgeInstalls } from './claude-installs.js';
+import { ENABLE_ENV, MOD_PLUGIN_ID, readRecord, readSettingsFile, settingsFileFor } from './install.js';
+import { PROJECTION_RELATIVE } from './policy-projection.js';
+export const HANDSHAKE_MARKER = 'RUFLO_MODS_OWNS';
+export const HEARTBEAT_RELATIVE = join('.claude-flow', 'mods', 'session.json');
+const SEC_DEFAULT_ID = 'cc-plugin-sec-default@builtin';
+function readJson(path) {
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function get(obj, ...keys) {
+    return keys.reduce((o, k) => (o !== null && typeof o === 'object' ? o[k] : undefined), obj);
+}
+/** Managed settings, where an organization sets sec-default's options. */
+export function managedSettingsPath(os = platform()) {
+    if (os === 'darwin')
+        return '/Library/Application Support/ClaudeCode/managed-settings.json';
+    if (os === 'win32')
+        return 'C:\\ProgramData\\ClaudeCode\\managed-settings.json';
+    return '/etc/claude-code/managed-settings.json';
+}
+export function probeMods(inputs) {
+    const root = resolve(inputs.projectRoot);
+    const home = inputs.home ?? homedir();
+    const env = inputs.env ?? process.env;
+    const findings = [];
+    // 1. Enabled for this project?
+    const files = [settingsFileFor(root, 'local'), settingsFileFor(root, 'project'), join(home, '.claude', 'settings.json')];
+    const enabledIn = files.find((f) => {
+        try {
+            return get(readSettingsFile(f), 'enabledPlugins', MOD_PLUGIN_ID) === true;
+        }
+        catch {
+            return false;
+        }
+    });
+    findings.push(enabledIn
+        ? { name: 'ruflo-mods plugin', status: 'pass', message: `enabled in ${enabledIn}` }
+        : { name: 'ruflo-mods plugin', status: 'warn', message: 'not enabled; classic hooks handle every event', fix: 'ruflo mods install' });
+    // 2. Function hooks switched on for installed plugins (early access).
+    const envOn = env[ENABLE_ENV] === '1';
+    const settingsOn = files.some((f) => {
+        try {
+            return get(readSettingsFile(f), 'env', ENABLE_ENV) === '1';
+        }
+        catch {
+            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 live (ADR-404): 2.1.287 loads mods with ENABLE_ENV unset;
+    // 2.1.282 refuses them without it ("not turned on for installed plugins");
+    // on either, a server-side rollout switch served off holds them off, the
+    // variable notwithstanding. Which binary runs is the 'claude installs' finding.
+    const rollout = get(readJson(join(home, '.claude.json')), 'cachedGrowthBookFeatures', 'tengu_plugin_hooks_modules');
+    const enableMsg = `${ENABLE_ENV} ${envOn ? 'set in this environment' : settingsOn ? 'set in settings env' : 'not set'}`;
+    findings.push(rollout === true
+        ? { name: 'function hooks', status: 'pass', message: `Claude Code rollout switch cached on; ${enableMsg}` }
+        : rollout === false
+            ? { name: 'function hooks', status: 'warn', message: `Claude Code serves function hooks OFF for this account (cached); the mod will not load and classic hooks keep every event; ${enableMsg}` }
+            : { name: 'function hooks', status: 'warn', message: `rollout switch not cached (unverified whether the mod can load); ${enableMsg}`, fix: `export ${ENABLE_ENV}=1 and start Claude Code once` });
+    // 3. Refused by policy?
+    const managed = readJson(inputs.managedPath ?? managedSettingsPath());
+    const managedOnly = get(managed, 'pluginConfigs', SEC_DEFAULT_ID, 'options', 'allowManagedModsOnly');
+    findings.push(managedOnly !== undefined && managedOnly !== false
+        ? { name: 'managed policy', status: 'warn', message: 'allowManagedModsOnly is set: Claude Code refuses user mods; classic hooks stay in charge' }
+        : { name: 'managed policy', status: 'pass', message: managed === undefined ? 'no managed settings' : 'user mods allowed (allowManagedModsOnly not set)' });
+    // 4. Every classic helper a hook could run honours the handshake (the mod's
+    // own rule, plugins/ruflo-mods/hooks/session.ts); else the mod stands down.
+    const helpers = [...new Set([join(root, '.claude', 'helpers', 'hook-handler.cjs'), join(home, '.claude', 'helpers', 'hook-handler.cjs')])].filter(existsSync);
+    const stale = helpers.filter((h) => {
+        try {
+            return !readFileSync(h, 'utf8').includes(HANDSHAKE_MARKER);
+        }
+        catch {
+            return true;
+        }
+    });
+    findings.push(helpers.length === 0
+        ? { name: 'classic handshake', status: 'pass', message: 'no hook-handler.cjs: the mod owns route and post-edit outright' }
+        : stale.length === 0
+            ? { name: 'classic handshake', status: 'pass', message: `${helpers.join(', ')} hand route and post-edit to the mod while it runs` }
+            : { name: 'classic handshake', status: 'warn', message: `${stale.join(', ')} predate${stale.length === 1 ? 's' : ''} the handshake: the mod stands down and classic hooks keep route/post-edit`, fix: 'ruflo init --upgrade (refresh helpers in the project and in ~/.claude)' });
+    // 5. Policy projection.
+    const projectionPath = join(root, PROJECTION_RELATIVE);
+    const projection = readJson(projectionPath);
+    const stateMode = get(readJson(join(root, '.claude-flow', 'policy', 'state.json')), 'mode');
+    findings.push(projection !== undefined
+        ? { name: 'policy projection', status: 'pass', message: `${get(projection, 'mode')} mode, ${get(projection, 'rules')?.length ?? 0} claude-code rule(s)` }
+        : stateMode === 'enforce' || stateMode === 'observe'
+            ? { name: 'policy projection', status: 'warn', message: `policy is ${String(stateMode)} but no projection exists (no claude-code.* rules, or state written by an older CLI)`, fix: 'ruflo mods sync-policy' }
+            : { name: 'policy projection', status: 'pass', message: 'none (no ruflo policy for Claude Code tools)' });
+    // 6. Evidence of a load.
+    const beat = readJson(join(root, HEARTBEAT_RELATIVE));
+    const startedAt = get(beat, 'startedAt');
+    const owned = get(beat, 'owned');
+    findings.push(typeof startedAt === 'string'
+        ? { name: 'last mod start', status: 'pass', message: `${startedAt}, owning ${Array.isArray(owned) && owned.length ? owned.join(', ') : 'nothing'}` }
+        : { name: 'last mod start', status: enabledIn ? 'warn' : 'pass', message: 'the mod has not started in this project' + (enabledIn ? ' (restart Claude Code; check function hooks above)' : '') });
+    if (readRecord(root))
+        findings.push({ name: 'install record', status: 'pass', message: join(root, '.claude-flow', 'mods', 'install.json') });
+    return findings;
+}
+//# sourceMappingURL=probe.js.map

package/v3/@claude-flow/cli/dist/src/plugins/manager.d.ts

@@ -3,6 +3,7 @@
  * Handles actual plugin installation, persistence, and lifecycle
  * Bridges discovery service with file system persistence
  */
+import { type TrustDecision } from './trust-policy.js';
 export interface InstalledPlugin {
     name: string;
     version: string;
@@ -13,6 +14,40 @@ export interface InstalledPlugin {
     commands?: string[];
     hooks?: string[];
     config?: Record<string, unknown>;
+    /** Declared (or registry-assigned) trust level, recorded at install time. */
+    trustLevel?: string;
+    /** Declared permissions, recorded at install time so they can be enforced. */
+    permissions?: string[];
+    /** How the install was verified. */
+    verification?: 'checksum' | 'npm-integrity' | 'policy' | 'skipped';
+    /** Whether npm lifecycle scripts ran during install (false = `--ignore-scripts`). */
+    scriptsRun?: boolean;
+    /** Hooks/commands the plugin declared but that were not registered, and why. */
+    withheld?: {
+        hooks: string[];
+        commands: string[];
+        reasons: string[];
+    };
+}
+/** Options for {@link PluginManager.installFromLocal} / {@link PluginManager.installFromNpm}. */
+export interface PluginInstallOptions {
+    /** `--verify` (default true). */
+    verify?: boolean;
+    /** `--trust` (default false). */
+    trust?: boolean;
+    /** Registry checksum (`sha256:<hex>`) the downloaded tarball must match. */
+    expectedChecksum?: string;
+    /** Trust level from the registry entry, when the plugin was found there. */
+    registryTrustLevel?: string;
+    /** Permissions from the registry entry, merged with the package's own declaration. */
+    registryPermissions?: string[];
+}
+export interface PluginInstallResult {
+    success: boolean;
+    error?: string;
+    plugin?: InstalledPlugin;
+    decision?: TrustDecision;
+    warnings?: string[];
 }
 export interface InstalledPluginsManifest {
     version: '1.0.0';
@@ -46,19 +81,11 @@ export declare class PluginManager {
     /**
      * Install a plugin from npm
      */
-    installFromNpm(packageName: string, version?: string): Promise<{
-        success: boolean;
-        error?: string;
-        plugin?: InstalledPlugin;
-    }>;
+    installFromNpm(packageName: string, version?: string, opts?: PluginInstallOptions): Promise<PluginInstallResult>;
     /**
      * Install a plugin from a local path
      */
-    installFromLocal(sourcePath: string): Promise<{
-        success: boolean;
-        error?: string;
-        plugin?: InstalledPlugin;
-    }>;
+    installFromLocal(sourcePath: string, opts?: PluginInstallOptions): Promise<PluginInstallResult>;
     /**
      * Uninstall a plugin
      */