create-theokit 1.21.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/surfaces/tui/tui/App.tsx.tmpl

@@ -1,21 +1,35 @@
 import { homedir } from 'node:os'
 
 import { Box, Text, useApp, useInput } from 'ink'
-import { type ReactElement, useState } from 'react'
+import { type ReactElement, useEffect, useState } from 'react'
 import {
   AgentStreaming,
   AgentTimeline,
   ChatComposer,
+  ContextWindowBar,
+  CostMeter,
   DEFAULT_COMPOSER_SHORTCUTS,
   findPendingApproval,
   InkInputProvider,
   KeyboardHelp,
   messagesToAgentEvents,
+  MultiStepProgress,
   Notice,
   PermissionPrompt,
+  PlanApproval,
+  ProgressActivity,
+  ProgressBar,
+  QuestionPrompt,
   readTurnUsage,
+  SelectList,
+  type SelectListItem,
+  Stack,
   StatusFooter,
   TheoTUIProvider,
+  Toast,
+  type TodoItem,
+  type TokenCategory,
+  TokenUsageChart,
   useTurnElapsed,
   type UIMessageLike,
 } from '@theokit/tui'
@@ -56,11 +70,40 @@ const GREETING: UIMessageLike = {
 const apiKey = (): string =>
   process.env.OPENROUTER_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? ''
 
+// ── Slash-command demo data ────────────────────────────────────────────────────────────────────────
+// The interactive `@theokit/tui` surfaces (`/plan`, `/ask`, `/select`, `/progress`) run live IN the app,
+// triggered from the composer, with real handlers — not a separate gallery. Delete the ones you don't need.
+const DEMO_PLAN = [
+  '## Proposed plan',
+  '',
+  '1. Scaffold the `reports` route',
+  '2. Add the `generateReport` server action',
+  '3. Stream results into the dashboard',
+].join('\n')
+
+const DEMO_ASK_OPTIONS: readonly SelectListItem[] = [
+  { value: 'python', label: 'Python (FastAPI)', description: 'polyglot service via --backend python' },
+  { value: 'node', label: 'Node (Hono)', description: 'fetch-handler service' },
+  { value: 'none', label: 'TypeScript only', description: 'no external backend' },
+]
+
+const DEMO_SELECT_ITEMS: readonly SelectListItem[] = [
+  { value: 'auth', label: 'Auth', description: 'sessions + requireAuth' },
+  { value: 'db', label: 'Database', description: 'SQLite by default' },
+  { value: 'ws', label: 'WebSocket', description: 'realtime channel' },
+  { value: 'deploy', label: 'Deploy', description: 'TheoCloud target' },
+]
+
+const DEMO_STEP_LABELS = ['Plan', 'Generate', 'Validate', 'Ship'] as const
+
+/** The composer mode — `chat` is the default; the others swap the composer for a live demo surface. */
+type Mode = 'chat' | 'plan' | 'ask' | 'select' | 'progress'
+
 /**
  * The terminal surface, composed from `@theokit/tui` the way a Claude Code / OpenCode / Codex CLI is:
  * `WelcomeBanner` header, a scrolling `<AgentTimeline>` (assistant turns rendered as Markdown + fenced code,
  * tool calls as collapsible cards, thinking rows — the Claude-Code render), a live `<AgentStreaming>` spinner,
- * a bordered `<ChatComposer>`, and a persistent `<AppStatusBar>` footer. Driven by the unified `useAgent`
+ * a bordered `<ChatComposer>`, and a persistent `<StatusFooter>` footer. Driven by the unified `useAgent`
  * hook (M41).
  *
  * The conversation comes from `useAgent().thread` (M46), projected to the timeline's `AgentEvent[]` by the
@@ -152,15 +195,33 @@ export function App(): ReactElement {
   // a resolved state (it is keyed by its own id, distinct from the tool call), so we remember settled ids
   // to hide the prompt once answered instead of re-showing it forever.
   const [settledApprovals, setSettledApprovals] = useState<readonly string[]>([])
+  // The composer mode + the slash-command demo state (a plan/ask/select/progress surface swaps the composer).
+  const [mode, setMode] = useState<Mode>('chat')
+  const [progressStep, setProgressStep] = useState(0)
+  // `/usage` toggles a token-usage panel; a Toast surfaces transient outcomes (a demo answered, a task done).
+  const [showUsage, setShowUsage] = useState(false)
+  const [toast, setToast] = useState<{ message: string; variant: 'info' | 'success' | 'error' } | null>(
+    null,
+  )
 
   // The store owns the conversation (M46) — prepend the warm greeting and project to timeline events.
   const events = messagesToAgentEvents([GREETING, ...agent.thread])
 
   // The last turn's usage (readTurnUsage reads the totals the agent stream rides on each assistant
-  // message's metadata) drives the streaming token count + the footer's context usage. Undefined until
-  // the first turn reports usage.
+  // message's metadata) drives the streaming token count, the footer's context usage, AND the `/usage`
+  // observability panel (ContextWindowBar / TokenUsageChart / CostMeter). Undefined until the first turn.
   const lastUsage = agent.thread.map(readTurnUsage).filter((u) => u !== undefined).at(-1)
 
+  // Only PRESENT categories render in the chart — build the map from whatever the turn actually reported.
+  const usageChart: Partial<Record<TokenCategory, number>> = lastUsage
+    ? {
+        input: lastUsage.inputTokens,
+        output: lastUsage.outputTokens,
+        ...(lastUsage.cacheReadTokens !== undefined ? { cached: lastUsage.cacheReadTokens } : {}),
+        ...(lastUsage.reasoningTokens !== undefined ? { reasoning: lastUsage.reasoningTokens } : {}),
+      }
+    : {}
+
   // Human-in-the-loop: a gated tool (`send_notification`) pauses the run awaiting a decision. When one is
   // pending (and not already settled) we show the approval prompt IN PLACE OF the composer and settle it.
   const rawApproval = findPendingApproval(agent.thread)
@@ -172,13 +233,32 @@ export function App(): ReactElement {
     void agent.approve(approvalId, { approved })
   }
 
-  // Global keys. While a gated tool awaits approval, the `<PermissionPrompt>` owns the keys (↑/↓/Enter/Esc)
-  // — stay out of its way. Otherwise: Esc cancels a running turn / closes help; Ctrl+C cancels a turn, else
-  // arms → quits on a second press. The ChatComposer owns editing keys (/, @, !, ?, ↑↓, emacs chords).
+  // `/progress` runs a live multi-step task: advance one step every 700ms; when it finishes, toast + return
+  // to chat. This is the only mode driven by a timer — the interactive modes complete on the user's input.
+  useEffect(() => {
+    if (mode !== 'progress') return
+    if (progressStep >= DEMO_STEP_LABELS.length) {
+      const done = setTimeout(() => {
+        setMode('chat')
+        setToast({ message: 'Task complete', variant: 'success' })
+      }, 600)
+      return () => clearTimeout(done)
+    }
+    const tick = setTimeout(() => setProgressStep((s) => s + 1), 700)
+    return () => clearTimeout(tick)
+  }, [mode, progressStep])
+
+  const inDemoInput = mode === 'plan' || mode === 'ask' || mode === 'select'
+
+  // Global keys. A gated tool (`PermissionPrompt`) or an interactive demo (`PlanApproval`/`QuestionPrompt`/
+  // `SelectList`) OWNS the keys while active — stay out of its way. Otherwise: Esc exits the progress demo /
+  // closes the usage panel / closes help / cancels a running turn; Ctrl+C cancels a turn, else arms → quits.
   useInput((input, key) => {
-    if (pendingApproval) return
+    if (pendingApproval || inDemoInput) return
     if (key.escape) {
-      if (showHelp) setShowHelp(false)
+      if (mode === 'progress') setMode('chat')
+      else if (showUsage) setShowUsage(false)
+      else if (showHelp) setShowHelp(false)
       else if (streaming) agent.abort()
       return
     }
@@ -197,43 +277,84 @@ export function App(): ReactElement {
   const handleSubmit = (text: string): void => {
     const trimmed = text.trim()
     if (trimmed.length === 0) return
-    if (trimmed === '/clear') {
-      agent.reset()
-      return
-    }
-    if (trimmed === '/help') {
-      setShowHelp((h) => !h)
-      return
+    switch (trimmed) {
+      case '/clear':
+        agent.reset()
+        return
+      case '/help':
+        setShowHelp((h) => !h)
+        return
+      case '/usage':
+        setShowUsage((u) => !u)
+        return
+      case '/plan':
+        setMode('plan')
+        return
+      case '/ask':
+        setMode('ask')
+        return
+      case '/select':
+        setMode('select')
+        return
+      case '/progress':
+        setProgressStep(0)
+        setMode('progress')
+        return
+      default:
+        agent.send({ message: trimmed })
     }
-    agent.send({ message: trimmed })
   }
 
+  // The `/progress` lanes: steps before the cursor are done, the cursor is active, the rest are pending.
+  const progressSteps: readonly TodoItem[] = DEMO_STEP_LABELS.map((label, i) => ({
+    id: label,
+    label,
+    status: i < progressStep ? 'done' : i === progressStep ? 'active' : 'pending',
+  }))
+  const progressPercent = Math.min(100, Math.round((progressStep / DEMO_STEP_LABELS.length) * 100))
+
   return (
     <TheoTUIProvider theme={THEME}>
-      {/* InkInputProvider bridges Ink's stdin to @theokit/tui's interactive surfaces (PermissionPrompt's
-          numbered choice menu) so they receive keys under plain Ink — the ChatComposer keeps Ink's own hooks. */}
+      {/* InkInputProvider bridges Ink's stdin to @theokit/tui's interactive surfaces (PermissionPrompt +
+          PlanApproval / QuestionPrompt / SelectList) so they receive keys under plain Ink — the ChatComposer
+          keeps Ink's own hooks. `Stack` gives the top-level sections the Claude-Code one-line cadence. */}
       <InkInputProvider>
-        <Box flexDirection="column">
-        <Banner />
-
-        <AgentTimeline events={events} />
-
-        {streaming ? (
-          <AgentStreaming
-            phrases={THINKING_PHRASES}
-            shimmer
-            elapsedSeconds={elapsed}
-            tokens={lastUsage?.totalTokens}
-            tokenDirection="down"
-            showCancelHint
-          />
-        ) : null}
-        {agent.error ? <Notice variant="error">{agent.error.message}</Notice> : null}
+        <Stack gap={1}>
+          <Banner />
 
-        {showHelp ? <KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} /> : null}
+          <AgentTimeline events={events} />
 
-        {/* A one-line top margin separates the input (or the approval prompt) from the conversation above. */}
-        <Box marginTop={1} flexDirection="column">
+          {streaming ? (
+            <AgentStreaming
+              phrases={THINKING_PHRASES}
+              shimmer
+              elapsedSeconds={elapsed}
+              tokens={lastUsage?.totalTokens}
+              tokenDirection="down"
+              showCancelHint
+            />
+          ) : null}
+          {agent.error ? <Notice variant="error">{agent.error.message}</Notice> : null}
+
+          {/* `/usage` — the observability panel, from the last turn's real usage. ContextWindowBar shows the
+              context fill, TokenUsageChart the per-category breakdown, CostMeter the session cost (if reported). */}
+          {showUsage && lastUsage ? (
+            <Box flexDirection="column">
+              <ContextWindowBar usedTokens={lastUsage.inputTokens} limitTokens={AGENT.contextWindow} />
+              <TokenUsageChart usage={usageChart} />
+              {lastUsage.cost !== undefined ? <CostMeter costUsd={lastUsage.cost} /> : null}
+            </Box>
+          ) : null}
+
+          {/* A transient outcome banner (a demo answered, a task finished). Auto-dismisses after 5s. */}
+          {toast ? (
+            <Toast message={toast.message} variant={toast.variant} onDismiss={() => setToast(null)} />
+          ) : null}
+
+          {showHelp ? <KeyboardHelp shortcuts={DEFAULT_COMPOSER_SHORTCUTS} /> : null}
+
+          {/* The input area: a gated tool's approval card, an interactive demo surface (/plan /ask /select
+              /progress), or the composer. Each demo completes back to chat (Enter) or cancels (Esc). */}
           {pendingApproval ? (
             <PermissionPrompt
               toolType="Tool call"
@@ -250,6 +371,56 @@ export function App(): ReactElement {
                 settleApproval(pendingApproval.approvalId, decision === 'yes')
               }}
             />
+          ) : mode === 'plan' ? (
+            <PlanApproval
+              plan={DEMO_PLAN}
+              onDecision={(d) => {
+                setMode('chat')
+                setToast({
+                  message:
+                    d.kind === 'approve'
+                      ? 'Plan approved'
+                      : `Revision requested${d.feedback ? `: ${d.feedback}` : ''}`,
+                  variant: 'success',
+                })
+              }}
+            />
+          ) : mode === 'ask' ? (
+            <QuestionPrompt
+              header="Backend"
+              question="Which backend should the app ship next to?"
+              options={DEMO_ASK_OPTIONS}
+              allowFreeText
+              onAnswer={(a) => {
+                setMode('chat')
+                setToast({
+                  message: `Answered: ${a.values.join(', ')}${a.text ? ` (${a.text})` : ''}`,
+                  variant: 'info',
+                })
+              }}
+            />
+          ) : mode === 'select' ? (
+            <SelectList
+              items={DEMO_SELECT_ITEMS}
+              multi
+              onSubmit={(values) => {
+                setMode('chat')
+                setToast({ message: `Selected: ${values.join(', ') || '(none)'}`, variant: 'info' })
+              }}
+            />
+          ) : mode === 'progress' ? (
+            <Box flexDirection="column">
+              <MultiStepProgress steps={progressSteps} current={progressStep} groupLabel="Demo task" />
+              <ProgressActivity
+                label="Working…"
+                percent={progressPercent}
+                elapsedSeconds={elapsed}
+                tokens={lastUsage?.totalTokens}
+                tokenDirection="up"
+              />
+              <ProgressBar percent={progressPercent} />
+              <Text dimColor>esc to exit</Text>
+            </Box>
           ) : (
             <ChatComposer
               placeholder={PLACEHOLDER}
@@ -258,27 +429,31 @@ export function App(): ReactElement {
               commands={[
                 { name: 'clear', description: 'clear the conversation' },
                 { name: 'help', description: 'toggle the keyboard shortcuts panel' },
+                { name: 'usage', description: 'toggle the token-usage panel' },
+                { name: 'plan', description: 'demo: plan approval card' },
+                { name: 'ask', description: 'demo: question prompt' },
+                { name: 'select', description: 'demo: multi-select list' },
+                { name: 'progress', description: 'demo: multi-step progress' },
               ]}
               onHelpToggle={() => setShowHelp((h) => !h)}
               onSubmit={handleSubmit}
             />
           )}
-        </Box>
 
-        {/* Claude Code's two-line footer: top-left the model, top-right the context usage; bottom the
-            shortcuts hint. `StatusFooter` justifies the top row to the terminal edges. */}
-        <StatusFooter
-          left={<Text>{MODEL}</Text>}
-          right={
-            lastUsage ? (
-              <Text>
-                {fmtK(lastUsage.inputTokens)}/{fmtK(AGENT.contextWindow)} context
-              </Text>
-            ) : undefined
-          }
-          hint="? for shortcuts"
-        />
-        </Box>
+          {/* Claude Code's two-line footer: top-left the model, top-right the context usage; bottom the
+              shortcuts hint. `StatusFooter` justifies the top row to the terminal edges. */}
+          <StatusFooter
+            left={<Text>{MODEL}</Text>}
+            right={
+              lastUsage ? (
+                <Text>
+                  {fmtK(lastUsage.inputTokens)}/{fmtK(AGENT.contextWindow)} context
+                </Text>
+              ) : undefined
+            }
+            hint="? for shortcuts"
+          />
+        </Stack>
       </InkInputProvider>
     </TheoTUIProvider>
   )