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): Plugins page detects the marketplace; install, update, enable, disable (ADR-434)

ruve139b03a570b
diff --git a/plugins/ruflo-console/hooks/bindings.ts b/plugins/ruflo-console/hooks/bindings.ts
index 5a1f3ef029..1f69102665 100644
--- a/plugins/ruflo-console/hooks/bindings.ts
+++ b/plugins/ruflo-console/hooks/bindings.ts
@@ -17,6 +17,7 @@ import { pluginNames, settingsActions } from './settings'
import { catalogOf } from './plugin-catalog'
import { devtoolsActions } from './devtools'
import { HARNESSES, harnessSpec, isAutoAccept, isLive, newSession, send, whyNotRun } from './harness'
+import { pluginSpec } from './plugin-ops'
import { startSpec } from './starts'
import { plain } from './data/parse'
import type { Host } from './host'
@@ -202,6 +203,7 @@ export function actionsOf(state: State, host: Host, runner: Runner, steps: Steps
host.invalidate()
},
focus: key => void host.focus(PANE_ID, key).catch(() => undefined),
+ plugin: (op, name = '') => runner.ask(pluginSpec(op, name), 'that plugin name cannot be passed'),
start: (id, text = '') => runner.ask(startSpec(id, Date.now(), text), id === 'mission' || id === 'task' ? 'type it first (it may not start with -)' : 'that start cannot run here'),
// The main menu's prompt, as a board's: a key (2, w, i), a name (swarm, x.ruv.io), ? for help, O to log off.
menu: text => {
diff --git a/plugins/ruflo-console/hooks/plugin-ops.ts b/plugins/ruflo-console/hooks/plugin-ops.ts
new file mode 100644
index 0000000000..eef36e888c
--- /dev/null
+++ b/plugins/ruflo-console/hooks/plugin-ops.ts
@@ -0,0 +1,45 @@
+/**
+ * What the Plugins page can do to a ruflo plugin or to the marketplace, as asks: each is one fixed `claude plugin ...` argv (verbs
+ * checked against `claude plugin --help`), shown on the confirm row before it runs, never a ruflo CLI call. The plugin name is one
+ * word from the marketplace clone's listing, validated here, and always qualified with the ruflo marketplace so another marketplace's
+ * plugin of the same name is never touched. Tested in tests/plugin-ops.spec.ts.
+ */
+import type { ActionSpec } from './actions'
+
+export type PluginOp = 'install' | 'update' | 'enable' | 'disable' | 'refresh'
+
+const MARKET = 'ruflo'
+const NAME = /^[a-z0-9][a-z0-9._-]{0,59}$/
+
+export const PLUGIN_OP_LABEL: Record<PluginOp, string> = { install: 'install', update: 'update', enable: 'enable', disable: 'disable', refresh: 'update the marketplace' }
+
+/** The ask for `op` on `name` (ignored by `refresh`), or null when the name is not one word of the shape a plugin has. */
+export function pluginSpec(op: PluginOp, name = ''): ActionSpec | null {
+ if (op === 'refresh') {
+ return {
+ label: `update the ${MARKET} marketplace clone (git pull of the plugin list: network)`,
+ args: [],
+ argv: ['claude', 'plugin', 'marketplace', 'update', MARKET],
+ shows: `claude plugin marketplace update ${MARKET}`,
+ expect: 'a newer clone of the ruflo marketplace',
+ note: 'NETWORK: pulls the marketplace from GitHub',
+ timeoutMs: 120_000,
+ }
+ }
+
+ if (!NAME.test(name)) return null
+
+ const id = `${name}@${MARKET}`
+ const label = { install: `install ${id} (writes Claude Code's plugin records; network)`, update: `update ${id} (network)`, enable: `enable ${id}`, disable: `disable ${id}` }[op]
+
+ return {
+ label,
+ args: [],
+ argv: ['claude', 'plugin', op, id],
+ shows: `claude plugin ${op} ${id}`,
+ expect: op === 'install' ? `${id} in the installed plugins` : `${id} ${op}d`,
+ note: op === 'install' || op === 'update' ? 'NETWORK: fetches the plugin; it loads in the next session' : 'takes effect in the next session',
+ ...(op === 'install' && { verify: snapshot => (snapshot.plugins.installed ?? []).some(plugin => plugin.id === id) }),
+ timeoutMs: 120_000,
+ }
+}
diff --git a/plugins/ruflo-console/hooks/views/common.ts b/plugins/ruflo-console/hooks/views/common.ts
index 1164192009..c4dea12ca0 100644
--- a/plugins/ruflo-console/hooks/views/common.ts
+++ b/plugins/ruflo-console/hooks/views/common.ts
@@ -21,6 +21,7 @@ import type { Grid } from '../gfx/raster'
import type { MemoryActions } from '../memory-lab'
import type { NavActions } from '../nav-state'
import type { SkillActions } from '../skills'
+import type { PluginOp } from '../plugin-ops'
import { START_LABEL, type StartId } from '../starts'
import type { MoreSkillActions } from '../skills-lab'
import { VIEWS, type HarnessId, type NavStyle, type State, type ViewId } from '../state'
@@ -65,6 +66,8 @@ export type Actions = {
/** Puts the keys in one of the pane's fields by its key (a row that takes text focuses its field). */
focus: (key: string) => void
start: (id: StartId, text?: string) => void
+ /** A plugin or marketplace operation on the Plugins page: asks first, then runs one `claude plugin` command. */
+ plugin: (op: PluginOp, name?: string) => void
/** The main menu's prompt: a key or a name takes the person to that area. */
menu: (text: string) => void
term: { harness: (id: HarnessId) => void; draft: (text: string) => void; submit: (text: string) => void; stop: () => void; fresh: () => void; clear: () => void; load: (id: HarnessId, text: string) => void; /** A click on an ask link: opens the terminal, picks the agent and sends the text at once (read-only, plan mode, the saved per-turn budget): the reply streams in with no second click. */ ask: (id: HarnessId, text: string) => void; /** Moves the window up (positive) or down by screen rows. */ scroll: (by: number) => void; /** Puts an earlier question back in the field. */ reuse: (text: string) => void }
diff --git a/plugins/ruflo-console/hooks/views/plugins.ts b/plugins/ruflo-console/hooks/views/plugins.ts
index b7f1b2c017..14ac45a86a 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, button, col, kv, picture, rule, starts, text, THEME, type Ctx } from './common'
+import { ago, button, col, kv, picture, row, rule, section, starts, text, THEME, type Ctx } from './common'
const WEEK = 7 * 86_400_000
@@ -41,6 +41,12 @@ export function pluginsView(ctx: Ctx): RenderElement {
}
}
+ if (market !== null) {
+ const isStale = facts.missingFromClone.length > 0
+
+ rows.push(row(ctx, [text(ctx, ' '), button(ctx, 'plg-refresh', isStale ? '▸ update the marketplace (the clone is stale)' : '▸ update the marketplace', () => ctx.act.plugin('refresh'), isStale ? { primary: true } : undefined)]))
+ }
+
const ruflo = (facts.installed ?? []).filter(plugin => plugin.marketplace === RUFLO_MARKET)
const enabled = ruflo.filter(plugin => facts.enabled.has(plugin.id)).length
@@ -53,6 +59,40 @@ export function pluginsView(ctx: Ctx): RenderElement {
if (gone.length > 0) rows.push(text(ctx, `installed but gone from the clone: ${gone.map(plugin => plugin.name).join(', ')}`, { color: THEME.warn }))
+ // Each installed ruflo plugin: its state and the two things worth doing to it. The marketplace's other plugins can be installed from here.
+ if (ruflo.length > 0) {
+ rows.push(
+ ...section(
+ ctx,
+ 'plg-installed',
+ 'Installed plugins',
+ `${ruflo.length} · update, enable, disable`,
+ ruflo.map(plugin => {
+ const isOn = facts.enabled.has(plugin.id)
+
+ return row(ctx, [
+ text(ctx, ` ${isOn ? '●' : '○'} ${plugin.name.padEnd(26)} ${plugin.version.padEnd(10)}`, { color: isOn ? THEME.ok : undefined, dimColor: !isOn }),
+ button(ctx, `plg-update-${plugin.name}`, 'update', () => ctx.act.plugin('update', plugin.name)),
+ button(ctx, `plg-toggle-${plugin.name}`, isOn ? 'disable' : 'enable', () => ctx.act.plugin(isOn ? 'disable' : 'enable', plugin.name)),
+ ])
+ }),
+ false,
+ ),
+ )
+ }
+
+ const installedNames = new Set(ruflo.map(plugin => plugin.name))
+ const available = (facts.rufloOffered ?? []).filter(name => !installedNames.has(name))
+
+ if (market !== null && available.length > 0) {
+ rows.push(
+ ...section(ctx, 'plg-available', 'Available to install', `${available.length} in the marketplace`, [
+ ...available.slice(0, 12).map(name => row(ctx, [text(ctx, ` ○ ${name.padEnd(30)}`, { dimColor: true }), button(ctx, `plg-install-${name}`, 'install', () => ctx.act.plugin('install', name))])),
+ ...(available.length > 12 ? [text(ctx, ` +${available.length - 12} more: the Plugin Catalog lists every one`, { dimColor: true })] : []),
+ ], ruflo.length === 0),
+ )
+ }
+
rows.push(rule(ctx, 'Mods', 'function hooks'))
rows.push(kv(ctx, PLUGIN_NAME, 'loaded (you are reading it)', THEME.ok))
rows.push(kv(ctx, 'ruflo-mods', state.ruflo.snapshot !== null ? 'seated ($.ruflo answers)' : 'not seated in this session', state.ruflo.snapshot !== null ? THEME.ok : undefined))
diff --git a/plugins/ruflo-console/hooks/views/steps.ts b/plugins/ruflo-console/hooks/views/steps.ts
index 9159cbf58c..f551806f41 100644
--- a/plugins/ruflo-console/hooks/views/steps.ts
+++ b/plugins/ruflo-console/hooks/views/steps.ts
@@ -88,8 +88,8 @@ export const STEPS: Partial<Record<ViewId, { title: string; steps: readonly Step
plugins: {
title: 'Get the ruflo plugins',
steps: [
- { label: 'Add the ruflo marketplace', why: 'so Claude Code can install its plugins', go: { start: 'marketplace' } },
- { label: 'Open the Plugin Catalog', why: 'every plugin, mod and skill', go: { view: 'market' } },
+ { label: 'Add the ruflo marketplace', why: 'so Claude Code can install its plugins', go: { start: 'marketplace' }, done: s => s.plugins.markets?.some(market => market.name === 'ruflo') === true },
+ { label: 'Install a ruflo plugin', why: 'pick one below, or in the Plugin Catalog', go: { view: 'market' }, done: s => (s.plugins.installed ?? []).some(plugin => plugin.marketplace === 'ruflo') },
],
},
}
diff --git a/plugins/ruflo-console/tests/plugin-ops.spec.ts b/plugins/ruflo-console/tests/plugin-ops.spec.ts
new file mode 100644
index 0000000000..34ffcc946a
--- /dev/null
+++ b/plugins/ruflo-console/tests/plugin-ops.spec.ts
@@ -0,0 +1,90 @@
+/**
+ * The Plugins page's operations (ADR-434): each is one fixed `claude plugin` argv, always qualified with the ruflo marketplace, and a
+ * name that is not one plugin-shaped word is refused. The page's "Start here" card sees an added marketplace as done. Run with
+ * npx vitest run plugins/ruflo-console/tests/plugin-ops.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { pluginSpec } from '../hooks/plugin-ops'
+import { newState } from '../hooks/state'
+import { viewText } from '../hooks/views/pane'
+import { stepsRows } from '../hooks/views/steps'
+
+const act = (() => {
+ const proxy: unknown = new Proxy(() => undefined, { get: (_t, key) => (key === 'then' ? undefined : proxy), apply: () => undefined })
+
+ return proxy
+})() as never
+
+describe('pluginSpec', () => {
+ it('is one fixed claude plugin argv, qualified with the ruflo marketplace', () => {
+ expect(pluginSpec('install', 'ruflo-core')?.argv).toEqual(['claude', 'plugin', 'install', 'ruflo-core@ruflo'])
+ expect(pluginSpec('disable', 'ruflo-swarm')?.argv).toEqual(['claude', 'plugin', 'disable', 'ruflo-swarm@ruflo'])
+ expect(pluginSpec('update', 'ruflo-mods')?.shows).toBe('claude plugin update ruflo-mods@ruflo')
+ expect(pluginSpec('refresh')?.argv).toEqual(['claude', 'plugin', 'marketplace', 'update', 'ruflo'])
+ })
+
+ it('refuses a name that is not one plugin-shaped word, so nothing can be smuggled into the argv', () => {
+ for (const bad of ['', 'a b', 'x;whoami', '--scope', '-y', 'a@evil', '../x', '$(id)', 'A'.repeat(61)]) expect(pluginSpec('install', bad), bad).toBeNull()
+ })
+
+ it('verifies an install against the installed records, and notes that the network is touched', () => {
+ const spec = pluginSpec('install', 'ruflo-core')
+ const snapshot = (ids: string[]) => ({ plugins: { installed: ids.map(id => ({ id })) } }) as never
+
+ expect(spec?.verify?.(snapshot(['ruflo-core@ruflo']))).toBe(true)
+ expect(spec?.verify?.(snapshot(['ruflo-core@other']))).toBe(false)
+ expect(spec?.note).toContain('NETWORK')
+ })
+})
+
+describe('the Plugins page', () => {
+ const withMarket = (installed: string[]) => {
+ const state = newState({})
+
+ state.view = 'plugins'
+ state.configDir = '/home/u/.claude'
+ state.snapshot = {
+ isRufloProject: false,
+ plugins: {
+ installed: installed.map(name => ({ id: `${name}@ruflo`, name, marketplace: 'ruflo', version: '1.0.0', scope: 'user' })),
+ enabled: new Set(installed.map(name => `${name}@ruflo`)),
+ markets: [{ name: 'ruflo', location: '/m/ruflo', updatedMs: Date.now(), isAutoUpdate: true }],
+ rufloOffered: ['ruflo-core', 'ruflo-swarm', 'ruflo-mods'],
+ missingFromClone: [],
+ },
+ } as never
+
+ return state
+ }
+
+ it('does not offer to add a marketplace that is added, and lists what can be installed', () => {
+ const text = viewText({ state: withMarket(['ruflo-core']), nowMs: Date.now(), columns: 120, act }, 'plugins')
+
+ expect(text).not.toContain('not added yet')
+ expect(text).toContain('Available to install')
+ expect(text).toContain('ruflo-swarm')
+ })
+
+ it('the Start here card marks the marketplace step done when it is added, and next when it is not', () => {
+ type El = { props: Record<string, unknown> }
+ const kit = { Box: (props: Record<string, unknown>): El => ({ props }), Text: (props: Record<string, unknown>): El => ({ props }), Button: (props: Record<string, unknown>): El => ({ props }), Input: (props: Record<string, unknown>): El => ({ props }) }
+ const flat = (el: unknown): El[] => {
+ const node = el as El
+
+ if (typeof node !== 'object' || node === null) return []
+
+ const kids = node.props.children
+
+ return [node, ...(Array.isArray(kids) ? kids.flatMap(flat) : typeof kids === 'object' ? flat(kids) : [])]
+ }
+ const lines = (state: ReturnType<typeof withMarket>): string[] => stepsRows({ kit, state, nowMs: 1, columns: 120, pictures: new Map(), act, cards: true } as never).flatMap(flat).map(node => String(node.props.children ?? ''))
+ const added = withMarket([])
+ const missing = withMarket([])
+
+ ;(missing.snapshot as { plugins: { markets: unknown } }).plugins.markets = []
+
+ expect(lines(added).join('|')).toMatch(/✔ 1\. Add the ruflo marketplace/)
+ expect(lines(missing).join('|')).toMatch(/▶ 1\. Add the ruflo marketplace/)
+ })
+})
diff --git a/v3/docs/adr/ADR-434-console-plugins-page-detects-marketplace-and-acts.md b/v3/docs/adr/ADR-434-console-plugins-page-detects-marketplace-and-acts.md
new file mode 100644
index 0000000000..20ec5bf2d5
--- /dev/null
+++ b/v3/docs/adr/ADR-434-console-plugins-page-detects-marketplace-and-acts.md
@@ -0,0 +1,22 @@
+# ADR 434: The Plugins page detects the marketplace, and can act on plugins
+
+Status: Accepted (ships in ruflo-console 0.26.0)
+
+Date: 2026 10 03
+
+Scope: `plugins/ruflo-console`: `hooks/plugin-ops.ts` (new), `hooks/views/plugins.ts`, `hooks/views/steps.ts`, `hooks/bindings.ts` (`plugin`), `hooks/views/common.ts` (`Actions.plugin`), `tests/plugin-ops.spec.ts` (new).
+
+## 1. The bug
+
+The page's "Start here: get the ruflo plugins" card showed "1. Add the ruflo marketplace" as the next step even when the marketplace was added. The page body read `known_marketplaces.json` correctly; the card's step simply had no `done` check, so it could never see it. Step 1 now checks the marketplace list; step 2 is "Install a ruflo plugin" and is done once a plugin from the ruflo marketplace is installed, so the card goes away when both are true. A spec calls `stepsRows` directly (a first version asserted on the page text, which does not include the card, and passed with the fix removed; it now fails without it).
+
+## 2. Capabilities added
+
+- **Update the marketplace** (primary button when the clone is stale): `claude plugin marketplace update ruflo`.
+- **Installed plugins** (folded): each ruflo plugin with its state (● enabled, ○ disabled) and version, and `update` and `enable`/`disable` buttons.
+- **Available to install**: what the clone lists that is not installed, each with an `install` button (twelve shown, the rest in the Plugin Catalog; open when nothing is installed yet).
+- Every one asks first (the confirm row shows the exact `claude plugin ...` command and whether it touches the network) and runs one fixed argv, always `<name>@ruflo`, never another marketplace's plugin. The name must be one lowercase plugin-shaped word, so nothing can be smuggled into the argv (spec). An install verifies against the installed records afterwards. Changes load in the next session.
+
+## 3. Not proven
+
+The commands were checked against `claude plugin --help`, not run (they write Claude Code's plugin records and use the network). Enable and disable have no verification (the snapshot reads enablement from settings, which a run does not re-read).