Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(ruflo-console): 0.9.0 — Plugin Catalog (every ruflo plugin, mod and skill), button sweep, tour GIF

ruved47d3755648
diff --git a/README.md b/README.md
index b5d5fe6c3a..10b4e61162 100644
--- a/README.md
+++ b/README.md
@@ -63,7 +63,7 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov
/reload-plugins
```
-`ruflo-console` is the cockpit above, `ruflo-mods` routes prompts and enforces policy in-process, `ruflo-swarm` shows the swarm in a pane, and `ruflo-ruos` adds the ruOS status segment. Open `/plugin` to confirm they appear in the active mods line.
+`ruflo-console` is the cockpit above, `ruflo-mods` routes prompts and enforces policy in-process, `ruflo-swarm` shows the swarm in a pane, and `ruflo-ruos` adds the ruOS status segment. Open `/plugin` to confirm they appear in the active mods line. Inside the console, `/ruflo market` is the Plugin Catalog: every ruflo plugin, mod and skill with what it ships, and buttons to install, enable, disable and update (each asks first).
## Quick Start
diff --git a/docs/assets/ruflo-console-tour.gif b/docs/assets/ruflo-console-tour.gif
index b1afa4d4ad..302ab46a90 100644
Binary files a/docs/assets/ruflo-console-tour.gif and b/docs/assets/ruflo-console-tour.gif differ
diff --git a/plugins/ruflo-console/.claude-plugin/plugin.json b/plugins/ruflo-console/.claude-plugin/plugin.json
index c62c797cb5..cd195e3a5e 100644
--- a/plugins/ruflo-console/.claude-plugin/plugin.json
+++ b/plugins/ruflo-console/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-console",
"description": "ruflo's cockpit inside Claude Code and the one /ruflo command for every ruflo mod (function hooks, early access). Views: overview with health alerts, swarm topology graph, claims flow with TTL rings, federation map, plugin health matrix, learning curve and pipeline, MetaHarness radar and audit trend, memory, cost gauge, agent timeline, approvals queue, event stream, a main menu, an x.ruv.io federation board, an AI terminal (codex, claude or both in remembered sessions, streamed), Skills (npx skills), a Hive-Mind view, a MetaHarness lab, agent drill-down; a command palette for confirm-gated actions through the ruflo CLI; a band above the prompt. Reads ruflo's files and the CLI's local JSON; anything not measured reads n/a; no network by default.",
- "version": "0.8.2",
+ "version": "0.9.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 925c259aa6..cf69c77955 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -5,6 +5,7 @@
import { claimTask, handoffClaim, releaseClaim, stealClaim, whyNot } from './actions'
import { EVENT_KINDS } from './data/events'
import { evolveActions } from './evolve'
+import { catalogActions } from './plugin-catalog'
import { devtoolsActions } from './devtools'
import { HARNESSES, harnessSpec, isLive, newSession, send, whyNotRun } from './harness'
import { startSpec } from './starts'
@@ -266,6 +267,7 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
// An rvlite query is MCP-only: it goes to the AI terminal typed, as â–¸ edit does, and runs only when sent.
vector: vectorActions(state, runner, text => actions.term.load('claude', text)),
evolve: evolveActions(state, host, text => actions.term.load('claude', text)),
+ catalog: catalogActions(state, host, runner, text => actions.term.load('claude', text)),
devtools: devtoolsActions(state, host, runner.runById, why => runner.ask(null, why)),
}
diff --git a/plugins/ruflo-console/hooks/controller.ts b/plugins/ruflo-console/hooks/controller.ts
index be292bd0f0..65d95c2f97 100644
--- a/plugins/ruflo-console/hooks/controller.ts
+++ b/plugins/ruflo-console/hooks/controller.ts
@@ -14,6 +14,7 @@ import { markPicture } from './gfx/pictures'
import type { Host } from './host'
import { agentLogs } from './ops'
import { createRunner, type Runner } from './runner'
+import { loadCatalog } from './plugin-catalog'
import { loadEvolve } from './evolve'
import { listSkills } from './skills'
import { CLI_PREFIXES, isBooting, PANE_ID, push, rowsOf, storeKeyOf, type State } from './state'
@@ -406,6 +407,8 @@ export function createController(state: State, host: Host): Controller {
}
// Opening Self-Evolution reads ruflo's own flywheel files (local, no CLI run); its checks wait for a click.
if (view === 'evolve') void loadEvolve(state, host)
+ // The catalog is read from the marketplace clone on disk: local, so opening it is enough.
+ if (view === 'market') loadCatalog(state, host)
}
/**
diff --git a/plugins/ruflo-console/hooks/data/plugin-catalog.ts b/plugins/ruflo-console/hooks/data/plugin-catalog.ts
new file mode 100644
index 0000000000..1894fa68d9
--- /dev/null
+++ b/plugins/ruflo-console/hooks/data/plugin-catalog.ts
@@ -0,0 +1,137 @@
+/**
+ * The ruflo marketplace as a catalog: every plugin its clone lists, with the skills, agents, commands, MCP config and
+ * mod (function hooks) each ships, read from the clone on disk. Read-only, bounded, nothing run: a file over the cap,
+ * a name that is not a plain word and a path with `..` are skipped, and every read may be refused.
+ */
+import type { ReaderFs } from './files'
+import { plain } from './parse'
+
+export type CatalogPlugin = {
+ name: string
+ description: string
+ version: string | null
+ /** Folder of the plugin inside the clone (absolute). */
+ dir: string
+ skills: string[]
+ agents: string[]
+ commands: string[]
+ hasMcp: boolean
+ /** A `hooks/register.ts` makes it a mod: function hooks run in the engine. */
+ isMod: boolean
+}
+
+const NAME = /^[A-Za-z0-9._-]{1,80}$/
+const PLUGINS_MAX = 200
+const LIST_MAX = 200
+const DOC_BYTES = 120_000
+/** Lines of a SKILL.md or command file the Result panel shows. */
+export const DOC_LINES = 40
+
+const recordOf = (value: unknown): Record<string, unknown> | null => (typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : null)
+
+const safeSource = (source: unknown): string | null =>
+ typeof source === 'string' && source.startsWith('./') && !source.split('/').includes('..') && source.length < 200 ? source.slice(2).replace(/\/+$/, '') : null
+
+async function namesIn(fs: ReaderFs, dir: string, kind: 'dir' | 'md'): Promise<string[]> {
+ const entries = await fs.list(dir).catch(() => [])
+
+ return entries
+ .flatMap(entry => {
+ const isDir = entry.kind === undefined ? !entry.name.includes('.') : entry.kind === 'directory' || entry.kind === 'dir'
+ const name = kind === 'md' ? entry.name.replace(/\.md$/, '') : entry.name
+
+ return (kind === 'md' ? entry.name.endsWith('.md') && !isDir : isDir) && NAME.test(name) ? [name] : []
+ })
+ .sort()
+ .slice(0, LIST_MAX)
+}
+
+const exists = async (fs: ReaderFs, path: string): Promise<boolean> => (await fs.stat(path).catch(() => undefined)) !== undefined
+
+async function pluginOf(fs: ReaderFs, location: string, entry: Record<string, unknown>): Promise<CatalogPlugin | null> {
+ const name = entry.name
+ const source = safeSource(entry.source)
+
+ if (typeof name !== 'string' || !NAME.test(name) || source === null) return null
+
+ const dir = `${location}/${source}`
+ const manifest = await fs.read(`${dir}/.claude-plugin/plugin.json`).then(
+ text => recordOf(JSON.parse(text)),
+ () => null,
+ )
+ const [skills, agents, commands, hasMcp, isMod] = await Promise.all([namesIn(fs, `${dir}/skills`, 'dir'), namesIn(fs, `${dir}/agents`, 'md'), namesIn(fs, `${dir}/commands`, 'md'), exists(fs, `${dir}/.mcp.json`), exists(fs, `${dir}/hooks/register.ts`)])
+ const version = typeof manifest?.version === 'string' ? plain(manifest.version, 30) : typeof entry.version === 'string' ? plain(entry.version, 30) : null
+
+ return { name, description: plain(typeof entry.description === 'string' ? entry.description : typeof manifest?.description === 'string' ? manifest.description : '', 400), version, dir, skills, agents, commands, hasMcp, isMod }
+}
+
+/** Every plugin the marketplace clone at `location` lists, or null when its manifest cannot be read. */
+export async function readCatalog(fs: ReaderFs, location: string): Promise<CatalogPlugin[] | null> {
+ if (!location.startsWith('/') || location.split('/').includes('..')) return null
+
+ const raw = await fs.read(`${location}/.claude-plugin/marketplace.json`).catch(() => null)
+ let list: unknown[] = []
+
+ try {
+ const plugins = raw === null ? null : recordOf(JSON.parse(raw))?.plugins
+
+ if (!Array.isArray(plugins)) return null
+
+ list = plugins.slice(0, PLUGINS_MAX)
+ } catch {
+ return null
+ }
+
+ const found: CatalogPlugin[] = []
+
+ // Eight at a time: forty-odd plugins are a few hundred small reads, none of which should crowd the engine's own.
+ for (let at = 0; at < list.length; at += 8) {
+ const batch = await Promise.all(
+ list.slice(at, at + 8).map(async entry => {
+ const record = recordOf(entry)
+
+ return record === null ? null : pluginOf(fs, location, record).catch(() => null)
+ }),
+ )
+
+ for (const plugin of batch) if (plugin !== null) found.push(plugin)
+ }
+
+ return found.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** A skill, agent or command file's first lines (and its frontmatter description), or null when it cannot be read. */
+export async function readDoc(fs: ReaderFs, plugin: CatalogPlugin, kind: 'skill' | 'agent' | 'command', name: string): Promise<{ description: string; lines: string[] } | null> {
+ if (!NAME.test(name)) return null
+
+ const path = kind === 'skill' ? `${plugin.dir}/skills/${name}/SKILL.md` : `${plugin.dir}/${kind === 'agent' ? 'agents' : 'commands'}/${name}.md`
+ const stat = await fs.stat(path).catch(() => undefined)
+
+ if (stat === undefined || (stat.size ?? 0) > DOC_BYTES) return null
+
+ const text = await fs.read(path).catch(() => null)
+
+ if (text === null) return null
+
+ const lines = text.split('\n').map(line => plain(line, 200))
+ const description = lines.find(line => /^description:/i.test(line))?.replace(/^description:\s*/i, '').replace(/^["']|["']$/g, '') ?? ''
+
+ return { description: plain(description, 200), lines: lines.slice(0, DOC_LINES) }
+}
+
+export type CatalogMode = 'all' | 'installed' | 'missing' | 'mods' | 'skills' | 'agents'
+
+/** The plugins a mode and a filter word keep: the word matches a name, a description, or any skill/agent/command name. */
+export function visible(all: readonly CatalogPlugin[], installed: ReadonlySet<string>, mode: CatalogMode, word: string): CatalogPlugin[] {
+ const needle = word.trim().toLowerCase()
+
+ return all.filter(plugin => {
+ if (mode === 'installed' && !installed.has(plugin.name)) return false
+ if (mode === 'missing' && installed.has(plugin.name)) return false
+ if (mode === 'mods' && !plugin.isMod) return false
+ if (mode === 'skills' && plugin.skills.length === 0) return false
+ if (mode === 'agents' && plugin.agents.length === 0) return false
+
+ return needle === '' || [plugin.name, plugin.description, ...plugin.skills, ...plugin.agents, ...plugin.commands].some(text => text.toLowerCase().includes(needle))
+ })
+}
diff --git a/plugins/ruflo-console/hooks/palette.ts b/plugins/ruflo-console/hooks/palette.ts
index 8999834709..ec5b250e5c 100644
--- a/plugins/ruflo-console/hooks/palette.ts
+++ b/plugins/ruflo-console/hooks/palette.ts
@@ -10,6 +10,7 @@ import { hiveBroadcast, hivePropose, hiveSpawn, hiveVote } from './hive'
import { claimTask, handoffClaim, releaseClaim, stealClaim, type ActionSpec } from './actions'
import { MEM_KEYWORDS, MEM_LAB, memSpecOf, memWhy } from './memory-lab'
import { EVOLVE, evolveSpec, evolveWhy } from './evolve'
+import { catalogPalette } from './plugin-catalog'
import { devPalette } from './devtools'
import { LAB, labSpec, labWhy } from './mh-lab'
import { PERF } from './perf'
@@ -61,7 +62,7 @@ export function fuzzy(query: string, label: string): number | null {
return whole < 0 ? score : score + 5 + (whole === 0 || text[whole - 1] === ' ' ? 3 : 0)
}
-const TEXT_KEYWORDS: readonly string[] = ['route', 'store', 'search', 'propose', 'broadcast', 'task', 'mission', 'cost-budget', 'x-join', 'x-read', 'x-publish', 'x-create', 'x-grant', 'x-hub', 'x-admit', ...MEM_KEYWORDS, ...SECURE_KEYWORDS, 'skills-find', 'auto-wf-new', 'auto-wf-validate', 'auto-ap-history', 'auto-ses-save', 'auto-cfg-get', 'auto-cfg-set', 'auto-task-new', 'nn-train', 'nn-route', 'nn-explain', 'nn-predict']
+const TEXT_KEYWORDS: readonly string[] = ['route', 'store', 'search', 'propose', 'broadcast', 'task', 'mission', 'cost-budget', 'x-join', 'x-read', 'x-publish', 'x-create', 'x-grant', 'x-hub', 'x-admit', 'catalog-install', 'catalog-uninstall', 'catalog-enable', 'catalog-disable', 'catalog-update', ...MEM_KEYWORDS, ...SECURE_KEYWORDS, 'skills-find', 'auto-wf-new', 'auto-wf-validate', 'auto-ap-history', 'auto-ses-save', 'auto-cfg-get', 'auto-cfg-set', 'auto-task-new', 'nn-train', 'nn-route', 'nn-explain', 'nn-predict']
/** Every entry for the state as it is, before filtering. */
export function paletteEntries(state: State, nowMs: number): PaletteEntry[] {
@@ -171,6 +172,7 @@ export function paletteEntries(state: State, nowMs: number): PaletteEntry[] {
// Dev Tools: local reads run at once, the rest ask first; an entry with a field takes its text (see devtools.ts).
out.push(...devPalette(state))
+ out.push(...catalogPalette(state))
for (const worker of WORKERS) add(`worker-${worker}`, 'workers', `dispatch the ${worker} background worker`, { kind: 'spec', spec: dispatchWorker(worker), why: 'unknown worker' })
diff --git a/plugins/ruflo-console/hooks/plugin-catalog.ts b/plugins/ruflo-console/hooks/plugin-catalog.ts
new file mode 100644
index 0000000000..01ff8f6006
--- /dev/null
+++ b/plugins/ruflo-console/hooks/plugin-catalog.ts
@@ -0,0 +1,227 @@
+/**
+ * The Plugin Catalog: every plugin in the ruflo marketplace, with the skills, agents, commands, MCP config and mods
+ * (function hooks) each ships, and the buttons to install, enable, disable, update and remove one. The list is read from
+ * the marketplace clone on disk (data/catalog.ts); nothing is run to draw it. A change is one fixed `claude plugin <verb>
+ * <name>@ruflo --scope user` argv on the confirm row with its cost in words, and only a name in this catalog is ever put
+ * in an argv. â–¸ view reads a skill, agent or command file from disk (bounded, read-only) into the result lines; â–¸ use
+ * types `/<plugin>:<skill>` into the AI terminal draft and never sends it.
+ */
+import type { ActionSpec } from './actions'
+import { type CatalogMode, type CatalogPlugin, readCatalog, readDoc, visible } from './data/plugin-catalog'
+import { plain } from './data/parse'
+import { RUFLO_MARKET } from './data/snapshot'
+import type { Host } from './host'
+import type { PaletteEntry } from './palette'
+import type { Runner } from './runner'
+import type { State } from './state'
+
+export type Verb = 'install' | 'uninstall' | 'enable' | 'disable' | 'update'
+
+export const VERBS: readonly Verb[] = ['install', 'uninstall', 'enable', 'disable', 'update']
+export const MODES: readonly { id: CatalogMode; label: string }[] = [
+ { id: 'all', label: 'all' },
+ { id: 'installed', label: 'installed' },
+ { id: 'missing', label: 'not installed' },
+ { id: 'mods', label: 'mods' },
+ { id: 'skills', label: 'has skills' },
+ { id: 'agents', label: 'has agents' },
+]
+export const PAGE = 12
+
+export type CatalogState = {
+ plugins: CatalogPlugin[] | null
+ /** Why there is no list: the clone is not added, or its manifest is unreadable. */
+ why: string
+ loading: boolean
+ mode: CatalogMode
+ filter: string
+ page: number
+ selected: string | null
+ /** The selected plugin's skill descriptions, by skill name. */
+ described: Map<string, string>
+ /** The last â–¸ view or change: a label and the lines it showed. */
+ last: { label: string; ok: boolean; lines: string[] } | null
+}
+
+const states = new WeakMap<State, CatalogState>()
+const wired = new WeakMap<State, { host: Host; load: (text: string) => void }>()
+
+export function catalogOf(state: State): CatalogState {
+ let found = states.get(state)
+
+ if (found === undefined) {
+ found = { plugins: null, why: 'not read yet', loading: false, mode: 'all', filter: '', page: 0, selected: null, described: new Map(), last: null }
+ states.set(state, found)
+ }
+
+ return found
+}
+
+/** The ruflo plugins Claude Code reports installed, by bare name; the enabled ones apart. */
+export function installedOf(state: State): { installed: Set<string>; enabled: Set<string>; version: Map<string, string> } {
+ const facts = state.snapshot?.plugins
+ const mine = (facts?.installed ?? []).filter(plugin => plugin.marketplace === RUFLO_MARKET)
+
+ return {
+ installed: new Set(mine.map(plugin => plugin.name)),
+ enabled: new Set(mine.filter(plugin => facts?.enabled.has(plugin.id) === true).map(plugin => plugin.name)),
+ version: new Map(mine.map(plugin => [plugin.name, plugin.version])),
+ }
+}
+
+export const listOf = (state: State): CatalogPlugin[] => {
+ const catalog = catalogOf(state)
+ const { installed } = installedOf(state)
+
+ return visible(catalog.plugins ?? [], installed, catalog.mode, catalog.filter)
+}
+
+const NOTES: Record<Verb, string> = {
+ install: 'network: clones the plugin from the ruflo marketplace on GitHub, then writes it into ~/.claude/plugins and settings',
+ uninstall: 'removes the plugin from this machine (its settings entry too); its data folder goes unless kept',
+ enable: 'writes enabledPlugins in your user settings; reload plugins (/reload-plugins) to load it',
+ disable: 'writes enabledPlugins in your user settings; reload plugins (/reload-plugins) to unload it',
+ update: 'network: pulls the plugin’s newest version from the marketplace; restart Claude Code to apply it',
+}
+
+/** One change as a fixed argv, or null when the name is not in the catalog (never a name typed in freely). */
+export function changeSpec(state: State, verb: Verb, name: string): ActionSpec | null {
+ const plugins = catalogOf(state).plugins
+
+ if (plugins === null || !plugins.some(plugin => plugin.name === name)) return null
+
+ const argv = ['claude', 'plugin', verb, `${name}@${RUFLO_MARKET}`, '--scope', 'user'] as const
+
+ return { label: `${verb} plugin ${name}`, args: [], argv, shows: argv.join(' '), expect: `${name} ${verb === 'install' ? 'installed' : verb === 'uninstall' ? 'removed' : verb === 'update' ? 'updated' : verb + 'd'}`, note: NOTES[verb], timeoutMs: 180_000 }
+}
+
+/** Reads the marketplace clone's list and each plugin's contents from disk (local, nothing run); a no-op while reading. */
+export function loadCatalog(state: State, host: Host): void {
+ const catalog = catalogOf(state)
+
+ if (catalog.loading) return
+
+ const market = state.snapshot?.plugins.markets?.find(entry => entry.name === RUFLO_MARKET)
+
+ if (market?.location === undefined) {
+ catalog.why = market === undefined ? 'the ruflo marketplace is not added to Claude Code yet' : 'the ruflo marketplace clone has no readable location'
+ host.invalidate()
+
+ return
+ }
+
+ catalog.loading = true
+ host.invalidate()
+ void readCatalog(host.fs, market.location)
+ .then(plugins => {
+ catalog.plugins = plugins
+ catalog.why = plugins === null ? 'the clone’s marketplace.json is not readable' : plugins.length === 0 ? 'the clone lists no plugins' : ''
+ })
+ .catch(() => {
+ catalog.why = 'reading the clone was refused'
+ })
+ .finally(() => {
+ catalog.loading = false
+ host.invalidate()
+ })
+}
+
+export type CatalogActions = {
+ /** Reads the marketplace clone (again): the whole list, with each plugin's contents. */
+ load: () => void
+ mode: (mode: CatalogMode) => void
+ filter: (text: string) => void
+ page: (delta: number) => void
+ select: (name: string | null) => void
+ /** Reads a skill, agent or command file from disk into the result lines. */
+ view: (kind: 'skill' | 'agent' | 'command', plugin: string, item: string) => void
+ /** Types `/<plugin>:<item>` into the AI terminal draft: reviewed, never sent. */
+ use: (plugin: string, item: string) => void
+ change: (verb: Verb, name: string) => void
+}
+
+export function catalogActions(state: State, host: Host, runner: Runner, load: (text: string) => void): CatalogActions {
+ wired.set(state, { host, load })
+
+ const catalog = catalogOf(state)
+ const say = (label: string, ok: boolean, lines: string[]) => {
+ catalog.last = { label, ok, lines }
+ host.invalidate()
+ }
+ const find = (name: string) => catalog.plugins?.find(plugin => plugin.name === name) ?? null
+
+ const describe = async (plugin: CatalogPlugin) => {
+ await Promise.all(
+ plugin.skills.slice(0, 40).map(async skill => {
+ const key = `${plugin.name}/${skill}`
+
+ if (catalog.described.has(key)) return
+
+ const doc = await readDoc(host.fs, plugin, 'skill', skill).catch(() => null)
+
+ catalog.described.set(key, doc?.description ?? '')
+ }),
+ )
+ host.invalidate()
+ }
+
+ return {
+ load: () => loadCatalog(state, host),
+ mode: mode => {
+ catalog.mode = mode
+ catalog.page = 0
+ host.invalidate()
+ },
+ filter: text => {
+ catalog.filter = plain(text, 80)
+ catalog.page = 0
+ host.invalidate()
+ },
+ page: delta => {
+ const pages = Math.max(1, Math.ceil(listOf(state).length / PAGE))
+
+ catalog.page = Math.max(0, Math.min(pages - 1, catalog.page + delta))
+ host.invalidate()
+ },
+ select: name => {
+ catalog.selected = name
+
+ const plugin = name === null ? null : find(name)
+
+ if (plugin !== null) void describe(plugin)
+
+ host.invalidate()
+ },
+ view: (kind, pluginName, item) => {
+ const plugin = find(pluginName)
+
+ if (plugin === null) return say(`view ${item}`, false, [`${pluginName} is not in the catalog`])
+
+ void readDoc(host.fs, plugin, kind, item).then(
+ doc => say(`${pluginName} · ${kind} ${item}`, doc !== null, doc === null ? ['not readable: missing, too large, or refused'] : doc.lines),
+ () => say(`${pluginName} · ${kind} ${item}`, false, ['refused']),
+ )
+ },
+ use: (pluginName, item) => {
+ if (find(pluginName) === null || !/^[A-Za-z0-9._-]{1,80}$/.test(item)) return say(`use ${item}`, false, [`${pluginName} is not in the catalog`])
+
+ load(`/${pluginName}:${item}`)
+ say(`use ${pluginName}:${item}`, true, [`/${pluginName}:${item} is typed in the AI terminal: read it, then Enter twice sends it to claude`])
+ },
+ change: (verb, name) => runner.ask(changeSpec(state, verb, name), `${name} is not in the ruflo catalog`),
+ }
+}
+
+/** Palette entries so `/ruflo run catalog-install <name>` works headless; a name outside the catalog is refused. */
+export function catalogPalette(state: State): PaletteEntry[] {
+ const entries: PaletteEntry[] = VERBS.map(verb => ({
+ id: `catalog-${verb}`,
+ group: 'plugins',
+ label: `catalog-${verb} <plugin>: ${verb} a ruflo plugin (asks first)`,
+ run: { kind: 'text', keyword: `catalog-${verb}`, make: (text: string) => changeSpec(state, verb, text.trim()), why: () => 'a plugin name from the catalog (the Plugin Catalog view lists them)' },
+ }))
+
+ return [...entries, { id: 'catalog-open', group: 'plugins', label: 'open the Plugin Catalog', run: { kind: 'view', view: 'market' } }]
+}
+
+export const wiredFor = (state: State) => wired.get(state)
diff --git a/plugins/ruflo-console/hooks/state.ts b/plugins/ruflo-console/hooks/state.ts
index fd6fafc2b7..a249666879 100644
--- a/plugins/ruflo-console/hooks/state.ts
+++ b/plugins/ruflo-console/hooks/state.ts
@@ -15,7 +15,7 @@ import type { RufloRoute, RufloSnapshot } from '../types'
export const PLUGIN_NAME = 'ruflo-console'
export const PANE_ID = 'ruflo-console'
-export type ViewId = 'menu' | 'overview' | 'swarm' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools'
+export type ViewId = 'menu' | 'overview' | 'swarm' | 'hive' | 'claims' | 'federation' | 'plugins' | 'learning' | 'metaharness' | 'memory' | 'cost' | 'timeline' | 'approvals' | 'events' | 'missions' | 'xruv' | 'terminal' | 'skills' | 'agent' | 'secure' | 'perf' | 'automate' | 'neural' | 'vector' | 'evolve' | 'devtools' | 'market'
/**
* The views in tab order, each with its hotkey and the inline height it asks for. Digits are the first nine; the three
@@ -58,6 +58,8 @@ export const VIEWS: readonly { id: ViewId; key: string; label: string; short: st
{ id: 'evolve', key: '', label: 'Self-Evolution', short: 'Evo', icon: '🧬', blurb: 'the governed loop: flywheel receipts, ledger, lineage, the policy gate, the witness; Autogenous and rGi', rows: 44 },
// Keyless too. The menu prompt, the tab and /ruflo devtools reach it by name.
{ id: 'devtools', key: '', label: 'Dev Tools', short: 'Dev', icon: 'đź”§', blurb: 'the integration surface: GitHub, diff analysis, agenticow, WASM, browser, terminal, providers, maintenance', rows: 40 },
+ // Keyless too: the menu prompt, the tab, the Plugins view's â–¸ catalog and /ruflo market reach it by name.
+ { id: 'market', key: '', label: 'Plugin Catalog', short: 'Cat', icon: '📦', blurb: 'every ruflo plugin, mod and skill: what it ships, install, enable, disable, update, view and use', rows: 50 },
]
export const AGENT_VIEW = { id: 'agent' as const, rows: 28 }
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 4bde269473..9ad5ee2b40 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -7,6 +7,7 @@ import type { Elements, RenderChildren, RenderElement } from 'claude-code'
import type { ProbeResult } from '../data/cli'
import type { EvolveActions } from '../evolve'
+import type { CatalogActions } from '../plugin-catalog'
import type { DevtoolsActions } from '../devtools'
import type { Grid } from '../gfx/raster'
import type { MemoryActions } from '../memory-lab'
@@ -63,6 +64,8 @@ export type Actions = {
evolve: EvolveActions
/** The Dev Tools view: keep a field's text, and Enter in a field runs its entry. */
devtools: DevtoolsActions
+ /** The Plugin Catalog: read the clone, filter, select a plugin, view or use an item, change a plugin (each asks first). */
+ catalog: CatalogActions
}
export type Ctx = {
diff --git a/plugins/ruflo-console/hooks/views/menu.ts b/plugins/ruflo-console/hooks/views/menu.ts
index 6943623a56..b540f99d64 100644
--- a/plugins/ruflo-console/hooks/views/menu.ts
+++ b/plugins/ruflo-console/hooks/views/menu.ts
@@ -39,7 +39,7 @@ const GROUPS: readonly { title: string; sections: readonly { name: string; items
title: 'NETWORK & EXTEND',
sections: [
{ name: 'federate', items: [{ key: '4', label: 'Federation', go: 'federation' }, { key: 'w', label: 'x.ruv.io Board', go: 'xruv' }] },
- { name: 'extend', items: [{ key: '5', label: 'Plugins & Mods', go: 'plugins' }, { key: '·', label: 'Skills', go: 'skills' }] },
+ { name: 'extend', items: [{ key: '5', label: 'Plugins & Mods', go: 'plugins' }, { key: '·', label: 'Skills', go: 'skills' }, { key: '·', label: 'Plugin Catalog', go: 'market' }] },
],
},
{
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index e6d97d6654..90e5c9dcc1 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -13,6 +13,7 @@ import { claimsView } from './claims'
import { ago, button, clip, col, isBbs, row, setLook, text, THEME, type Ctx } from './common'
import { costView } from './cost'
import { evolveView } from './evolve'
+import { catalogView } from './plugin-catalog'
import { devtoolsView } from './devtools'
import { federationView } from './federation'
import { hiveView } from './hive'
@@ -70,6 +71,7 @@ const BODIES: Record<ViewId, (ctx: Ctx) => RenderElement> = {
vector: vectorView,
evolve: evolveView,
devtools: devtoolsView,
+ market: catalogView,
agent: agentView,
}
@@ -255,7 +257,7 @@ export function paneView(ctx: Ctx): RenderElement {
const isMenu = ctx.state.view === 'menu'
// The terminal's own Enter-again confirm stays under its field, where the field is.
const isTerminal = ctx.state.view === 'terminal'
- const gap = isBbs() && !isCompact ? [text(ctx, ' ')] : []
+ const gap = isBbs() && !isCompact && !isMenu ? [text(ctx, ' ')] : []
// The confirm row sits above the body in both layouts: below it, a tall view would push the question off the screen.
// Compact keeps every page's title and its line of purpose; only the banner and the spacing go.
const parts = isCompact
diff --git a/plugins/ruflo-console/hooks/views/plugin-catalog.ts b/plugins/ruflo-console/hooks/views/plugin-catalog.ts
new file mode 100644
index 0000000000..3d9e1eb58d
--- /dev/null
+++ b/plugins/ruflo-console/hooks/views/plugin-catalog.ts
@@ -0,0 +1,146 @@
+import type { RenderElement } from 'claude-code'
+
+import { catalogOf, installedOf, listOf, MODES, PAGE, type Verb } from '../plugin-catalog'
+import type { CatalogPlugin } from '../data/plugin-catalog'
+import { button, clip, col, kv, row, rule, text, THEME, type Ctx } from './common'
+
+/** The â–¸ verb a row ends with: install when absent, else enable or disable. */
+function verbOf(ctx: Ctx, plugin: CatalogPlugin): { verb: Verb; label: string } {
+ const { installed, enabled } = installedOf(ctx.state)
+
+ return !installed.has(plugin.name) ? { verb: 'install', label: 'install' } : enabled.has(plugin.name) ? { verb: 'disable', label: 'disable' } : { verb: 'enable', label: 'enable' }
+}
+
+function counts(plugin: CatalogPlugin): string {
+ return [plugin.skills.length > 0 ? `S${plugin.skills.length}` : '', plugin.agents.length > 0 ? `A${plugin.agents.length}` : '', plugin.commands.length > 0 ? `C${plugin.commands.length}` : '', plugin.hasMcp ? 'MCP' : '', plugin.isMod ? 'MOD' : ''].filter(Boolean).join(' ')
+}
+
+/** One plugin row: the whole row selects it, the trailing button changes it. */
+function pluginRow(ctx: Ctx, plugin: CatalogPlugin, lead: number): RenderElement {
+ const { installed, enabled } = installedOf(ctx.state)
+ const badge = enabled.has(plugin.name) ? '■' : installed.has(plugin.name) ? '□' : '·'
+ const act = verbOf(ctx, plugin)
+ const isPicked = catalogOf(ctx.state).selected === plugin.name
+ const press = () => ctx.act.catalog.select(isPicked ? null : plugin.name)
+
+ return row(
+ ctx,
+ [
+ ctx.kit.Button({ key: `cat-name-${plugin.name}`, label: ` ${badge} ${plugin.name} `.padEnd(lead, '.'), plain: true, ...(isPicked && { variant: 'primary' as const }), onPress: press }),
+ ctx.kit.Button({ key: `cat-about-${plugin.name}`, label: clip(`${counts(plugin).padEnd(18)} ${plugin.description}`, Math.max(4, ctx.columns - lead - 14)), plain: true, dimColor: true, onPress: press }),
+ ctx.kit.Button({ key: `cat-${act.verb}-${plugin.name}`, label: ` â–¸ ${act.label}`, plain: true, dimColor: true, onPress: () => ctx.act.catalog.change(act.verb, plugin.name) }),
+ ],
+ `cat-row-${plugin.name}`,
+ )
+}
+
+/** One skill, agent or command in the selected plugin: its name and what it says it is, with â–¸ view and â–¸ use. */
+function itemRow(ctx: Ctx, kind: 'skill' | 'agent' | 'command', plugin: CatalogPlugin, item: string): RenderElement {
+ const about = kind === 'skill' ? (catalogOf(ctx.state).described.get(`${plugin.name}/${item}`) ?? '') : ''
+ const view = () => ctx.act.catalog.view(kind, plugin.name, item)
+
+ return row(
+ ctx,
+ [
+ ctx.kit.Button({ key: `cat-${kind}-${plugin.name}-${item}`, label: ` ${item}`.padEnd(30, ' '), plain: true, onPress: view }),
+ ctx.kit.Button({ key: `cat-${kind}-about-${plugin.name}-${item}`, label: clip(about, Math.max(4, ctx.columns - 50)), plain: true, dimColor: true, onPress: view }),
+ ...(kind === 'agent' ? [] : [ctx.kit.Button({ key: `cat-use-${plugin.name}-${item}`, label: ' â–¸ use', plain: true, dimColor: true, onPress: () => ctx.act.catalog.use(plugin.name, item) })]),
+ ],
+ `cat-${kind}-row-${plugin.name}-${item}`,
+ )
+}
+
+function detailRows(ctx: Ctx, plugin: CatalogPlugin): RenderElement[] {
+ const { installed, enabled, version } = installedOf(ctx.state)
+ const state = enabled.has(plugin.name) ? 'installed and enabled' : installed.has(plugin.name) ? 'installed, disabled' : 'not installed'
+ const rows: RenderElement[] = [rule(ctx, plugin.name, state), text(ctx, ` ${plugin.description}`, { color: THEME.info })]
+
+ rows.push(kv(ctx, 'version', `${plugin.version ?? 'n/a'}${installed.has(plugin.name) ? ` (installed ${version.get(plugin.name) ?? '?'})` : ''}`))
+
+ const verbs: Verb[] = !installed.has(plugin.name) ? ['install'] : ['update', enabled.has(plugin.name) ? 'disable' : 'enable', 'uninstall']
+
+ rows.push(row(ctx, verbs.map(verb => button(ctx, `cat-do-${verb}-${plugin.name}`, verb, () => ctx.act.catalog.change(verb, plugin.name))), `cat-verbs-${plugin.name}`))
+
+ if (plugin.isMod) rows.push(text(ctx, ' MOD: function hooks run in the engine once this plugin is loaded (trust it like code you run)', { color: THEME.warn }))
+ if (plugin.hasMcp) rows.push(text(ctx, ' MCP: ships an .mcp.json: its servers start with the plugin', { dimColor: true }))
+
+ const section = (title: string, kind: 'skill' | 'agent' | 'command', items: string[]) => {
+ if (items.length === 0) return
+
+ rows.push(rule(ctx, title, `${items.length}${items.length > 12 ? ' · first 12 shown' : ''}`))
+ for (const item of items.slice(0, 12)) rows.push(itemRow(ctx, kind, plugin, item))
+ }
+
+ section('Skills', 'skill', plugin.skills)
+ section('Agents', 'agent', plugin.agents)
+ section('Commands', 'command', plugin.commands)
+
+ return rows
+}
+
+/** The last â–¸ view or change: what a skill file says, or why it could not be read. */
+function lastRows(ctx: Ctx): RenderElement[] {
+ const { last } = catalogOf(ctx.state)
+
+ if (last === null) return []
+
+ return [rule(ctx, 'Result', last.ok ? 'âś“' : 'âś—'), text(ctx, ` ${last.label}`, { bold: true, color: last.ok ? THEME.ok : THEME.bad }), ...last.lines.slice(0, 40).map(line => text(ctx, ` ${line}`))]
+}
+
+/**
+ * Every plugin the ruflo marketplace offers: what it ships (skills, agents, commands, MCP, mod), its state here, and the
+ * buttons to install, enable, disable, update or remove it, each asking first with its exact argv. The whole row selects
+ * a plugin and opens its contents; â–¸ view reads a skill, â–¸ use types it into the AI terminal.
+ */
+export function catalogView(ctx: Ctx): RenderElement {
+ const { state } = ctx
+ const catalog = catalogOf(state)
+ const rows: RenderElement[] = []
+
+ if (catalog.plugins === null) {
+ return col(ctx, [rule(ctx, 'Plugin Catalog', catalog.loading ? 'reading the marketplace clone…' : 'not read yet'), text(ctx, ` ${catalog.loading ? 'reading…' : catalog.why}`, { dimColor: true }), button(ctx, 'cat-load', '▸ read the catalog', () => ctx.act.catalog.load())], 'catalog')
+ }
+
+ const { installed, enabled } = installedOf(state)
+ const all = catalog.plugins
+ const list = listOf(state)
+ const pages = Math.max(1, Math.ceil(list.length / PAGE))
+ const page = Math.min(catalog.page, pages - 1)
+ const total = (pick: (plugin: CatalogPlugin) => number) => all.reduce((sum, plugin) => sum + pick(plugin), 0)
+ const lead = Math.max(24, Math.min(34, ctx.columns - 60))
+
+ rows.push(rule(ctx, 'Plugin Catalog', `${all.length} plugins · ${installed.size} installed · ${enabled.size} enabled`))
+ rows.push(text(ctx, ` ${total(plugin => plugin.skills.length)} skills · ${total(plugin => plugin.agents.length)} agents · ${total(plugin => plugin.commands.length)} commands · ${all.filter(plugin => plugin.hasMcp).length} MCP · ${all.filter(plugin => plugin.isMod).length} mods · ■ enabled □ installed · not installed`, { dimColor: true }))
+ rows.push(
+ row(
+ ctx,
+ MODES.map(mode => ctx.kit.Button({ key: `cat-mode-${mode.id}`, label: ` ${catalog.mode === mode.id ? 'â—Ź' : 'â—‹'} ${mode.label}`, plain: true, ...(catalog.mode === mode.id && { variant: 'primary' as const }), onPress: () => ctx.act.catalog.mode(mode.id) })),
+ 'cat-modes',
+ ),
+ )
+
+ const Input = ctx.kit.Input
+
+ rows.push(
+ Input === undefined
+ ? text(ctx, ' filter: from the palette (p): catalog filters need a surface with text fields', { dimColor: true })
+ : Input({ key: 'cat-filter', label: ' â–¸ filter', placeholder: 'a name, a skill, an agent or a word from a description: Enter filters', submitLabel: 'filter', onSubmit: value => ctx.act.catalog.filter(value) }),
+ )
+
+ // The result of a â–¸ view or a change sits above the list: a click far down a long catalog answers where it can be seen.
+ rows.push(...lastRows(ctx))
+ // The selected plugin's contents sit above the list too: opening one on a short screen must not push them off it.
+ const picked = all.find(plugin => plugin.name === catalog.selected)
+
+ if (picked !== undefined) rows.push(...detailRows(ctx, picked))
+
+ rows.push(rule(ctx, 'Plugins', `${list.length} shown · page ${page + 1} of ${pages}${catalog.filter !== '' ? ` · filter “${catalog.filter}”` : ''}`))
+ for (const plugin of list.slice(page * PAGE, page * PAGE + PAGE)) rows.push(pluginRow(ctx, plugin, lead))
+ if (list.length === 0) rows.push(text(ctx, ' nothing matches this mode and filter', { dimColor: true }))
+
+ rows.push(
+ row(ctx, [button(ctx, 'cat-prev', '◂ prev', () => ctx.act.catalog.page(-1), { hotkey: 'k' }), button(ctx, 'cat-next', 'next ▸', () => ctx.act.catalog.page(1), { hotkey: 'j' }), button(ctx, 'cat-reload', '↻ read again', () => ctx.act.catalog.load())], 'cat-pages'),
+ )
+
+ return col(ctx, rows, 'catalog')
+}
diff --git a/plugins/ruflo-console/hooks/views/plugins.ts b/plugins/ruflo-console/hooks/views/plugins.ts
index 695b85f9be..b7f1b2c017 100644
--- a/plugins/ruflo-console/hooks/views/plugins.ts
+++ b/plugins/ruflo-console/hooks/views/plugins.ts
@@ -2,7 +2,7 @@ import type { RenderElement } from 'claude-code'
import { EXPECTED_IN_MARKET, RUFLO_MARKET } from '../data/snapshot'
import { PLUGIN_NAME } from '../state'
-import { ago, col, kv, picture, rule, starts, text, THEME, type Ctx } from './common'
+import { ago, button, col, kv, picture, rule, starts, text, THEME, type Ctx } from './common'
const WEEK = 7 * 86_400_000
@@ -61,6 +61,7 @@ export function pluginsView(ctx: Ctx): RenderElement {
rows.push(kv(ctx, mod.name, `${mod.isLoaded ? 'loaded' : `REFUSED: ${mod.reason ?? 'no reason given'}`} · ${mod.provenance} · ${ago(mod.atMs, nowMs)}`, mod.isLoaded ? undefined : THEME.bad))
}
+ rows.push(button(ctx, 'plg-catalog', 'â–¸ open the Plugin Catalog: every ruflo plugin, mod and skill', () => ctx.act.view('market')))
rows.push(text(ctx, 'mods list: those registered after the console loaded (the engine admits earlier ones unseen)', { dimColor: true }))
return col(ctx, rows, 'plugins')
diff --git a/plugins/ruflo-console/scripts/smoke.sh b/plugins/ruflo-console/scripts/smoke.sh
index 2474dd0509..f0aff1d71b 100755
--- a/plugins/ruflo-console/scripts/smoke.sh
+++ b/plugins/ruflo-console/scripts/smoke.sh
@@ -11,9 +11,9 @@ step() { printf "→ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares ruflo-console 0.8.2"
+step "1. plugin.json declares ruflo-console 0.9.0"
grep -q '"name": "ruflo-console"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.8.2"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.9.0"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-console/tests/conformance.spec.ts b/plugins/ruflo-console/tests/conformance.spec.ts
index 09b6af5fdd..3b143520a4 100644
--- a/plugins/ruflo-console/tests/conformance.spec.ts
+++ b/plugins/ruflo-console/tests/conformance.spec.ts
@@ -7,6 +7,7 @@
* over a project with a hive-mind, so the entries that need a selection exist.
*/
import { spawnSync } from 'node:child_process'
+import { VERBS } from '../hooks/plugin-catalog'
import { readFileSync, readdirSync } from 'node:fs'
import { describe, expect, it } from 'vitest'
@@ -188,4 +189,13 @@ describe.skipIf(process.env.RUFLO_CONFORMANCE !== '1')('console actions vs the r
expect(problems).toEqual([])
}, 900_000)
+ it('every claude plugin verb the Plugin Catalog runs exists and takes --scope', () => {
+ for (const verb of VERBS) {
+ const run = spawnSync('claude', ['plugin', verb, '--help'], { encoding: 'utf8', timeout: 60_000 })
+ const help = `${run.stdout ?? ''}${run.stderr ?? ''}`
+
+ expect(help, `claude plugin ${verb}`).toMatch(/Usage: claude plugin/)
+ expect(help, `claude plugin ${verb}`).toContain('--scope')
+ }
+ }, 300_000)
})
diff --git a/plugins/ruflo-console/tests/fixtures/plugin-catalog.ts b/plugins/ruflo-console/tests/fixtures/plugin-catalog.ts
new file mode 100644
index 0000000000..664f042164
--- /dev/null
+++ b/plugins/ruflo-console/tests/fixtures/plugin-catalog.ts
@@ -0,0 +1,36 @@
+/** A small ruflo marketplace clone as Claude Code writes it: three plugins, one with skills, agents, commands, MCP and a mod. */
+const CLONE = '.claude/plugins/marketplaces/ruflo'
+
+const skill = (name: string, description: string) => `---\nname: ${name}\ndescription: ${description}\n---\n# ${name}\n\nStep one: do the thing.\nStep two: check it.\n`
+
+export const CATALOG_HOME = {
+ '.claude/plugins/installed_plugins.json': JSON.stringify({
+ version: 2,
+ plugins: {
+ 'ruflo-core@ruflo': [{ scope: 'user', version: '0.2.6', lastUpdated: '2026-07-30T12:06:11.791Z' }],
+ 'ruflo-swarm@ruflo': [{ scope: 'user', version: '0.2.1' }],
+ },
+ }),
+ '.claude/plugins/known_marketplaces.json': JSON.stringify({ ruflo: { installLocation: '/home/dev/.claude/plugins/marketplaces/ruflo', lastUpdated: '2026-09-03T18:45:31.282Z', autoUpdate: true } }),
+ [`${CLONE}/.claude-plugin/marketplace.json`]: JSON.stringify({
+ name: 'ruflo',
+ plugins: [
+ { name: 'ruflo-core', source: './plugins/ruflo-core', description: 'Core Ruflo MCP tools, commands, and orchestration patterns' },
+ { name: 'ruflo-mods', source: './plugins/ruflo-mods', description: 'ruflo as a Claude Code mod (function hooks)' },
+ { name: 'ruflo-swarm', source: './plugins/ruflo-swarm', description: 'Swarm coordination in a pane' },
+ { name: 'ruflo-bad', source: './../escape', description: 'a source that climbs out of the clone is skipped' },
+ ],
+ }),
+ [`${CLONE}/plugins/ruflo-core/.claude-plugin/plugin.json`]: JSON.stringify({ name: 'ruflo-core', version: '0.2.6' }),
+ [`${CLONE}/plugins/ruflo-core/skills/ruflo-doctor/SKILL.md`]: skill('ruflo-doctor', 'Diagnose a ruflo install and fix what it can'),
+ [`${CLONE}/plugins/ruflo-core/skills/ruflo-status/SKILL.md`]: skill('ruflo-status', 'Show swarm, memory and daemon status'),
+ [`${CLONE}/plugins/ruflo-core/agents/coder.md`]: '---\nname: coder\n---\nImplementation specialist.\n',
+ [`${CLONE}/plugins/ruflo-core/agents/reviewer.md`]: '---\nname: reviewer\n---\nReview specialist.\n',
+ [`${CLONE}/plugins/ruflo-core/commands/ruflo-init.md`]: '---\ndescription: Initialise ruflo here\n---\nRun init.\n',
+ [`${CLONE}/plugins/ruflo-core/.mcp.json`]: '{"mcpServers":{"ruflo":{"command":"npx"}}}',
+ [`${CLONE}/plugins/ruflo-mods/.claude-plugin/plugin.json`]: JSON.stringify({ name: 'ruflo-mods', version: '0.1.0' }),
+ [`${CLONE}/plugins/ruflo-mods/hooks/register.ts`]: 'export default {}',
+ [`${CLONE}/plugins/ruflo-swarm/.claude-plugin/plugin.json`]: JSON.stringify({ name: 'ruflo-swarm', version: '0.2.1' }),
+ [`${CLONE}/plugins/ruflo-swarm/skills/swarm-watch/SKILL.md`]: skill('swarm-watch', 'Watch a swarm in the pane'),
+ [`${CLONE}/plugins/ruflo-swarm/hooks/register.ts`]: 'export default {}',
+}
diff --git a/plugins/ruflo-console/tests/fixtures/world.ts b/plugins/ruflo-console/tests/fixtures/world.ts
index 9e06b85305..1c25a64909 100644
--- a/plugins/ruflo-console/tests/fixtures/world.ts
+++ b/plugins/ruflo-console/tests/fixtures/world.ts
@@ -110,9 +110,13 @@ export function worldOf(on: On, files: Readonly<Record<string, string>>, options
})
on('fs.list', ($, e) => {
const prefix = `${e.path ?? CWD}/`
- const names = [...all.keys()].filter(path => path.startsWith(prefix) && !path.slice(prefix.length).includes('/')).map(path => path.slice(prefix.length))
+ const below = [...all.keys()].filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length))
+ const files = below.filter(name => !name.includes('/'))
+ // A folder holding a file shows as a directory entry of its own, as a real listing does.
+ const dirs = [...new Set(below.filter(name => name.includes('/')).map(name => name.split('/')[0] as string))]
+ const entries = [...files.map(name => ({ name, kind: 'file' as const })), ...dirs.map(name => ({ name, kind: 'dir' as const }))]
- return refuse || names.length === 0 ? { deny: 'ENOENT' } : { value: names.map(name => ({ name, kind: 'file' as const, size: 1, mtimeMs: 1, isLink: false })) }
+ return refuse || entries.length === 0 ? { deny: 'ENOENT' } : { value: entries.map(entry => ({ ...entry, size: 1, mtimeMs: 1, isLink: false })) }
})
on('process.run', ($, e) => {
if (refuse) return { deny: 'process.run withheld' }
diff --git a/plugins/ruflo-console/tests/plugin-catalog.spec.ts b/plugins/ruflo-console/tests/plugin-catalog.spec.ts
new file mode 100644
index 0000000000..12f65b37de
--- /dev/null
+++ b/plugins/ruflo-console/tests/plugin-catalog.spec.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+
+import { readCatalog, readDoc, visible, type CatalogPlugin } from '../hooks/data/plugin-catalog'
+import type { ReaderFs } from '../hooks/data/files'
+
+const ROOT = '/h/.claude/plugins/marketplaces/ruflo'
+const files: Record<string, string> = {
+ [`${ROOT}/.claude-plugin/marketplace.json`]: JSON.stringify({
+ plugins: [
+ { name: 'a-plugin', source: './plugins/a-plugin', description: 'Does A things' },
+ { name: 'b-mod', source: './plugins/b-mod', description: 'A mod' },
+ { name: 'evil', source: './../../etc', description: 'climbs out' },
+ { name: 'bad name!', source: './plugins/x', description: 'not a word' },
+ ],
+ }),
+ [`${ROOT}/plugins/a-plugin/.claude-plugin/plugin.json`]: '{"version":"1.2.3"}',
+ [`${ROOT}/plugins/a-plugin/skills/alpha/SKILL.md`]: '---\nname: alpha\ndescription: "Alpha does a"\n---\nbody\n',
+ [`${ROOT}/plugins/a-plugin/agents/helper.md`]: 'x',
+ [`${ROOT}/plugins/a-plugin/commands/go.md`]: 'x',
+ [`${ROOT}/plugins/a-plugin/.mcp.json`]: '{}',
+ [`${ROOT}/plugins/b-mod/hooks/register.ts`]: 'x',
+}
+
+const fs: ReaderFs = {
+ read: async path => {
+ if (!(path in files)) throw new Error('ENOENT')
+
+ return files[path] as string
+ },
+ stat: async path => (path in files ? { size: (files[path] as string).length } : undefined),
+ list: async path => {
+ const below = Object.keys(files).filter(file => file.startsWith(`${path}/`)).map(file => file.slice(path.length + 1))
+
+ if (below.length === 0) throw new Error('ENOENT')
+
+ return [...new Set(below.map(name => name.split('/')[0] as string))].map(name => ({ name, kind: below.some(file => file === name) ? 'file' : 'dir' }))
+ },
+}
+
+describe('plugin catalog reader', () => {
+ it('lists each plugin with what it ships, skipping a climbing source and a non-word name', async () => {
+ const plugins = (await readCatalog(fs, ROOT)) as CatalogPlugin[]
+
+ expect(plugins.map(plugin => plugin.name)).toEqual(['a-plugin', 'b-mod'])
+ expect(plugins[0]).toMatchObject({ version: '1.2.3', skills: ['alpha'], agents: ['helper'], commands: ['go'], hasMcp: true, isMod: false })
+ expect(plugins[1]).toMatchObject({ isMod: true, skills: [] })
+ })
+
+ it('refuses a location with .. or a relative one, and a missing manifest', async () => {
+ expect(await readCatalog(fs, '/h/../etc')).toBeNull()
+ expect(await readCatalog(fs, 'relative/clone')).toBeNull()
+ expect(await readCatalog(fs, '/nowhere')).toBeNull()
+ })
+
+ it('reads a skill’s description from its frontmatter and bounds the lines', async () => {
+ const [plugin] = (await readCatalog(fs, ROOT)) as CatalogPlugin[]
+ const doc = await readDoc(fs, plugin as CatalogPlugin, 'skill', 'alpha')
+
+ expect(doc?.description).toBe('Alpha does a')
+ expect(doc?.lines.length).toBeLessThanOrEqual(40)
+ expect(await readDoc(fs, plugin as CatalogPlugin, 'skill', '../escape')).toBeNull()
+ })
+
+ it('filters by mode and by a word found in a name, description, or skill name', async () => {
+ const plugins = (await readCatalog(fs, ROOT)) as CatalogPlugin[]
+ const installed = new Set(['a-plugin'])
+
+ expect(visible(plugins, installed, 'installed', '').map(plugin => plugin.name)).toEqual(['a-plugin'])
+ expect(visible(plugins, installed, 'missing', '').map(plugin => plugin.name)).toEqual(['b-mod'])
+ expect(visible(plugins, installed, 'mods', '').map(plugin => plugin.name)).toEqual(['b-mod'])
+ expect(visible(plugins, installed, 'all', 'alpha').map(plugin => plugin.name)).toEqual(['a-plugin'])
+ expect(visible(plugins, installed, 'skills', '').map(plugin => plugin.name)).toEqual(['a-plugin'])
+ expect(visible(plugins, installed, 'all', 'nothing-like-this')).toEqual([])
+ })
+})
diff --git a/plugins/ruflo-console/tests/plugin-catalog.test.ts b/plugins/ruflo-console/tests/plugin-catalog.test.ts
new file mode 100644
index 0000000000..8711527371
--- /dev/null
+++ b/plugins/ruflo-console/tests/plugin-catalog.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, mock, test } from 'claude-code/testing'
+
+import { CATALOG_HOME } from './fixtures/plugin-catalog'
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+import { command, elementsOf, keyOf, paneAt, PLUGIN, SESSION, textOf, worldOf } from './fixtures/world'
+
+import type { TestBody } from 'claude-code/testing'
+
+type Body = Parameters<TestBody>
+async function opened($: Body[0], on: Body[1]) {
+ const world = worldOf(on, RUFLO_FILES, { home: CATALOG_HOME })
+
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command('market'))
+
+ const pane = await $.ui.mount({ ...paneAt(150), surface: 'terminal' as const, plugin: PLUGIN })
+
+ await pane.drawn()
+ await pane.drawn()
+
+ return { world, pane }
+}
+
+describe('plugin catalog', () => {
+ test('opening reads the clone from disk: every plugin with its counts and state, nothing run, a climbing source skipped', { options: { boot: false } }, async ($, on) => {
+ const { world, pane } = await opened($, on)
+ const tree = await pane.drawn()
+ const text = textOf(tree)
+
+ expect(text).toContain('3 plugins · 2 installed')
+ expect(text).toContain('3 skills · 2 agents · 1 commands · 1 MCP · 2 mods')
+ expect(text).toContain('â–  ruflo-core')
+ expect(text).toContain('· ruflo-mods')
+ expect(text).toContain('S2 A2 C1 MCP')
+ expect(text).not.toContain('ruflo-bad')
+ expect(elementsOf(tree, 'Button').map(keyOf)).toEqual(expect.arrayContaining(['cat-name-ruflo-core', 'cat-about-ruflo-core', 'cat-install-ruflo-mods', 'cat-mode-mods', 'cat-reload']))
+ expect(world.runs.filter(argv => argv[0] === 'claude')).toEqual([])
+ await pane.unmount()
+ })
+
+ test('modes and the filter narrow the list; the filter matches a skill name', { options: { boot: false } }, async ($, on) => {
+ const { pane } = await opened($, on)
+
+ await pane.press({ key: 'cat-mode-mods' })
+ expect(textOf(await pane.drawn())).toContain('2 shown')
+ expect(textOf(await pane.drawn())).not.toContain('ruflo-core ....')
+ await pane.press({ key: 'cat-mode-all' })
+ await pane.input({ key: 'cat-filter', text: 'doctor', kind: 'submit' })
+
+ const text = textOf(await pane.drawn())
+
+ expect(text).toContain('1 shown')
+ expect(text).toContain('ruflo-core')
+ await pane.unmount()
+ })
+
+ test('pressing a row opens its contents; â–¸ view reads the skill file; â–¸ use only types it into the terminal draft', { options: { boot: false } }, async ($, on) => {
+ const { world, pane } = await opened($, on)
+
+ await pane.press({ key: 'cat-name-ruflo-core' })
+ await pane.drawn()
+
+ let text = textOf(await pane.drawn())
+
+ expect(text).toContain('Skills')
+ expect(text).toContain('ruflo-doctor')
+ expect(text).toContain('Diagnose a ruflo install')
+ expect(text).toContain('reviewer')
+ expect(text).toContain('ruflo-init')
+
+ await pane.press({ key: 'cat-skill-ruflo-core-ruflo-doctor' })
+ await pane.drawn()
+ text = textOf(await pane.drawn())
+ expect(text).toContain('Step one: do the thing.')
+
+ await pane.press({ key: 'cat-use-ruflo-core-ruflo-doctor' })
+ text = textOf(await pane.drawn())
+ expect(text).toContain('TERMINAL')
+ const field = elementsOf(await pane.drawn(), 'Input').find(input => keyOf(input) === 'term-input') as { props?: { value?: string } } | undefined
+
+ expect(field?.props?.value).toContain('/ruflo-core:ruflo-doctor')
+ expect(world.runs.some(argv => argv[0] === 'claude' || argv[0] === 'codex')).toBe(false)
+ await pane.unmount()
+ })
+
+ test('install asks first with the exact argv and runs it once on yes; enable and disable follow the state', { options: { boot: false } }, async ($, on) => {
+ const { world, pane } = await opened($, on)
+ const claudeRuns = () => world.runs.filter(argv => argv[0] === 'claude')
+
+ await pane.press({ key: 'cat-install-ruflo-mods' })
+
+ const asked = textOf(await pane.drawn())
+
+ expect(asked).toContain('Confirm: install plugin ruflo-mods')
+ expect(asked).toContain('claude plugin install ruflo-mods@ruflo --scope user')
+ expect(asked).toContain('clones the plugin from the ruflo marketplace')
+ expect(claudeRuns()).toEqual([])
+ expect((await $.command.run(command('yes'))).text).toBeDefined()
+ expect(claudeRuns()).toEqual([['claude', 'plugin', 'install', 'ruflo-mods@ruflo', '--scope', 'user']])
+
+ // The enabled one offers disable, the installed-but-disabled one offers enable.
+ expect(elementsOf(await pane.drawn(), 'Button').map(keyOf)).toEqual(expect.arrayContaining(['cat-disable-ruflo-core', 'cat-enable-ruflo-swarm']))
+ await pane.unmount()
+ })
+
+ test('a name outside the catalog is refused headless; a listed one asks with its argv', { options: { boot: false } }, async ($, on) => {
+ const { world, pane } = await opened($, on)
+
+ expect((await $.command.run(command('run catalog-install ruflo-nope'))).text).toMatch(/not in the ruflo catalog|nothing to do/)
+ expect(world.runs.filter(argv => argv[0] === 'claude')).toEqual([])
+ expect((await $.command.run(command('run catalog-update ruflo-core'))).text).toContain('Asked: update plugin ruflo-core')
+ expect(world.runs.filter(argv => argv[0] === 'claude')).toEqual([])
+ await pane.unmount()
+ })
+})
diff --git a/plugins/ruflo-console/tests/sweep.test.ts b/plugins/ruflo-console/tests/sweep.test.ts
new file mode 100644
index 0000000000..bde9c7890b
--- /dev/null
+++ b/plugins/ruflo-console/tests/sweep.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, mock, test } from 'claude-code/testing'
+
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+import { cliAnswer, command, elementsOf, keyOf, paneAt, PLUGIN, SESSION, textOf, worldOf } from './fixtures/world'
+
+/** Every area, by the name `/ruflo <name>` takes. */
+const VIEWS = ['overview', 'swarm', 'hive', 'claims', 'federation', 'plugins', 'learning', 'metaharness', 'memory', 'cost', 'timeline', 'approvals', 'events', 'missions', 'xruv', 'skills', 'secure', 'perf', 'automate', 'neural', 'vector', 'evolve', 'devtools', 'market']
+
+/** Buttons that only move the cursor inside a list that has nothing to move over in the fixture world. */
+const SCROLL = /^(prev|next|up|down|older|newer|page|older-|newer-|refresh|close|task-next|approve-1|net-|sk-scope-project|evolve-reread|xr-(name|about)-|cat-load|cat-reload)/i
+
+describe('every button does something', () => {
+ for (const view of VIEWS) {
+ test(`${view}: pressing each button changes the screen, asks, or runs one thing`, { options: { boot: false } }, async ($, on) => {
+ const world = worldOf(on, RUFLO_FILES)
+
+ world.respond = argv => cliAnswer(argv)
+ mock.clock(on)
+ await $.session.start(SESSION)
+ await $.command.run(command(view))
+
+ const pane = await $.ui.mount({ ...paneAt(140), surface: 'terminal' as const, plugin: PLUGIN })
+ const keys = [...new Set(elementsOf(await pane.drawn(), 'Button').map(keyOf))].filter(key => !key.startsWith('tab-') && key !== '')
+ const dead: string[] = []
+
+ for (const key of keys) {
+ await $.command.run(command('no'))
+ await $.command.run(command(view))
+
+ const before = textOf(await pane.drawn())
+ const runs = world.runs.length
+
+ try {
+ await pane.press({ key })
+ } catch {
+ dead.push(`${key} (press threw)`)
+
+ continue
+ }
+
+ const after = textOf(await pane.drawn())
+
+ if (after === before && world.runs.length === runs && !SCROLL.test(key)) dead.push(key)
+ }
+
+ await pane.unmount()
+ expect(dead).toEqual([])
+ })
+ }
+})
diff --git a/scripts/ci-test-baseline.txt b/scripts/ci-test-baseline.txt
index e648960fd1..c34b77ceae 100644
--- a/scripts/ci-test-baseline.txt
+++ b/scripts/ci-test-baseline.txt
@@ -164,6 +164,8 @@ plugins/ruflo-console/tests/behaviour.test.ts
plugins/ruflo-console/tests/palette.test.ts
plugins/ruflo-console/tests/views.test.ts
plugins/ruflo-console/tests/labs.test.ts
+plugins/ruflo-console/tests/plugin-catalog.test.ts
+plugins/ruflo-console/tests/sweep.test.ts
plugins/ruflo-console/tests/devtools.test.ts
plugins/ruflo-console/tests/evolve.test.ts
plugins/ruflo-console/tests/vector.test.ts
diff --git a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md b/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
index ff80808493..d766faa501 100644
--- a/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
+++ b/v3/docs/adr/ADR-407-ruflo-console-cockpit.md
@@ -203,6 +203,12 @@ Two layout rules came from live clicks that seemed dead: the Result panel sits a
`tests/conformance.spec.ts` (`RUFLO_CONFORMANCE=1`) runs every action's argv against the real CLI's help and source, every `mcp exec` tool name against the registered tools, and the Vector Lab's argv against the ruvector CLI.
+## 11b. Plugin Catalog (0.9.0)
+
+`/ruflo market` (the Plugins view's ▸ button, the main menu, the tab) lists every plugin the ruflo marketplace offers, read from the marketplace clone on disk: nothing is run to draw it. Each row shows its state (■ enabled, □ installed, · not installed) and what it ships (S skills, A agents, C commands, MCP, MOD for function hooks, from a `hooks/register.ts`). Pressing a row opens its skills (with the description from each SKILL.md), agents and commands above the list; ▸ view reads the file from disk (bounded, read-only) and ▸ use types `/<plugin>:<skill>` into the AI terminal draft without sending it. Modes (all, installed, not installed, mods, has skills, has agents) and a text filter narrow the list.
+
+A change is one fixed `claude plugin <install|uninstall|enable|disable|update> <name>@ruflo --scope user` argv on the confirm row, with its cost in words (install and update reach GitHub). Only a name found in the catalog is ever put in an argv; `/ruflo run catalog-install <name>` (and the other four verbs) works headless and refuses anything else. Conformance checks that each verb exists and takes `--scope`. A button sweep (`tests/sweep.test.ts`) presses every button of every view and fails on one that changes nothing, except a short allowlist of cursor-only and self-link buttons.
+
## 12. Release gates
A console change ships only when all of these hold: