nastech-tui 0.0.1

package/src/lib/fuzzy.ts

@@ -0,0 +1,177 @@
+// Lightweight fuzzy subsequence scorer for picker filtering.
+//
+// Matches a query as an ordered subsequence of the target (so `g4o` matches
+// `gpt-4o`) and scores by match quality so callers can rank results. Higher
+// score is a better match. Returns the matched character indices so callers
+// can highlight them.
+//
+// The scoring favours, in rough order: exact full match, prefix match, matches
+// that start on a word boundary (after `-`, `_`, `/`, `.`, space, or a
+// lower→upper case transition), contiguous runs, and earlier matches. This is
+// intentionally simple — no external dependency — but good enough to make
+// `son4` rank `claude-sonnet-4` above an incidental scattered hit.
+//
+// The WebUI ships a logically identical copy of this module at
+// web/src/lib/fuzzy.ts (only prettier formatting differs); keep the two in
+// sync. The TUI copy carries the vitest suite (the web package has no test
+// runner), so changes should be validated here.
+
+export interface FuzzyMatch {
+  /** Total score; higher is better. */
+  score: number
+  /** Indices into the original (non-lowercased) target that were matched. */
+  positions: number[]
+}
+
+const WORD_BOUNDARY = /[-_/.\s]/
+
+function isBoundary(target: string, index: number): boolean {
+  if (index === 0) {
+    return true
+  }
+
+  const prev = target[index - 1]
+
+  if (WORD_BOUNDARY.test(prev)) {
+    return true
+  }
+
+  // camelCase / lower→upper transition (e.g. the `O` in `gptO`).
+  const cur = target[index]
+
+  return prev === prev.toLowerCase() && cur !== cur.toLowerCase() && cur === cur.toUpperCase()
+}
+
+/**
+ * Score a single query token against a target. Returns null when the token is
+ * not a subsequence of the target. An empty query scores 0 with no positions.
+ */
+export function fuzzyScore(target: string, query: string): FuzzyMatch | null {
+  if (!query) {
+    return { score: 0, positions: [] }
+  }
+
+  const lowerTarget = target.toLowerCase()
+  const lowerQuery = query.toLowerCase()
+
+  const positions: number[] = []
+  let score = 0
+  let prevIndex = -1
+  let searchFrom = 0
+
+  for (const ch of lowerQuery) {
+    const idx = lowerTarget.indexOf(ch, searchFrom)
+
+    if (idx < 0) {
+      return null
+    }
+
+    positions.push(idx)
+
+    // Base point for the matched character.
+    score += 1
+
+    // Contiguous with the previous match → strong bonus.
+    if (prevIndex >= 0 && idx === prevIndex + 1) {
+      score += 5
+    } else if (prevIndex >= 0) {
+      // Penalise the gap we had to skip (capped), so contiguous beats scattered.
+      score -= Math.min(idx - prevIndex - 1, 3)
+    }
+
+    // Word-boundary / start-of-string matches are meaningful.
+    if (isBoundary(target, idx)) {
+      score += 3
+    }
+
+    // Matching the very first character of the target is the strongest signal.
+    if (idx === 0) {
+      score += 5
+    }
+
+    prevIndex = idx
+    searchFrom = idx + 1
+  }
+
+  // Prefix bonus: the query matched a contiguous prefix of the target.
+  if (positions.length && positions[0] === 0 && positions[positions.length - 1] === positions.length - 1) {
+    score += 8
+  }
+
+  // Exact full match dominates everything else.
+  if (lowerTarget === lowerQuery) {
+    score += 20
+  }
+
+  // Slightly prefer shorter targets when scores are otherwise close, so a
+  // query that fully prefixes a short id beats the same prefix on a long one.
+  score -= lowerTarget.length * 0.01
+
+  return { score, positions }
+}
+
+/**
+ * Score a target against a whitespace-separated, multi-token query. Every token
+ * must match (AND semantics); the result aggregates per-token scores and the
+ * union of matched positions. Returns null if any token fails to match.
+ */
+export function fuzzyScoreMulti(target: string, query: string): FuzzyMatch | null {
+  const tokens = query.trim().toLowerCase().split(/\s+/).filter(Boolean)
+
+  if (!tokens.length) {
+    return { score: 0, positions: [] }
+  }
+
+  let score = 0
+  const positionSet = new Set<number>()
+
+  for (const token of tokens) {
+    const match = fuzzyScore(target, token)
+
+    if (!match) {
+      return null
+    }
+
+    score += match.score
+
+    for (const pos of match.positions) {
+      positionSet.add(pos)
+    }
+  }
+
+  return { score, positions: [...positionSet].sort((a, b) => a - b) }
+}
+
+export interface RankedItem<T> {
+  item: T
+  score: number
+  positions: number[]
+}
+
+/**
+ * Filter + rank a list by a fuzzy query against a derived text key. Non-matching
+ * items are dropped; matches are sorted by score (descending), ties broken by
+ * the original index so ordering is stable for equal scores. An empty query
+ * returns every item in original order with no positions.
+ */
+export function fuzzyRank<T>(items: readonly T[], query: string, toText: (item: T) => string): RankedItem<T>[] {
+  const trimmed = query.trim()
+
+  if (!trimmed) {
+    return items.map(item => ({ item, score: 0, positions: [] }))
+  }
+
+  const ranked: Array<RankedItem<T> & { index: number }> = []
+
+  items.forEach((item, index) => {
+    const match = fuzzyScoreMulti(toText(item), trimmed)
+
+    if (match) {
+      ranked.push({ item, score: match.score, positions: match.positions, index })
+    }
+  })
+
+  ranked.sort((a, b) => b.score - a.score || a.index - b.index)
+
+  return ranked.map(({ item, score, positions }) => ({ item, score, positions }))
+}

