dsh-code 0.1.0

package/src/index.ts

@@ -0,0 +1,146 @@
+/**
+ * @deepseek-ai/dsh-tui — the interactive terminal driver. The bundle patch
+ * rides over dsh-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, mounts the Ink app (DeepSeek
+ * blue, whale wordmark), folds submitted prompts into the same durable
+ * session, streams `session/event` into the transcript, and on quit flushes
+ * and requests process exit.
+ *
+ * @module @deepseek-ai/dsh-tui
+ */
+
+import { randomUUID } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { createElement } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+// Empty type imports carry the loader Context merge for the settlement await
+// and the cmdline Context merge for the appExit host value.
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+import type {} from '@deepseek-ai/dsh-cmdline'
+import { App } from './app.ts'
+import { internals, type TuiMount } from './internals.ts'
+import { createTranscriptStore } from './store.ts'
+
+/** Stable Cordis plugin name. */
+export const name = 'tui-runner'
+
+/** Core services required before the interactive session can start. */
+export const inject = ['agentDefaultModel', 'agents', 'sessions']
+
+/** Process-facing effects of the runner: the Ink mount plus the launcher's exit request. */
+interface TuiIo {
+  mount: typeof internals.mount
+  exit(code: number): void
+}
+
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io: TuiIo, error: unknown): void {
+  internals.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
+  io.exit(1)
+}
+
+/**
+ * Resolve the working directory's git branch for the status line.
+ * @param cwd - the session's working directory.
+ * @returns the branch name, or '' outside a repository or on a detached HEAD.
+ */
+function gitBranch(cwd: string): string {
+  try {
+    const ref = readFileSync(join(cwd, '.git', 'HEAD'), 'utf8').trim().match(/^ref: refs\/heads\/(.+)$/)
+    return ref?.[1] ?? ''
+  } catch {
+    // Only the single HEAD read is attempted, so the sole reachable failure is
+    // a missing repository (or unreadable HEAD file): the branch group drops out.
+    return ''
+  }
+}
+
+/**
+ * Run the interactive terminal session: create one Agent, mount the app, and
+ * keep the process alive until the user quits.
+ * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+ * @param io - process-facing effects.
+ */
+async function run(ctx: Context, io: TuiIo): Promise<void> {
+  // Loader siblings mount concurrently. Await the complete application before
+  // creating an Agent so its scoped tools and adapters are not half-composed.
+  await ctx.get('loader')?.await()
+  const agents = ctx.get('agents')
+  const defaultModel = ctx.get('agentDefaultModel')
+  const sessions = ctx.get('sessions')
+  // Early process shutdown can dispose the tree while settlement is pending.
+  if (agents === undefined || defaultModel === undefined || sessions === undefined) return
+
+  const selection = defaultModel.currentSelection()
+  // This bundle composes no preset roster, so the model-facing rows sit in the
+  // host plane and the agent reads them from the global layer (mirrors dsh-headless).
+  const { agent } = await agents.create({
+    sessionId: SessionId(`session-${randomUUID()}`),
+    meta: { cwd: process.cwd() },
+    agentOptions: { provider: selection.provider, model: selection.model },
+    setup: (agentCtx) => {
+      const selected: ModelSelectionRef = { current: selection, assembled: undefined }
+      installModelSelection(agentCtx, selected)
+    },
+  })
+
+  const store = createTranscriptStore()
+  const off = ctx.on('session/event', (session: Session, event: SessionEvent) => {
+    if (session.id === agent.session.id) store.apply(event)
+  })
+
+  // The mount handle lives in a box: quit closes over it, while the mount
+  // itself is created after quit (the App element needs quit as a prop).
+  const mountRef: { current?: TuiMount } = {}
+  let quitting = false
+  const quit = (): void => {
+    if (quitting) return
+    quitting = true
+    off()
+    mountRef.current?.unmount()
+    void sessions.flush(agent.session)
+      .catch((flushError: unknown) => {
+        // The session log already carries every durable event; a failed flush
+        // must not trap the user in a dead terminal, so report and still exit.
+        internals.stderr.write(`dsh: session flush failed: ${flushError instanceof Error ? flushError.message : String(flushError)}\n`)
+      })
+      .then(() => { io.exit(0) })
+  }
+
+  mountRef.current = io.mount(createElement(App, {
+    store,
+    model: `${selection.provider}/${selection.model}`,
+    cwd: basename(process.cwd()),
+    branch: gitBranch(process.cwd()),
+    sessionId: agent.session.id.slice(-8),
+    onSubmit: (text: string) => {
+      agent.followup(createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: 'user' },
+      }))
+    },
+    onQuit: quit,
+  }))
+}
+
+/**
+ * Mount the interactive terminal driver.
+ * @param ctx - plugin context carrying core services and the launcher-provided exit request.
+ */
+export function apply(ctx: Context): void {
+  // Read through the global service store, not the property proxy: appExit is
+  // an optional host value, never an injected dependency.
+  const exit = ctx.get('appExit')
+  if (exit === undefined) {
+    throw new Error('tui-runner: the launcher must provide ctx.appExit before the tree mounts')
+  }
+  const io: TuiIo = { mount: internals.mount, exit }
+  void run(ctx, io).catch((error: unknown) => { fail(io, error) })
+}

