claude-flow 3.50.0 → 3.51.0

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

@@ -0,0 +1,137 @@
+/**
+ * ADR-406 §6 — the canonical command registry contract.
+ *
+ * `CommandDefinition` mirrors the ADR's proposed TypeScript contract field for
+ * field. Every object is `.strict()` (unknown fields are rejected), every
+ * string and array is capped, and `argumentsSchema` is capped by its
+ * serialized size. A definition carries no executable path, shell template,
+ * network grant or approval override: `bindingId` is only a key into a
+ * reviewed allowlist owned by runtime code.
+ *
+ * Inventory facts (where a command was found, its digest, how the engine
+ * spells it) live beside the definition in a catalog entry, never inside it,
+ * so the §6 shape stays exact.
+ */
+import { z } from 'zod';
+export const COMMAND_CATALOG_CONTRACT = 'ruflo.command-catalog/1';
+export const LIMITS = Object.freeze({
+    id: 160,
+    name: 128,
+    names: 16,
+    path: 512,
+    ownerPlugin: 96,
+    capabilities: 64,
+    capability: 128,
+    argumentsSchemaBytes: 4_096,
+    entries: 4_096,
+    note: 512,
+});
+const SHA256 = /^[a-f0-9]{64}$/;
+const SAFE_ID = /^[a-z0-9][a-z0-9._:/-]*$/i;
+// A command spelling as the engine accepts it: letters, digits, `-`, `_`,
+// `.` and the `:` namespace separator. No whitespace, no shell metacharacters.
+const COMMAND_NAME = /^[a-z0-9][a-z0-9._:-]*$/i;
+// Repository-relative, forward slashes, no `..` segment, no leading slash.
+const REL_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^\0\\]+$/;
+export const commandKindSchema = z.enum(['prompt', 'query', 'mutation', 'workflow', 'help']);
+export const modDispositionSchema = z.enum(['view', 'dispatch', 'delegate', 'legacy']);
+const nameSchema = z.string().min(1).max(LIMITS.name).regex(COMMAND_NAME);
+const relPathSchema = z.string().min(1).max(LIMITS.path).regex(REL_PATH);
+const argumentsSchemaSchema = z
+    .record(z.unknown())
+    .refine((value) => JSON.stringify(value).length <= LIMITS.argumentsSchemaBytes, {
+    message: `argumentsSchema exceeds ${LIMITS.argumentsSchemaBytes} serialized bytes`,
+});
+export const commandDefinitionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1).max(LIMITS.id).regex(SAFE_ID),
+    revision: z.number().int().min(1).max(1_000_000),
+    ownerPlugin: z.string().min(1).max(LIMITS.ownerPlugin).regex(SAFE_ID),
+    legacyNames: z.array(nameSchema).max(LIMITS.names),
+    modNames: z.array(nameSchema).max(LIMITS.names),
+    kind: commandKindSchema,
+    argumentsSchema: argumentsSchemaSchema,
+    resultSchemaId: z.string().min(1).max(LIMITS.id).regex(SAFE_ID).optional(),
+    prompt: z
+        .object({
+        path: relPathSchema,
+        sha256: z.string().regex(SHA256),
+        substitution: z.enum(['$ARGUMENTS', 'positional', 'none']),
+    })
+        .strict()
+        .optional(),
+    bindingId: z.string().min(1).max(LIMITS.id).regex(SAFE_ID).optional(),
+    requiredCapabilities: z.array(z.string().min(1).max(LIMITS.capability)).max(LIMITS.capabilities),
+    requiredHostFeatures: z.array(z.string().min(1).max(LIMITS.capability)).max(LIMITS.capabilities),
+    disposition: modDispositionSchema,
+    viewId: z.string().min(1).max(LIMITS.id).regex(SAFE_ID).optional(),
+    modelVisibility: z.enum(['same-as-legacy', 'explicit-summary']),
+    source: z
+        .object({
+        repository: z.string().min(1).max(LIMITS.id),
+        commit: z.string().regex(/^(?:[a-f0-9]{40}|uncommitted)$/),
+        path: relPathSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((def, ctx) => {
+    if (def.legacyNames.length + def.modNames.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'a command needs at least one name' });
+    }
+    if (def.kind === 'prompt' && !def.prompt) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'a prompt command must record its prompt provenance' });
+    }
+    // §7: prompt dispatch is not verified on any engine yet, so a prompt
+    // workflow can be delegated or kept legacy but never claim `dispatch`.
+    if (def.kind === 'prompt' && def.disposition === 'dispatch') {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'prompt workflows cannot use dispatch (ADR-406 §7)' });
+    }
+    if (def.disposition === 'dispatch' && !def.bindingId) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'dispatch requires a reviewed bindingId' });
+    }
+    if (def.disposition === 'view' && !def.viewId) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'view disposition requires a viewId' });
+    }
+});
+/** Where an inventoried command came from. */
+export const deliveryChannelSchema = z.enum([
+    'repo-project-commands', // `.claude/commands/**` at the repository root
+    'cli-init-template', // packaged `.claude/commands/**` that `init` copies
+    'marketplace-plugin', // `plugins/<p>/commands/*.md` listed in the marketplace
+    'source-plugin', // a plugin command folder not listed in any marketplace
+    'mod-registration', // `$.command.register` inside a function-hook mod
+]);
+export const inventorySourceSchema = z
+    .object({
+    channel: deliveryChannelSchema,
+    package: z.string().min(1).max(LIMITS.id),
+    sourcePath: relPathSchema,
+    digest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    observedInvocation: z.string().min(1).max(LIMITS.name + 1),
+    // How the engine reaches it: a Markdown file load, a mod `command.register`,
+    // or mod middleware attached to a Markdown command (`command.run` match).
+    binding: z.enum(['markdown-loader', 'mod-register', 'mod-middleware-on-markdown']),
+    initCategory: z.string().max(LIMITS.ownerPlugin).optional(),
+    shippedIn: z.array(z.string().max(LIMITS.ownerPlugin)).max(8),
+})
+    .strict();
+export const catalogEntrySchema = z
+    .object({
+    definition: commandDefinitionSchema,
+    status: z.enum(['shipped', 'source-only', 'documentation']),
+    divergent: z.boolean(),
+    sources: z.array(inventorySourceSchema).min(1).max(8),
+    notes: z.array(z.string().max(LIMITS.note)).max(8),
+})
+    .strict();
+export const commandCatalogSchema = z
+    .object({
+    contractVersion: z.literal(COMMAND_CATALOG_CONTRACT),
+    sourceCommit: z.string().regex(/^(?:[a-f0-9]{40}|uncommitted)$/),
+    sourceDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    entries: z.array(catalogEntrySchema).max(LIMITS.entries),
+})
+    .strict();
+//# sourceMappingURL=schema.js.map

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