package/src/lib/gracefulExit.ts

@@ -0,0 +1,47 @@
+interface SetupOptions {
+  cleanups?: (() => Promise<void> | void)[]
+  failsafeMs?: number
+  onError?: (scope: 'uncaughtException' | 'unhandledRejection', err: unknown) => void
+  onSignal?: (signal: NodeJS.Signals) => void
+}
+
+const SIGNAL_EXIT_CODE: Record<'SIGHUP' | 'SIGINT' | 'SIGTERM', number> = {
+  SIGHUP: 129,
+  SIGINT: 130,
+  SIGTERM: 143
+}
+
+let wired = false
+
+export function setupGracefulExit({ cleanups = [], failsafeMs = 4000, onError, onSignal }: SetupOptions = {}) {
+  if (wired) {
+    return
+  }
+
+  wired = true
+
+  let shuttingDown = false
+
+  const exit = (code: number, signal?: NodeJS.Signals) => {
+    if (shuttingDown) {
+      return
+    }
+
+    shuttingDown = true
+
+    if (signal) {
+      onSignal?.(signal)
+    }
+
+    setTimeout(() => process.exit(code), failsafeMs).unref?.()
+
+    void Promise.allSettled(cleanups.map(fn => Promise.resolve().then(fn))).finally(() => process.exit(code))
+  }
+
+  for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const) {
+    process.on(sig, () => exit(SIGNAL_EXIT_CODE[sig], sig))
+  }
+
+  process.on('uncaughtException', err => onError?.('uncaughtException', err))
+  process.on('unhandledRejection', reason => onError?.('unhandledRejection', reason))
+}

package/src/lib/history.ts

