@alumbwe/anvil 1.0.0

package/src/utils/__tests__/osc-timeout-scenarios.test.ts

@@ -0,0 +1,172 @@
+import { describe, test, expect } from 'bun:test'
+
+import {
+  withTimeout,
+  getGlobalOscTimeout,
+  getQueryOscTimeout,
+} from '../terminal-color-detection'
+
+/**
+ * These tests document the timeout scenarios that could cause users to get stuck.
+ * They verify that the timeout mechanisms work correctly.
+ */
+
+describe('OSC Timeout Protection Scenarios', () => {
+  describe('Scenario 1: Terminal ignores OSC queries entirely', () => {
+    test('withTimeout returns fallback value when promise never resolves', async () => {
+      // Simulate a terminal that ignores the OSC query completely
+      const neverResolvingPromise = new Promise<string>(() => {
+        // This promise never resolves, simulating a non-responsive terminal
+      })
+
+      const startTime = Date.now()
+      const result = await withTimeout(neverResolvingPromise, 100, 'fallback')
+      const elapsed = Date.now() - startTime
+
+      expect(result).toBe('fallback')
+      expect(elapsed).toBeGreaterThanOrEqual(100)
+      expect(elapsed).toBeLessThan(200) // Should not hang
+    })
+
+    test('returns null theme when detection hangs', async () => {
+      const hangingDetection = new Promise<'dark' | 'light' | null>(() => {})
+
+      const result = await withTimeout(hangingDetection, 50, null)
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('Scenario 2: Terminal responds very slowly', () => {
+    test('withTimeout returns fallback for slow responses', async () => {
+      const slowPromise = new Promise<string>((resolve) => {
+        setTimeout(() => resolve('slow-response'), 500)
+      })
+
+      const result = await withTimeout(slowPromise, 100, 'timeout-fallback')
+      expect(result).toBe('timeout-fallback')
+    })
+
+    test('withTimeout returns actual value for responses within timeout', async () => {
+      const fastPromise = new Promise<string>((resolve) => {
+        setTimeout(() => resolve('fast-response'), 10)
+      })
+
+      const result = await withTimeout(fastPromise, 100, 'timeout-fallback')
+      expect(result).toBe('fast-response')
+    })
+  })
+
+  describe('Scenario 3: Timeout hierarchy', () => {
+    test('global timeout is greater than query timeout', () => {
+      const queryTimeout = getQueryOscTimeout()
+      const globalTimeout = getGlobalOscTimeout()
+
+      // Global timeout should be greater than individual query timeout
+      // to allow for retries and cleanup
+      expect(globalTimeout).toBeGreaterThan(queryTimeout)
+    })
+  })
+
+  describe('Scenario 4: Race conditions in cleanup', () => {
+    test('multiple timeouts racing dont cause issues', async () => {
+      // Create multiple promises that might complete at similar times
+      const promises = Array.from({ length: 10 }, (_, i) =>
+        withTimeout(
+          new Promise<number>((resolve) =>
+            setTimeout(() => resolve(i), Math.random() * 100),
+          ),
+          50,
+          -1,
+        ),
+      )
+
+      const results = await Promise.all(promises)
+
+      // All results should be either the resolved value or the timeout value
+      for (const result of results) {
+        expect(typeof result).toBe('number')
+      }
+    })
+
+    test('cleanup happens even on timeout', async () => {
+      // This test verifies that withTimeout properly cleans up its own timeout
+      // even when the underlying promise doesn't resolve
+      const neverResolves = new Promise<string>(() => {
+        // This promise intentionally never resolves
+      })
+
+      // This should timeout and return the fallback value
+      const result = await withTimeout(neverResolves, 50, 'timeout')
+      expect(result).toBe('timeout')
+
+      // Note: withTimeout cleans up its own setTimeout via the finally block
+      // The underlying promise's resources would need to be cleaned up separately
+    })
+  })
+
+  describe('Scenario 5: Subprocess detection safety', () => {
+    test('global timeout is reasonable for user experience', () => {
+      const globalTimeout = getGlobalOscTimeout()
+
+      // Users shouldnt wait more than 3 seconds for theme detection
+      expect(globalTimeout).toBeLessThanOrEqual(3000)
+
+      // But it should be long enough to actually work
+      expect(globalTimeout).toBeGreaterThanOrEqual(1000)
+    })
+
+    test('query timeout allows for network latency in SSH scenarios', () => {
+      const queryTimeout = getQueryOscTimeout()
+
+      // SSH terminals might have up to 200-300ms latency
+      // Query timeout should accommodate this plus some buffer
+      expect(queryTimeout).toBeGreaterThanOrEqual(300)
+    })
+  })
+
+  describe('Scenario 6: Error handling', () => {
+    test('rejected promises propagate through withTimeout', async () => {
+      const rejectingPromise = Promise.reject(new Error('test error'))
+
+      await expect(
+        withTimeout(rejectingPromise, 100, 'fallback'),
+      ).rejects.toThrow('test error')
+    })
+
+    test('timeout value can be any type', async () => {
+      const hangingPromise = new Promise<{ theme: string }>(() => {})
+
+      const objectResult = await withTimeout(hangingPromise, 50, {
+        theme: 'default',
+      })
+      expect(objectResult).toEqual({ theme: 'default' })
+
+      const hangingPromise2 = new Promise<number[]>(() => {})
+      const arrayResult = await withTimeout(hangingPromise2, 50, [1, 2, 3])
+      expect(arrayResult).toEqual([1, 2, 3])
+    })
+  })
+
+  describe('Scenario 7: Stacked timeouts (defense in depth)', () => {
+    test('inner timeout fires before outer timeout', async () => {
+      const innerPromise = new Promise<string>(() => {})
+      const innerResult = withTimeout(innerPromise, 30, 'inner-timeout')
+
+      const outerPromise = withTimeout(innerResult, 100, 'outer-timeout')
+
+      const result = await outerPromise
+      // Inner timeout should fire first
+      expect(result).toBe('inner-timeout')
+    })
+
+    test('outer timeout catches if inner timeout fails', async () => {
+      // Simulate a case where inner timeout mechanism fails
+      const brokenInnerPromise = new Promise<string>(() => {
+        // This never resolves, simulating broken inner timeout
+      })
+
+      const result = await withTimeout(brokenInnerPromise, 50, 'outer-saved-us')
+      expect(result).toBe('outer-saved-us')
+    })
+  })
+})

package/src/utils/__tests__/pending-attachments.test.ts

@@ -0,0 +1,277 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+
+import { useChatStore } from '../../state/chat-store'
+import type { PendingImageAttachment } from '../../types/store'
+import {
+  addClipboardPlaceholder,
+  addPendingImageFromBase64,
+  addPendingImageWithError,
+  capturePendingAttachments,
+} from '../pending-attachments'
+
+/** Helper to get only image attachments from the unified pendingAttachments array */
+function getPendingImages(): PendingImageAttachment[] {
+  return useChatStore
+    .getState()
+    .pendingAttachments.filter(
+      (att): att is PendingImageAttachment => att.kind === 'image',
+    )
+}
+
+describe('pending-attachments', () => {
+  beforeEach(() => {
+    // Reset the store before each test
+    useChatStore.getState().clearPendingAttachments()
+  })
+
+  afterEach(() => {
+    useChatStore.getState().clearPendingAttachments()
+  })
+
+  describe('addClipboardPlaceholder', () => {
+    test('creates placeholder with processing status', () => {
+      const placeholderPath = addClipboardPlaceholder()
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(1)
+      expect(pendingImages[0].path).toBe(placeholderPath)
+      expect(pendingImages[0].status).toBe('processing')
+      expect(pendingImages[0].filename).toBe('clipboard image')
+    })
+
+    test('generates unique placeholder paths', () => {
+      const path1 = addClipboardPlaceholder()
+      const path2 = addClipboardPlaceholder()
+
+      expect(path1).not.toBe(path2)
+      expect(path1).toContain('clipboard:pending-')
+      expect(path2).toContain('clipboard:pending-')
+    })
+
+    test('multiple placeholders coexist in store', () => {
+      addClipboardPlaceholder()
+      addClipboardPlaceholder()
+      addClipboardPlaceholder()
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(3)
+      expect(pendingImages.every((img) => img.status === 'processing')).toBe(
+        true,
+      )
+    })
+  })
+
+  describe('addPendingImageFromBase64', () => {
+    test('adds image with ready status', async () => {
+      await addPendingImageFromBase64(
+        'base64data',
+        'image/png',
+        'test.png',
+        '/tmp/test.png',
+      )
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(1)
+      expect(pendingImages[0].status).toBe('ready')
+      expect(pendingImages[0].filename).toBe('test.png')
+      expect(pendingImages[0].processedImage?.base64).toBe('base64data')
+      expect(pendingImages[0].processedImage?.mediaType).toBe('image/png')
+    })
+
+    test('uses clipboard path when tempPath not provided', async () => {
+      await addPendingImageFromBase64('base64data', 'image/png', 'test.png')
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages[0].path).toBe('clipboard:test.png')
+    })
+
+    test('calculates approximate size from base64', async () => {
+      const base64Data = 'a'.repeat(1000) // 1000 base64 chars
+      await addPendingImageFromBase64(base64Data, 'image/png', 'test.png')
+
+      const pendingImages = getPendingImages()
+      // Size should be approximately 750 bytes (3/4 of 1000)
+      expect(pendingImages[0].size).toBe(750)
+    })
+  })
+
+  describe('addPendingImageWithError', () => {
+    test('adds image with error status', () => {
+      addPendingImageWithError('/path/to/image.png', '❌ file not found')
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(1)
+      expect(pendingImages[0].status).toBe('error')
+      expect(pendingImages[0].note).toBe('❌ file not found')
+      expect(pendingImages[0].filename).toBe('image.png')
+    })
+  })
+
+  describe('capturePendingAttachments', () => {
+    test('returns and clears all pending attachments', () => {
+      addClipboardPlaceholder()
+      addClipboardPlaceholder()
+
+      expect(getPendingImages()).toHaveLength(2)
+
+      const captured = capturePendingAttachments()
+
+      expect(captured).toHaveLength(2)
+      expect(getPendingImages()).toHaveLength(0)
+    })
+
+    test('returns empty array when no pending attachments', () => {
+      const captured = capturePendingAttachments()
+      expect(captured).toHaveLength(0)
+    })
+  })
+
+  describe('placeholder replacement flow', () => {
+    test('placeholder can be updated via setState', () => {
+      const placeholderPath = addClipboardPlaceholder()
+
+      // Simulate what addPendingImageFromFile does when replacing placeholder
+      useChatStore.setState((state) => ({
+        pendingAttachments: state.pendingAttachments.map((att) =>
+          att.kind === 'image' && att.path === placeholderPath
+            ? { ...att, path: '/real/path.png', filename: 'screenshot.png' }
+            : att,
+        ),
+      }))
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(1)
+      expect(pendingImages[0].path).toBe('/real/path.png')
+      expect(pendingImages[0].filename).toBe('screenshot.png')
+      expect(pendingImages[0].status).toBe('processing') // Still processing
+    })
+
+    test('status transitions from processing to ready', () => {
+      const placeholderPath = addClipboardPlaceholder()
+
+      // Simulate processing completion
+      useChatStore.setState((state) => ({
+        pendingAttachments: state.pendingAttachments.map((att) =>
+          att.kind === 'image' && att.path === placeholderPath
+            ? {
+                ...att,
+                status: 'ready' as const,
+                processedImage: { base64: 'data', mediaType: 'image/png' },
+              }
+            : att,
+        ),
+      }))
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages[0].status).toBe('ready')
+      expect(pendingImages[0].processedImage).toBeDefined()
+    })
+
+    test('status transitions from processing to error', () => {
+      const placeholderPath = addClipboardPlaceholder()
+
+      // Simulate processing failure
+      useChatStore.setState((state) => ({
+        pendingAttachments: state.pendingAttachments.map((att) =>
+          att.kind === 'image' && att.path === placeholderPath
+            ? { ...att, status: 'error' as const, note: 'Processing failed' }
+            : att,
+        ),
+      }))
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages[0].status).toBe('error')
+      expect(pendingImages[0].note).toBe('Processing failed')
+    })
+  })
+
+  describe('mixed status scenarios', () => {
+    test('can have images in different states simultaneously', async () => {
+      // Add a processing placeholder
+      const placeholder = addClipboardPlaceholder()
+
+      // Add a ready image
+      await addPendingImageFromBase64(
+        'data',
+        'image/png',
+        'ready.png',
+        '/ready.png',
+      )
+
+      // Add an error image
+      addPendingImageWithError('/error.png', '❌ error')
+
+      const pendingImages = getPendingImages()
+      expect(pendingImages).toHaveLength(3)
+
+      const processing = pendingImages.find((img) => img.path === placeholder)
+      const ready = pendingImages.find((img) => img.path === '/ready.png')
+      const error = pendingImages.find((img) => img.path === '/error.png')
+
+      expect(processing?.status).toBe('processing')
+      expect(ready?.status).toBe('ready')
+      expect(error?.status).toBe('error')
+    })
+
+    test('counting by status works correctly', () => {
+      // Add 2 processing, 3 ready, 1 error
+      addClipboardPlaceholder()
+      addClipboardPlaceholder()
+
+      useChatStore.getState().addPendingImage({
+        path: '/ready1.png',
+        filename: 'ready1.png',
+        status: 'ready',
+      })
+      useChatStore.getState().addPendingImage({
+        path: '/ready2.png',
+        filename: 'ready2.png',
+        status: 'ready',
+      })
+      useChatStore.getState().addPendingImage({
+        path: '/ready3.png',
+        filename: 'ready3.png',
+        status: 'ready',
+      })
+
+      addPendingImageWithError('/error.png', '❌ error')
+
+      const pendingImages = getPendingImages()
+      const processingCount = pendingImages.filter(
+        (img) => img.status === 'processing',
+      ).length
+      const readyCount = pendingImages.filter(
+        (img) => img.status === 'ready',
+      ).length
+      const errorCount = pendingImages.filter(
+        (img) => img.status === 'error',
+      ).length
+
+      expect(processingCount).toBe(2)
+      expect(readyCount).toBe(3)
+      expect(errorCount).toBe(1)
+    })
+  })
+
+  describe('removePendingImage', () => {
+    test('removes placeholder by path', () => {
+      const placeholderPath = addClipboardPlaceholder()
+      expect(getPendingImages()).toHaveLength(1)
+
+      useChatStore.getState().removePendingImage(placeholderPath)
+      expect(getPendingImages()).toHaveLength(0)
+    })
+
+    test('only removes matching path', () => {
+      const path1 = addClipboardPlaceholder()
+      const path2 = addClipboardPlaceholder()
+      expect(getPendingImages()).toHaveLength(2)
+
+      useChatStore.getState().removePendingImage(path1)
+
+      const remaining = getPendingImages()
+      expect(remaining).toHaveLength(1)
+      expect(remaining[0].path).toBe(path2)
+    })
+  })
+})

package/src/utils/__tests__/polling-backoff.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test'
+
+import { failedPollDelayMs, jitterPollIntervalMs } from '../polling-backoff'
+
+describe('polling backoff', () => {
+  test('uses capped exponential windows with equal jitter', () => {
+    const delay = (failures: number, random: number) =>
+      failedPollDelayMs({
+        consecutiveFailures: failures,
+        random: () => random,
+      })
+
+    expect(delay(1, 0)).toBe(10_000)
+    expect(delay(1, 1)).toBe(20_000)
+    expect(delay(2, 0)).toBe(20_000)
+    expect(delay(3, 1)).toBe(80_000)
+    expect(delay(20, 0)).toBe(150_000)
+    expect(delay(20, 1)).toBe(300_000)
+  })
+
+  test('jitters successful poll cadences around the requested interval', () => {
+    expect(jitterPollIntervalMs({ intervalMs: 30_000, random: () => 0 })).toBe(
+      24_000,
+    )
+    expect(
+      jitterPollIntervalMs({ intervalMs: 30_000, random: () => 0.5 }),
+    ).toBe(30_000)
+    expect(jitterPollIntervalMs({ intervalMs: 30_000, random: () => 1 })).toBe(
+      36_000,
+    )
+  })
+
+  test('never schedules before a server Retry-After floor', () => {
+    const delay = (random: number) =>
+      failedPollDelayMs({
+        consecutiveFailures: 1,
+        retryAfterMs: 30_000,
+        random: () => random,
+      })
+
+    expect(delay(0)).toBe(30_000)
+    expect(delay(1)).toBe(36_000)
+    expect(
+      failedPollDelayMs({
+        consecutiveFailures: 1,
+        retryAfterMs: Number.MAX_VALUE,
+        random: () => 1,
+      }),
+    ).toBe(300_000)
+  })
+})

package/src/utils/__tests__/queue-panel-actions.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from 'bun:test'
+
+import {
+  resolveChatKeyboardAction,
+  createDefaultChatKeyboardState,
+} from '../keyboard-actions'
+import { resolveQueuePanelAction } from '../queue-panel-actions'
+
+import type { KeyEvent } from '@opentui/core'
+
+const createKey = (overrides: Partial<KeyEvent> = {}): KeyEvent =>
+  ({
+    name: '',
+    sequence: '',
+    ctrl: false,
+    meta: false,
+    shift: false,
+    option: false,
+    ...overrides,
+  }) as KeyEvent
+
+const browsing = { editing: false }
+const editing = { editing: true }
+
+describe('resolveQueuePanelAction', () => {
+  test('arrows move the selection, modified arrows move the message', () => {
+    expect(resolveQueuePanelAction(createKey({ name: 'up' }), browsing)).toEqual({
+      type: 'select',
+      delta: -1,
+    })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'down' }), browsing),
+    ).toEqual({ type: 'select', delta: 1 })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'up', shift: true }), browsing),
+    ).toEqual({ type: 'move', delta: -1 })
+    expect(
+      resolveQueuePanelAction(
+        createKey({ name: 'down', ctrl: true }),
+        browsing,
+      ),
+    ).toEqual({ type: 'move', delta: 1 })
+  })
+
+  test('shift+J/K reorder for terminals that swallow modified arrows', () => {
+    expect(
+      resolveQueuePanelAction(
+        createKey({ name: 'k', shift: true, sequence: 'K' }),
+        browsing,
+      ),
+    ).toEqual({ type: 'move', delta: -1 })
+    expect(
+      resolveQueuePanelAction(
+        createKey({ name: 'j', shift: true, sequence: 'J' }),
+        browsing,
+      ),
+    ).toEqual({ type: 'move', delta: 1 })
+    // Their unshifted twins still only move the cursor.
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'k', sequence: 'k' }), browsing),
+    ).toEqual({ type: 'select', delta: -1 })
+  })
+
+  test('edit, delete, promote, and close', () => {
+    expect(resolveQueuePanelAction(createKey({ name: 'e' }), browsing)).toEqual({
+      type: 'edit',
+    })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'return' }), browsing),
+    ).toEqual({ type: 'edit' })
+    expect(resolveQueuePanelAction(createKey({ name: 'd' }), browsing)).toEqual({
+      type: 'delete',
+    })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'backspace' }), browsing),
+    ).toEqual({ type: 'delete' })
+    expect(resolveQueuePanelAction(createKey({ name: 't' }), browsing)).toEqual({
+      type: 'move-to-top',
+    })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'escape' }), browsing),
+    ).toEqual({ type: 'close' })
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'c', ctrl: true }), browsing),
+    ).toEqual({ type: 'close' })
+  })
+
+  test('while editing, only the exits are the panel’s — the rest is typing', () => {
+    expect(resolveQueuePanelAction(createKey({ name: 'escape' }), editing)).toEqual(
+      { type: 'cancel-edit' },
+    )
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'c', ctrl: true }), editing),
+    ).toEqual({ type: 'cancel-edit' })
+
+    // Every shortcut letter has to reach the text input instead.
+    for (const name of ['d', 'e', 'q', 't', 'j', 'k']) {
+      expect(resolveQueuePanelAction(createKey({ name }), editing)).toEqual({
+        type: 'none',
+      })
+    }
+    expect(
+      resolveQueuePanelAction(createKey({ name: 'backspace' }), editing),
+    ).toEqual({ type: 'none' })
+    expect(resolveQueuePanelAction(createKey({ name: 'up' }), editing)).toEqual({
+      type: 'none',
+    })
+  })
+})
+
+describe('ctrl+q opens the queue editor', () => {
+  const ctrlQ = createKey({ name: 'q', ctrl: true })
+
+  test('opens when something is queued', () => {
+    expect(
+      resolveChatKeyboardAction(ctrlQ, {
+        ...createDefaultChatKeyboardState(),
+        queuedCount: 2,
+      }),
+    ).toEqual({ type: 'open-queue-panel' })
+  })
+
+  test('does nothing on an empty queue', () => {
+    expect(
+      resolveChatKeyboardAction(ctrlQ, createDefaultChatKeyboardState()),
+    ).toEqual({ type: 'none' })
+  })
+
+  test('still opens with a half-typed message in the composer', () => {
+    expect(
+      resolveChatKeyboardAction(ctrlQ, {
+        ...createDefaultChatKeyboardState(),
+        inputValue: 'and another thing',
+        cursorPosition: 17,
+        queuedCount: 1,
+      }),
+    ).toEqual({ type: 'open-queue-panel' })
+  })
+
+  test('a bare q is not a shortcut', () => {
+    expect(
+      resolveChatKeyboardAction(createKey({ name: 'q', sequence: 'q' }), {
+        ...createDefaultChatKeyboardState(),
+        queuedCount: 2,
+      }),
+    ).toEqual({ type: 'none' })
+  })
+})