@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/tools/lincoln/tests/hooks/useKeyHandler.test.tsx

@@ -0,0 +1,130 @@
+import { Text } from 'ink'
+import { render } from 'ink-testing-library'
+import React from 'react'
+import { describe, expect, test, vi } from 'vitest'
+import { useKeyHandler } from '../../src/hooks/useKeyHandler'
+
+interface TestComponentProps {
+  onRecord?: () => void
+  onStop?: () => void
+  onCancel?: () => void
+  onQuit?: () => void
+  onDevices?: () => void
+  onModel?: () => void
+  onAnyKey?: () => void
+}
+
+function TestComponent(props: TestComponentProps) {
+  useKeyHandler(props)
+  return <Text>handlers active</Text>
+}
+
+async function tick() {
+  return new Promise(resolve => setTimeout(resolve, 0))
+}
+
+describe('useKeyHandler', () => {
+  test('calls onRecord when r is pressed', async () => {
+    const onRecord = vi.fn()
+    const { stdin } = render(
+      <TestComponent onRecord={onRecord} />,
+    )
+
+    await tick()
+    stdin.write('r')
+    await tick()
+
+    expect(onRecord).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onStop when s is pressed', async () => {
+    const onStop = vi.fn()
+    const { stdin } = render(
+      <TestComponent onStop={onStop} />,
+    )
+
+    await tick()
+    stdin.write('s')
+    await tick()
+
+    expect(onStop).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onCancel when c is pressed', async () => {
+    const onCancel = vi.fn()
+    const { stdin } = render(
+      <TestComponent onCancel={onCancel} />,
+    )
+
+    await tick()
+    stdin.write('c')
+    await tick()
+
+    expect(onCancel).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onQuit when q is pressed', async () => {
+    const onQuit = vi.fn()
+    const { stdin } = render(
+      <TestComponent onQuit={onQuit} />,
+    )
+
+    await tick()
+    stdin.write('q')
+    await tick()
+
+    expect(onQuit).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onQuit when Escape is pressed', async () => {
+    const onQuit = vi.fn()
+    const { stdin } = render(
+      <TestComponent onQuit={onQuit} />,
+    )
+
+    await tick()
+    stdin.write('')
+    await tick()
+
+    expect(onQuit).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onDevices when d is pressed', async () => {
+    const onDevices = vi.fn()
+    const { stdin } = render(
+      <TestComponent onDevices={onDevices} />,
+    )
+
+    await tick()
+    stdin.write('d')
+    await tick()
+
+    expect(onDevices).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onModel when m is pressed', async () => {
+    const onModel = vi.fn()
+    const { stdin } = render(
+      <TestComponent onModel={onModel} />,
+    )
+
+    await tick()
+    stdin.write('m')
+    await tick()
+
+    expect(onModel).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onAnyKey for unrecognized input', async () => {
+    const onAnyKey = vi.fn()
+    const { stdin } = render(
+      <TestComponent onAnyKey={onAnyKey} />,
+    )
+
+    await tick()
+    stdin.write('x')
+    await tick()
+
+    expect(onAnyKey).toHaveBeenCalledTimes(1)
+  })
+})

package/framework/tools/lincoln/tests/models/models.test.ts

@@ -0,0 +1,27 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, test } from 'vitest'
+import { KNOWN_MODELS, listModelStatuses, modelCachePath } from '../../src/models/models'
+
+describe('models', () => {
+  test('KNOWN_MODELS includes common whisper models', () => {
+    expect(KNOWN_MODELS).toContain('tiny')
+    expect(KNOWN_MODELS).toContain('base')
+    expect(KNOWN_MODELS).toContain('large-v3')
+  })
+
+  test('modelCachePath returns the ggml path under the engine dir', () => {
+    expect(modelCachePath('base', '/cache')).toBe('/cache/whisper/ggml-base.bin')
+  })
+
+  test('listModelStatuses marks cached and missing models', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'lincoln-models-'))
+    mkdirSync(join(dir, 'whisper'), { recursive: true })
+    writeFileSync(join(dir, 'whisper', 'ggml-base.bin'), 'fake')
+
+    const statuses = listModelStatuses(dir)
+    expect(statuses.find(s => s.name === 'base')?.cached).toBe(true)
+    expect(statuses.find(s => s.name === 'small')?.cached).toBe(false)
+  })
+})

