@sushanglewis/lincoln 1.5.0 → 1.5.2

package/framework/tools/lincoln/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sushanglewis/lincoln-recorder",
+  "version": "1.5.2",
+  "description": "Cross-tool terminal UI for recording Lincoln interviews",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "lincoln-record": "./dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "lint": "echo 'lint not configured'"
+  },
+  "dependencies": {
+    "ink": "^5.2.0",
+    "js-yaml": "^4.1.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.0",
+    "@types/react": "^18.3.12",
+    "ink-testing-library": "^4.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.9"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "lincoln",
+    "interview",
+    "recording",
+    "tui"
+  ],
+  "license": "MIT"
+}

package/framework/tools/lincoln/src/cli.tsx

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { Box, Text } from 'ink'
+import React from 'react'
+
+import { parseArgs, type ParsedArgs } from './config/args'
+import { resolveConfig, type ResolvedConfig } from './config/resolveConfig'
+import { RecordingApp } from './components/RecordingApp'
+
+export interface AppProps {
+  args: ParsedArgs
+  config: ResolvedConfig
+}
+
+export function App({ args, config }: AppProps) {
+  if (args.help) {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Text bold>lincoln-record</Text>
+        <Text>Cross-tool TUI for Lincoln interview recording.</Text>
+        <Text />
+        <Text bold>Usage:</Text>
+        <Text>  lincoln-record [options]</Text>
+        <Text />
+        <Text bold>Options:</Text>
+        <Text>  --topic       Interview topic</Text>
+        <Text>  --design-id   Design ID for the session</Text>
+        <Text>  --branch      Current branch name</Text>
+        <Text>  --session-id  Explicit session ID</Text>
+        <Text>  --no-tui      Run without the terminal UI</Text>
+        <Text>  --help, -h    Show this help message</Text>
+        <Text />
+        <Text dimColor>Configuration files: ~/.lincolnrc, ./.lincolnrc</Text>
+      </Box>
+    )
+  }
+
+  return (
+    <RecordingApp
+      workspaceRoot={config.workspaceRoot}
+      sessionId={config.sessionId}
+      topic={config.topic}
+      designId={config.designId}
+      branch={config.branch}
+      audioMeterStyle={config.audioMeterStyle}
+    />
+  )
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const args = parseArgs(argv)
+  const config = resolveConfig(args)
+
+  if (args.noTui) {
+    console.log(JSON.stringify(config, null, 2))
+    return
+  }
+
+  const { render } = await import('ink')
+  render(<App args={args} config={config} />)
+}

package/framework/tools/lincoln/src/components/AudioMeter.tsx

@@ -0,0 +1,34 @@
+import { Box, Text } from 'ink'
+import React from 'react'
+
+import { amplitudeToMeter } from '../utils/amplitudeToMeter'
+
+export interface AudioMeterProps {
+  amplitude: number
+  style: 'bar' | 'dot' | 'wave'
+}
+
+const BLOCKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']
+
+export function AudioMeter({ amplitude, style }: AudioMeterProps) {
+  const bars = amplitudeToMeter(amplitude, 16)
+
+  if (style === 'bar') {
+    const filled = '█'.repeat(bars)
+    const empty = '░'.repeat(16 - bars)
+    return (<Text>{filled + empty}</Text>)
+  }
+
+  if (style === 'dot') {
+    const filled = '●'.repeat(bars)
+    const empty = '○'.repeat(16 - bars)
+    return (<Text>{filled + empty}</Text>)
+  }
+
+  // wave
+  const wave = BLOCKS.slice(0, Math.max(1, Math.ceil(amplitude * BLOCKS.length)))
+    .join('')
+    .repeat(2)
+    .slice(0, 16)
+  return (<Text>{wave.padEnd(16, '~')}</Text>)
+}

package/framework/tools/lincoln/src/components/CancelledScreen.tsx

@@ -0,0 +1,11 @@
+import { Box, Text } from 'ink'
+import React from 'react'
+
+export function CancelledScreen() {
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text bold color="yellow">Recording cancelled</Text>
+      <Text>No files were saved.</Text>
+    </Box>
+  )
+}

package/framework/tools/lincoln/src/components/DevicesMenu.tsx