@@ -1,14 +1,16 @@
 /**
- * `ruflo mods install|uninstall` (ADR-404): enable the ruflo-mods plugin for
- * one project, opt-in, and take back exactly what was added.
+ * `ruflo mods install|uninstall` (ADR-404): enable the ruflo mods for one
+ * project, 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
+ * Writes three kinds of key in a Claude Code settings file: one
+ * `enabledPlugins` entry per plugin in MOD_PLUGINS, 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).
+ * `ruflo init` writes them to the committed `.claude/settings.json` (project
+ * scope); a standalone `ruflo mods install` defaults to
+ * `.claude/settings.local.json`. What was added is recorded per settings file
+ * 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 (a mod takes an event over at runtime only).
  */
 export declare const MOD_PLUGIN_ID = "ruflo-mods@ruflo";
 export declare const MARKETPLACE_NAME = "ruflo";
@@ -18,18 +20,48 @@ export declare const MARKETPLACE_SOURCE: {
         readonly repo: "ruvnet/ruflo";
     };
 };
+/** An `extraKnownMarketplaces` entry: github ruvnet/ruflo, or a local ruflo checkout (dogfooding). */
+export type MarketplaceEntry = {
+    source: {
+        source: 'github';
+        repo: string;
+    } | {
+        source: 'directory';
+        path: string;
+    };
+};
+export declare function directoryMarketplace(path: string): MarketplaceEntry;
 export declare const ENABLE_ENV = "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS";
 export declare const INSTALL_RECORD: string;
