claude-flow 3.50.0 → 3.51.0

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

@@ -0,0 +1,63 @@
+/**
+ * Whether Claude Code can actually load the ruflo mod plugins (ADR-404).
+ *
+ * `enabledPlugins["ruflo-mods@ruflo"] = true` in settings is only a request.
+ * Observed live on Claude Code 2.1.287: an interactive, trusted session clones
+ * the `ruflo` marketplace a project declares and loads an enabled plugin
+ * straight from that clone (no install record needed); a headless `-p` run
+ * clones nothing. A clone from before ruflo-mods shipped has no
+ * `plugins/ruflo-mods`, and Claude Code skips the enabled plugin without a
+ * word: `/ruflo-mods` is an unknown command, and the clone is not refreshed
+ * on start. So the clone decides; an install record (`installed_plugins.json`,
+ * pointing into `plugins/cache/`) is a cached copy that still loads when the
+ * clone goes stale.
+ *
+ * Read-only. The config directory is `CLAUDE_CONFIG_DIR` when set, else
+ * `~/.claude`, as Claude Code itself resolves it.
+ */
+import { type MarketplaceEntry, type ModPlugin, type Scope } from './install.js';
+import type { Finding } from './probe.js';
+/** The two filesystem reads detection needs; injectable for tests. */
+export interface ReadFs {
+    exists(path: string): boolean;
+    readText(path: string): string | undefined;
+}
+export declare const nodeReadFs: ReadFs;
+export declare function claudeConfigDir(env: NodeJS.ProcessEnv, home: string): string;
+export interface MarketplaceState {
+    /** Listed in known_marketplaces.json (so `marketplace update ruflo` works). */
+    known: boolean;
+    /** The local clone (or, for a directory source, the directory), when it exists on disk. */
+    location: string | null;
+    /** The source Claude Code knows the marketplace by, when known. */
+    source?: MarketplaceEntry['source'];
+}
+/** "github ruvnet/ruflo" or "directory /path" (a working tree: no clone, nothing to go stale). */
+export declare function describeSource(source: unknown): string;
+export declare function sameSource(a: unknown, b: unknown): boolean;
+export declare function marketplaceState(configDir: string, fs?: ReadFs): MarketplaceState;
+/** The plugin's manifest inside a clone: its marketplace.json `source`, else plugins/<name>. */
+export declare function pluginManifestIn(clone: string, id: string, fs?: ReadFs): string;
+/** The clone carries this plugin. */
+export declare function cloneHas(market: MarketplaceState, id: string, fs?: ReadFs): boolean;
+export interface InstalledState {
+    installed: boolean;
+    scope?: string;
+    installPath?: string;
+}
+/** Installed for this project: user scope anywhere, local/project scope for this root; its cache dir present. */
+export declare function installedState(projectRoot: string, configDir: string, id: string, fs?: ReadFs): InstalledState;
+/**
+ * The exact commands that refresh the marketplace and install the plugins,
+ * for a person to run. `known` is true only when Claude Code already knows
+ * the marketplace by the wanted source (then an update suffices). A
+ * directory source loads live from the working tree: nothing to install.
+ */
+export declare function repairCommands(projectRoot: string, scope: Scope | 'user', known: boolean, plugins?: readonly ModPlugin[], wanted?: MarketplaceEntry): string[];
+/**
+ * The marketplace finding plus one finding per plugin enabled in settings.
+ * A required plugin missing from the clone with no cached install is the
+ * failure Claude Code hides; a plugin not yet released is "pending".
+ */
+export declare function resolveFindings(projectRoot: string, scope: Scope | 'user', configDir: string, fs?: ReadFs, enabled?: readonly string[], declared?: unknown): Finding[];
+//# sourceMappingURL=plugin-resolve.d.ts.map

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

