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): redesign the command palette page like the other sections (ADR-435)

ruvee291b86be92
diff --git a/plugins/ruflo-console/hooks/views/palette.ts b/plugins/ruflo-console/hooks/views/palette.ts
index 7d750e608c..22e4291703 100644
--- a/plugins/ruflo-console/hooks/views/palette.ts
+++ b/plugins/ruflo-console/hooks/views/palette.ts
@@ -1,19 +1,45 @@
import type { RenderElement } from 'claude-code'
-import { filterPalette, paletteEntries } from '../palette'
-import { button, col, row, rule, text, THEME, type Ctx } from './common'
+import { filterPalette, paletteEntries, type PaletteEntry } from '../palette'
+import { button, clip, col, row, rule, tagChip, text, THEME, type Ctx } from './common'
export const PALETTE_ROWS = 12
+/** What pressing an entry does, as the tag it wears: a page to go to, a read that runs at once, a change that asks first, a command that takes text. */
+export function entryTag(entry: PaletteEntry): { text: string; color: string } {
+ const run = entry.run
+
+ switch (run.kind) {
+ case 'view':
+ return { text: ' go ', color: THEME.info }
+ case 'drill':
+ return { text: 'drill', color: THEME.info }
+ case 'command':
+ return { text: ' cmd ', color: THEME.info }
+ case 'text':
+ return { text: 'text ', color: THEME.warn }
+ case 'spec':
+ return run.spec === null ? { text: ' n/a ', color: THEME.bad } : run.spec.isReadOnly === true ? { text: ' $0 ', color: THEME.ok } : { text: 'ask ', color: THEME.warn }
+ }
+}
+
+/** The text commands the palette takes (`route <words>`, `store <text>`…), one chip each, so they can be started by a click. */
+const keywordsOf = (all: readonly PaletteEntry[]): string[] => [...new Set(all.flatMap(entry => (entry.run.kind === 'text' ? [entry.run.keyword] : [])))].slice(0, 8)
+
/**
- * The command palette over the view: a text field (typing filters, Enter runs the best match) and the matches as
- * buttons. `x` opens it scoped to the selection's actions. While it is open the view's own buttons are not drawn, so
- * Tab and the arrows walk the matches.
+ * The command palette over the view, laid out like the other pages: a card with the filter field and the keywords that take text, and a
+ * card of matches. Each match is a dotted-leader row ending in what pressing it does (a tag: go, $0 read, ask first, takes text); the
+ * first, which Enter runs, is marked ▶ and primary. With nothing typed the matches are grouped under dim `── group ──` rules, as the menu
+ * groups its entries; once a query ranks them the group moves to the end of each row. `x` opens it scoped to the selection's actions.
+ * While it is open the view's own buttons are not drawn, so Tab and the arrows walk the matches.
*/
export function paletteView(ctx: Ctx): RenderElement {
const { state } = ctx
const all = paletteEntries(state, ctx.nowMs)
const matches = filterPalette(all, state.palette.query, state.palette.context)
+ const shown = matches.slice(0, PALETTE_ROWS)
+ const isGrouped = state.palette.query.trim() === ''
+ const lead = Math.max(22, Math.min(44, ctx.columns - 34))
const rows: RenderElement[] = [rule(ctx, state.palette.context === 'selection' ? 'Actions for the selection' : 'Palette', `${matches.length} of ${all.length}`)]
if (ctx.kit.Input !== undefined) {
@@ -36,20 +62,44 @@ export function paletteView(ctx: Ctx): RenderElement {
rows.push(text(ctx, 'this surface has no text field: pick an entry below, or use /ruflo run <entry> [text]', { dimColor: true }))
}
- for (const entry of matches.slice(0, PALETTE_ROWS)) {
+ const keywords = state.palette.context === 'selection' ? [] : keywordsOf(all)
+
+ if (keywords.length > 0) {
+ rows.push(row(ctx, [text(ctx, ' takes text ', { dimColor: true }), ...keywords.map(word => ctx.kit.Button({ key: `pal-kw-${word}`, label: ` ${word} `, plain: true, onPress: () => ctx.act.paletteQuery(`${word} `) }))], 'pal-keywords'))
+ }
+
+ rows.push(rule(ctx, 'Matches', matches.length === 0 ? 'none' : `${shown.length} shown · ▶ is what Enter runs`))
+
+ let previous = ''
+
+ shown.forEach((entry, i) => {
+ const tag = entryTag(entry)
+ const isFirst = i === 0
+
+ if (isGrouped && entry.group !== previous) rows.push(text(ctx, clip(`── ${entry.group} ${'─'.repeat(Math.max(0, ctx.columns - entry.group.length - 8))}`, ctx.columns - 2), { color: THEME.info, dimColor: true }))
+
+ previous = entry.group
rows.push(
- row(ctx, [
- ctx.kit.Text({ dimColor: true, children: `${entry.group.padEnd(12)}` }),
- ctx.kit.Button({ key: `pal-${entry.id}`, label: entry.label, plain: true, onPress: () => ctx.act.paletteRun(entry.id) }),
- ]),
+ row(
+ ctx,
+ [
+ text(ctx, isFirst ? ' â–¶' : ' ', { bold: true, color: THEME.ok }),
+ ctx.kit.Button({ key: `pal-${entry.id}`, label: ` ${clip(entry.label, lead - 1)}`.padEnd(lead, '.'), plain: true, ...(isFirst && { variant: 'primary' as const }), onPress: () => ctx.act.paletteRun(entry.id) }),
+ tagChip(ctx, tag.text, tag.color),
+ ...(isGrouped || ctx.columns < 80 ? [] : [text(ctx, ` ${entry.group}`, { dimColor: true })]),
+ ],
+ `pal-row-${entry.id}`,
+ ),
)
- }
+ })
- if (matches.length > PALETTE_ROWS) rows.push(text(ctx, `+${matches.length - PALETTE_ROWS} more: keep typing`, { dimColor: true }))
- if (matches.length === 0) rows.push(text(ctx, 'no match', { color: THEME.warn }))
+ if (matches.length > PALETTE_ROWS) rows.push(text(ctx, ` +${matches.length - PALETTE_ROWS} more: keep typing`, { dimColor: true }))
+ if (matches.length === 0) rows.push(text(ctx, ' no match: try fewer letters, or a word from the entry’s name', { color: THEME.warn }))
+ rows.push(rule(ctx, 'How it runs'))
+ rows.push(text(ctx, ' $0 reads run at once · ask changes ask y/n first · go opens a page · text takes the words you type after its keyword', { dimColor: true }))
+ rows.push(text(ctx, ' every entry is also /ruflo run <id>, from any session', { dimColor: true }))
rows.push(row(ctx, [button(ctx, 'palette-close', 'Close palette', () => ctx.act.palette(state.palette.context), { hotkey: state.palette.context === 'selection' ? 'x' : 'p' })]))
- rows.push(text(ctx, 'changes ask y/n before they run · reads (logs, route, search, score) run at once · same entries: /ruflo run <id>', { dimColor: true }))
return col(ctx, rows, 'palette')
}
diff --git a/plugins/ruflo-console/hooks/views/pane.ts b/plugins/ruflo-console/hooks/views/pane.ts
index 9d2e715143..28d2b5dacf 100644
--- a/plugins/ruflo-console/hooks/views/pane.ts
+++ b/plugins/ruflo-console/hooks/views/pane.ts
@@ -305,9 +305,9 @@ export function paneView(base: Ctx): RenderElement {
: col(ctx, [text(ctx, 'CONNECT 115200 · RUFLO AGENT SWARM CONSOLE · loading…', { bold: true, color: THEME.head })], 'boot')
}
// A section of a page is a bordered card (views/card.ts): the body is drawn narrower by the border and padding, through a kit that groups its rows.
- const cardsOn = hasCards(base.columns, isCompactPane(base.state)) && !ctx.state.palette.isOpen && !ctx.state.isHelp
+ const cardsOn = hasCards(base.columns, isCompactPane(base.state)) && !ctx.state.isHelp
const bodyCtx: Ctx = cardsOn ? { ...ctx, columns: ctx.columns - CARD_COLUMNS, cards: true, kit: withCards(ctx.kit, isBbs() ? (accentOfView(ctx.state.view === 'agent' ? ctx.state.back : ctx.state.view) ?? undefined) : undefined) } : ctx
- const drawBody = () => (ctx.state.palette.isOpen ? paletteView(ctx) : ctx.state.isHelp ? help(ctx) : BODIES[ctx.state.view](bodyCtx))
+ const drawBody = () => (ctx.state.palette.isOpen ? paletteView(bodyCtx) : ctx.state.isHelp ? help(ctx) : BODIES[ctx.state.view](bodyCtx))
// A lab's result block is drawn first into the panel (pass one), then the page is drawn with the panel placed under the clicked row.
if (ctx.state.origin !== null && (ctx.state.lab.result !== null || ctx.state.lab.running !== null)) {
attention.donated = donated(ctx, () => {
diff --git a/plugins/ruflo-console/tests/palette-view.spec.ts b/plugins/ruflo-console/tests/palette-view.spec.ts
new file mode 100644
index 0000000000..9113ec11e4
--- /dev/null
+++ b/plugins/ruflo-console/tests/palette-view.spec.ts
@@ -0,0 +1,109 @@
+/**
+ * The command palette's design (ADR-435): grouped under `── group ──` rules while nothing is typed, one flat ranked list once there is a
+ * query, every row a dotted-leader line ending in a tag for what pressing it does, the first marked â–¶ and primary because Enter runs it, and
+ * the keywords that take text as buttons. Run with
+ * npx vitest run plugins/ruflo-console/tests/palette-view.spec.ts
+ */
+import { describe, expect, it } from 'vitest'
+
+import { filterPalette, paletteEntries } from '../hooks/palette'
+import { newState, type State } from '../hooks/state'
+import type { Ctx } from '../hooks/views/common'
+import { entryTag, paletteView, PALETTE_ROWS } from '../hooks/views/palette'
+
+type El = { props: Record<string, unknown> }
+
+const calls: string[] = []
+const recorder = (path: string): unknown =>
+ new Proxy(() => undefined, {
+ get: (_t, key) => (key === 'then' ? undefined : recorder(`${path}.${String(key)}`)),
+ apply: (_t, _this, args) => void calls.push(`${path.slice(1)}(${args.join(',')})`),
+ })
+const act = recorder('') as never
+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 open = (query = '', columns = 120): { tree: unknown; state: State } => {
+ const state = newState({})
+
+ state.palette.isOpen = true
+ state.palette.query = query
+
+ return { tree: paletteView({ kit, state, nowMs: Date.now(), columns, pictures: new Map(), act, cards: true } as unknown as Ctx), state }
+}
+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 entryButtons = (tree: unknown): El[] => flat(tree).filter(node => /^pal-(?!kw-|row-|keywords)/.test(String(node.props.key)))
+
+describe('the palette page', () => {
+ it('groups the entries under rules while nothing is typed, and ranks them flat once there is a query', () => {
+ const grouped = flat(open('').tree).map(node => String(node.props.children ?? ''))
+ const ranked = flat(open('spawn').tree).map(node => String(node.props.children ?? ''))
+
+ expect(grouped.filter(line => line.startsWith('── ')).length).toBeGreaterThan(1)
+ expect(ranked.filter(line => line.startsWith('── '))).toEqual([])
+ })
+
+ it('marks the first match â–¶ and primary, because Enter runs it, and only the first', () => {
+ const { tree, state } = open('spawn')
+ const buttons = entryButtons(tree)
+ const best = filterPalette(paletteEntries(state, Date.now()), 'spawn', 'all')[0]
+
+ expect(buttons[0]?.props.key).toBe(`pal-${best?.id}`)
+ expect(buttons[0]?.props.variant).toBe('primary')
+ expect(buttons.slice(1).every(node => node.props.variant === undefined)).toBe(true)
+ expect(flat(tree).filter(node => node.props.children === ' â–¶').length).toBe(1)
+ })
+
+ it('shows every row at one width, ending in a tag for what pressing it does', () => {
+ const { tree } = open('')
+ const buttons = entryButtons(tree)
+
+ expect(buttons.length).toBe(PALETTE_ROWS)
+ expect(new Set(buttons.map(node => String(node.props.label).length)).size).toBe(1)
+ })
+
+ it('tags a page as go, a read as $0, a change as ask, and a command that takes words as text', () => {
+ const { state } = open('')
+ const tags = new Map(paletteEntries(state, Date.now()).map(entry => [entry.run.kind === 'spec' ? (entry.run.spec?.isReadOnly === true ? 'read' : 'change') : entry.run.kind, entryTag(entry).text.trim()]))
+
+ expect(tags.get('view')).toBe('go')
+ expect(tags.get('text')).toBe('text')
+ expect(tags.get('change') ?? 'ask').toBe('ask')
+ expect([...tags.values()].every(tag => ['go', 'text', 'ask', '$0', 'cmd', 'drill', 'n/a'].includes(tag))).toBe(true)
+ })
+
+ it('offers the text keywords as buttons that start the command, and its Close button works', () => {
+ calls.length = 0
+
+ const { tree } = open('')
+ const keyword = flat(tree).find(node => String(node.props.key).startsWith('pal-kw-'))
+
+ expect(keyword).toBeDefined()
+ ;(keyword?.props.onPress as () => void)()
+ expect(calls[0]).toMatch(/^paletteQuery\(.+ \)$/)
+
+ const close = flat(tree).find(node => node.props.key === 'palette-close')
+
+ ;(close?.props.onPress as () => void)()
+ expect(calls[1]).toBe('palette(all)')
+ })
+
+ it('says so when nothing matches, and in the selection context offers no keyword buttons', () => {
+ expect(flat(open('zzzzqqqq').tree).some(node => String(node.props.children ?? '').includes('no match'))).toBe(true)
+
+ const state = newState({})
+
+ state.palette.isOpen = true
+ state.palette.context = 'selection'
+
+ const tree = paletteView({ kit, state, nowMs: Date.now(), columns: 120, pictures: new Map(), act, cards: true } as unknown as Ctx)
+
+ expect(flat(tree).some(node => String(node.props.key).startsWith('pal-kw-'))).toBe(false)
+ })
+})
diff --git a/v3/docs/adr/ADR-435-console-palette-page-design.md b/v3/docs/adr/ADR-435-console-palette-page-design.md
new file mode 100644
index 0000000000..1e810e5373
--- /dev/null
+++ b/v3/docs/adr/ADR-435-console-palette-page-design.md
@@ -0,0 +1,27 @@
+# ADR 435: The command palette laid out like the other pages
+
+Status: Accepted (ships in ruflo-console 0.26.0)
+
+Date: 2026 10 03
+
+Scope: `plugins/ruflo-console`: `hooks/views/palette.ts`, `hooks/views/pane.ts` (the palette now draws in cards), `tests/palette-view.spec.ts` (new).
+
+Extends: ADR 430 (the menu's design), ADR 431 (the design carried through the pages).
+
+## 1. Decision
+
+The palette was a plain list: a dim group column and a bare button per entry, outside the cards every other page uses, with nothing to say what pressing an entry does or which one Enter runs. It now reads like the rest of the console:
+
+- **Cards.** The palette draws through the same card kit as the pages (a section per `rule`): *Palette* (the filter field and the keywords that take text), *Matches*, *How it runs*.
+- **Keywords as buttons.** The text commands (`route`, `store`, `search`, `task`, `mission`, `ask`, …) are chips that start the command (they put `route ` in the field), so they can be found without knowing them.
+- **Rows.** One dotted-leader row per match, all one width, ending in a tag for what pressing it does: **go** (opens a page), **$0** (a read that runs at once), **ask** (a change: asks y/n first), **text** (takes the words typed after its keyword), **cmd**, **drill**, **n/a** (cannot run now). The first match, which Enter runs, is marked **â–¶** and primary.
+- **Grouped, then ranked.** With nothing typed the entries sit under dim `── group ──` rules, as the menu groups its entries; once a query ranks them the list is flat (a group in the middle of a ranking would interleave) and the group moves to the end of each row.
+- **Footer.** What the tags mean, that every entry is also `/ruflo run <id>`, and Close.
+
+## 2. Not proven
+
+Seen through a fake kit, not on a terminal. The twelve-row cap is unchanged ("+N more: keep typing").
+
+## 3. Tests
+
+`tests/palette-view.spec.ts` (6): grouped versus ranked; â–¶ and primary on the first match only; every row one width; the tag for each kind; the keyword buttons and Close; no match and the selection context. Removing the â–¶ and removing the leader padding each fail a spec.