@@ -0,0 +1,82 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const MAX = 1000
+const dir = process.env.NASTECH_HOME ?? join(homedir(), '.nastech')
+const file = join(dir, '.nastech_history')
+
+let cache: string[] | null = null
+
+export function load() {
+  if (cache) {
+    return cache
+  }
+
+  try {
+    if (!existsSync(file)) {
+      cache = []
+
+      return cache
+    }
+
+    const entries: string[] = []
+    let current: string[] = []
+
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+      if (line.startsWith('+')) {
+        current.push(line.slice(1))
+      } else if (current.length) {
+        entries.push(current.join('\n'))
+        current = []
+      }
+    }
+
+    if (current.length) {
+      entries.push(current.join('\n'))
+    }
+
+    cache = entries.slice(-MAX)
+  } catch {
+    cache = []
+  }
+
+  return cache
+}
+
+export function append(line: string) {
+  const trimmed = line.trim()
+
+  if (!trimmed) {
+    return
+  }
+
+  const items = load()
+
+  if (items.at(-1) === trimmed) {
+    return
+  }
+
+  items.push(trimmed)
+
+  if (items.length > MAX) {
+    items.splice(0, items.length - MAX)
+  }
+
+  try {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+
+    const ts = new Date().toISOString().replace('T', ' ').replace('Z', '')
+
+    const encoded = trimmed
+      .split('\n')
+      .map(l => `+${l}`)
+      .join('\n')
+
+    appendFileSync(file, `\n# ${ts}\n${encoded}\n`)
+  } catch {
+    void 0
+  }
+}

package/src/lib/inputMetrics.ts