@@ -0,0 +1,182 @@
+/**
+ * Whether Claude Code can actually load the ruflo mod plugins (ADR-404).
+ *
+ * `enabledPlugins["ruflo-mods@ruflo"] = true` in settings is only a request.
+ * Observed live on Claude Code 2.1.287: an interactive, trusted session clones
+ * the `ruflo` marketplace a project declares and loads an enabled plugin
+ * straight from that clone (no install record needed); a headless `-p` run
+ * clones nothing. A clone from before ruflo-mods shipped has no
+ * `plugins/ruflo-mods`, and Claude Code skips the enabled plugin without a
+ * word: `/ruflo-mods` is an unknown command, and the clone is not refreshed
+ * on start. So the clone decides; an install record (`installed_plugins.json`,
+ * pointing into `plugins/cache/`) is a cached copy that still loads when the
+ * clone goes stale.
+ *
+ * Read-only. The config directory is `CLAUDE_CONFIG_DIR` when set, else
+ * `~/.claude`, as Claude Code itself resolves it.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { MARKETPLACE_NAME, MARKETPLACE_SOURCE, MOD_PLUGINS } from './install.js';
+export const nodeReadFs = {
+    exists: (p) => existsSync(p),
+    readText: (p) => {
+        try {
+            return readFileSync(p, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    },
+};
+export function claudeConfigDir(env, home) {
+    return env.CLAUDE_CONFIG_DIR || join(home, '.claude');
+}
+function readJson(fs, path) {
+    const text = fs.readText(path);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+const nameOf = (id) => id.split('@')[0];
+/** "github ruvnet/ruflo" or "directory /path" (a working tree: no clone, nothing to go stale). */
+export function describeSource(source) {
+    if (!isRecord(source))
+        return 'unknown source';
+    if (source.source === 'directory')
+        return `directory ${String(source.path)}`;
+    if (source.source === 'github')
+        return `github ${String(source.repo)}`;
+    return String(source.source ?? 'unknown source');
+}
+export function sameSource(a, b) {
+    if (!isRecord(a) || !isRecord(b) || a.source !== b.source)
+        return false;
+    return a.source === 'directory' ? resolve(String(a.path)) === resolve(String(b.path)) : a.repo === b.repo;
+}
+export function marketplaceState(configDir, fs = nodeReadFs) {
+    const known = readJson(fs, join(configDir, 'plugins', 'known_marketplaces.json'));
+    const entry = isRecord(known) ? known[MARKETPLACE_NAME] : undefined;
+    const declared = isRecord(entry) && typeof entry.installLocation === 'string' ? entry.installLocation : undefined;
+    const candidates = [declared, join(configDir, 'plugins', 'marketplaces', MARKETPLACE_NAME)].filter((p) => !!p);
+    const source = isRecord(entry) && isRecord(entry.source) ? entry.source : undefined;
+    return { known: isRecord(entry), location: candidates.find((p) => fs.exists(p)) ?? null, source };
+}
+/** The plugin's manifest inside a clone: its marketplace.json `source`, else plugins/<name>. */
+export function pluginManifestIn(clone, id, fs = nodeReadFs) {
+    const catalog = readJson(fs, join(clone, '.claude-plugin', 'marketplace.json'));
+    const listed = isRecord(catalog) && Array.isArray(catalog.plugins)
+        ? catalog.plugins.find((p) => isRecord(p) && p.name === nameOf(id))
+        : undefined;
+    const source = isRecord(listed) && typeof listed.source === 'string' ? listed.source : `./plugins/${nameOf(id)}`;
+    return join(clone, source, '.claude-plugin', 'plugin.json');
+}
+/** The clone carries this plugin. */
+export function cloneHas(market, id, fs = nodeReadFs) {
+    return market.location !== null && fs.exists(pluginManifestIn(market.location, id, fs));
+}
+function sameDir(a, b) {
+    if (resolve(a) === resolve(b))
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Installed for this project: user scope anywhere, local/project scope for this root; its cache dir present. */
+export function installedState(projectRoot, configDir, id, fs = nodeReadFs) {
+    const record = readJson(fs, join(configDir, 'plugins', 'installed_plugins.json'));
+    const plugins = isRecord(record) && isRecord(record.plugins) ? record.plugins : undefined;
+    const entries = plugins && Array.isArray(plugins[id]) ? plugins[id] : [];
+    for (const e of entries) {
+        if (!isRecord(e) || typeof e.installPath !== 'string' || !fs.exists(e.installPath))
+            continue;
+        const forHere = e.scope === 'user' || (typeof e.projectPath === 'string' && sameDir(e.projectPath, projectRoot));
+        if (forHere)
+            return { installed: true, scope: String(e.scope), installPath: e.installPath };
+    }
+    return { installed: false };
+}
+/**
+ * The exact commands that refresh the marketplace and install the plugins,
+ * for a person to run. `known` is true only when Claude Code already knows
+ * the marketplace by the wanted source (then an update suffices). A
+ * directory source loads live from the working tree: nothing to install.
+ */
+export function repairCommands(projectRoot, scope, known, plugins = MOD_PLUGINS, wanted = MARKETPLACE_SOURCE) {
+    const dir = wanted.source.source === 'directory' ? wanted.source.path : null;
+    return [
+        `cd ${JSON.stringify(resolve(projectRoot))}`,
+        known
+            ? `claude plugin marketplace update ${MARKETPLACE_NAME}`
+            : `claude plugin marketplace add ${dir ? JSON.stringify(dir) : 'ruvnet/ruflo'} --scope ${scope}`,
+        ...(dir ? [] : plugins.filter((p) => p.required).map((p) => `claude plugin install ${p.id} --scope ${scope}`)),
+    ];
+}
+/**
+ * The marketplace finding plus one finding per plugin enabled in settings.
+ * A required plugin missing from the clone with no cached install is the
+ * failure Claude Code hides; a plugin not yet released is "pending".
+ */
+export function resolveFindings(projectRoot, scope, configDir, fs = nodeReadFs, enabled = MOD_PLUGINS.map((p) => p.id), declared) {
+    const market = marketplaceState(configDir, fs);
+    const wanted = (isRecord(declared) && isRecord(declared.source) ? declared : MARKETPLACE_SOURCE);
+    const matches = market.known && sameSource(market.source, wanted.source);
+    const fix = repairCommands(projectRoot, scope, matches, MOD_PLUGINS.filter((p) => enabled.includes(p.id)), wanted).join(' && ');
+    const findings = [];
+    const kind = market.source?.source === 'directory' ? 'directory (loads live from the working tree)' : `cloned at ${market.location}`;
+    findings.push(market.location && market.known && !sameSource(market.source, wanted.source)
+        ? {
+            name: 'ruflo marketplace',
+            status: 'warn',
+            message: `this project declares ${describeSource(wanted.source)}, but Claude Code knows ruflo as ${describeSource(market.source)} (one ruflo marketplace per config dir)`,
+            fix,
+        }
+        : market.location
+            ? { name: 'ruflo marketplace', status: 'pass', message: `${describeSource(market.source ?? wanted.source)}: ${kind}` }
+            : {
+                name: 'ruflo marketplace',
+                status: 'warn',
+                message: `not cloned under ${join(configDir, 'plugins')}: Claude Code clones it at the next interactive start of a trusted session (headless -p runs do not)`,
+                fix,
+            });
+    for (const plugin of MOD_PLUGINS.filter((p) => enabled.includes(p.id))) {
+        const name = `plugin ${plugin.id}`;
+        const installed = installedState(projectRoot, configDir, plugin.id, fs);
+        const also = installed.installed ? `; also installed (${installed.scope} scope)` : '';
+        if (cloneHas(market, plugin.id, fs)) {
+            findings.push({ name, status: 'pass', message: `loads from the marketplace clone${also}` });
+        }
+        else if (!market.location) {
+            findings.push(installed.installed
+                ? { name, status: 'pass', message: `installed (${installed.scope} scope, ${installed.installPath})` }
+                : { name, status: 'warn', message: plugin.required ? 'loads once Claude Code has cloned the marketplace' : 'pending: not released in the ruflo marketplace yet' });
+        }
+        else if (!plugin.required) {
+            findings.push({ name, status: 'warn', message: `pending: not in the ruflo marketplace yet (${market.location})${also}` });
+        }
+        else if (installed.installed) {
+            findings.push({ name, status: 'warn', message: `the clone at ${market.location} is stale (no ${nameOf(plugin.id)}); the cached install still loads`, fix });
+        }
+        else {
+            findings.push({
+                name,
+                status: 'fail',
+                message: `the clone at ${market.location} is stale: it predates ${nameOf(plugin.id)}, so Claude Code skips the enabled plugin without a word${plugin.id.startsWith('ruflo-mods@') ? ' (/ruflo-mods is an unknown command)' : ''}`,
+                fix,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=plugin-resolve.js.map

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

@@ -5,6 +5,7 @@
  * evidence of a load is the heartbeat the mod writes at session start.
  */
 import { type ClaudeInstall } from './claude-installs.js';
+import { type ReadFs } from './plugin-resolve.js';
 export declare const HANDSHAKE_MARKER = "RUFLO_MODS_OWNS";
 export declare const HEARTBEAT_RELATIVE: string;
 export type Status = 'pass' | 'warn' | 'fail';
@@ -23,6 +24,10 @@ export interface ProbeInputs {
     managedPath?: string;
     /** Claude Code binaries on PATH; discovered (each `--version` run) when absent. */
     installs?: ClaudeInstall[];
+    /** Claude Code's config directory; CLAUDE_CONFIG_DIR, else ~/.claude, when absent. */
+    configDir?: string;
+    /** Reads for the plugin-resolution findings; the real filesystem when absent. */
+    fs?: ReadFs;
 }
 export declare function probeMods(inputs: ProbeInputs): Finding[];
 //# sourceMappingURL=probe.d.ts.map

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

@@ -8,7 +8,8 @@ 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 { ENABLE_ENV, MOD_PLUGIN_ID, MOD_PLUGIN_IDS, readRecord, readSettingsFile, settingsFileFor } from './install.js';
+import { claudeConfigDir, resolveFindings } from './plugin-resolve.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');
@@ -36,9 +37,10 @@ export function probeMods(inputs) {
     const root = resolve(inputs.projectRoot);
     const home = inputs.home ?? homedir();
     const env = inputs.env ?? process.env;
+    const configDir = inputs.configDir ?? claudeConfigDir(env, home);
     const findings = [];
     // 1. Enabled for this project?
-    const files = [settingsFileFor(root, 'local'), settingsFileFor(root, 'project'), join(home, '.claude', 'settings.json')];
+    const files = [settingsFileFor(root, 'local'), settingsFileFor(root, 'project'), join(configDir, 'settings.json')];
     const enabledIn = files.find((f) => {
         try {
             return get(readSettingsFile(f), 'enabledPlugins', MOD_PLUGIN_ID) === true;
@@ -48,8 +50,31 @@ export function probeMods(inputs) {
         }
     });
     findings.push(enabledIn
-        ? { name: 'ruflo-mods plugin', status: 'pass', message: `enabled in ${enabledIn}` }
+        ? { name: 'ruflo-mods plugin', status: 'pass', message: `enabled in settings: ${enabledIn} (whether Claude Code can load it: see below)` }
         : { name: 'ruflo-mods plugin', status: 'warn', message: 'not enabled; classic hooks handle every event', fix: 'ruflo mods install' });
+    // 1a. Enabled is a request; Claude Code silently skips a plugin its
+    // marketplace clone does not carry (a clone older than the plugin).
+    if (enabledIn) {
+        const scope = enabledIn === files[0] ? 'local' : enabledIn === files[1] ? 'project' : 'user';
+        const enabled = MOD_PLUGIN_IDS.filter((id) => files.some((f) => {
+            try {
+                return get(readSettingsFile(f), 'enabledPlugins', id) === true;
+            }
+            catch {
+                return false;
+            }
+        }));
+        // The marketplace the first settings file declaring one names (local wins, as in Claude Code).
+        const declared = files.map((f) => {
+            try {
+                return get(readSettingsFile(f), 'extraKnownMarketplaces', 'ruflo');
+            }
+            catch {
+                return undefined;
+            }
+        }).find((d) => d !== undefined);
+        findings.push(...resolveFindings(root, scope, configDir, inputs.fs, enabled, declared));
+    }
     // 2. Function hooks switched on for installed plugins (early access).
     const envOn = env[ENABLE_ENV] === '1';
     const settingsOn = files.some((f) => {

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.d.ts

@@ -1,4 +1,9 @@
 import { AgenticPolicyEngine, type BudgetLimit, type CapabilityEnvelope, type PolicyApproval, type PolicyDecision, type PolicyRequest, type PolicyRule, type PolicyState } from '@claude-flow/security';
+/**
+ * Exported for ADR-406 mission storage, which takes the same per-file lock
+ * (pid, pid namespace and boot id identify a dead owner) rather than a copy.
+ */
+export declare function acquireLock(lockPath: string): Promise<() => void>;
 export declare function loadPolicyState(projectRoot?: string): PolicyState;
 export declare function autoMigratePolicyStateIfNeeded(projectRoot?: string): Promise<{
     migrated: boolean;

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -120,7 +120,11 @@ function lockOwnerIsDead(lockPath) {
         return false;
     }
 }
-async function acquireLock(lockPath) {
+/**
+ * Exported for ADR-406 mission storage, which takes the same per-file lock
+ * (pid, pid namespace and boot id identify a dead owner) rather than a copy.
+ */
+export async function acquireLock(lockPath) {
     const started = Date.now();
     while (Date.now() - started < LOCK_WAIT_MS) {
         try {

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.50.0",
+  "version": "3.51.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",