From 9d6894002a072d2c635f4d31602c831101217b30 Mon Sep 17 00:00:00 2001 From: Blake Bauman Date: Sat, 14 Nov 2026 14:43:40 -0700 Subject: [PATCH] Polish TUI coding workflow and add command discovery --- apps/tui/README.md | 27 +++++- apps/tui/src/app.tsx | 12 ++- apps/tui/src/command-hints.ts | 33 +++++++ apps/tui/src/theme.ts | 19 +++- apps/tui/src/ui/composer.tsx | 141 +++++++++++++++++++++++------- apps/tui/src/ui/greeting.tsx | 17 ++-- apps/tui/src/ui/inspector.tsx | 4 +- apps/tui/src/ui/prompts.tsx | 17 +++- apps/tui/src/ui/rails.tsx | 50 ++++++++--- apps/tui/src/ui/transcript.tsx | 116 ++++++++++++++++++------ apps/tui/tests/app.test.ts | 42 +++++++++ apps/tui/tests/composer.test.ts | 82 +++++++++++++++++ apps/tui/tests/greeting.test.ts | 2 +- apps/tui/tests/theme.test.ts | 3 + apps/tui/tests/transcript.test.ts | 75 ++++++++++++++++ 15 files changed, 545 insertions(+), 95 deletions(-) create mode 100644 apps/tui/src/command-hints.ts diff --git a/apps/tui/README.md b/apps/tui/README.md index 198a2698..7f7c0c95 100644 --- a/apps/tui/README.md +++ b/apps/tui/README.md @@ -87,6 +87,12 @@ $PAGER /artifact [file] · /skills /skill (read-only) client /refresh the thread list · /quit ``` +Type `/` in the composer to browse commands, or keep typing to filter them. Use ↑/↓ to +choose and Enter to insert; the next Enter runs a complete command. Commands with arguments +leave a space for you to keep typing. Escape dismisses suggestions without clearing the draft. +Tab still opens threads. Suggestions hide while a blocking prompt or another overlay owns +the keyboard, and on terminals too short to fit the menu above the editor. + ## The shape of the screen Three things worth knowing before moving anything. @@ -143,10 +149,23 @@ on the prompt that asks before a write, which is the moment it counts. ## Colour -`src/theme.ts` holds what the colours *mean* — waiting, danger, failed, running, ready, faint — -and the five hues come from `@felix/design`, which owns this repo's palette. It had only a -neutral scale before this: right for surfaces, useless for status, because "waiting on you" and -"this failed" cannot be told apart in greys. +`src/theme.ts` holds what the colours mean. State hues come from `@felix/design`: +green for success, amber for a decision, red for failures, and blue for work in progress. +The terminal adds cyan for tools and navigation, violet for the agent, and blue for your +prompts. The ready composer, connected host, successful tools, and completed plan steps +use green. Replies have a violet side rail; code frames and selected navigation use cyan. +The status line colours the agent, connection, directory, permission mode, and active phase +separately while keeping its single-row width budget. + +The composer says **Ask Felix** when idle and **Steer the agent** during a run. Its placeholder +suggests a coding task or pasted error, then a correction or next step while the agent works. +These hints occupy the existing editor and border rather than taking transcript rows. + +Tool cards show search scope, rename destinations, and shell working directories when supplied. +Their names, arguments, and activity labels share a width budget so long local calls stay on +one row. Successful shell previews show the final two nonempty output lines, where build and +test summaries usually appear; a leading ellipsis marks omitted output. Artifact handles stay +cyan and reserve their space beside the preview. `/artifact ` opens the full spilled result. **When the palette applies is the interesting part.** A named colour is not a request for the terminal's palette: `parseColor` resolves `"magenta"` to the literal `#FF00FF`, so the sixteen diff --git a/apps/tui/src/app.tsx b/apps/tui/src/app.tsx index 60f93f15..47e82a11 100644 --- a/apps/tui/src/app.tsx +++ b/apps/tui/src/app.tsx @@ -708,10 +708,18 @@ export function App({ // paragraph, and a shell does not filter its history either. history.add(text); setRecent(history.entries()); - if (text.startsWith('/')) command(text); + const selection = text.trim(); + if ( + turns.length === 0 && + !streaming && + /^[1-9]\d*$/.test(selection) && + entry?.starters?.[Number(selection) - 1] + ) { + command(`/start ${selection}`); + } else if (text.startsWith('/')) command(text); else send(text); }, - [command, engine, history, send], + [command, engine, entry, history, send, streaming, turns.length], ); // The first message from argv, once the engine exists — and once the lease has diff --git a/apps/tui/src/command-hints.ts b/apps/tui/src/command-hints.ts new file mode 100644 index 00000000..7cfa76f0 --- /dev/null +++ b/apps/tui/src/command-hints.ts @@ -0,0 +1,33 @@ +/** Common commands for discovery; /help remains the full command reference. */ +export const COMMAND_HINTS = [ + { name: '/help', description: 'Show commands and keyboard shortcuts', args: false }, + { name: '/plan', description: 'Toggle plan mode', args: false }, + { name: '/think', description: 'Set thinking level: off to max', args: true }, + { name: '/manifest', description: 'List or switch agents', args: true }, + { name: '/start', description: 'Choose a numbered starter prompt', args: true }, + { name: '/artifact', description: 'Open full tool output by number', args: true }, + { name: '/search', description: 'Search conversation history', args: true }, + { name: '/new', description: 'Start a new thread', args: false }, + { name: '/continue', description: 'Continue the current run', args: false }, + { name: '/skills', description: 'Browse available skills', args: false }, + { name: '/skill', description: 'Read a skill by name', args: true }, + { name: '/style', description: 'List or select an output style', args: true }, + { name: '/ask', description: 'Ask a side question', args: true }, + { name: '/rename', description: 'Rename the current thread', args: true }, + { name: '/fork', description: 'Branch the current conversation', args: false }, + { name: '/compact', description: 'Compact conversation context', args: false }, + { name: '/export', description: 'Export the conversation', args: true }, + { name: '/rewind', description: 'Rewind conversation history', args: true }, + { name: '/version', description: 'Switch a prompt version', args: true }, + { name: '/open', description: 'Open a thread or search result', args: true }, + { name: '/refresh', description: 'Refresh the thread list', args: false }, + { name: '/clear', description: 'Clear the current thread history', args: false }, + { name: '/quit', description: 'Exit the terminal client', args: false }, +] as const; + +export function commandHints(draft: string) { + if (!/^\/[a-z]*$/.test(draft)) return []; + // A complete command is ready to run. Never intercept its Enter key. + if (COMMAND_HINTS.some((hint) => hint.name === draft)) return []; + return COMMAND_HINTS.filter((hint) => hint.name.startsWith(draft)); +} diff --git a/apps/tui/src/theme.ts b/apps/tui/src/theme.ts index cc9c8f8b..71ffc533 100644 --- a/apps/tui/src/theme.ts +++ b/apps/tui/src/theme.ts @@ -17,9 +17,9 @@ * every role falls back to an ANSI **index**, which is a reference into the * user's own sixteen and is themed by them rather than by us. * - * The five hues come from `@felix/design`, which owns this repo's palette and - * until now had only a neutral scale — right for surfaces, useless for status, - * because "waiting on you" and "this failed" cannot be told apart in greys. + * State hues come from `@felix/design`. Three additional terminal roles + * distinguish navigation and tools (cyan), agent identity (violet), and the + * operator's input (blue), with separate light and dark variants. */ import { @@ -55,6 +55,12 @@ export const DIM_ITALIC = createTextAttributes({ dim: true, italic: true }); * rather than spread across the components. */ export interface Theme { + /** Navigation, commands, and tool names. */ + accent: ColorInput; + /** Agent identity, separate from the state of a run. */ + agent: ColorInput; + /** Your prompts in the transcript. The ready editor uses green. */ + input: ColorInput; /** * A transient message in the status area: a confirmation, a listing, `/help`. * The terminal's own foreground, never `blocked` — amber means a person is @@ -114,6 +120,9 @@ export interface Theme { * respecting a solarized terminal and painting over it. */ const INDEXED: Theme = { + accent: RGBA.fromIndex(6), + agent: RGBA.fromIndex(5), + input: RGBA.fromIndex(4), notice: RGBA.defaultForeground(), blocked: RGBA.fromIndex(3), danger: RGBA.fromIndex(9), @@ -148,7 +157,11 @@ function tint(state: string, base: string, amount: number): RGBA { } function fromPalette(state: StatePalette, neutral: ThemePalette): Theme { + const light = neutral === LIGHT; return { + accent: RGBA.fromHex(light ? '#0e7490' : '#67d4e8'), + agent: RGBA.fromHex(light ? '#7e22ce' : '#c4a5f5'), + input: RGBA.fromHex(light ? '#1d4ed8' : '#93b4ff'), notice: RGBA.defaultForeground(), blocked: RGBA.fromHex(state.blocked), danger: RGBA.fromHex(state.danger), diff --git a/apps/tui/src/ui/composer.tsx b/apps/tui/src/ui/composer.tsx index d650d73a..182c16dd 100644 --- a/apps/tui/src/ui/composer.tsx +++ b/apps/tui/src/ui/composer.tsx @@ -27,8 +27,10 @@ */ import type { KeyBinding, KeyEvent, TextareaRenderable } from '@opentui/core'; -import { useKeyboard, usePaste } from '@opentui/react'; +import { useKeyboard, usePaste, useTerminalDimensions } from '@opentui/react'; import { useEffect, useRef, useState } from 'react'; +import { commandHints } from '../command-hints.js'; +import { oneLine } from '../text.js'; import type { Theme } from '../theme.js'; /** Any newline, and any run of them, however the source spelled it. */ @@ -97,11 +99,25 @@ export function Composer({ const ref = useRef(null); /** The editor owns the terminal while this is true; nothing else may. */ const [editing, setEditing] = useState(false); + const [draftText, setDraftText] = useState(''); + const [completionIndex, setCompletionIndex] = useState(0); + const [completionDismissed, setCompletionDismissed] = useState(false); + const { width, height } = useTerminalDimensions(); /** Index into `history`, or null while editing the draft. */ const recalled = useRef(null); const draft = useRef(''); const active = !disabled && !editing; + const completions = active && height >= 10 && !completionDismissed ? commandHints(draftText) : []; + const selectedCompletion = Math.min(completionIndex, Math.max(0, completions.length - 1)); + const completionRows = Math.max(1, Math.min(3, height - 10)); + const completionStart = Math.max( + 0, + Math.min( + selectedCompletion - Math.floor(completionRows / 2), + completions.length - completionRows, + ), + ); const read = () => ref.current?.plainText ?? ''; /** * Replace the field and leave the cursor at the end, the way a shell leaves a @@ -114,6 +130,7 @@ export function Composer({ const write = (text: string) => { ref.current?.setText(text); ref.current?.gotoBufferEnd(); + setDraftText(text); }; // Keyed on `n` alone: the text is read when it changes, and re-filling on an @@ -146,6 +163,30 @@ export function Composer({ */ useKeyboard((key: KeyEvent) => { if (!active) return; + if (completions.length && !key.ctrl && !key.meta && !key.shift) { + if (key.name === 'escape') { + key.preventDefault(); + // This Escape belongs to the menu. Stop the parent's global handler + // too, so dismissing suggestions during a run does not abort it. + key.stopPropagation(); + setCompletionDismissed(true); + return; + } + if (key.name === 'up' || key.name === 'down') { + key.preventDefault(); + setCompletionIndex( + (selectedCompletion + (key.name === 'up' ? -1 : 1) + completions.length) % + completions.length, + ); + return; + } + if (key.name === 'return' || key.name === 'kpenter') { + key.preventDefault(); + const choice = completions[selectedCompletion]; + if (choice) write(`${choice.name}${choice.args ? ' ' : ''}`); + return; + } + } if (key.ctrl && key.name === 'e') { key.preventDefault(); if (!onEdit) return; @@ -197,36 +238,74 @@ export function Composer({ }); return ( - // Framed, because an unframed prompt does not read as somewhere you type — - // it reads as the last line of the transcript. The border also gives the - // hint somewhere to live that is not a row of its own: `bottomTitle` costs - // nothing vertically, where the old inline hint cost a line the - // conversation could have had. - - {streaming ? '⇥ ' : '> '} -