@@ -0,0 +1,203 @@
+import { stringWidth, wrapAnsi } from '@nastechai/ink'
+
+import type { Role } from '../types.js'
+
+export const COMPOSER_PROMPT_GAP_WIDTH = 1
+
+let _seg: Intl.Segmenter | null = null
+const seg = () => (_seg ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' }))
+
+interface VisualLine {
+  end: number
+  start: number
+}
+
+const graphemes = (value: string) =>
+  [...seg().segment(value)].map(({ segment, index }) => ({
+    end: index + segment.length,
+    index,
+    segment,
+    width: Math.max(1, stringWidth(segment))
+  }))
+
+// Build VisualLines from wrap-ansi's output by mapping each emitted character
+// back to its original offset in `value`. wrap-ansi only INSERTS '\n' at wrap
+// boundaries — it never drops, reorders, or substitutes existing characters —
+// so a parallel walk uniquely identifies each line's source range.
+//
+// This used to be a hand-rolled word-wrap whose break points disagreed with
+// wrap-ansi in subtle but visible ways: exact-fill rows pushed the cursor to
+// a phantom next line, mid-word breaks landed one grapheme off, etc. The
+// composer's TextInput renders text via Ink's <Text wrap="wrap">, which
+// delegates to wrap-ansi — so any drift between the two algorithms parks the
+// hardware cursor several cells away from the last rendered character.
+// Sourcing both from wrap-ansi guarantees agreement.
+function visualLines(value: string, cols: number): VisualLine[] {
+  if (!value.length) {
+    return [{ start: 0, end: 0 }]
+  }
+
+  const width = Math.max(1, cols)
+  const wrapped = wrapAnsi(value, width, { hard: true, trim: false })
+  const lines: VisualLine[] = []
+
+  let originalIdx = 0
+  let lineStart = 0
+
+  for (let i = 0; i < wrapped.length; i += 1) {
+    const ch = wrapped[i]!
+
+    if (ch === '\n') {
+      // wrap-ansi inserts '\n' to mark a soft-wrap boundary OR copies a
+      // literal '\n' from the input. Either way the next char in `wrapped`
+      // begins a new visual line. If the source character is a hard '\n',
+      // consume it (it doesn't appear in either line). Otherwise the '\n'
+      // is purely a wrap marker and originalIdx stays put.
+      lines.push({ start: lineStart, end: originalIdx })
+      const isHardNewline = originalIdx < value.length && value[originalIdx] === '\n'
+
+      if (isHardNewline) {
+        originalIdx += 1
+      }
+
+      lineStart = originalIdx
+
+      continue
+    }
+
+    // Defensive sync check. wrap-ansi (with `hard: true, trim: false`, no
+    // styled input) is documented to only insert '\n' at break points and
+    // never substitute, drop, or reorder source characters — so under those
+    // options `wrapped[i]` should always equal `value[originalIdx]`. But
+    // future option changes, library upgrades, or callers that start passing
+    // styled input (ANSI escapes) could violate that invariant silently. If
+    // they do, we'd slide `originalIdx` past the end of `value` and emit
+    // garbage line ranges with no diagnostic. Realign by scanning forward
+    // for the matching character; bail out (return whatever we have) if the
+    // sync is unrecoverable rather than producing wrong-but-plausible output.
+    if (originalIdx >= value.length) {
+      break
+    }
+
+    if (value[originalIdx] !== ch) {
+      const reSync = value.indexOf(ch, originalIdx)
+
+      if (reSync === -1) {
+        break
+      }
+
+      originalIdx = reSync
+    }
+
+    originalIdx += 1
+  }
+
+  lines.push({ start: lineStart, end: originalIdx })
+
+  // wrap-ansi collapses an empty input into [""] which we already handled
+  // above; preserve the invariant that lines is never empty for any input.
+  return lines.length ? lines : [{ start: 0, end: 0 }]
+}
+
+function widthBetween(value: string, start: number, end: number) {
+  let width = 0
+
+  for (const part of graphemes(value.slice(start, end))) {
+    width += part.width
+  }
+
+  return width
+}
+
+/**
+ * Mirrors the word-wrap behavior used by the composer TextInput.
+ * Returns the zero-based visual line and column of the cursor cell.
+ *
+ * IMPORTANT: this MUST stay in lock-step with how Ink's `<Text wrap="wrap">`
+ * lays the value out (which uses `wrap-ansi`). Any divergence parks the
+ * hardware cursor several cells off the last rendered character — see the
+ * "cursor drift past blank cells" bug. `visualLines` is sourced directly
+ * from wrap-ansi to enforce that invariant.
+ */
+export function cursorLayout(value: string, cursor: number, cols: number) {
+  const pos = Math.max(0, Math.min(cursor, value.length))
+  const w = Math.max(1, cols)
+  const lines = visualLines(value, w)
+  let lineIndex = 0
+
+  for (let i = 0; i < lines.length; i += 1) {
+    if (lines[i]!.start <= pos) {
+      lineIndex = i
+    } else {
+      break
+    }
+  }
+
+  const line = lines[lineIndex]!
+  const column = widthBetween(value, line.start, Math.min(pos, line.end))
+
+  // NOTE: the previous implementation forced an extra line break when
+  // `column >= w` (the "trailing cursor-cell overflows" rule). With
+  // `visualLines` sourcing breaks from wrap-ansi, the line wrapping
+  // above already matches what Ink will actually render. Pushing the
+  // cursor onto a phantom next line here would re-introduce the same
+  // drift we're fixing, so we don't.
+  return { column, line: lineIndex }
+}
+
+export function offsetFromPosition(value: string, row: number, col: number, cols: number) {
+  if (!value.length) {
+    return 0
+  }
+
+  const lines = visualLines(value, cols)
+  const target = lines[Math.max(0, Math.min(lines.length - 1, Math.floor(row)))]!
+  const targetCol = Math.max(0, Math.floor(col))
+  let column = 0
+
+  for (const part of graphemes(value.slice(target.start, target.end))) {
+    if (targetCol <= column + Math.max(0, part.width - 1)) {
+      return target.start + part.index
+    }
+
+    column += part.width
+  }
+
+  return target.end
+}
+
+export function inputVisualHeight(value: string, columns: number) {
+  return cursorLayout(value, value.length, columns).line + 1
+}
+
+export function composerPromptWidth(promptText: string) {
+  return Math.max(1, stringWidth(promptText)) + COMPOSER_PROMPT_GAP_WIDTH
+}
+
+export function transcriptGutterWidth(role: Role, userPrompt: string) {
+  return role === 'user' ? composerPromptWidth(userPrompt) : 3
+}
+
+export function transcriptBodyWidth(totalCols: number, role: Role, userPrompt: string, termuxMode = false) {
+  const horizontalReserve = termuxMode ? 2 : 4
+  const available = Math.max(1, totalCols - transcriptGutterWidth(role, userPrompt) - horizontalReserve)
+
+  if (termuxMode) {
+    // On narrow / unusual aspect-ratio mobile panes, forcing a wide minimum
+    // width causes right-edge clipping and chopped words.
+    return available
+  }
+
+  return Math.max(20, available)
+}
+
+export function stableComposerColumns(totalCols: number, promptWidth: number, termuxMode = false) {
+  // Physical render/wrap width. Always reserve outer composer padding and
+  // prompt prefix. Only reserve the transcript scrollbar gutter when the
+  // terminal is wide enough; on narrow panes, preserving input columns beats
+  // keeping gutters visually aligned.
+  const afterPrompt = totalCols - promptWidth
+  const reserveScrollbar = afterPrompt >= (termuxMode ? 36 : 24) ? 2 : 0
+
+  return Math.max(1, totalCols - promptWidth - 2 - reserveScrollbar)
+}

package/src/lib/liveProgress.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest'
+
+import type { Msg } from '../types.js'
+
+import { appendToolShelfMessage, canHoldToolShelf, isTodoDone, mergeToolShelfInto } from './liveProgress.js'
+
+describe('isTodoDone', () => {
+  it('only treats non-empty all-completed/cancelled lists as done', () => {
+    expect(isTodoDone([])).toBe(false)
+    expect(isTodoDone([{ content: 'x', id: 'x', status: 'completed' }])).toBe(true)
+    expect(isTodoDone([{ content: 'x', id: 'x', status: 'in_progress' }])).toBe(false)
+    expect(
+      isTodoDone([
+        { content: 'x', id: 'x', status: 'completed' },
+        { content: 'y', id: 'y', status: 'cancelled' }
+      ])
+    ).toBe(true)
+  })
+})
+
+describe('tool shelf helpers', () => {
+  it('recognizes contextual thinking shelves as holders', () => {
+    expect(canHoldToolShelf({ kind: 'trail', role: 'system', text: '', thinking: 'plan' })).toBe(true)
+    expect(canHoldToolShelf({ kind: 'trail', role: 'system', text: '', tools: ['one ✓'] })).toBe(true)
+    expect(canHoldToolShelf({ role: 'assistant', text: 'done' })).toBe(false)
+  })
+
+  it('merges source rows into an existing shelf', () => {
+    expect(
+      mergeToolShelfInto(
+        { kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['one ✓'] },
+        { kind: 'trail', role: 'system', text: '', tools: ['two ✓'] }
+      )
+    ).toEqual({ kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['one ✓', 'two ✓'] })
+  })
+})
+
+describe('appendToolShelfMessage', () => {
+  it('merges adjacent tool shelves into one contextual shelf', () => {
+    const merged = appendToolShelfMessage([{ kind: 'trail', role: 'system', text: '', tools: ['one ✓'] }], {
+      kind: 'trail',
+      role: 'system',
+      text: '',
+      tools: ['two ✓']
+    })
+
+    expect(merged).toEqual([{ kind: 'trail', role: 'system', text: '', tools: ['one ✓', 'two ✓'] }])
+  })
+
+  it('adds tools to the nearest contextual thinking shelf', () => {
+    const merged = appendToolShelfMessage(
+      [{ kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['one ✓'] }],
+      { kind: 'trail', role: 'system', text: '', tools: ['two ✓'] }
+    )
+
+    expect(merged).toEqual([{ kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['one ✓', 'two ✓'] }])
+  })
+
+  it('merges through intervening thinking-only rows back into the nearest holder', () => {
+    const prev: Msg[] = [
+      { kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['one ✓'] },
+      { kind: 'trail', role: 'system', text: '', thinking: 'more plan' }
+    ]
+
+    const merged = appendToolShelfMessage(prev, {
+      kind: 'trail',
+      role: 'system',
+      text: '',
+      tools: ['two ✓']
+    })
+
+    expect(merged).toHaveLength(2)
+    expect(merged[0]).toEqual({
+      kind: 'trail',
+      role: 'system',
+      text: '',
+      thinking: 'plan',
+      tools: ['one ✓', 'two ✓']
+    })
+    expect(merged[1]).toEqual({ kind: 'trail', role: 'system', text: '', thinking: 'more plan' })
+  })
+
+  it('collapses a chronological thinking/tool/thinking/tool stream into one shelf', () => {
+    const events: Msg[] = [
+      { kind: 'trail', role: 'system', text: '', thinking: 'plan' },
+      { kind: 'trail', role: 'system', text: '', tools: ['one ✓'] },
+      { kind: 'trail', role: 'system', text: '', thinking: 'more plan' },
+      { kind: 'trail', role: 'system', text: '', tools: ['two ✓'] },
+      { kind: 'trail', role: 'system', text: '', tools: ['three ✓'] }
+    ]
+
+    const reduced = events.reduce<Msg[]>((acc, msg) => appendToolShelfMessage(acc, msg), [])
+
+    expect(reduced).toHaveLength(2)
+    expect(reduced[0]).toEqual({
+      kind: 'trail',
+      role: 'system',
+      text: '',
+      thinking: 'plan',
+      tools: ['one ✓', 'two ✓', 'three ✓']
+    })
+    expect(reduced[1]).toEqual({ kind: 'trail', role: 'system', text: '', thinking: 'more plan' })
+  })
+
+  it('starts a new shelf across assistant text boundaries', () => {
+    const merged = appendToolShelfMessage(
+      [
+        { kind: 'trail', role: 'system', text: '', tools: ['one ✓'] },
+        { role: 'assistant', text: 'done' }
+      ],
+      { kind: 'trail', role: 'system', text: '', tools: ['two ✓'] }
+    )
+
+    expect(merged).toHaveLength(3)
+  })
+})

package/src/lib/liveProgress.ts

@@ -0,0 +1,79 @@
+import type { Msg, TodoItem } from '../types.js'
+
+export const countPendingTodos = (todos: readonly TodoItem[]) =>
+  todos.filter(todo => todo.status === 'in_progress' || todo.status === 'pending').length
+
+export const isTodoDone = (todos: readonly TodoItem[]) =>
+  todos.length > 0 && todos.every(todo => todo.status === 'completed' || todo.status === 'cancelled')
+
+export const isToolShelfMessage = (msg: Msg | undefined) =>
+  Boolean(msg?.kind === 'trail' && !msg.text && !msg.thinking?.trim() && msg.tools?.length)
+
+export const canHoldToolShelf = (msg: Msg | undefined) =>
+  Boolean(msg?.kind === 'trail' && !msg.text && (msg.thinking?.trim() || msg.tools?.length))
+
+export const mergeToolShelfInto = (target: Msg, source: Msg): Msg => ({
+  ...target,
+  tools: [...(target.tools ?? []), ...(source.tools ?? [])]
+})
+
+const isBarrierMessage = (msg: Msg | undefined) => {
+  if (!msg) {
+    return true
+  }
+
+  // Assistant text, user input, intro/panel rows all terminate the shelf.
+  if (msg.kind === 'intro' || msg.kind === 'panel' || msg.kind === 'diff') {
+    return true
+  }
+
+  if (msg.role && msg.role !== 'system') {
+    return true
+  }
+
+  if (msg.text) {
+    return true
+  }
+
+  return false
+}
+
+const isToolCarryingTrail = (msg: Msg | undefined) => Boolean(msg?.kind === 'trail' && !msg.text && msg.tools?.length)
+
+export const appendToolShelfMessage = (prev: readonly Msg[], msg: Msg): Msg[] => {
+  if (!isToolShelfMessage(msg)) {
+    return [...prev, msg]
+  }
+
+  let fallbackHolder: number | null = null
+
+  for (let index = prev.length - 1; index >= 0; index--) {
+    const candidate = prev[index]
+
+    if (isToolCarryingTrail(candidate)) {
+      const next = [...prev]
+
+      next[index] = mergeToolShelfInto(candidate!, msg)
+
+      return next
+    }
+
+    if (fallbackHolder === null && canHoldToolShelf(candidate)) {
+      fallbackHolder = index
+    }
+
+    if (isBarrierMessage(candidate)) {
+      break
+    }
+  }
+
+  if (fallbackHolder !== null) {
+    const next = [...prev]
+
+    next[fallbackHolder] = mergeToolShelfInto(prev[fallbackHolder]!, msg)
+
+    return next
+  }
+
+  return [...prev, msg]
+}