package/framework/tools/lincoln/tests/models/warmupProgress.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vitest'
+import { parseWarmupProgress } from '../../src/models/warmupProgress'
+
+describe('parseWarmupProgress', () => {
+  test('parses progress with a total', () => {
+    expect(parseWarmupProgress('\r  downloaded 512 / 1024 bytes (50.0%)')).toEqual({
+      downloaded: 512,
+      total: 1024,
+      percent: 50,
+    })
+  })
+
+  test('parses progress without a total', () => {
+    expect(parseWarmupProgress('\r  downloaded 512 bytes')).toEqual({
+      downloaded: 512,
+      total: null,
+      percent: null,
+    })
+  })
+
+  test('returns null for unrelated lines', () => {
+    expect(parseWarmupProgress("Warming up whisper model 'base'")).toBeNull()
+    expect(parseWarmupProgress('Model ready at /tmp/x')).toBeNull()
+  })
+})

package/framework/tools/lincoln/tests/recording/spawnRecorder.test.ts

@@ -0,0 +1,85 @@
+import { EventEmitter } from 'node:events'
+import { describe, expect, test, vi, beforeEach, afterEach } from 'vitest'
+import { spawnRecorder, type RecorderProcess } from '../../src/recording/spawnRecorder'
+
+describe('spawnRecorder', () => {
+  let spawnMock: ReturnType<typeof vi.fn>
+  let child: EventEmitter
+
+  beforeEach(() => {
+    child = new EventEmitter()
+    child.pid = 12345
+    child.kill = vi.fn()
+    child.stdout = new EventEmitter()
+    child.stderr = new EventEmitter()
+    spawnMock = vi.fn(() => child)
+    vi.doMock('node:child_process', () => ({ spawn: spawnMock }))
+  })
+
+  afterEach(() => {
+    vi.doUnmock('node:child_process')
+  })
+
+  test('spawns lincoln-record record with correct args', async () => {
+    const { spawnRecorder: spawnRecorderMocked } = await import('../../src/recording/spawnRecorder')
+    spawnRecorderMocked({
+      workspaceRoot: '/workspace',
+      sessionId: '2026-06-28-test',
+      lincolnRecordPath: '/usr/local/bin/lincoln-record',
+    })
+
+    expect(spawnMock).toHaveBeenCalledWith(
+      '/usr/local/bin/lincoln-record',
+      [
+        'record',
+        '--session-id',
+        '2026-06-28-test',
+        '--output',
+        '/workspace',
+      ],
+      expect.objectContaining({ cwd: '/workspace', stdio: ['pipe', 'pipe', 'pipe'] }),
+    )
+  })
+
+  test('emits ready immediately after spawn', async () => {
+    const { spawnRecorder: spawnRecorderMocked } = await import('../../src/recording/spawnRecorder')
+    const recorder = spawnRecorderMocked({
+      workspaceRoot: '/workspace',
+      sessionId: '2026-06-28-test',
+    })
+
+    const readyHandler = vi.fn()
+    recorder.on('ready', readyHandler)
+
+    await new Promise((resolve) => setImmediate(resolve))
+    expect(readyHandler).toHaveBeenCalled()
+  })
+
+  test('stop sends SIGINT and resolves on exit', async () => {
+    const { spawnRecorder: spawnRecorderMocked } = await import('../../src/recording/spawnRecorder')
+    const recorder = spawnRecorderMocked({
+      workspaceRoot: '/workspace',
+      sessionId: '2026-06-28-test',
+    })
+
+    const stopPromise = recorder.stop()
+    expect(child.kill).toHaveBeenCalledWith('SIGINT')
+    child.emit('exit', 0, null)
+
+    await expect(stopPromise).resolves.toBeUndefined()
+  })
+
+  test('cancel sends SIGKILL and resolves on exit', async () => {
+    const { spawnRecorder: spawnRecorderMocked } = await import('../../src/recording/spawnRecorder')
+    const recorder = spawnRecorderMocked({
+      workspaceRoot: '/workspace',
+      sessionId: '2026-06-28-test',
+    })
+
+    const cancelPromise = recorder.cancel()
+    expect(child.kill).toHaveBeenCalledWith('SIGKILL')
+    child.emit('exit', null, 'SIGTERM')
+
+    await expect(cancelPromise).resolves.toBeUndefined()
+  })
+})