package/src/internals.ts

@@ -0,0 +1,37 @@
+/**
+ * Injectable process-facing effects for the TUI runner. Tests substitute the
+ * Ink mount with a capturing fake and the streams with string sinks, keeping
+ * the runner's lifecycle testable without a terminal.
+ *
+ * @module @deepseek-ai/dsh-tui/internals
+ */
+
+import { render } from 'ink'
+import type { ReactElement } from 'react'
+
+/** A mounted terminal app instance; the runner owns unmount ordering. */
+export interface TuiMount {
+  /** Tear the terminal app down before flush and exit. */
+  unmount(): void
+}
+
+/** The Ink mount seam: renders the app element and returns its handle. */
+export type Mount = (element: ReactElement) => TuiMount
+
+/** Substitutable runner effects; production values write to the real terminal. */
+export const internals: {
+  /** Ink renderer mount; tests substitute a fake that captures the element. */
+  mount: Mount
+  /** Diagnostics stream for direct-driver failures. */
+  stderr: { write(chunk: string): unknown }
+} = {
+  mount: (element: ReactElement): TuiMount => {
+    const instance = render(element)
+    return {
+      unmount(): void {
+        instance.unmount()
+      },
+    }
+  },
+  stderr: process.stderr,
+}

package/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tui`.
+ * @module @deepseek-ai/dsh-tui/invariant
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tui'
+
+/** Cordis companion plugin name. */
+export const name = 'tui-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant beyond the projection's own contract: the TUI renders
+ * only from `session/event` (model-visible means logged), so the display
+ * relation the renderer could desync from is already asserted by the session
+ * log's projection invariants; this companion registers nothing.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

package/src/render/projection.ts

@@ -0,0 +1,222 @@
+/**
+ * Pure session-event-to-view projection for the TUI transcript: one reducer
+ * over {@link SessionEvent}s producing the ordered entries the renderer draws.
+ * Rendering never reads the session directly — this module owns the view
+ * model, so tests drive it with plain event arrays.
+ *
+ * @module @deepseek-ai/dsh-tui/render/projection
+ */
+
+import { boundContextSummary, type ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** One user prompt line. */
+export interface UserEntry {
+  kind: 'user'
+  /** Joined text blocks of the user message. */
+  text: string
+}
+
+/** One assembled assistant reply. */
+export interface AssistantEntry {
+  kind: 'assistant'
+  /** Joined text blocks of the assistant message. */
+  text: string
+}
+
+/** One model-requested tool invocation and its settled state. */
+export interface ToolEntry {
+  kind: 'tool'
+  /** Correlation id shared with the matching `tool/result`. */
+  callId: string
+  /** Tool name as the model addressed it. */
+  name: string
+  /** Raw arguments JSON string exactly as the model produced it. */
+  arguments: string
+  /** Execution state; `running` until the paired result lands. */
+  state: 'running' | 'done' | 'error'
+  /** Bounded first text block of the result, empty until it lands. */
+  summary: string
+}
+
+/** One turn-level failure surfaced from `turn/end`. */
+export interface ErrorEntry {
+  kind: 'error'
+  /** `code: message` of the failure. */
+  text: string
+}
+
+/** Ordered transcript items the renderer draws. */
+export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | ErrorEntry
+
+/** Cumulative token accounting folded from `assistant/message` usage reports. */
+export interface UsageTotals {
+  /** Prompt-side billed tokens: `inputTokens` plus both cache buckets. */
+  inputTokens: number
+  /** Completion-side tokens over the whole log. */
+  outputTokens: number
+  /** Cache-read tokens over the whole log (0 when the adapter reports none). */
+  cacheReadTokens: number
+}
+
+/** Window-scoped figures the status line shows; timing uses event timestamps. */
+export interface TranscriptStats {
+  /** Durable turns opened (`turn/start` events). */
+  turns: number
+  /** Model requests made (`step/start` events). */
+  steps: number
+  /** Summed model wall time: `step/start` → `assistant/message`, in ms. */
+  llmMs: number
+  /** Summed tool wall time: `tool/call` → `tool/result`, in ms. */
+  toolMs: number
+  /** Cumulative token accounting; input stays 0 until a report lands. */
+  usage: UsageTotals
+}
+
+/** The complete TUI transcript view for one session. */
+export interface TranscriptView {
+  /** Settled entries in log order. */
+  entries: readonly TranscriptEntry[]
+  /** Text accumulated from `assistant/chunk` deltas since the last flush. */
+  streaming: string
+  /** Latest whole-list todo snapshot from `todo/write`, empty when none. */
+  todos: SessionEvent<'todo/write'>['data']['todos']
+  /** True while a durable turn is open (`turn/start` … `turn/end`). */
+  busy: boolean
+  /** Figures the status line renders. */
+  stats: TranscriptStats
+  /**
+   * Fold-internal timing anchors, never rendered: open step and tool-call
+   * start timestamps the next `assistant/message` / `tool/result` resolves
+   * against. Keyed `turn:step` and by call id.
+   */
+  readonly anchors: { stepStart: Map<string, number>; toolStart: Map<string, number> }
+}
+
+/** Join the text blocks of a content list; non-text blocks contribute nothing. */
+function textOf(content: readonly ContentBlock[]): string {
+  return content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+/** A fresh, empty transcript view. */
+export function createTranscriptView(): TranscriptView {
+  return {
+    entries: [],
+    streaming: '',
+    todos: [],
+    busy: false,
+    stats: { turns: 0, steps: 0, llmMs: 0, toolMs: 0, usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 } },
+    anchors: { stepStart: new Map(), toolStart: new Map() },
+  }
+}
+
+/**
+ * Fold one session event into an updated view (copy-on-write).
+ * @param view - the view before the event.
+ * @param event - one durable session event from `session/event` or the log.
+ * @returns the view after the event; the input view is never mutated.
+ */
+export function projectEvent(view: TranscriptView, event: SessionEvent): TranscriptView {
+  switch (event.type) {
+    case 'user/message': {
+      // Injected context (plugin/model-continuation sources) stays collapsed
+      // to a bounded notice row, exactly like collapsed transcript context
+      // elsewhere in the product; only direct human prompts render in full.
+      const message = event.data
+      if (message.source.kind === 'user') {
+        return { ...view, entries: [...view.entries, { kind: 'user', text: textOf(message.content) }] }
+      }
+      const notice = message.source.kind === 'plugin' && message.source.form === 'notice'
+        ? message.source.summary
+        : message.source.kind
+      return { ...view, entries: [...view.entries, { kind: 'user', text: boundContextSummary(notice) }] }
+    }
+    case 'assistant/chunk': {
+      const chunk = event.data.chunk
+      if (chunk.type !== 'text-delta') return view
+      return { ...view, streaming: view.streaming + chunk.text }
+    }
+    case 'assistant/message': {
+      // The assembled message is authoritative; drop the streamed buffer.
+      const key = `${event.data.turn}:${event.data.step}`
+      const started = view.anchors.stepStart.get(key)
+      view.anchors.stepStart.delete(key)
+      const usage = event.data.usage
+      const totals = view.stats.usage
+      return {
+        ...view,
+        streaming: '',
+        entries: [...view.entries, { kind: 'assistant', text: textOf(event.data.message.content) }],
+        stats: {
+          ...view.stats,
+          llmMs: view.stats.llmMs + (started === undefined ? 0 : Math.max(0, event.time - started)),
+          usage: usage === undefined ? totals : {
+            inputTokens: totals.inputTokens + usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0),
+            outputTokens: totals.outputTokens + usage.outputTokens,
+            cacheReadTokens: totals.cacheReadTokens + (usage.cacheReadTokens ?? 0),
+          },
+        },
+      }
+    }
+    case 'tool/call': {
+      const data = event.data
+      view.anchors.toolStart.set(data.callId, event.time)
+      return {
+        ...view,
+        entries: [...view.entries, {
+          kind: 'tool',
+          callId: data.callId,
+          name: data.name,
+          arguments: data.arguments,
+          state: 'running',
+          summary: '',
+        }],
+      }
+    }
+    case 'tool/result': {
+      const block = event.data.message.content[0]
+      const started = view.anchors.toolStart.get(block.toolCallId)
+      view.anchors.toolStart.delete(block.toolCallId)
+      const summary = boundContextSummary(textOf(block.content))
+      const entries = view.entries.map((entry) => {
+        if (entry.kind !== 'tool' || entry.callId !== block.toolCallId) return entry
+        return { ...entry, state: block.isError === true ? 'error' as const : 'done' as const, summary }
+      })
+      return {
+        ...view,
+        entries,
+        stats: {
+          ...view.stats,
+          toolMs: view.stats.toolMs + (started === undefined ? 0 : Math.max(0, event.time - started)),
+        },
+      }
+    }
+    case 'todo/write':
+      return { ...view, todos: event.data.todos }
+    case 'turn/start':
+      return { ...view, busy: true, stats: { ...view.stats, turns: view.stats.turns + 1 } }
+    case 'step/start':
+      view.anchors.stepStart.set(`${event.data.turn}:${event.data.step}`, event.time)
+      return { ...view, stats: { ...view.stats, steps: view.stats.steps + 1 } }
+    case 'turn/end': {
+      const reason = event.data.reason
+      if (reason.kind !== 'error') return { ...view, busy: false }
+      return {
+        ...view,
+        busy: false,
+        entries: [...view.entries, { kind: 'error', text: `${reason.error.code}: ${reason.error.message}` }],
+      }
+    }
+    default:
+      return view
+  }
+}
+
+/**
+ * Fold a replayed event history into one view.
+ * @param events - events in `seq` order.
+ * @returns the folded view.
+ */
+export function projectEvents(events: readonly SessionEvent[]): TranscriptView {
+  return events.reduce(projectEvent, createTranscriptView())
+}

package/src/render/status.ts

@@ -0,0 +1,87 @@
+/**
+ * Status-line composition for the TUI footer: pipe-separated groups blending
+ * the Claude-Code-style identity facts (model, working directory, git branch,
+ * session) with the web StatsLine's session figures (turns/steps, model and
+ * tool wall time, cache hit, token totals). Pure functions only — the footer
+ * renders exactly what {@link buildStatusGroups} returns.
+ *
+ * @module @deepseek-ai/dsh-tui/render/status
+ */
+
+import type { TranscriptStats } from './projection.ts'
+
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
+ * digits), mirroring the web composer's StatsLine format.
+ * @param n - token count.
+ * @returns display string.
+ */
+export function formatTokens(n: number): string {
+  const scaled = (v: number): string =>
+    v >= 100 ? String(Math.round(v)) : String(Math.round(v * 10) / 10)
+  if (n < 1_000) return String(n)
+  if (n < 1_000_000) return `${scaled(n / 1_000)}K`
+  return `${scaled(n / 1_000_000)}M`
+}
+
+/**
+ * Compact duration: 45.2s under a minute, 2m42s from there on.
+ * @param ms - duration in milliseconds.
+ * @returns display string.
+ */
+export function formatDuration(ms: number): string {
+  const s = ms / 1_000
+  if (s < 60) return `${Math.round(s * 10) / 10}s`
+  const whole = Math.round(s)
+  return `${Math.floor(whole / 60)}m${whole % 60}s`
+}
+
+/**
+ * Cache-hit share of billed prompt-side input.
+ * @param usage - cumulative token totals.
+ * @returns rounded integer percent, or null when no input was billed.
+ */
+export function cacheHitPercent(usage: TranscriptStats['usage']): number | null {
+  return usage.inputTokens === 0
+    ? null
+    : Math.round(usage.cacheReadTokens / usage.inputTokens * 100)
+}
+
+/** Identity facts the runner resolves once at mount; empty strings drop out. */
+export interface StatusFacts {
+  /** `provider/model` selection serving this session. */
+  model: string
+  /** Working-directory basename the session serves. */
+  cwd: string
+  /** Git branch name, empty outside a repository or on a detached HEAD file. */
+  branch: string
+  /** Short session identifier (last dash-separated segment or tail). */
+  sessionId: string
+}
+
+/**
+ * Build the footer's display groups; a group with no data drops out whole.
+ * @param facts - identity facts resolved by the runner.
+ * @param stats - session figures folded from the durable log.
+ * @returns one string per pipe-separated group, in display order.
+ */
+export function buildStatusGroups(facts: StatusFacts, stats: TranscriptStats): string[] {
+  const groups: string[] = []
+  const identity = [facts.model, facts.cwd, facts.branch === '' ? undefined : `⑂ ${facts.branch}`]
+    .filter(part => part !== undefined && part !== '')
+  if (identity.length > 0) groups.push(identity.join(' · '))
+  if (stats.turns > 0 || stats.steps > 0) {
+    groups.push(`T${stats.turns} · S${stats.steps}`)
+    const durations: string[] = []
+    if (stats.llmMs > 0) durations.push(`llm ${formatDuration(stats.llmMs)}`)
+    if (stats.toolMs > 0) durations.push(`tool ${formatDuration(stats.toolMs)}`)
+    if (durations.length > 0) groups.push(durations.join(' · '))
+  }
+  const cacheHit = cacheHitPercent(stats.usage)
+  if (stats.usage.inputTokens > 0 || stats.usage.outputTokens > 0) {
+    if (cacheHit !== null) groups.push(`cache ${cacheHit}%`)
+    groups.push(`↑${formatTokens(stats.usage.inputTokens)} ↓${formatTokens(stats.usage.outputTokens)}`)
+  }
+  if (facts.sessionId !== '') groups.push(facts.sessionId)
+  return groups
+}

package/src/store.ts

@@ -0,0 +1,47 @@
+/**
+ * Observable transcript store: folds session events into the projection view
+ * and notifies subscribers. The renderer subscribes through
+ * `useSyncExternalStore`; the runner owns event feeding. The store owns no
+ * timing — listeners fire synchronously after each applied event.
+ *
+ * @module @deepseek-ai/dsh-tui/store
+ */
+
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { createTranscriptView, projectEvent, type TranscriptView } from './render/projection.ts'
+
+/** The externally readable, event-fed transcript store for one session. */
+export interface TranscriptStore {
+  /** The current view; the same object identity until an event changes it. */
+  getView(): TranscriptView
+  /** Subscribe to view changes; returns the unsubscribe function. */
+  subscribe(listener: () => void): () => void
+  /** Fold one session event; ignored events change nothing and notify nobody. */
+  apply(event: SessionEvent): void
+}
+
+/**
+ * Create one transcript store.
+ * @returns the store the runner feeds and the renderer subscribes to.
+ */
+export function createTranscriptStore(): TranscriptStore {
+  let view = createTranscriptView()
+  const listeners = new Set<() => void>()
+  return {
+    getView: () => view,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    apply(event: SessionEvent): void {
+      const next = projectEvent(view, event)
+      if (next === view) return
+      view = next
+      for (const listener of listeners) {
+        listener()
+      }
+    },
+  }
+}

package/src/theme.ts

@@ -0,0 +1,66 @@
+/**
+ * Terminal color tokens for the dsh TUI, mapped from the product design
+ * platform's DeepSeek palette
+ * (`packages/client/ui-theme/src/styles/design-platform.css`). Truecolor RGB
+ * rides chalk, which degrades automatically on terminals without truecolor.
+ *
+ * @module @deepseek-ai/dsh-tui/theme
+ */
+
+import chalk from 'chalk'
+
+/**
+ * RGB triples for the TUI, one entry per design-platform token in use.
+ * Keep names and values in sync with the CSS custom properties cited inline.
+ */
+export const TUI_RGB = {
+  /** Primary brand blue — `--dsw-static-deepseek-500`. */
+  brand: [65, 118, 230],
+  /** Brighter brand blue for live/streaming emphasis — `--dsw-static-deepseek-400`. */
+  brandBright: [103, 158, 254],
+  /** Deep brand blue for secondary chrome — `--dsw-static-deepseek-600`. */
+  brandDeep: [72, 104, 178],
+  /** Muted caption gray — `--dsw-static-neutral-bluish-600`. */
+  dim: [129, 133, 140],
+  /** Success green — `--dsw-static-green-500`. */
+  success: [34, 197, 94],
+  /** Error red — `--dsw-static-red-500`. */
+  error: [239, 68, 68],
+  /** Warning amber — `--dsw-static-amber-500`. */
+  warn: [245, 158, 11],
+} as const satisfies Record<string, readonly [number, number, number]>
+
+/** Paint with the primary brand blue: whale, wordmark, tool names, accents. */
+export function brand(text: string): string {
+  return chalk.rgb(...TUI_RGB.brand)(text)
+}
+
+/** Paint with the bright brand blue: streaming output and active spinners. */
+export function brandBright(text: string): string {
+  return chalk.rgb(...TUI_RGB.brandBright)(text)
+}
+
+/** Paint with the deep brand blue: borders and secondary chrome. */
+export function brandDeep(text: string): string {
+  return chalk.rgb(...TUI_RGB.brandDeep)(text)
+}
+
+/** Paint muted captions, hints, and meta lines. */
+export function dim(text: string): string {
+  return chalk.rgb(...TUI_RGB.dim)(text)
+}
+
+/** Paint completed tool results and confirmations. */
+export function success(text: string): string {
+  return chalk.rgb(...TUI_RGB.success)(text)
+}
+
+/** Paint failures and error entries. */
+export function error(text: string): string {
+  return chalk.rgb(...TUI_RGB.error)(text)
+}
+
+/** Paint warnings. */
+export function warn(text: string): string {
+  return chalk.rgb(...TUI_RGB.warn)(text)
+}

package/src/whale-glyph.ts

@@ -0,0 +1,23 @@
+// GENERATED by scripts/gen-whale-glyph.ts — do not edit by hand. Rerun the
+// generator after changing the FishLogo path. Half-block rendering of the
+// DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract;
+// native 23.16x17.04 → 26 columns × 8 half-block rows).
+// Blank cells are part of the glyph's fixed 26-column grid: pad, never trim.
+
+/** Half-block whale glyph rows; render with the brand color. */
+export const WHALE_GLYPH: readonly string[] = [
+  '    ▄▄▄▄▄▄▄▄█    ▄█▄     ▄',
+  ' ▄▄██████████▄▄  ▀███▄████',
+  '▄███████████████▄  ███▀▀▀ ',
+  '██     ▀▀█████▄▀██████    ',
+  '██▄       ▀████▄▄████     ',
+  ' ██▄        ▀██████▀      ',
+  '  ▀██▄▄  ██▄  ▀███▄▄      ',
+  '     ▀▀███████▀▀ ▀▀▀      ',
+]
+
+/** Fixed glyph width in terminal columns. */
+export const WHALE_GLYPH_COLUMNS = 26
+
+/** Fixed glyph height in half-block rows. */
+export const WHALE_GLYPH_ROWS = 8