claude-flow 3.49.0 → 3.51.0

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

@@ -0,0 +1,186 @@
+/**
+ * Turn the ruflo mods on (or off) for a project (ADR-404): merge the
+ * settings, sync the policy projection, then make the plugins loadable with
+ * `claude`. One path for `ruflo mods install`, `ruflo init` (and its wizard)
+ * and `ruflo init upgrade --mods`; `removeMods` is `ruflo mods uninstall`.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { output } from '../output.js';
+import { installMod, MARKETPLACE_NAME, MARKETPLACE_SOURCE, MOD_PLUGINS, readRecord, recordClaudeInstalled, scopeOfSettingsFile, uninstallMod, } from './install.js';
+import { findClaudeBinary, installArgv, marketplaceArgv, repairPluginInstall, uninstallArgv, uninstallPlugins } from './plugin-repair.js';
+import { claudeConfigDir, describeSource, installedState, marketplaceState, repairCommands, resolveFindings, sameSource } from './plugin-resolve.js';
+/** One line per thing a run added; empty on a re-run. */
+export function describeAdded(added) {
+    return [
+        ...added.plugins.map((id) => `enabledPlugins["${id}"] = true`),
+        ...(added.marketplace ? ['extraKnownMarketplaces.ruflo'] : []),
+        ...(added.env ? ['env.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS = "1"'] : []),
+    ];
+}
+/** What default-on means, said exactly (ADR-404 Amendment 1). */
+export const LOAD_NOTE = [
+    'ruflo-mods and ruflo-console run only where Claude Code function hooks are on: with them off, or the rollout switch off, they do nothing and the classic hooks keep every event.',
+    "ruflo-swarm's commands, skills and agents load without function hooks; with them on, ruflo-swarm is also a mod that can run host commands (pane actions you start).",
+    "Each teammate's first trusted interactive Claude Code start clones github.com/ruvnet/ruflo; a headless claude -p on a fresh config loads nothing.",
+    'Optional hardening: pluginConfigs["ruflo-mods@ruflo"].options.modTrust = "refuse-risky" with modTrustAllow, in user or managed settings (project settings cannot set it).',
+];
+async function syncPolicyQuietly(root) {
+    try {
+        const { loadPolicyState } = await import('../services/policy-runtime.js');
+        const { syncPolicyProjection } = await import('./policy-projection.js');
+        const result = syncPolicyProjection(root, loadPolicyState(root));
+        if (result.action !== 'unchanged')
+            output.writeln(`policy projection: ${result.action} (${result.path})`);
+    }
+    catch (error) {
+        output.printWarning(`policy projection not synced: ${error.message}`);
+    }
+}
+function printSteps(steps) {
+    for (const step of steps) {
+        const mark = step.state === 'ok' ? output.success('✓') : step.state === 'pending' ? output.warning('…') : output.error('✗');
+        output.writeln(`${mark} claude ${step.argv.join(' ')}${step.state === 'pending' ? ' (pending: not in the ruflo marketplace yet)' : ''}`);
+        if (step.state === 'failed' && step.output)
+            output.writeln(output.dim(`    ${step.output.split('\n').slice(-3).join('\n    ')}`));
+    }
+}
+const canon = (v) => Array.isArray(v) ? v.map(canon) : v && typeof v === 'object' ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])])) : v;
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Claude Code re-serializes settings it touches; say so, never fight it. */
+function noteRewrite(file, before) {
+    const after = readText(file);
+    if (before === undefined || after === undefined || before === after)
+        return;
+    try {
+        output.writeln(output.dim(JSON.stringify(canon(JSON.parse(before))) === JSON.stringify(canon(JSON.parse(after)))
+            ? `Claude Code reformatted ${file} (key order and layout only; content unchanged).`
+            : `Claude Code also changed ${file}; review it before committing.`));
+    }
+    catch {
+        // Not ours to judge further.
+    }
+}
+export async function applyMods(root, opts) {
+    const install = installMod(root, opts.scope, opts.dryRun === true, undefined, opts.marketplace ?? MARKETPLACE_SOURCE);
+    const configDir = claudeConfigDir(process.env, homedir());
+    const lines = describeAdded(install.added);
+    // Only what is enabled in the file: `claude plugin install` would flip a
+    // plugin someone set to false back to true.
+    const enabled = (install.next.enabledPlugins ?? {});
+    const plugins = MOD_PLUGINS.filter((p) => enabled[p.id] === true);
+    // The marketplace the file declares wins: a person's own declaration is kept and used.
+    const declared = install.next.extraKnownMarketplaces?.[MARKETPLACE_NAME] ?? MARKETPLACE_SOURCE;
+    const market = marketplaceState(configDir);
+    const known = market.known && sameSource(market.source, declared.source);
+    if (install.dryRun) {
+        output.writeln(`Would write ${install.settingsFile}:`);
+        output.printJson(install.next);
+        if (opts.pluginInstall !== false) {
+            output.writeln('Would run:');
+            const installs = declared.source.source === 'directory' ? [] : plugins.map((p) => installArgv(p.id, opts.scope));
+            for (const argv of [marketplaceArgv(opts.scope, known, declared), ...installs])
+                output.writeln(`  claude ${argv.join(' ')}`);
+        }
+        return { install, resolvable: true };
+    }
+    await syncPolicyQuietly(root);
+    if (lines.length) {
+        output.printSuccess(`ruflo mods enabled in ${install.settingsFile}${install.backup ? ` (backup: ${install.backup})` : ''}`);
+        for (const line of lines)
+            output.writeln(`  + ${line}`);
+    }
+    else {
+        output.printSuccess(`ruflo mods already enabled in ${install.settingsFile} (nothing changed)`);
+    }
+    output.writeln(`  marketplace: ${describeSource(declared.source)}`);
+    if (opts.marketplace && !sameSource(opts.marketplace.source, declared.source)) {
+        output.printWarning(`extraKnownMarketplaces.ruflo was already set (${describeSource(declared.source)}); left as it is.`);
+    }
+    for (const line of LOAD_NOTE)
+        output.writeln(output.dim(line));
+    const manual = (k = known) => {
+        output.writeln('Run these to make the plugins loadable:');
+        for (const line of repairCommands(root, opts.scope, k, plugins, declared))
+            output.writeln(`  ${line}`);
+    };
+    if (opts.pluginInstall === false)
+        return { install, resolvable: true, skipped: '--no-plugin-install' };
+    if (opts.skipInTestEnv && (process.env.VITEST || process.env.CI)) {
+        output.writeln(output.dim(`claude plugin step skipped (${process.env.VITEST ? 'VITEST' : 'CI'} set).`));
+        manual();
+        return { install, resolvable: false, skipped: 'test or CI environment' };
+    }
+    const claude = findClaudeBinary(process.env, homedir());
+    if (!claude) {
+        output.printWarning('No runnable claude binary on PATH: the plugins are enabled in settings, not installed.');
+        manual();
+        return { install, resolvable: false, skipped: 'no claude on PATH' };
+    }
+    if (declared.source.source === 'directory' && market.known && !sameSource(market.source, declared.source)) {
+        output.printWarning(`Claude Code keeps one ruflo marketplace per config dir: it now switches from ${describeSource(market.source)} to ${describeSource(declared.source)} for every project on this machine. Switch back with: claude plugin marketplace add ruvnet/ruflo`);
+    }
+    // Never claim (and so never uninstall) a plugin that was installed before, or one ruflo did not enable.
+    const before = new Set(plugins.filter((p) => installedState(root, configDir, p.id).installed).map((p) => p.id));
+    const textBefore = readText(install.settingsFile);
+    const repair = await repairPluginInstall({ projectRoot: root, scope: opts.scope, configDir, claude, plugins, marketplace: declared, exec: opts.exec });
+    printSteps(repair.steps);
+    if (declared.source.source === 'directory' && repair.ok)
+        output.writeln(output.dim(`Directory marketplace: plugins load live from ${declared.source.path} (no clone, no install).`));
+    const enabledByRuflo = new Set(readRecord(root)?.files[install.settingsFile]?.plugins ?? []);
+    const ours = repair.steps
+        .filter((st) => st.state === 'ok' && st.argv[1] === 'install')
+        .map((st) => st.argv[2])
+        .filter((id) => !before.has(id) && enabledByRuflo.has(id));
+    recordClaudeInstalled(root, install.settingsFile, ours);
+    noteRewrite(install.settingsFile, textBefore);
+    const failed = resolveFindings(root, opts.scope, configDir, undefined, plugins.map((p) => p.id), declared).filter((f) => f.status === 'fail');
+    if (repair.ok && failed.length === 0)
+        return { install, resolvable: true };
+    for (const f of failed)
+        output.writeln(`${output.error('✗')} ${f.name}: ${f.message}`);
+    const now = marketplaceState(configDir);
+    manual(now.known && sameSource(now.source, declared.source));
+    return { install, resolvable: false };
+}
+/**
+ * `ruflo mods uninstall`: `claude plugin uninstall` exactly the plugins ruflo
+ * installed, then remove exactly the settings keys it added.
+ */
+export async function removeMods(root, opts = {}) {
+    const record = readRecord(root);
+    const plan = Object.entries(record?.files ?? {}).map(([file, added]) => ({ file, scope: scopeOfSettingsFile(file), ids: added.claudeInstalled ?? [] }));
+    const uninstalled = [];
+    const failed = [];
+    if (opts.dryRun) {
+        for (const p of plan)
+            for (const id of p.ids)
+                output.writeln(`Would run: claude ${uninstallArgv(id, p.scope).join(' ')}`);
+    }
+    else if (plan.some((p) => p.ids.length)) {
+        const claude = findClaudeBinary(process.env, homedir());
+        for (const p of plan.filter((x) => x.ids.length)) {
+            if (!claude) {
+                output.printWarning('No runnable claude binary on PATH; run these to remove what ruflo installed:');
+                for (const id of p.ids)
+                    output.writeln(`  cd ${JSON.stringify(root)} && claude ${uninstallArgv(id, p.scope).join(' ')}`);
+                failed.push(...p.ids);
+                continue;
+            }
+            const result = await uninstallPlugins({ projectRoot: root, scope: p.scope, ids: p.ids, claude, exec: opts.exec });
+            printSteps(result.steps);
+            for (const st of result.steps)
+                (st.state === 'ok' ? uninstalled : failed).push(st.argv[2]);
+        }
+    }
+    const result = uninstallMod(root, opts.dryRun === true);
+    return { ...result, uninstalled, failed };
+}
+//# sourceMappingURL=apply.js.map

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export declare const MODS_DEFAULT_ON = "2.1.287";
+export declare const MODS_FIRST = "2.1.277";
+export interface ClaudeInstall {
+    path: string;
+    version: string | null;
+}
+export type VersionOf = (path: string) => string | null;
+/** a < b for dotted numeric versions. */
+export declare function versionLess(a: string, b: string): boolean;
+/** `claude --version` of one binary, bounded; null when it cannot say. */
+export declare const defaultVersionOf: VersionOf;
+/** Every `claude` on PATH, in PATH order (the first is what runs), plus ~/.local/bin. */
+export declare function findClaudeInstalls(env: NodeJS.ProcessEnv, home: string, versionOf?: VersionOf): ClaudeInstall[];
+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 declare function judgeInstalls(installs: readonly ClaudeInstall[], enableEnvSet: boolean): InstallsFinding;
+//# sourceMappingURL=claude-installs.d.ts.map

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