package/framework/tools/lincoln/tests/recording/useRecorder.test.tsx

@@ -0,0 +1,172 @@
+import { Text } from 'ink'
+import { render } from 'ink-testing-library'
+import { EventEmitter } from 'node:events'
+import React, { useEffect } from 'react'
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { useRecorder, type RecorderController } from '../../src/recording/useRecorder'
+import { spawnRecorder as spawnRecorderMock } from '../../src/recording/spawnRecorder'
+
+vi.mock('../../src/recording/spawnRecorder', () => {
+  const { EventEmitter } = require('node:events')
+
+  function createMockRecorder() {
+    const recorder = new EventEmitter()
+    recorder.stop = vi.fn(() => Promise.resolve())
+    recorder.cancel = vi.fn(() => Promise.resolve())
+    return recorder
+  }
+
+  return {
+    spawnRecorder: vi.fn(() => createMockRecorder()),
+  }
+})
+
+function TestApp() {
+  const { state } = useRecorder({
+    workspaceRoot: '/workspace',
+    sessionId: '2026-06-28-test',
+  })
+  return <Text>{state.status}</Text>
+}
+
+function TestAppWithRerender({ startOnMount }: { startOnMount?: boolean } = {}) {
+  const [count, setCount] = React.useState(0)
+  const { state } = useRecorder({
+    workspaceRoot: '/workspace',
+    sessionId: '2026-06-28-test',
+    startOnMount,
+  })
+
+  return <Text>{state.status}:{count}</Text>
+}
+
+describe('useRecorder', () => {
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('starts in idle state', () => {
+    const { lastFrame } = render(<TestApp />)
+
+    expect(lastFrame()).toBe('idle')
+    expect(spawnRecorderMock).not.toHaveBeenCalled()
+  })
+
+  test('does not start recorder by default', async () => {
+    const { lastFrame, rerender } = render(<TestAppWithRerender />)
+
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(lastFrame()).toContain('idle')
+    expect(spawnRecorderMock).not.toHaveBeenCalled()
+
+    rerender(<TestAppWithRerender />)
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    expect(spawnRecorderMock).not.toHaveBeenCalled()
+  })
+
+  test('starts recorder once on mount when startOnMount is true', async () => {
+    const { lastFrame, rerender } = render(
+      <TestAppWithRerender startOnMount={true} />
+    )
+
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(lastFrame()).toContain('recording')
+    expect(spawnRecorderMock).toHaveBeenCalledTimes(1)
+
+    rerender(<TestAppWithRerender startOnMount={true} />)
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    expect(spawnRecorderMock).toHaveBeenCalledTimes(1)
+  })
+
+  test('shows error when recorder exits unexpectedly', async () => {
+    let recorder: EventEmitter | undefined
+    function CaptureRecorder() {
+      const { state } = useRecorder({
+        workspaceRoot: '/workspace',
+        sessionId: '2026-06-28-test',
+        topic: '',
+        designId: '',
+        branch: '',
+        startOnMount: true,
+      })
+      useEffect(() => {
+        recorder = spawnRecorderMock.mock.results[0]?.value
+      }, [])
+      return <Text>{state.status}:{state.errorMessage ?? ''}</Text>
+    }
+
+    const { lastFrame } = render(<CaptureRecorder />)
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(lastFrame()).toContain('recording')
+
+    recorder!.emit('exit', 1, null)
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(lastFrame()).toContain('error')
+    expect(lastFrame()).toContain('exited unexpectedly')
+  })
+
+  test('stays stopped when stop is called and recorder exits with non-zero code', async () => {
+    let controller: RecorderController | null = null
+    let recorder: EventEmitter | undefined
+
+    function StopController() {
+      controller = useRecorder({
+        workspaceRoot: '/workspace',
+        sessionId: '2026-06-28-test',
+        topic: '',
+        designId: '',
+        branch: '',
+        startOnMount: true,
+      })
+      useEffect(() => {
+        recorder = spawnRecorderMock.mock.results[0]?.value
+      }, [])
+      return <Text>{controller.state.status}</Text>
+    }
+
+    const { lastFrame } = render(<StopController />)
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(lastFrame()).toBe('recording')
+
+    const stopPromise = controller!.stop()
+    recorder!.emit('exit', 1, null)
+    await stopPromise
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(lastFrame()).toBe('stopped')
+  })
+
+  test('stays cancelled when cancel is called and recorder exits with non-zero code', async () => {
+    let controller: RecorderController | null = null
+    let recorder: EventEmitter | undefined
+
+    function CancelController() {
+      controller = useRecorder({
+        workspaceRoot: '/workspace',
+        sessionId: '2026-06-28-test',
+        topic: '',
+        designId: '',
+        branch: '',
+        startOnMount: true,
+      })
+      useEffect(() => {
+        recorder = spawnRecorderMock.mock.results[0]?.value
+      }, [])
+      return <Text>{controller.state.status}</Text>
+    }
+
+    const { lastFrame } = render(<CancelController />)
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(lastFrame()).toBe('recording')
+
+    const cancelPromise = controller!.cancel()
+    recorder!.emit('exit', null, 'SIGTERM')
+    await cancelPromise
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(lastFrame()).toBe('cancelled')
+  })
+})

