@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/tools/lincoln/src/recording/spawnRecorder.ts

@@ -0,0 +1,127 @@
+import { spawn, type ChildProcessByStdio } from 'node:child_process'
+import { type Readable, type Writable } from 'node:stream'
+import { EventEmitter } from 'node:events'
+
+export interface SpawnRecorderOptions {
+  workspaceRoot: string
+  sessionId: string
+  lincolnRecordPath?: string
+  mic?: string | null
+  model?: string | null
+}
+
+export interface RecorderProcess {
+  on(event: 'ready', listener: () => void): this
+  on(event: 'error', listener: (error: Error) => void): this
+  on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this
+  stop(): Promise<void>
+  cancel(): Promise<void>
+}
+
+class RecorderProcessImpl extends EventEmitter implements RecorderProcess {
+  private child: ChildProcessByStdio<Writable, Readable, Readable>
+  private stopped = false
+  private exitPromise: Promise<void>
+  private resolveExit: () => void = () => {}
+  private exitSettled = false
+
+  constructor(child: ChildProcessByStdio<Writable, Readable, Readable>) {
+    super()
+    this.child = child
+    this.exitPromise = new Promise((resolve) => {
+      this.resolveExit = resolve
+    })
+
+    this.child.on('error', (error) => {
+      this.emit('error', error)
+      this.settleExit()
+    })
+
+    this.child.on('exit', (code, signal) => {
+      this.emit('exit', code, signal)
+      this.settleExit()
+    })
+
+    this.child.stdout.on('data', (data: Buffer) => {
+      process.stdout.write(data)
+    })
+
+    this.child.stderr.on('data', (data: Buffer) => {
+      process.stderr.write(data)
+    })
+
+    // lincoln-record begins capturing immediately; treat it as ready.
+    process.nextTick(() => this.emit('ready'))
+  }
+
+  private settleExit(): void {
+    if (!this.exitSettled) {
+      this.exitSettled = true
+      this.resolveExit()
+    }
+  }
+
+  stop(): Promise<void> {
+    return this._terminate('SIGINT')
+  }
+
+  cancel(): Promise<void> {
+    return this._terminate('SIGKILL')
+  }
+
+  private _terminate(signal: NodeJS.Signals): Promise<void> {
+    if (this.stopped) {
+      return this.exitPromise
+    }
+    this.stopped = true
+
+    if (this.child.killed) {
+      return this.exitPromise
+    }
+
+    this.child.kill(signal)
+
+    const timeout = setTimeout(() => {
+      if (!this.child.killed) {
+        this.child.kill('SIGKILL')
+      }
+    }, 5000)
+
+    this.exitPromise.finally(() => clearTimeout(timeout))
+
+    return this.exitPromise
+  }
+}
+
+export function spawnRecorder(options: SpawnRecorderOptions): RecorderProcess {
+  const {
+    workspaceRoot,
+    sessionId,
+    lincolnRecordPath = 'lincoln-record',
+    mic,
+    model,
+  } = options
+
+  const args: string[] = [
+    'record',
+    '--session-id',
+    sessionId,
+    '--output',
+    workspaceRoot,
+  ]
+
+  if (mic) {
+    args.push('--mic', mic)
+  }
+
+  if (model) {
+    args.push('--model', model)
+  }
+
+  const child = spawn(lincolnRecordPath, args, {
+    cwd: workspaceRoot,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+
+  return new RecorderProcessImpl(child)
+}

package/framework/tools/lincoln/src/recording/useRecorder.ts

@@ -0,0 +1,146 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { spawnRecorder, type RecorderProcess, type SpawnRecorderOptions } from './spawnRecorder'
+
+export interface UseRecorderOptions extends SpawnRecorderOptions {
+  startOnMount?: boolean
+}
+
+export interface RecorderState {
+  status: 'idle' | 'recording' | 'stopped' | 'cancelled' | 'error'
+  duration: number
+  amplitude: number
+  errorMessage: string | null
+}
+
+export interface RecorderController {
+  state: RecorderState
+  start: () => void
+  stop: () => Promise<void>
+  cancel: () => Promise<void>
+}
+
+function mockAmplitude(duration: number): number {
+  return 0.5 + 0.4 * Math.sin(duration * 0.8)
+}
+
+export function useRecorder(options: UseRecorderOptions): RecorderController {
+  const {
+    startOnMount = false,
+    workspaceRoot,
+    sessionId,
+    lincolnRecordPath,
+    mic,
+    model,
+  } = options
+  const [state, setState] = useState<RecorderState>({
+    status: 'idle',
+    duration: 0,
+    amplitude: 0,
+    errorMessage: null,
+  })
+
+  const recorderRef = useRef<RecorderProcess | null>(null)
+  const intervalRef = useRef<NodeJS.Timeout | null>(null)
+  const durationRef = useRef(0)
+  const terminatingRef = useRef(false)
+
+  const clearRecordingInterval = useCallback(() => {
+    if (intervalRef.current) {
+      clearInterval(intervalRef.current)
+      intervalRef.current = null
+    }
+  }, [])
+
+  const start = useCallback(() => {
+    if (recorderRef.current) {
+      return
+    }
+
+    terminatingRef.current = false
+    setState({ status: 'recording', duration: 0, amplitude: 0.3, errorMessage: null })
+    durationRef.current = 0
+
+    try {
+      const recorder = spawnRecorder({
+        workspaceRoot,
+        sessionId,
+        lincolnRecordPath,
+        mic,
+        model,
+      })
+      recorderRef.current = recorder
+
+      recorder.on('ready', () => {
+        // Recording is active
+      })
+
+      recorder.on('error', error => {
+        setState(s => ({ ...s, status: 'error', errorMessage: error.message }))
+        clearRecordingInterval()
+      })
+
+      recorder.on('exit', (code, signal) => {
+        recorderRef.current = null
+        clearRecordingInterval()
+
+        if (terminatingRef.current) {
+          return
+        }
+
+        const reason = code !== null && code !== undefined
+          ? `lincoln-record exited unexpectedly with code ${code}`
+          : `lincoln-record exited unexpectedly with signal ${signal}`
+        setState(s => ({ ...s, status: 'error', errorMessage: reason }))
+      })
+
+      intervalRef.current = setInterval(() => {
+        durationRef.current += 1
+        setState(s => ({
+          ...s,
+          duration: durationRef.current,
+          amplitude: mockAmplitude(durationRef.current),
+        }))
+      }, 1000)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      setState(s => ({ ...s, status: 'error', errorMessage: message }))
+    }
+  }, [workspaceRoot, sessionId, lincolnRecordPath, mic, model, clearRecordingInterval])
+
+  const stop = useCallback(async () => {
+    const recorder = recorderRef.current
+    if (!recorder) return
+
+    terminatingRef.current = true
+    clearRecordingInterval()
+    setState(s => ({ ...s, status: 'stopped' }))
+    await recorder.stop()
+  }, [clearRecordingInterval])
+
+  const cancel = useCallback(async () => {
+    const recorder = recorderRef.current
+    if (!recorder) return
+
+    terminatingRef.current = true
+    clearRecordingInterval()
+    setState(s => ({ ...s, status: 'cancelled' }))
+    await recorder.cancel()
+  }, [clearRecordingInterval])
+
+  useEffect(() => {
+    if (startOnMount) {
+      start()
+    }
+
+    return () => {
+      clearRecordingInterval()
+      if (recorderRef.current) {
+        recorderRef.current.cancel().catch(() => {})
+        recorderRef.current = null
+      }
+    }
+  }, [startOnMount, start, clearRecordingInterval])
+
+  return { state, start, stop, cancel }
+}

package/framework/tools/lincoln/src/utils/amplitudeToMeter.ts

@@ -0,0 +1,4 @@
+export function amplitudeToMeter(amplitude: number, maxBars: number): number {
+  const clamped = Math.max(0, Math.min(1, amplitude))
+  return Math.round(clamped * maxBars)
+}

package/framework/tools/lincoln/src/utils/formatDuration.ts

@@ -0,0 +1,6 @@
+export function formatDuration(totalSeconds: number): string {
+  const safeSeconds = Math.max(0, Math.floor(totalSeconds))
+  const minutes = Math.floor(safeSeconds / 60)
+  const seconds = safeSeconds % 60
+  return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`
+}

package/framework/tools/lincoln/src/utils/sessionId.ts

@@ -0,0 +1,25 @@
+export interface GenerateSessionIdOptions {
+  now?: Date
+  descriptor?: string
+}
+
+export function generateSessionId(options: GenerateSessionIdOptions = {}): string {
+  const now = options.now ?? new Date()
+  const date = now.toISOString().slice(0, 10)
+  const slug = normalizeDescriptor(options.descriptor)
+  return `${date}-${slug}`
+}
+
+function normalizeDescriptor(descriptor: string | undefined): string {
+  if (!descriptor) {
+    return 'recording'
+  }
+
+  const normalized = descriptor
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9一-龥]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized.slice(0, 80) || 'recording'
+}

package/framework/tools/lincoln/tests/cli.test.tsx

@@ -0,0 +1,52 @@
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { describe, expect, test, vi } from 'vitest'
+import { App } from '../src/cli'
+
+vi.mock('../src/recording/useRecorder', () => ({
+  useRecorder: vi.fn(() => ({
+    state: { status: 'recording', duration: 0, amplitude: 0.3, errorMessage: null },
+    start: vi.fn(),
+    stop: vi.fn(),
+    cancel: vi.fn(),
+  })),
+}))
+
+const baseConfig = {
+  workspaceRoot: '/workspace',
+  topic: '',
+  designId: '',
+  branch: '',
+  sessionId: '2026-06-28-test',
+  noTui: false,
+  autoProcess: false,
+  showAudioMeter: true,
+  audioMeterStyle: 'bar' as const,
+}
+
+describe('App', () => {
+  test('renders help when help arg is true', () => {
+    const { lastFrame } = render(<App args={{ help: true, noTui: false }} config={baseConfig} />,
+    )
+
+    expect(lastFrame()).toContain('Usage:')
+  })
+
+  test('renders recording app when help is false', () => {
+    const { lastFrame } = render(
+      <App
+        args={{ help: false, noTui: false }}
+        config={{
+          ...baseConfig,
+          topic: '测试',
+          designId: 'test-design',
+          branch: 'main',
+        }}
+      />,
+    )
+
+    expect(lastFrame()).toContain('Lincoln Recorder')
+    expect(lastFrame()).toContain('2026-06-28-test')
+    expect(lastFrame()).toContain('测试')
+  })
+})

package/framework/tools/lincoln/tests/components/AudioMeter.test.tsx

@@ -0,0 +1,31 @@
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { describe, expect, test } from 'vitest'
+import { AudioMeter } from '../../src/components/AudioMeter'
+
+describe('AudioMeter', () => {
+  test('renders bar style with correct number of blocks', () => {
+    const { lastFrame } = render(<AudioMeter amplitude={0.5} style="bar" />)
+
+    expect(lastFrame()).toContain('█')
+    expect(lastFrame()?.length).toBeGreaterThan(0)
+  })
+
+  test('renders dot style', () => {
+    const { lastFrame } = render(<AudioMeter amplitude={0.5} style="dot" />)
+
+    expect(lastFrame()).toContain('●')
+  })
+
+  test('renders wave style', () => {
+    const { lastFrame } = render(<AudioMeter amplitude={0.5} style="wave" />)
+
+    expect(lastFrame()).toContain('~')
+  })
+
+  test('renders empty meter for zero amplitude', () => {
+    const { lastFrame } = render(<AudioMeter amplitude={0} style="bar" />)
+
+    expect(lastFrame()).not.toContain('█')
+  })
+})

package/framework/tools/lincoln/tests/components/CancelledScreen.test.tsx

@@ -0,0 +1,12 @@
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { describe, expect, test } from 'vitest'
+import { CancelledScreen } from '../../src/components/CancelledScreen'
+
+describe('CancelledScreen', () => {
+  test('renders cancellation message', () => {
+    const { lastFrame } = render(<CancelledScreen />)
+
+    expect(lastFrame()).toContain('cancelled')
+  })
+})

package/framework/tools/lincoln/tests/components/ReadyScreen.test.tsx

@@ -0,0 +1,68 @@
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { describe, expect, test } from 'vitest'
+import { ReadyScreen } from '../../src/components/ReadyScreen'
+
+describe('ReadyScreen', () => {
+  test('renders title and session info', () => {
+    const { lastFrame } = render(
+      <ReadyScreen
+        sessionId="2026-06-28-test"
+        topic="测试访谈"
+        designId="checkout-redesign"
+        branch="main"
+      />,
+    )
+
+    expect(lastFrame()).toContain('Lincoln Recorder')
+    expect(lastFrame()).toContain('Session: 2026-06-28-test')
+    expect(lastFrame()).toContain('Topic: 测试访谈')
+    expect(lastFrame()).toContain('Design: checkout-redesign')
+    expect(lastFrame()).toContain('Branch: main')
+  })
+
+  test('hides empty optional fields', () => {
+    const { lastFrame } = render(
+      <ReadyScreen
+        sessionId="2026-06-28-test"
+        topic=""
+        designId=""
+        branch=""
+      />,
+    )
+
+    expect(lastFrame()).toContain('Session: 2026-06-28-test')
+    expect(lastFrame()).not.toContain('Topic:')
+    expect(lastFrame()).not.toContain('Design:')
+    expect(lastFrame()).not.toContain('Branch:')
+  })
+
+  test('highlights the selected option', () => {
+    const { lastFrame: selectedLastFrame } = render(
+      <ReadyScreen
+        sessionId="2026-06-28-test"
+        topic=""
+        designId=""
+        branch=""
+        selectedIndex={0}
+      />,
+    )
+
+    expect(selectedLastFrame()).toContain('▸')
+    expect(selectedLastFrame()).toContain('开始录音')
+    expect(selectedLastFrame()).toContain('退出')
+
+    const { lastFrame: exitLastFrame } = render(
+      <ReadyScreen
+        sessionId="2026-06-28-test"
+        topic=""
+        designId=""
+        branch=""
+        selectedIndex={1}
+      />,
+    )
+
+    expect(exitLastFrame()).toContain('▸')
+    expect(exitLastFrame()).toContain('退出')
+  })
+})

package/framework/tools/lincoln/tests/components/RecordingApp.menus.test.tsx

@@ -0,0 +1,158 @@
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { RecordingApp } from '../../src/components/RecordingApp'
+import type { RecorderController, RecorderState } from '../../src/recording/useRecorder'
+import type { ModelStatus } from '../../src/models/models'
+import type { WarmupProgress } from '../../src/models/warmupProgress'
+
+const idleState: RecorderState = {
+  status: 'idle',
+  duration: 0,
+  amplitude: 0,
+  errorMessage: null,
+}
+
+let currentController: RecorderController
+const exitMock = vi.fn()
+
+vi.mock('ink', async () => {
+  const actual = await vi.importActual<typeof import('ink')>('ink')
+  return {
+    ...actual,
+    useApp: () => ({ exit: exitMock }),
+  }
+})
+
+vi.mock('../../src/recording/useRecorder', () => ({
+  useRecorder: vi.fn(() => currentController),
+}))
+
+async function tick(ms = 0) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+const modelStatuses: ModelStatus[] = [
+  { name: 'tiny', cached: false },
+  { name: 'base', cached: true },
+]
+
+function renderApp(extraProps: Record<string, unknown> = {}) {
+  return render(
+    <RecordingApp
+      workspaceRoot="/workspace"
+      sessionId="2026-06-28-test"
+      topic=""
+      designId=""
+      branch=""
+      audioMeterStyle="bar"
+      listDevicesFn={async () => ({
+        defaultDevice: 'MacBook Pro Microphone',
+        devices: ['MacBook Pro Microphone', 'External Mic'],
+      })}
+      listModelStatusesFn={async () => modelStatuses}
+      runWarmupFn={async () => '/cache/whisper/ggml-tiny.bin'}
+      {...extraProps}
+    />,
+  )
+}
+
+describe('RecordingApp menus', () => {
+  beforeEach(() => {
+    currentController = {
+      state: { ...idleState },
+      start: vi.fn(),
+      stop: vi.fn(() => Promise.resolve()),
+      cancel: vi.fn(() => Promise.resolve()),
+    }
+    exitMock.mockClear()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('opens the devices menu when d is pressed and selects a device', async () => {
+    const { lastFrame, stdin } = renderApp()
+
+    await tick()
+    stdin.write('d')
+    await tick(10)
+
+    expect(lastFrame()).toContain('Devices')
+    expect(lastFrame()).toContain('MacBook Pro Microphone')
+    expect(lastFrame()).toContain('External Mic')
+
+    stdin.write('')
+    await tick()
+    stdin.write('\r')
+    await tick()
+
+    expect(lastFrame()).toContain('Input device: External Mic')
+    expect(lastFrame()).toContain('[r] record')
+  })
+
+  test('closes the devices menu on escape without selecting', async () => {
+    const { lastFrame, stdin } = renderApp()
+
+    await tick()
+    stdin.write('d')
+    await tick(10)
+    stdin.write('')
+    await tick()
+
+    expect(lastFrame()).not.toContain('› MacBook')
+    expect(lastFrame()).toContain('[r] record')
+  })
+
+  test('opens the model menu when m is pressed and selects a cached model', async () => {
+    const { lastFrame, stdin } = renderApp()
+
+    await tick()
+    stdin.write('m')
+    await tick(10)
+
+    expect(lastFrame()).toContain('Model')
+    expect(lastFrame()).toContain('base')
+
+    stdin.write('')
+    await tick()
+    stdin.write('\r')
+    await tick()
+
+    expect(lastFrame()).toContain('Model: base')
+  })
+
+  test('runs warmup with progress when selecting an uncached model', async () => {
+    const runWarmupFn = vi.fn(
+      async (_model: string, onProgress: (p: WarmupProgress) => void) => {
+        onProgress({ downloaded: 50, total: 100, percent: 50 })
+        return '/cache/whisper/ggml-tiny.bin'
+      },
+    )
+    const { lastFrame, stdin } = renderApp({ runWarmupFn })
+
+    await tick()
+    stdin.write('m')
+    await tick(10)
+
+    // tiny is the first item and is not cached
+    stdin.write('\r')
+    await tick(10)
+
+    expect(runWarmupFn).toHaveBeenCalledWith('tiny', expect.any(Function))
+    expect(lastFrame()).toContain('Model: tiny')
+  })
+
+  test('does not quit with q while a menu is open', async () => {
+    const { stdin } = renderApp()
+
+    await tick()
+    stdin.write('d')
+    await tick(10)
+    stdin.write('q')
+    await tick()
+
+    expect(exitMock).not.toHaveBeenCalled()
+  })
+})