@@ -0,0 +1,83 @@
+/**
+ * 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';
+const parse = (v) => v.split('.').map((n) => Number(n));
+/** a < b for dotted numeric versions. */
+export function versionLess(a, b) {
+    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 = (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, home, versionOf = defaultVersionOf) {
+    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();
+    const installs = [];
+    for (const dir of dirs) {
+        for (const name of names) {
+            const path = join(dir, name);
+            let real;
+            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;
+}
+/** The doctor's reading of what `claude` resolves to and what else is installed. */
+export function judgeInstalls(installs, enableEnvSet) {
+    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` };
+}
+//# sourceMappingURL=claude-installs.js.map

package/v3/@claude-flow/cli/dist/src/mods/command-registry/catalog.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ADR-406 P1 — classify the inventory into `CommandDefinition`s, validate
+ * them, and emit a deterministic catalog.
+ *
+ * Determinism: entries sorted by id, object keys sorted recursively, no
+ * generation timestamp, and `source.commit` is the last commit that touched
+ * the source file (not the generator's HEAD), so regenerating an unchanged
+ * tree yields the same bytes.
+ */
+import { type CatalogEntry, type CommandCatalog } from './schema.js';
+import { type RawCommand } from './inventory.js';
+export declare const REPOSITORY = "ruvnet/ruflo";
+export interface CatalogOptions {
+    /** Repository-relative path -> last commit sha touching it. Missing = `uncommitted`. */
+    readonly commits?: Readonly<Record<string, string>>;
+    /** True when `packedFiles` was supplied to the inventory, so `shippedIn` is meaningful. */
+    readonly packageContentsInspected: boolean;
+    /** Last commit touching any command source (stable across unrelated commits). */
+    readonly sourceCommit?: string;
+}
+/** JSON with object keys sorted at every depth and no whitespace. */
+export declare function canonicalJson(value: unknown): string;
+export declare function catalogDigest(entries: readonly CatalogEntry[]): string;
+/** Merge the occurrences of one invocation spelling into one catalog entry. */
+export declare function classify(key: string, occurrences: readonly RawCommand[], options: CatalogOptions): CatalogEntry;
+export interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/** §14 P1 gate: schema-valid definitions, no duplicate ids, no duplicate names. */
+export declare function validateEntries(entries: readonly unknown[]): ValidationResult;
+export declare function buildCatalog(inventory: readonly RawCommand[], options: CatalogOptions): CommandCatalog;
+/** Parse and re-verify a catalog read from disk (the parity check a consumer runs). */
+export declare function verifyCatalog(raw: unknown): ValidationResult;
+export declare function serializeCatalog(catalog: CommandCatalog): string;
+/**
+ * Write the catalog atomically. `expectedSha256` is the digest of the file the
+ * caller last read (or `null` for "must not exist"); a mismatch means someone
+ * else changed it and the write is refused (§6 concurrent-edit detection).
+ */
+export declare function writeCatalog(path: string, catalog: CommandCatalog, expectedSha256?: string | null): {
+    written: boolean;
+    sha256: string;
+};
+//# sourceMappingURL=catalog.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/command-registry/catalog.js

@@ -0,0 +1,234 @@
+/**
+ * ADR-406 P1 — classify the inventory into `CommandDefinition`s, validate
+ * them, and emit a deterministic catalog.
+ *
+ * Determinism: entries sorted by id, object keys sorted recursively, no
+ * generation timestamp, and `source.commit` is the last commit that touched
+ * the source file (not the generator's HEAD), so regenerating an unchanged
+ * tree yields the same bytes.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync, mkdirSync, openSync, fsyncSync, closeSync } from 'node:fs';
+import { dirname, basename } from 'node:path';
+import { COMMAND_CATALOG_CONTRACT, LIMITS, catalogEntrySchema, commandCatalogSchema, } from './schema.js';
+import { sha256Hex } from './inventory.js';
+export const REPOSITORY = 'ruvnet/ruflo';
+// Loader-exposed documentation is named in capitals (README, CHANGELOG,
+// COMMAND_COMPLIANCE_REPORT). Lower-case names such as `performance-report`
+// are real workflows and must not be matched by content words.
+const DOC_NAME = /^[A-Z][A-Z0-9_]+$/;
+const CHANNEL_PRIORITY = {
+    'repo-project-commands': 0,
+    'cli-init-template': 1,
+    'marketplace-plugin': 2,
+    'source-plugin': 3,
+    'mod-registration': 4,
+};
+/** JSON with object keys sorted at every depth and no whitespace. */
+export function canonicalJson(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        }
+        return v;
+    });
+}
+export function catalogDigest(entries) {
+    return `sha256:${sha256Hex(canonicalJson(entries))}`;
+}
+function frontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const out = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+        if (kv)
+            out[kv[1].toLowerCase()] = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+}
+function substitutionOf(content) {
+    if (content.includes('$ARGUMENTS'))
+        return '$ARGUMENTS';
+    if (/\$[1-9]\b/.test(content))
+        return 'positional';
+    return 'none';
+}
+function allowedTools(meta) {
+    const raw = meta['allowed-tools'];
+    if (!raw)
+        return [];
+    return [...new Set(raw.replace(/^\[|\]$/g, '').split(',').map((t) => t.trim().replace(/^["']|["']$/g, '')).filter(Boolean))]
+        .map((t) => t.slice(0, LIMITS.capability))
+        .slice(0, LIMITS.capabilities)
+        .sort();
+}
+function isDocumentation(source) {
+    return DOC_NAME.test(basename(source.sourcePath, '.md'));
+}
+/** Merge the occurrences of one invocation spelling into one catalog entry. */
+export function classify(key, occurrences, options) {
+    const ordered = [...occurrences].sort((a, b) => CHANNEL_PRIORITY[a.source.channel] - CHANNEL_PRIORITY[b.source.channel]
+        || a.source.sourcePath.localeCompare(b.source.sourcePath));
+    const markdown = ordered.filter((o) => o.source.binding === 'markdown-loader');
+    const registered = ordered.filter((o) => o.source.binding === 'mod-register');
+    const middleware = ordered.filter((o) => o.source.binding === 'mod-middleware-on-markdown');
+    const primary = markdown[0] ?? ordered[0];
+    const notes = [];
+    const commit = (path) => options.commits?.[path] ?? 'uncommitted';
+    let definition;
+    const base = {
+        schemaVersion: 1,
+        id: `${primary.ownerPlugin}/${key}`.toLowerCase(),
+        revision: 1,
+        ownerPlugin: primary.ownerPlugin,
+        modelVisibility: 'same-as-legacy',
+        source: { repository: REPOSITORY, commit: commit(primary.source.sourcePath), path: primary.source.sourcePath },
+    };
+    const documentation = markdown.length > 0 && isDocumentation(primary.source);
+    if (markdown.length > 0) {
+        const content = primary.content ?? '';
+        const meta = frontmatter(content);
+        const hint = (meta['argument-hint'] ?? '').slice(0, 200);
+        definition = {
+            ...base,
+            legacyNames: [key],
+            modNames: [],
+            kind: documentation ? 'help' : 'prompt',
+            argumentsSchema: hint
+                ? { type: 'string', maxLength: 8_192, description: hint }
+                : { type: 'string', maxLength: 8_192 },
+            prompt: { path: primary.source.sourcePath, sha256: primary.source.digest.slice(7), substitution: substitutionOf(content) },
+            requiredCapabilities: allowedTools(meta),
+            requiredHostFeatures: [],
+            // §7: no engine path to invoke a prompt workflow with its semantics is
+            // verified, so the workbench may show or fill it but never run it.
+            disposition: documentation ? 'legacy' : 'delegate',
+        };
+        if (documentation)
+            notes.push('documentation file exposed by the engine command loader; not an executable workflow');
+        if (middleware.length > 0) {
+            notes.push(`mod middleware attached by ${[...new Set(middleware.map((m) => m.ownerPlugin))].join(', ')} (command.run match)`);
+        }
+    }
+    else {
+        definition = {
+            ...base,
+            legacyNames: [],
+            modNames: [key],
+            kind: 'query',
+            argumentsSchema: { type: 'string', maxLength: 1_024 },
+            requiredCapabilities: [],
+            requiredHostFeatures: ['command.register'],
+            disposition: 'view',
+            viewId: `${primary.ownerPlugin}/${key}`.toLowerCase(),
+        };
+        notes.push('registered by a function-hook mod; exists only while that mod is loaded');
+    }
+    if (registered.length > 0 && markdown.length > 0)
+        notes.push('also registered by a mod under the same spelling');
+    const markdownDigests = new Set(markdown.map((m) => m.source.digest));
+    const divergent = markdownDigests.size > 1;
+    if (divergent)
+        notes.push('copies differ between delivery channels; see sources[].digest');
+    const shipped = ordered.some((o) => o.source.shippedIn.length > 0
+        || o.source.channel === 'marketplace-plugin'
+        || (o.source.channel === 'mod-registration' && o.source.package.endsWith('@ruflo')));
+    if (!options.packageContentsInspected)
+        notes.push('npm package contents not inspected for this catalog');
+    return catalogEntrySchema.parse({
+        definition,
+        status: documentation ? 'documentation' : shipped ? 'shipped' : 'source-only',
+        divergent,
+        sources: ordered.map((o) => o.source).slice(0, 8),
+        notes: notes.map((n) => n.slice(0, LIMITS.note)),
+    });
+}
+/** §14 P1 gate: schema-valid definitions, no duplicate ids, no duplicate names. */
+export function validateEntries(entries) {
+    const errors = [];
+    const ids = new Map();
+    const names = new Map();
+    entries.forEach((raw, index) => {
+        const parsed = catalogEntrySchema.safeParse(raw);
+        if (!parsed.success) {
+            errors.push(`entry ${index}: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+            return;
+        }
+        const def = parsed.data.definition;
+        if (ids.has(def.id))
+            errors.push(`duplicate id ${def.id} (entries ${ids.get(def.id)} and ${index})`);
+        else
+            ids.set(def.id, index);
+        for (const name of new Set([...def.legacyNames, ...def.modNames])) {
+            const owner = names.get(name.toLowerCase());
+            if (owner && owner !== def.id)
+                errors.push(`duplicate name /${name} (${owner} and ${def.id})`);
+            else
+                names.set(name.toLowerCase(), def.id);
+        }
+    });
+    return { valid: errors.length === 0, errors };
+}
+export function buildCatalog(inventory, options) {
+    const groups = new Map();
+    for (const item of inventory) {
+        const list = groups.get(item.key) ?? [];
+        list.push(item);
+        groups.set(item.key, list);
+    }
+    const entries = [...groups.entries()]
+        .map(([key, list]) => classify(key, list, options))
+        .sort((a, b) => (a.definition.id < b.definition.id ? -1 : a.definition.id > b.definition.id ? 1 : 0));
+    const validation = validateEntries(entries);
+    if (!validation.valid)
+        throw new Error(`command-registry-invalid:\n${validation.errors.join('\n')}`);
+    const sourceCommit = options.sourceCommit ?? 'uncommitted';
+    return commandCatalogSchema.parse({
+        contractVersion: COMMAND_CATALOG_CONTRACT,
+        sourceCommit,
+        sourceDigest: catalogDigest(entries),
+        entries,
+    });
+}
+/** Parse and re-verify a catalog read from disk (the parity check a consumer runs). */
+export function verifyCatalog(raw) {
+    const parsed = commandCatalogSchema.safeParse(raw);
+    if (!parsed.success)
+        return { valid: false, errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`) };
+    const errors = [...validateEntries(parsed.data.entries).errors];
+    if (catalogDigest(parsed.data.entries) !== parsed.data.sourceDigest)
+        errors.push('sourceDigest does not match entries');
+    return { valid: errors.length === 0, errors };
+}
+export function serializeCatalog(catalog) {
+    return `${JSON.stringify(JSON.parse(canonicalJson(catalog)), null, 2)}\n`;
+}
+/**
+ * Write the catalog atomically. `expectedSha256` is the digest of the file the
+ * caller last read (or `null` for "must not exist"); a mismatch means someone
+ * else changed it and the write is refused (§6 concurrent-edit detection).
+ */
+export function writeCatalog(path, catalog, expectedSha256) {
+    const text = serializeCatalog(catalog);
+    const next = sha256Hex(text);
+    const current = existsSync(path) ? sha256Hex(readFileSync(path)) : null;
+    if (expectedSha256 !== undefined && expectedSha256 !== current) {
+        throw new Error(`catalog-changed-on-disk: expected ${expectedSha256 ?? 'absent'}, found ${current ?? 'absent'}`);
+    }
+    if (current === next)
+        return { written: false, sha256: next };
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o644 });
+    const fd = openSync(tmp, 'r');
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+    return { written: true, sha256: next };
+}
+//# sourceMappingURL=catalog.js.map

package/v3/@claude-flow/cli/dist/src/mods/command-registry/engine-report.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ADR-406 P0 — engine capability report.
+ *
+ * Every probe runs a fixed argv through an injected runner (never a shell),
+ * with `CLAUDE_CONFIG_DIR` pointed at an isolated directory so the probe
+ * never reads or writes the person's real `~/.claude`. Anything that could
+ * not be observed is reported as `unknown` with the reason, never assumed.
+ */
+import type { ModCommandHook } from './inventory.js';
+export type Runner = (file: string, args: readonly string[], env: NodeJS.ProcessEnv) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};
+export interface PluginValidation {
+    readonly plugin: string;
+    readonly passed: boolean | 'unknown';
+    readonly commandHooks: readonly string[];
+    readonly hostCalls: readonly string[];
+    /** A `command.run{command=?}` matcher: names chosen at run time, which only the source scan can list. */
+    readonly dynamicCommandHook?: true;
+    readonly reason?: string;
+}
+export interface EngineReport {
+    readonly schemaVersion: 1;
+    readonly engine: {
+        readonly executable: string | null;
+        readonly version: string | null;
+        readonly binarySha256: string | null;
+    };
+    readonly typeGeneration: 'none-in-engine-cli' | 'unknown';
+    readonly vendoredTypes: readonly {
+        readonly path: string;
+        readonly sha256: string;
+    }[];
+    readonly validations: readonly PluginValidation[];
+    readonly affordances: {
+        readonly promptFill: boolean | 'unknown';
+        readonly processRun: boolean | 'unknown';
+    };
+    readonly collisions: readonly {
+        readonly name: string;
+        readonly builtin: boolean | 'unknown';
+        readonly repoCommand: boolean;
+        readonly verdict: 'free' | 'taken' | 'unknown';
+    }[];
+    readonly limits: readonly string[];
+}
+/** Parse `claude plugin validate` text: hooks and `$.` calls the static scanner found. */
+export declare function parseValidateOutput(plugin: string, status: number | null, text: string): PluginValidation;
+/** Plugins that are function-hook mods (have `hooks/register.ts`). */
+export declare function modPlugins(repoRoot: string): string[];
+export interface EngineProbeInput {
+    readonly repoRoot: string;
+    readonly executable: string | null;
+    readonly isolatedConfigDir: string;
+    readonly run: Runner;
+    /** Names to check for collisions, e.g. `ruflo`, `ruflo-workbench`. */
+    readonly proposedNames: readonly string[];
+    /** Every name the repository already exposes (legacy + mod names). */
+    readonly existingNames: ReadonlySet<string>;
+}
+export declare function probeEngine(input: EngineProbeInput): EngineReport;
+/** Engine-observed command hooks, in the inventory's `ModCommandHook` shape. */
+export declare function hooksFromValidations(validations: readonly PluginValidation[]): ModCommandHook[];
+//# sourceMappingURL=engine-report.d.ts.map