@@ -0,0 +1,79 @@
+import { Box, Text, useInput } from 'ink'
+import React, { useEffect, useState } from 'react'
+
+import { SelectMenu } from './SelectMenu'
+import type { DeviceList } from '../devices/parseDevices'
+
+export interface DevicesMenuProps {
+  listDevicesFn: () => Promise<DeviceList>
+  onSelect: (device: string) => void
+  onClose: () => void
+}
+
+type LoadState =
+  | { status: 'loading' }
+  | { status: 'loaded'; list: DeviceList }
+  | { status: 'error'; message: string }
+
+export function DevicesMenu({ listDevicesFn, onSelect, onClose }: DevicesMenuProps) {
+  const [loadState, setLoadState] = useState<LoadState>({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    listDevicesFn()
+      .then(list => {
+        if (!cancelled) setLoadState({ status: 'loaded', list })
+      })
+      .catch(error => {
+        if (!cancelled) {
+          setLoadState({
+            status: 'error',
+            message: error instanceof Error ? error.message : String(error),
+          })
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [listDevicesFn])
+
+  useInput(
+    (_input, key) => {
+      if (key.escape) onClose()
+    },
+    { isActive: loadState.status !== 'loaded' },
+  )
+
+  if (loadState.status === 'loading') {
+    return (
+      <Box paddingX={1}>
+        <Text dimColor>Loading devices…</Text>
+      </Box>
+    )
+  }
+
+  if (loadState.status === 'error') {
+    return (
+      <Box flexDirection="column" paddingX={1}>
+        <Text color="red">Failed to list devices: {loadState.message}</Text>
+        <Text dimColor>[esc] back</Text>
+      </Box>
+    )
+  }
+
+  const { list } = loadState
+  const items = list.devices.map(name => ({
+    key: name,
+    label: name === list.defaultDevice ? `${name} (default)` : name,
+  }))
+
+  return (
+    <SelectMenu
+      title="Devices"
+      items={items}
+      onSelect={onSelect}
+      onClose={onClose}
+      footer="[↑↓] select  [enter] confirm  [esc] back"
+    />
+  )
+}

package/framework/tools/lincoln/src/components/HintBar.tsx

@@ -0,0 +1,25 @@
+import { Box, Text } from 'ink'
+import React from 'react'
+
+export type HintKey = 'idle' | 'recording' | 'stopped' | 'cancelled' | 'error' | 'menu'
+
+export interface HintBarProps {
+  mode: HintKey
+}
+
+const HINTS: Record<HintKey, string> = {
+  idle: '[r] record  [d] devices  [m] model  [q] quit',
+  recording: '[s] stop  [c] cancel',
+  stopped: '[any key] exit',
+  cancelled: '[q] exit',
+  error: '[q] exit',
+  menu: '[↑↓] select  [enter] confirm  [esc] back',
+}
+
+export function HintBar({ mode }: HintBarProps) {
+  return (
+    <Box paddingX={1} paddingY={1}>
+      <Text dimColor>{HINTS[mode]}</Text>
+    </Box>
+  )
+}

package/framework/tools/lincoln/src/components/LogView.tsx

@@ -0,0 +1,36 @@
+import { Box, Text } from 'ink'
+import React from 'react'
+
+export interface LogEntry {
+  id: string
+  message: string
+  type?: 'info' | 'success' | 'error' | 'command'
+}
+
+export interface LogViewProps {
+  logs: LogEntry[]
+}
+
+const TYPE_COLORS: Record<string, string | undefined> = {
+  info: undefined,
+  success: 'green',
+  error: 'red',
+  command: 'cyan',
+}
+
+export function LogView({ logs }: LogViewProps) {
+  const visible = logs.slice(-8)
+
+  return (
+    <Box flexDirection="column" paddingX={1} flexGrow={1}>
+      <Text underline dimColor>Log</Text>
+      {visible.length === 0 ? (
+        <Text dimColor>No events yet.</Text>
+      ) : (
+        visible.map(log => (
+          <Text key={log.id} color={TYPE_COLORS[log.type ?? 'info']}>{log.message}</Text>
+        ))
+      )}
+    </Box>
+  )
+}

package/framework/tools/lincoln/src/components/ModelMenu.tsx

@@ -0,0 +1,122 @@
+import { Box, Text, useInput } from 'ink'
+import React, { useEffect, useState } from 'react'
+
+import { SelectMenu } from './SelectMenu'
+import type { ModelStatus } from '../models/models'
+import type { WarmupProgress } from '../models/warmupProgress'
+
+export interface ModelMenuProps {
+  listModelStatusesFn: () => Promise<ModelStatus[]>
+  runWarmupFn: (model: string, onProgress: (p: WarmupProgress) => void) => Promise<string>
+  onSelect: (model: string) => void
+  onClose: () => void
+}
+
+type MenuState =
+  | { status: 'loading' }
+  | { status: 'loaded'; models: ModelStatus[] }
+  | { status: 'downloading'; model: string; percent: number | null; downloaded: number }
+  | { status: 'error'; message: string }
+
+export function ModelMenu({ listModelStatusesFn, runWarmupFn, onSelect, onClose }: ModelMenuProps) {
+  const [menuState, setMenuState] = useState<MenuState>({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    listModelStatusesFn()
+      .then(models => {
+        if (!cancelled) setMenuState({ status: 'loaded', models })
+      })
+      .catch(error => {
+        if (!cancelled) {
+          setMenuState({
+            status: 'error',
+            message: error instanceof Error ? error.message : String(error),
+          })
+        }
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [listModelStatusesFn])
+
+  useInput(
+    (_input, key) => {
+      if (key.escape) onClose()
+    },
+    { isActive: menuState.status === 'error' },
+  )
+
+  const handleSelect = (name: string) => {
+    if (menuState.status !== 'loaded') return
+    const target = menuState.models.find(m => m.name === name)
+    if (!target) return
+
+    if (target.cached) {
+      onSelect(name)
+      return
+    }
+
+    setMenuState({ status: 'downloading', model: name, percent: null, downloaded: 0 })
+    runWarmupFn(name, progress => {
+      setMenuState({
+        status: 'downloading',
+        model: name,
+        percent: progress.percent,
+        downloaded: progress.downloaded,
+      })
+    })
+      .then(() => onSelect(name))
+      .catch(error => {
+        setMenuState({
+          status: 'error',
+          message: error instanceof Error ? error.message : String(error),
+        })
+      })
+  }
+
+  if (menuState.status === 'loading') {
+    return (
+      <Box paddingX={1}>
+        <Text dimColor>Loading models…</Text>
+      </Box>
+    )
+  }
+
+  if (menuState.status === 'error') {
+    return (
+      <Box flexDirection="column" paddingX={1}>
+        <Text color="red">{menuState.message}</Text>
+        <Text dimColor>[esc] back</Text>
+      </Box>
+    )
+  }
+
+  if (menuState.status === 'downloading') {
+    const progressText =
+      menuState.percent !== null
+        ? `${menuState.percent.toFixed(1)}%`
+        : `${menuState.downloaded} bytes`
+    return (
+      <Box flexDirection="column" paddingX={1}>
+        <Text>Downloading model '{menuState.model}'… {progressText}</Text>
+        <Text dimColor>please wait</Text>
+      </Box>
+    )
+  }
+
+  const items = menuState.models.map(m => ({
+    key: m.name,
+    label: m.cached ? `✓ ${m.name}` : `· ${m.name} (not downloaded)`,
+  }))
+
+  return (
+    <SelectMenu
+      title="Model"
+      items={items}
+      onSelect={handleSelect}
+      onClose={onClose}
+      footer="[↑↓] select  [enter] confirm  [esc] back"
+    />
+  )
+}

package/framework/tools/lincoln/src/components/ReadyScreen.tsx

@@ -0,0 +1,54 @@
+import { Box, Text } from 'ink'
+import React from 'react'
+
+export interface ReadyScreenProps {
+  sessionId: string
+  topic: string
+  designId: string
+  branch: string
+  selectedIndex?: number
+}
+
+const OPTIONS = [
+  { label: '开始录音', hint: 'Enter' },
+  { label: '退出', hint: 'q / Esc' },
+]
+
+export function ReadyScreen({ sessionId, topic, designId, branch, selectedIndex = 0 }: ReadyScreenProps) {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="gray" padding={1}>
+      <Box flexDirection="row" justifyContent="space-between" alignItems="center">
+        <Box gap={1}>
+          <Text color="red">●</Text>
+          <Text color="yellow">●</Text>
+          <Text color="green">●</Text>
+        </Box>
+        <Text bold color="white">Lincoln Recorder</Text>
+      </Box>
+
+      <Box flexDirection="column" paddingY={1}>
+        <Text color="gray">Session: {sessionId}</Text>
+        {topic ? <Text color="gray">Topic: {topic}</Text> : null}
+        {designId ? <Text color="gray">Design: {designId}</Text> : null}
+        {branch ? <Text color="gray">Branch: {branch}</Text> : null}
+      </Box>
+
+      <Box flexDirection="column" paddingY={1} gap={1}>
+        {OPTIONS.map((option, index) => {
+          const isSelected = index === selectedIndex
+          return (
+            <Box key={option.label} flexDirection="row" gap={1}>
+              <Text color={isSelected ? 'green' : 'gray'}>{isSelected ? '▸' : ' '}</Text>
+              <Text bold={isSelected} color={isSelected ? 'green' : 'gray'} dimColor={!isSelected}>
+                {option.label}
+              </Text>
+              <Text color="gray" dimColor>
+                [{option.hint}]
+              </Text>
+            </Box>
+          )
+        })}
+      </Box>
+    </Box>
+  )
+}

package/framework/tools/lincoln/src/components/RecordingApp.tsx

@@ -0,0 +1,211 @@
+import { Box, useApp } from 'ink'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+
+import { StatusPanel } from './StatusPanel'
+import { LogView, type LogEntry } from './LogView'
+import { HintBar } from './HintBar'
+import { DevicesMenu } from './DevicesMenu'
+import { ModelMenu } from './ModelMenu'
+import { useKeyHandler } from '../hooks/useKeyHandler'
+import { useRecorder } from '../recording/useRecorder'
+import { listDevices } from '../devices/listDevices'
+import { defaultModelCacheDir, listModelStatuses, type ModelStatus } from '../models/models'
+import { runWarmup } from '../models/runWarmup'
+import type { WarmupProgress } from '../models/warmupProgress'
+import type { DeviceList } from '../devices/parseDevices'
+
+type AppMode = 'main' | 'devices' | 'model'
+
+export interface RecordingAppProps {
+  workspaceRoot: string
+  sessionId: string
+  topic: string
+  designId: string
+  branch: string
+  audioMeterStyle?: 'bar' | 'dot' | 'wave'
+  lincolnRecordPath?: string
+  listDevicesFn?: () => Promise<DeviceList>
+  listModelStatusesFn?: () => Promise<ModelStatus[]>
+  runWarmupFn?: (model: string, onProgress: (p: WarmupProgress) => void) => Promise<string>
+}
+
+function createLogId() {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+export function RecordingApp({
+  workspaceRoot,
+  sessionId,
+  topic,
+  designId,
+  branch,
+  audioMeterStyle = 'bar',
+  lincolnRecordPath,
+  listDevicesFn,
+  listModelStatusesFn,
+  runWarmupFn,
+}: RecordingAppProps) {
+  const { exit } = useApp()
+  const [logs, setLogs] = useState<LogEntry[]>([])
+  const [mode, setMode] = useState<AppMode>('main')
+  const [mic, setMic] = useState<string | null>(null)
+  const [model, setModel] = useState<string | null>(null)
+
+  const addLog = useCallback((message: string, type: LogEntry['type'] = 'info') => {
+    setLogs(prev => [...prev, { id: createLogId(), message, type }])
+  }, [])
+
+  const { state, start, stop, cancel } = useRecorder({
+    workspaceRoot,
+    sessionId,
+    lincolnRecordPath,
+    mic,
+    model,
+    startOnMount: false,
+  })
+
+  useEffect(() => {
+    switch (state.status) {
+      case 'recording':
+        addLog('Recording started.', 'info')
+        break
+      case 'stopped':
+        addLog(`Saved to ${workspaceRoot}/${sessionId}/audio.wav`, 'success')
+        addLog(`Run: claude process-interview ${sessionId}`, 'command')
+        break
+      case 'cancelled':
+        addLog('Recording cancelled. No files were saved.', 'error')
+        break
+      case 'error':
+        addLog(`Recording error: ${state.errorMessage ?? 'unknown error'}`, 'error')
+        break
+    }
+  }, [state.status, state.errorMessage, addLog, workspaceRoot, sessionId])
+
+  const handleQuit = useCallback(() => {
+    exit()
+  }, [exit])
+
+  const handleRecord = useCallback(() => {
+    if (state.status === 'idle') {
+      start()
+    }
+  }, [state.status, start])
+
+  const handleStop = useCallback(() => {
+    if (state.status === 'recording') {
+      stop().catch(() => {})
+    }
+  }, [state.status, stop])
+
+  const handleCancel = useCallback(() => {
+    if (state.status === 'recording') {
+      cancel().catch(() => {})
+    }
+  }, [state.status, cancel])
+
+  const handleDevices = useCallback(() => {
+    if (state.status === 'idle') {
+      setMode('devices')
+    }
+  }, [state.status])
+
+  const handleModel = useCallback(() => {
+    if (state.status === 'idle') {
+      setMode('model')
+    }
+  }, [state.status])
+
+  const handleDeviceSelect = useCallback(
+    (device: string) => {
+      setMic(device)
+      addLog(`Input device: ${device}`, 'success')
+      setMode('main')
+    },
+    [addLog],
+  )
+
+  const handleModelSelect = useCallback(
+    (name: string) => {
+      setModel(name)
+      addLog(`Model: ${name}`, 'success')
+      setMode('main')
+    },
+    [addLog],
+  )
+
+  const handleMenuClose = useCallback(() => {
+    setMode('main')
+  }, [])
+
+  const isTerminal = state.status === 'stopped' || state.status === 'cancelled' || state.status === 'error'
+
+  useKeyHandler({
+    enabled: mode === 'main',
+    onRecord: handleRecord,
+    onStop: handleStop,
+    onCancel: handleCancel,
+    onQuit: handleQuit,
+    onDevices: handleDevices,
+    onModel: handleModel,
+    onAnyKey: isTerminal ? handleQuit : undefined,
+  })
+
+  const hintMode = useMemo(() => {
+    if (mode !== 'main') return 'menu'
+    if (state.status === 'idle') return 'idle'
+    if (state.status === 'recording') return 'recording'
+    if (state.status === 'stopped') return 'stopped'
+    if (state.status === 'cancelled') return 'cancelled'
+    return 'error'
+  }, [mode, state.status])
+
+  const devicesLoader = useCallback(
+    () => (listDevicesFn ?? (() => listDevices(lincolnRecordPath)))(),
+    [listDevicesFn, lincolnRecordPath],
+  )
+
+  const modelsLoader = useCallback(
+    () => (listModelStatusesFn ?? (() => Promise.resolve(listModelStatuses(defaultModelCacheDir()))))(),
+    [listModelStatusesFn],
+  )
+
+  const warmupRunner = useCallback(
+    (name: string, onProgress: (p: WarmupProgress) => void) =>
+      runWarmupFn
+        ? runWarmupFn(name, onProgress)
+        : runWarmup({ model: name, lincolnRecordPath, onProgress }),
+    [runWarmupFn, lincolnRecordPath],
+  )
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="gray" height={24}>
+      <StatusPanel
+        sessionId={sessionId}
+        topic={topic}
+        designId={designId}
+        branch={branch}
+        status={state.status}
+        duration={state.duration}
+      />
+      {mode === 'devices' && (
+        <DevicesMenu
+          listDevicesFn={devicesLoader}
+          onSelect={handleDeviceSelect}
+          onClose={handleMenuClose}
+        />
+      )}
+      {mode === 'model' && (
+        <ModelMenu
+          listModelStatusesFn={modelsLoader}
+          runWarmupFn={warmupRunner}
+          onSelect={handleModelSelect}
+          onClose={handleMenuClose}
+        />
+      )}
+      <LogView logs={logs} />
+      <Box flexGrow={1} />
+      <HintBar mode={hintMode} />
+    </Box>
+  )
+}