+export interface ModPlugin {
+    id: string;
+    /**
+     * Missing from a ruflo marketplace clone means the clone is stale (a
+     * failure). A plugin not yet released on main is `required: false`: missing
+     * is "pending", never a failure. Flip it once the plugin lands.
+     */
+    required: boolean;
+}
+/** Every plugin `ruflo mods install` and `ruflo init` enable. The one list to edit. */
+export declare const MOD_PLUGINS: readonly ModPlugin[];
+export declare const MOD_PLUGIN_IDS: readonly string[];
 export type Scope = 'local' | 'project';
+export interface Added {
+    plugins: string[];
+    marketplace: boolean;
+    env: boolean;
+    /**
+     * Plugins ruflo itself installed with `claude plugin install` (absent
+     * before, enabled by ruflo); uninstall runs `claude plugin uninstall` for
+     * exactly these.
+     */
+    claudeInstalled?: string[];
+}
 export interface InstallRecord {
-    version: 1;
-    settingsFile: string;
+    version: 2;
     installedAt: string;
-    added: {
-        plugin: boolean;
-        marketplace: boolean;
-        env: boolean;
-    };
+    /** What install added, per settings file it wrote. */
+    files: Record<string, Added>;
 }
 type Settings = Record<string, unknown> & {
     enabledPlugins?: Record<string, unknown>;
@@ -39,24 +71,30 @@ type Settings = Record<string, unknown> & {
 export declare function settingsFileFor(projectRoot: string, scope: Scope): string;
 /** Reads a settings file; absent is `{}`, anything unparseable throws (never overwritten). */
 export declare function readSettingsFile(path: string): Settings;
-/** The settings after install, and what install added (pure). */
-export declare function withModEnabled(settings: Settings): {
+/** The settings after install, and what install added (pure). Existing values are kept. */
+export declare function withModEnabled(settings: Settings, plugins?: readonly string[], marketplace?: MarketplaceEntry): {
     next: Settings;
-    added: InstallRecord['added'];
+    added: Added;
 };
 /** The settings after uninstall: only what the record says install added (pure). */
-export declare function withModRemoved(settings: Settings, added: InstallRecord['added']): Settings;
+export declare function withModRemoved(settings: Settings, added: Added): Settings;
 export interface InstallResult {
     settingsFile: string;
     backup?: string;
-    added: InstallRecord['added'];
+    /** What this run added (empty on a re-run). */
+    added: Added;
     dryRun: boolean;
     next: Settings;
 }
-export declare function installMod(projectRoot: string, scope: Scope, dryRun?: boolean): InstallResult;
+export declare function installMod(projectRoot: string, scope: Scope, dryRun?: boolean, plugins?: readonly string[], marketplace?: MarketplaceEntry): InstallResult;
+/** The install record, v1 (3.50.0: one file, ruflo-mods only) read as v2. */
 export declare function readRecord(projectRoot: string): InstallRecord | null;
+/** Note plugins ruflo installed with `claude plugin install` for one settings file. */
+export declare function recordClaudeInstalled(projectRoot: string, settingsFile: string, ids: readonly string[]): void;
+/** The scope a recorded settings file was written at. */
+export declare function scopeOfSettingsFile(file: string): Scope;
 export declare function uninstallMod(projectRoot: string, dryRun?: boolean): {
-    settingsFile?: string;
+    settingsFiles: string[];
     removed: boolean;
     dryRun: boolean;
 };

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

@@ -1,22 +1,34 @@
 /**
- * `ruflo mods install|uninstall` (ADR-404): enable the ruflo-mods plugin for
- * one project, opt-in, and take back exactly what was added.
+ * `ruflo mods install|uninstall` (ADR-404): enable the ruflo mods for one
+ * project, 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
+ * Writes three kinds of key in a Claude Code settings file: one
+ * `enabledPlugins` entry per plugin in MOD_PLUGINS, 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).
+ * `ruflo init` writes them to the committed `.claude/settings.json` (project
+ * scope); a standalone `ruflo mods install` defaults to
+ * `.claude/settings.local.json`. What was added is recorded per settings file
+ * 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 (a 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 function directoryMarketplace(path) {
+    return { source: { source: 'directory', path: resolve(path) } };
+}
 export const ENABLE_ENV = 'CLAUDE_CODE_ENABLE_FUNCTION_HOOKS';
 export const INSTALL_RECORD = join('.claude-flow', 'mods', 'install.json');
+/** Every plugin `ruflo mods install` and `ruflo init` enable. The one list to edit. */
+export const MOD_PLUGINS = [
+    { id: MOD_PLUGIN_ID, required: true },
+    { id: 'ruflo-swarm@ruflo', required: true },
+    { id: 'ruflo-console@ruflo', required: true },
+];
+export const MOD_PLUGIN_IDS = MOD_PLUGINS.map((p) => p.id);
 export function settingsFileFor(projectRoot, scope) {
     return join(resolve(projectRoot), '.claude', scope === 'local' ? 'settings.local.json' : 'settings.json');
 }
@@ -38,22 +50,26 @@ function writeJson(path, value) {
     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 nothingAdded = (a) => a.plugins.length === 0 && !a.marketplace && !a.env;
+/** The settings after install, and what install added (pure). Existing values are kept. */
+export function withModEnabled(settings, plugins = MOD_PLUGIN_IDS, marketplace = MARKETPLACE_SOURCE) {
     const next = { ...settings };
-    const plugins = isRecord(settings.enabledPlugins) ? { ...settings.enabledPlugins } : {};
+    const enabled = isRecord(settings.enabledPlugins) ? { ...settings.enabledPlugins } : {};
     const markets = isRecord(settings.extraKnownMarketplaces) ? { ...settings.extraKnownMarketplaces } : {};
     const env = isRecord(settings.env) ? { ...settings.env } : {};
+    // A plugin a person set to false is their decision: never flipped.
     const added = {
-        plugin: plugins[MOD_PLUGIN_ID] !== true,
+        plugins: plugins.filter((id) => !(id in enabled)),
         marketplace: !(MARKETPLACE_NAME in markets),
-        env: env[ENABLE_ENV] !== '1',
+        env: !(ENABLE_ENV in env),
     };
-    plugins[MOD_PLUGIN_ID] = true;
+    for (const id of added.plugins)
+        enabled[id] = true;
     if (added.marketplace)
-        markets[MARKETPLACE_NAME] = MARKETPLACE_SOURCE;
-    env[ENABLE_ENV] = '1';
-    next.enabledPlugins = plugins;
+        markets[MARKETPLACE_NAME] = marketplace;
+    if (added.env)
+        env[ENABLE_ENV] = '1';
+    next.enabledPlugins = enabled;
     next.extraKnownMarketplaces = markets;
     next.env = env;
     return { next, added };
@@ -72,19 +88,19 @@ export function withModRemoved(settings, added) {
         else
             next[key] = copy;
     };
-    if (added.plugin)
-        drop('enabledPlugins', MOD_PLUGIN_ID);
+    for (const id of added.plugins)
+        drop('enabledPlugins', id);
     if (added.marketplace)
         drop('extraKnownMarketplaces', MARKETPLACE_NAME);
     if (added.env)
         drop('env', ENABLE_ENV);
     return next;
 }
-export function installMod(projectRoot, scope, dryRun = false) {
+export function installMod(projectRoot, scope, dryRun = false, plugins = MOD_PLUGIN_IDS, marketplace = MARKETPLACE_SOURCE) {
     const settingsFile = settingsFileFor(projectRoot, scope);
     const current = readSettingsFile(settingsFile);
-    const { next, added } = withModEnabled(current);
-    if (dryRun)
+    const { next, added } = withModEnabled(current, plugins, marketplace);
+    if (dryRun || nothingAdded(added))
         return { settingsFile, added, dryRun, next };
     let backup;
     if (existsSync(settingsFile)) {
@@ -92,44 +108,78 @@ export function installMod(projectRoot, scope, dryRun = false) {
         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 };
+    // What ruflo added once is still ruflo's to remove: merge into the record.
+    const record = readRecord(projectRoot) ?? { version: 2, installedAt: '', files: {} };
+    const before = record.files[settingsFile] ?? { plugins: [], marketplace: false, env: false };
+    record.files[settingsFile] = {
+        plugins: [...new Set([...before.plugins, ...added.plugins])],
+        marketplace: before.marketplace || added.marketplace,
+        env: before.env || added.env,
+        claudeInstalled: before.claudeInstalled ?? [],
+    };
+    record.installedAt = new Date().toISOString();
+    writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+    return { settingsFile, backup, added, dryRun, next };
 }
+/** The install record, v1 (3.50.0: one file, ruflo-mods only) read as v2. */
 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;
+        if (parsed.version === 2 && isRecord(parsed.files)) {
+            const files = {};
+            for (const [file, a] of Object.entries(parsed.files)) {
+                if (!isRecord(a))
+                    continue;
+                const strings = (v) => (Array.isArray(v) ? v.filter((p) => typeof p === 'string') : []);
+                files[file] = { plugins: strings(a.plugins), marketplace: a.marketplace === true, env: a.env === true, claudeInstalled: strings(a.claudeInstalled) };
+            }
+            return { version: 2, installedAt: String(parsed.installedAt ?? ''), files };
+        }
+        if (parsed.version === 1 && typeof parsed.settingsFile === 'string' && isRecord(parsed.added)) {
+            const a = parsed.added;
+            return { version: 2, installedAt: String(parsed.installedAt ?? ''), files: { [parsed.settingsFile]: { plugins: a.plugin === true ? [MOD_PLUGIN_ID] : [], marketplace: a.marketplace === true, env: a.env === true } } };
+        }
+        return null;
     }
     catch {
         return null;
     }
 }
+/** Note plugins ruflo installed with `claude plugin install` for one settings file. */
+export function recordClaudeInstalled(projectRoot, settingsFile, ids) {
+    const record = readRecord(projectRoot);
+    const entry = record?.files[settingsFile];
+    if (!record || !entry || ids.length === 0)
+        return;
+    entry.claudeInstalled = [...new Set([...(entry.claudeInstalled ?? []), ...ids])];
+    writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+}
+/** The scope a recorded settings file was written at. */
+export function scopeOfSettingsFile(file) {
+    return file.endsWith('settings.local.json') ? 'local' : 'project';
+}
 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.
+        return { settingsFiles: [], removed: false, dryRun };
+    // The record names the files; never follow one 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}`);
+    const settingsFiles = Object.keys(record.files);
+    for (const file of settingsFiles) {
+        if (!resolve(file).startsWith(join(root, '.claude') + sep)) {
+            throw new Error(`install record names a settings file outside ${root}/.claude: ${file}`);
+        }
     }
     if (dryRun)
-        return { settingsFile: record.settingsFile, removed: true, dryRun };
-    if (existsSync(record.settingsFile)) {
-        writeJson(record.settingsFile, withModRemoved(readSettingsFile(record.settingsFile), record.added));
+        return { settingsFiles, removed: true, dryRun };
+    for (const file of settingsFiles) {
+        if (existsSync(file))
+            writeJson(file, withModRemoved(readSettingsFile(file), record.files[file]));
     }
     unlinkSync(join(root, INSTALL_RECORD));
-    return { settingsFile: record.settingsFile, removed: true, dryRun };
+    return { settingsFiles, removed: true, dryRun };
 }
 //# sourceMappingURL=install.js.map

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

@@ -0,0 +1,81 @@
+/**
+ * After settings are written, make the mod plugins loadable the way a person
+ * would (ADR-404): refresh (or add) the `ruflo` marketplace clone, then
+ * `claude plugin install <id> --scope <scope>` for each plugin the clone
+ * carries. The refreshed clone is what makes a plugin load; the install adds
+ * a cached copy (and the `claude plugin list` entry) that survives a later
+ * stale clone.
+ *
+ * Fixed argv through execFile, never a shell; each step bounded. The `add`
+ * step passes `--scope` so the marketplace is declared in the same settings
+ * file ruflo already wrote, not in user settings. `~/.claude.json` is never
+ * touched by ruflo. No `-y`: a marketplace-declared command is never accepted
+ * on a person's behalf.
+ */
+import { type MarketplaceEntry, type ModPlugin, type Scope } from './install.js';
+import { type ReadFs } from './plugin-resolve.js';
+export declare const MARKETPLACE_TIMEOUT_MS = 150000;
+export declare const INSTALL_TIMEOUT_MS = 60000;
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type Exec = (file: string, args: readonly string[], opts: {
+    cwd: string;
+    timeout: number;
+    env: NodeJS.ProcessEnv;
+}) => Promise<ExecResult>;
+export declare const nodeExec: Exec;
+/** The `claude` a shell would run, when it can be exec'd without a shell. */
+export declare function findClaudeBinary(env: NodeJS.ProcessEnv, home: string): string | null;
+export type StepState = 'ok' | 'failed' | 'pending';
+export interface RepairStep {
+    argv: string[];
+    state: StepState;
+    output: string;
+}
+export interface RepairOptions {
+    projectRoot: string;
+    scope: Scope;
+    /** Claude Code's config directory, read after the marketplace step to see what the clone carries. */
+    configDir: string;
+    claude: string;
+    plugins?: readonly ModPlugin[];
+    /** The marketplace the settings declare (default github ruvnet/ruflo). */
+    marketplace?: MarketplaceEntry;
+    exec?: Exec;
+    env?: NodeJS.ProcessEnv;
+    fs?: ReadFs;
+}
+/**
+ * `update` when Claude Code already knows ruflo by the wanted source; else
+ * `add` it at the scope, which also switches a ruflo marketplace known by
+ * another source (Claude Code keeps one per config dir).
+ */
+export declare function marketplaceArgv(scope: Scope, known: boolean, wanted?: MarketplaceEntry): string[];
+export declare function uninstallArgv(id: string, scope: Scope): string[];
+export declare function installArgv(id: string, scope: Scope): string[];
+/**
+ * Marketplace first (a failure there stops everything: nothing below can
+ * work); then one install per plugin, every failure collected. A plugin the
+ * refreshed clone does not carry is pending when not required, a failure when
+ * required.
+ */
+export declare function repairPluginInstall(opts: RepairOptions): Promise<{
+    ok: boolean;
+    steps: RepairStep[];
+}>;
+/** `claude plugin uninstall` for each id, every failure collected. */
+export declare function uninstallPlugins(opts: {
+    projectRoot: string;
+    scope: Scope;
+    ids: readonly string[];
+    claude: string;
+    exec?: Exec;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    ok: boolean;
+    steps: RepairStep[];
+}>;
+//# sourceMappingURL=plugin-repair.d.ts.map

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

@@ -0,0 +1,120 @@
+/**
+ * After settings are written, make the mod plugins loadable the way a person
+ * would (ADR-404): refresh (or add) the `ruflo` marketplace clone, then
+ * `claude plugin install <id> --scope <scope>` for each plugin the clone
+ * carries. The refreshed clone is what makes a plugin load; the install adds
+ * a cached copy (and the `claude plugin list` entry) that survives a later
+ * stale clone.
+ *
+ * Fixed argv through execFile, never a shell; each step bounded. The `add`
+ * step passes `--scope` so the marketplace is declared in the same settings
+ * file ruflo already wrote, not in user settings. `~/.claude.json` is never
+ * touched by ruflo. No `-y`: a marketplace-declared command is never accepted
+ * on a person's behalf.
+ */
+import { execFile } from 'node:child_process';
+import { findClaudeInstalls } from './claude-installs.js';
+import { MARKETPLACE_NAME, MARKETPLACE_SOURCE, MOD_PLUGINS } from './install.js';
+import { cloneHas, marketplaceState, nodeReadFs, sameSource } from './plugin-resolve.js';
+export const MARKETPLACE_TIMEOUT_MS = 150_000; // Claude Code's own clone timeout is 120s
+export const INSTALL_TIMEOUT_MS = 60_000;
+export const nodeExec = (file, args, opts) => new Promise((done) => {
+    execFile(file, [...args], { ...opts, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+        // error.code is the exit status, or a string (ENOENT, ...) when it never ran; a timeout kills it.
+        const status = error?.code;
+        const code = !error ? 0 : typeof status === 'number' && status !== 0 ? status : 1;
+        done({ code, stdout: String(stdout), stderr: String(stderr) || (error ? error.message : '') });
+    });
+});
+/** The `claude` a shell would run, when it can be exec'd without a shell. */
+export function findClaudeBinary(env, home) {
+    const first = findClaudeInstalls(env, home, () => null)[0];
+    if (!first)
+        return null;
+    // A .cmd shim needs a shell to run; ruflo never uses one.
+    return process.platform === 'win32' && !first.path.toLowerCase().endsWith('.exe') ? null : first.path;
+}
+/**
+ * `update` when Claude Code already knows ruflo by the wanted source; else
+ * `add` it at the scope, which also switches a ruflo marketplace known by
+ * another source (Claude Code keeps one per config dir).
+ */
+export function marketplaceArgv(scope, known, wanted = MARKETPLACE_SOURCE) {
+    if (known)
+        return ['plugin', 'marketplace', 'update', MARKETPLACE_NAME];
+    const from = wanted.source.source === 'directory' ? wanted.source.path : wanted.source.repo;
+    return ['plugin', 'marketplace', 'add', from, '--scope', scope];
+}
+export function uninstallArgv(id, scope) {
+    return ['plugin', 'uninstall', id, '--scope', scope];
+}
+export function installArgv(id, scope) {
+    return ['plugin', 'install', id, '--scope', scope];
+}
+/**
+ * Marketplace first (a failure there stops everything: nothing below can
+ * work); then one install per plugin, every failure collected. A plugin the
+ * refreshed clone does not carry is pending when not required, a failure when
+ * required.
+ */
+export async function repairPluginInstall(opts) {
+    const exec = opts.exec ?? nodeExec;
+    const env = opts.env ?? process.env;
+    const fs = opts.fs ?? nodeReadFs;
+    const plugins = opts.plugins ?? MOD_PLUGINS;
+    const steps = [];
+    const run = async (argv, timeout) => {
+        let result;
+        try {
+            result = await exec(opts.claude, argv, { cwd: opts.projectRoot, timeout, env });
+        }
+        catch (error) {
+            result = { code: 1, stdout: '', stderr: error.message };
+        }
+        steps.push({ argv, state: result.code === 0 ? 'ok' : 'failed', output: `${result.stdout}${result.stderr}`.trim() });
+        return result.code === 0;
+    };
+    const wanted = opts.marketplace ?? MARKETPLACE_SOURCE;
+    const before = marketplaceState(opts.configDir, fs);
+    if (!(await run(marketplaceArgv(opts.scope, before.known && sameSource(before.source, wanted.source), wanted), MARKETPLACE_TIMEOUT_MS))) {
+        return { ok: false, steps };
+    }
+    const market = marketplaceState(opts.configDir, fs);
+    // A directory marketplace loads each plugin live from the working tree;
+    // an install would pin a cached snapshot of it instead.
+    if (wanted.source.source === 'directory') {
+        const missing = plugins.filter((p) => p.required && !cloneHas(market, p.id, fs));
+        for (const p of missing)
+            steps.push({ argv: installArgv(p.id, opts.scope), state: 'failed', output: `${p.id} is not in ${wanted.source.path}` });
+        return { ok: missing.length === 0, steps };
+    }
+    let ok = true;
+    for (const plugin of plugins) {
+        const argv = installArgv(plugin.id, opts.scope);
+        if (!cloneHas(market, plugin.id, fs)) {
+            steps.push({ argv, state: plugin.required ? 'failed' : 'pending', output: `${plugin.id} is not in the ruflo marketplace${plugin.required ? ' even after the update' : ' yet (pending)'}` });
+            ok &&= !plugin.required;
+            continue;
+        }
+        ok = (await run(argv, INSTALL_TIMEOUT_MS)) && ok;
+    }
+    return { ok, steps };
+}
+/** `claude plugin uninstall` for each id, every failure collected. */
+export async function uninstallPlugins(opts) {
+    const exec = opts.exec ?? nodeExec;
+    const steps = [];
+    for (const id of opts.ids) {
+        const argv = uninstallArgv(id, opts.scope);
+        let result;
+        try {
+            result = await exec(opts.claude, argv, { cwd: opts.projectRoot, timeout: INSTALL_TIMEOUT_MS, env: opts.env ?? process.env });
+        }
+        catch (error) {
+            result = { code: 1, stdout: '', stderr: error.message };
+        }
+        steps.push({ argv, state: result.code === 0 ? 'ok' : 'failed', output: `${result.stdout}${result.stderr}`.trim() });
+    }
+    return { ok: steps.every((st) => st.state === 'ok'), steps };
+}
+//# sourceMappingURL=plugin-repair.js.map