package/framework/tools/lincoln/tests/utils/amplitudeToMeter.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'vitest'
+import { amplitudeToMeter } from '../../src/utils/amplitudeToMeter'
+
+describe('amplitudeToMeter', () => {
+  test('returns 0 bars for zero amplitude', () => {
+    expect(amplitudeToMeter(0, 10)).toBe(0)
+  })
+
+  test('returns max bars for full amplitude', () => {
+    expect(amplitudeToMeter(1, 10)).toBe(10)
+  })
+
+  test('scales linearly between 0 and max', () => {
+    expect(amplitudeToMeter(0.5, 10)).toBe(5)
+    expect(amplitudeToMeter(0.23, 10)).toBe(2)
+  })
+
+  test('clamps out-of-range values', () => {
+    expect(amplitudeToMeter(-0.5, 10)).toBe(0)
+    expect(amplitudeToMeter(1.5, 10)).toBe(10)
+  })
+})

package/framework/tools/lincoln/tests/utils/formatDuration.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, test } from 'vitest'
+import { formatDuration } from '../../src/utils/formatDuration'
+
+describe('formatDuration', () => {
+  test('formats seconds as mm:ss', () => {
+    expect(formatDuration(0)).toBe('00:00')
+    expect(formatDuration(5)).toBe('00:05')
+    expect(formatDuration(83)).toBe('01:23')
+    expect(formatDuration(3661)).toBe('61:01')
+  })
+})

package/framework/tools/lincoln/tests/utils/sessionId.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest'
+import { generateSessionId } from '../../src/utils/sessionId'
+
+describe('generateSessionId', () => {
+  test('uses date and descriptor', () => {
+    const result = generateSessionId({
+      now: new Date('2026-06-28T10:00:00Z'),
+      descriptor: 'stakeholder-checkout',
+    })
+
+    expect(result).toBe('2026-06-28-stakeholder-checkout')
+  })
+
+  test('falls back to recording when no descriptor', () => {
+    const result = generateSessionId({ now: new Date('2026-06-28T10:00:00Z') })
+
+    expect(result).toBe('2026-06-28-recording')
+  })
+
+  test('slugifies descriptors with spaces and special characters', () => {
+    const result = generateSessionId({
+      now: new Date('2026-06-28T10:00:00Z'),
+      descriptor: '结算流程 redesign 需求访谈!',
+    })
+
+    expect(result).toMatch(/^2026-06-28-/)
+    expect(result).not.toContain(' ')
+    expect(result).not.toContain('!')
+  })
+})

package/framework/tools/lincoln/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/framework/tools/lincoln/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "declaration": false,
+    "declarationMap": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}

package/framework/tools/lincoln/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/main.tsx'],
+  outDir: 'dist',
+  format: ['esm'],
+  target: 'node20',
+  platform: 'node',
+  bundle: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  dts: false,
+  esbuildOptions(options) {
+    options.jsx = 'automatic'
+  },
+})

package/framework/tools/lincoln/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  resolve: {
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+      },
+    },
+  },
+})