nastech-tui 0.0.1

package/src/__tests__/forceTruecolor.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from 'vitest'
+
+const ENV_KEYS = ['COLORTERM', 'FORCE_COLOR', 'NASTECH_TUI_TRUECOLOR', 'NO_COLOR', 'TERM', 'TERM_PROGRAM'] as const
+let importId = 0
+
+async function withCleanEnv(setup: () => void, body: () => Promise<void>) {
+  const saved: Record<string, string | undefined> = {}
+
+  for (const k of ENV_KEYS) {
+    saved[k] = process.env[k]
+    delete process.env[k]
+  }
+
+  try {
+    setup()
+    await body()
+  } finally {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) {
+        delete process.env[k]
+      } else {
+        process.env[k] = saved[k]
+      }
+    }
+  }
+}
+
+describe('forceTruecolor', () => {
+  it('does not force truecolor by default', async () => {
+    await withCleanEnv(
+      () => {},
+      async () => {
+        await import('../lib/forceTruecolor.js?t=default-' + importId++)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBeUndefined()
+      }
+    )
+  })
+
+  it('does not infer truecolor from Apple Terminal on pre-Tahoe macOS', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.TERM_PROGRAM = 'Apple_Terminal'
+        process.env.TERM = 'xterm-256color'
+      },
+      async () => {
+        const mod = await import('../lib/forceTruecolor.js?t=apple-' + importId++)
+        expect(mod.shouldForceTruecolor({ TERM_PROGRAM: 'Apple_Terminal' })).toBe(false)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBeUndefined()
+      }
+    )
+  })
+
+  it('downgrades Apple Terminal when truecolor is only advertised by env', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.TERM_PROGRAM = 'Apple_Terminal'
+        process.env.COLORTERM = 'truecolor'
+        process.env.FORCE_COLOR = '3'
+      },
+      async () => {
+        const mod = await import('../lib/forceTruecolor.js?t=downgrade-' + importId++)
+        expect(
+          mod.shouldDowngradeAppleTerminalTruecolor({
+            TERM_PROGRAM: 'Apple_Terminal',
+            COLORTERM: 'truecolor',
+            FORCE_COLOR: '3'
+          } as NodeJS.ProcessEnv)
+        ).toBe(true)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBeUndefined()
+      }
+    )
+  })
+
+  it('keeps non-Apple terminals untouched when they advertise truecolor', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.TERM_PROGRAM = 'vscode'
+        process.env.COLORTERM = 'truecolor'
+        process.env.FORCE_COLOR = '3'
+      },
+      async () => {
+        const mod = await import('../lib/forceTruecolor.js?t=keep-non-apple-' + importId++)
+        expect(
+          mod.shouldDowngradeAppleTerminalTruecolor({
+            TERM_PROGRAM: 'vscode',
+            COLORTERM: 'truecolor',
+            FORCE_COLOR: '3'
+          } as NodeJS.ProcessEnv)
+        ).toBe(false)
+        expect(process.env.COLORTERM).toBe('truecolor')
+        expect(process.env.FORCE_COLOR).toBe('3')
+      }
+    )
+  })
+
+  it('sets COLORTERM=truecolor and FORCE_COLOR=3 when explicitly enabled', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.NASTECH_TUI_TRUECOLOR = '1'
+      },
+      async () => {
+        await import('../lib/forceTruecolor.js?t=enabled-' + importId++)
+        expect(process.env.COLORTERM).toBe('truecolor')
+        expect(process.env.FORCE_COLOR).toBe('3')
+      }
+    )
+  })
+
+  it('respects NASTECH_TUI_TRUECOLOR=0 opt-out', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.NASTECH_TUI_TRUECOLOR = '0'
+        process.env.TERM_PROGRAM = 'Apple_Terminal'
+      },
+      async () => {
+        await import('../lib/forceTruecolor.js?t=optout-' + importId++)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBeUndefined()
+      }
+    )
+  })
+
+  it('lets explicit opt-in keep Apple truecolor advertisement', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.TERM_PROGRAM = 'Apple_Terminal'
+        process.env.COLORTERM = 'truecolor'
+        process.env.FORCE_COLOR = '3'
+        process.env.NASTECH_TUI_TRUECOLOR = '1'
+      },
+      async () => {
+        const mod = await import('../lib/forceTruecolor.js?t=apple-explicit-on-' + importId++)
+        expect(
+          mod.shouldDowngradeAppleTerminalTruecolor({
+            TERM_PROGRAM: 'Apple_Terminal',
+            COLORTERM: 'truecolor',
+            FORCE_COLOR: '3',
+            NASTECH_TUI_TRUECOLOR: '1'
+          } as NodeJS.ProcessEnv)
+        ).toBe(false)
+        expect(process.env.COLORTERM).toBe('truecolor')
+        expect(process.env.FORCE_COLOR).toBe('3')
+      }
+    )
+  })
+
+  it('respects NO_COLOR', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.NO_COLOR = '1'
+        process.env.NASTECH_TUI_TRUECOLOR = '1'
+      },
+      async () => {
+        await import('../lib/forceTruecolor.js?t=no-color-' + importId++)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBeUndefined()
+      }
+    )
+  })
+
+  it('respects existing FORCE_COLOR unless NasTech truecolor is explicit', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.FORCE_COLOR = ''
+      },
+      async () => {
+        const mod = await import('../lib/forceTruecolor.js?t=force-color-' + importId++)
+        expect(mod.shouldForceTruecolor(process.env)).toBe(false)
+        expect(process.env.COLORTERM).toBeUndefined()
+        expect(process.env.FORCE_COLOR).toBe('')
+      }
+    )
+  })
+
+  it('lets explicit NasTech truecolor override existing FORCE_COLOR', async () => {
+    await withCleanEnv(
+      () => {
+        process.env.FORCE_COLOR = '0'
+        process.env.NASTECH_TUI_TRUECOLOR = '1'
+      },
+      async () => {
+        await import('../lib/forceTruecolor.js?t=explicit-force-' + importId++)
+        expect(process.env.COLORTERM).toBe('truecolor')
+        expect(process.env.FORCE_COLOR).toBe('3')
+      }
+    )
+  })
+})

package/src/__tests__/gatewayClient.test.ts

@@ -0,0 +1,394 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { GatewayClient } from '../gatewayClient.js'
+
+interface ListenerEntry {
+  callback: (event: any) => void
+  once: boolean
+}
+
+class FakeWebSocket {
+  static CONNECTING = 0
+  static OPEN = 1
+  static CLOSING = 2
+  static CLOSED = 3
+  static instances: FakeWebSocket[] = []
+
+  readyState = FakeWebSocket.CONNECTING
+  sent: string[] = []
+  readonly url: string
+  private listeners = new Map<string, ListenerEntry[]>()
+
+  constructor(url: string) {
+    this.url = url
+    FakeWebSocket.instances.push(this)
+  }
+
+  static reset() {
+    FakeWebSocket.instances = []
+  }
+
+  addEventListener(type: string, callback: (event: any) => void, options?: unknown) {
+    const once =
+      typeof options === 'object' &&
+      options !== null &&
+      'once' in options &&
+      Boolean((options as { once?: unknown }).once)
+
+    const entries = this.listeners.get(type) ?? []
+
+    entries.push({ callback, once })
+    this.listeners.set(type, entries)
+  }
+
+  removeEventListener(type: string, callback: (event: any) => void) {
+    const entries = this.listeners.get(type)
+
+    if (!entries) {
+      return
+    }
+
+    this.listeners.set(
+      type,
+      entries.filter(entry => entry.callback !== callback)
+    )
+  }
+
+  send(payload: string) {
+    if (this.readyState !== FakeWebSocket.OPEN) {
+      throw new Error('socket not open')
+    }
+
+    this.sent.push(payload)
+  }
+
+  close(code = 1000) {
+    if (this.readyState === FakeWebSocket.CLOSED) {
+      return
+    }
+
+    this.readyState = FakeWebSocket.CLOSED
+    this.emit('close', { code })
+  }
+
+  open() {
+    this.readyState = FakeWebSocket.OPEN
+    this.emit('open', {})
+  }
+
+  message(data: string) {
+    this.emit('message', { data })
+  }
+
+  private emit(type: string, event: any) {
+    const entries = [...(this.listeners.get(type) ?? [])]
+
+    for (const entry of entries) {
+      entry.callback(event)
+
+      if (entry.once) {
+        this.removeEventListener(type, entry.callback)
+      }
+    }
+  }
+}
+
+describe('GatewayClient websocket attach mode', () => {
+  const originalWebSocket = globalThis.WebSocket
+  let originalGatewayUrl: string | undefined
+  let originalSidecarUrl: string | undefined
+
+  beforeEach(() => {
+    originalGatewayUrl = process.env.NASTECH_TUI_GATEWAY_URL
+    originalSidecarUrl = process.env.NASTECH_TUI_SIDECAR_URL
+    FakeWebSocket.reset()
+    ;(globalThis as { WebSocket?: unknown }).WebSocket = FakeWebSocket as unknown as typeof WebSocket
+  })
+
+  afterEach(() => {
+    if (originalGatewayUrl === undefined) {
+      delete process.env.NASTECH_TUI_GATEWAY_URL
+    } else {
+      process.env.NASTECH_TUI_GATEWAY_URL = originalGatewayUrl
+    }
+
+    if (originalSidecarUrl === undefined) {
+      delete process.env.NASTECH_TUI_SIDECAR_URL
+    } else {
+      process.env.NASTECH_TUI_SIDECAR_URL = originalSidecarUrl
+    }
+
+    FakeWebSocket.reset()
+
+    if (originalWebSocket) {
+      globalThis.WebSocket = originalWebSocket
+    } else {
+      delete (globalThis as { WebSocket?: unknown }).WebSocket
+    }
+  })
+
+  it('waits for websocket open and resolves RPC requests', async () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    const gw = new GatewayClient()
+
+    gw.start()
+    const gatewaySocket = FakeWebSocket.instances[0]!
+    const req = gw.request<{ ok: boolean }>('session.create', { cols: 80 })
+
+    expect(gatewaySocket.sent).toHaveLength(0)
+    gatewaySocket.open()
+    await vi.waitFor(() => expect(gatewaySocket.sent).toHaveLength(1))
+
+    const frame = JSON.parse(gatewaySocket.sent[0] ?? '{}') as { id: string; method: string }
+    expect(frame.method).toBe('session.create')
+
+    gatewaySocket.message(JSON.stringify({ id: frame.id, jsonrpc: '2.0', result: { ok: true } }))
+    await expect(req).resolves.toEqual({ ok: true })
+
+    gw.kill()
+  })
+
+  it('mirrors event frames to sidecar websocket when configured', async () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    process.env.NASTECH_TUI_SIDECAR_URL = 'ws://gateway.test/api/pub?token=abc&channel=demo'
+
+    const gw = new GatewayClient()
+    const seen: string[] = []
+
+    gw.on('event', ev => seen.push(ev.type))
+    gw.start()
+
+    const gatewaySocket = FakeWebSocket.instances[0]!
+    gatewaySocket.open()
+    await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2))
+
+    const sidecarSocket = FakeWebSocket.instances[1]!
+
+    sidecarSocket.open()
+    gw.drain()
+
+    const eventFrame = JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'event',
+      params: { type: 'tool.start', payload: { tool_id: 't1' } }
+    })
+
+    gatewaySocket.message(eventFrame)
+
+    expect(seen).toContain('tool.start')
+    expect(sidecarSocket.sent).toContain(eventFrame)
+
+    gw.kill()
+  })
+
+  it('emits exit when attached websocket closes', () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    const gw = new GatewayClient()
+    const exits: Array<null | number> = []
+
+    gw.on('exit', code => exits.push(code))
+    gw.start()
+
+    const gatewaySocket = FakeWebSocket.instances[0]!
+
+    gatewaySocket.open()
+    gw.drain()
+    gatewaySocket.close(1011)
+
+    expect(exits).toEqual([1011])
+    expect(gw.getLogTail(20)).toContain('[lifecycle] websocket close code=1011')
+    expect(gw.getLogTail(20)).toContain('[lifecycle] transport exit code=1011')
+  })
+
+  it('rejects pending RPCs with websocket wording when the attached socket closes', async () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    const gw = new GatewayClient()
+
+    gw.start()
+    const gatewaySocket = FakeWebSocket.instances[0]!
+
+    gatewaySocket.open()
+    gw.drain()
+
+    const req = gw.request('session.create', {})
+    await vi.waitFor(() => expect(gatewaySocket.sent.length).toBeGreaterThan(0))
+
+    gatewaySocket.close(1011)
+
+    await expect(req).rejects.toThrow(/gateway websocket closed \(1011\)/)
+  })
+
+  it('rejects pending RPCs when kill() closes the attached websocket', async () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    const gw = new GatewayClient()
+
+    gw.start()
+    const gatewaySocket = FakeWebSocket.instances[0]!
+
+    gatewaySocket.open()
+    gw.drain()
+
+    const req = gw.request('session.create', {})
+    await vi.waitFor(() => expect(gatewaySocket.sent.length).toBeGreaterThan(0))
+
+    gw.kill('test.shutdown')
+
+    await expect(req).rejects.toThrow(/gateway closed/)
+    expect(gw.getLogTail(20)).toContain('[lifecycle] GatewayClient.kill reason=test.shutdown')
+  })
+
+  it('reattaches when NASTECH_TUI_GATEWAY_URL rotates between requests', async () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway-old.test/api/ws?token=abc'
+    const gw = new GatewayClient()
+
+    gw.start()
+    const firstSocket = FakeWebSocket.instances[0]!
+
+    firstSocket.open()
+    gw.drain()
+
+    const stale = gw.request('session.create', {})
+    await vi.waitFor(() => expect(firstSocket.sent.length).toBeGreaterThan(0))
+
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway-new.test/api/ws?token=xyz'
+    const next = gw.request('session.create', {})
+
+    await expect(stale).rejects.toThrow(/gateway attach url changed/)
+    await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2))
+
+    const secondSocket = FakeWebSocket.instances[1]!
+    expect(secondSocket.url).toContain('gateway-new.test')
+
+    secondSocket.open()
+    await vi.waitFor(() => expect(secondSocket.sent.length).toBeGreaterThan(0))
+
+    const frame = JSON.parse(secondSocket.sent[0] ?? '{}') as { id: string }
+    secondSocket.message(JSON.stringify({ id: frame.id, jsonrpc: '2.0', result: { ok: true } }))
+
+    await expect(next).resolves.toEqual({ ok: true })
+    gw.kill()
+  })
+
+  it('redacts query string secrets in attach failure logs and events', () => {
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=hunter2&channel=secret'
+    delete (globalThis as { WebSocket?: unknown }).WebSocket
+
+    const gw = new GatewayClient()
+    const stderrLines: string[] = []
+
+    gw.on('event', ev => {
+      if (ev.type === 'gateway.stderr' && typeof ev.payload?.line === 'string') {
+        stderrLines.push(ev.payload.line)
+      }
+    })
+    gw.start()
+    gw.drain()
+
+    expect(stderrLines.length).toBeGreaterThan(0)
+
+    for (const line of stderrLines) {
+      expect(line).not.toContain('hunter2')
+      expect(line).not.toContain('channel=secret')
+    }
+
+    expect(gw.getLogTail(20)).not.toContain('hunter2')
+    expect(gw.getLogTail(20)).not.toContain('channel=secret')
+
+    gw.kill()
+  })
+
+  it('redacts attach URL secrets when the WebSocket constructor throws', () => {
+    const secretUrl = 'ws://gateway.test/api/ws?token=hunter2&channel=secret'
+
+    process.env.NASTECH_TUI_GATEWAY_URL = secretUrl
+    ;(globalThis as { WebSocket?: unknown }).WebSocket = class ThrowingWebSocket extends FakeWebSocket {
+      constructor(url: string) {
+        throw new TypeError(`Invalid URL: ${url}`)
+      }
+    } as unknown as typeof WebSocket
+
+    const gw = new GatewayClient()
+
+    gw.start()
+    gw.drain()
+
+    const tail = gw.getLogTail(20)
+    expect(tail).not.toContain('hunter2')
+    expect(tail).not.toContain('channel=secret')
+    expect(tail).not.toContain(secretUrl)
+    expect(tail).toContain('ws://gateway.test/api/ws?***')
+
+    gw.kill()
+  })
+
+  it('redacts sidecar URL secrets when the WebSocket constructor throws', async () => {
+    const sidecarUrl = 'ws://gateway.test/api/pub?token=hunter2&channel=secret'
+
+    process.env.NASTECH_TUI_GATEWAY_URL = 'ws://gateway.test/api/ws?token=abc'
+    process.env.NASTECH_TUI_SIDECAR_URL = sidecarUrl
+    ;(globalThis as { WebSocket?: unknown }).WebSocket = class ThrowingSidecarWebSocket extends FakeWebSocket {
+      constructor(url: string) {
+        if (url.includes('/api/pub')) {
+          throw new TypeError(`Invalid URL: ${url}`)
+        }
+
+        super(url)
+      }
+    } as unknown as typeof WebSocket
+
+    const gw = new GatewayClient()
+
+    gw.start()
+    const gatewaySocket = FakeWebSocket.instances[0]!
+    gatewaySocket.open()
+    await vi.waitFor(() => expect(gw.getLogTail(20)).toContain('[sidecar] failed to connect'))
+
+    const tail = gw.getLogTail(20)
+    expect(tail).not.toContain('hunter2')
+    expect(tail).not.toContain('channel=secret')
+    expect(tail).not.toContain(sidecarUrl)
+    expect(tail).toContain('ws://gateway.test/api/pub?***')
+
+    gw.kill()
+  })
+
+  it('redacts user-info credentials even on URLs the WHATWG parser rejects', () => {
+    // Port 99999 is outside the WHATWG URL parser's valid 0–65535
+    // range and survives `.trim()`, so the fixture deterministically
+    // exercises `redactUrl()`'s fallback branch across Node versions.
+    // (An earlier `%zz` user-info fixture did NOT actually throw in
+    // recent Node — WHATWG accepts malformed percent escapes there —
+    // which silently routed the test through the structured-URL path.)
+    const fixture = 'ws://alice:hunter2@gateway.test:99999/api/ws?token=secret'
+    expect(() => new URL(fixture)).toThrow()
+
+    process.env.NASTECH_TUI_GATEWAY_URL = fixture
+    delete (globalThis as { WebSocket?: unknown }).WebSocket
+
+    const gw = new GatewayClient()
+    const stderrLines: string[] = []
+
+    gw.on('event', ev => {
+      if (ev.type === 'gateway.stderr' && typeof ev.payload?.line === 'string') {
+        stderrLines.push(ev.payload.line)
+      }
+    })
+    gw.start()
+    gw.drain()
+
+    expect(stderrLines.length).toBeGreaterThan(0)
+
+    for (const line of stderrLines) {
+      expect(line).not.toContain('alice')
+      expect(line).not.toContain('hunter2')
+      expect(line).not.toContain('token=secret')
+    }
+
+    const tail = gw.getLogTail(20)
+    expect(tail).not.toContain('alice')
+    expect(tail).not.toContain('hunter2')
+    expect(tail).not.toContain('token=secret')
+
+    gw.kill()
+  })
+})

package/src/__tests__/gatewayRecovery.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+
+import { GATEWAY_RECOVERY_LIMIT, GATEWAY_RECOVERY_WINDOW_MS, planGatewayRecovery } from '../app/gatewayRecovery.js'
+
+describe('planGatewayRecovery', () => {
+  it('recovers the live session and records the attempt', () => {
+    const plan = planGatewayRecovery('sess-1', null, [], 1000)
+
+    expect(plan).toEqual({ attempts: [1000], recover: true, sid: 'sess-1' })
+  })
+
+  it('does not recover when there is no session to resume', () => {
+    expect(planGatewayRecovery(null, null, [], 1000)).toEqual({ attempts: [], recover: false, sid: null })
+  })
+
+  it('keeps retrying the recovery target through a startup crash-loop, bounded by the budget', () => {
+    // First exit: live sid present.
+    let attempts: number[] = []
+    let plan = planGatewayRecovery('sess-1', null, attempts, 0)
+
+    expect(plan.recover).toBe(true)
+    expect(plan.sid).toBe('sess-1')
+    attempts = plan.attempts
+
+    // Respawn crash-loops before gateway.ready: live sid is now null, but the
+    // recovery target carries it forward so we keep trying up to the budget.
+    for (let i = 1; i < GATEWAY_RECOVERY_LIMIT; i++) {
+      plan = planGatewayRecovery(null, 'sess-1', attempts, i)
+      expect(plan.recover).toBe(true)
+      expect(plan.sid).toBe('sess-1')
+      attempts = plan.attempts
+    }
+
+    // Budget exhausted: fall back to the inert state instead of spawn-storming.
+    plan = planGatewayRecovery(null, 'sess-1', attempts, GATEWAY_RECOVERY_LIMIT)
+    expect(plan.recover).toBe(false)
+    expect(plan.sid).toBe('sess-1')
+  })
+
+  it('prunes attempts older than the window so recovery re-arms', () => {
+    const old = Array.from({ length: GATEWAY_RECOVERY_LIMIT }, (_, i) => i)
+    const plan = planGatewayRecovery('sess-1', null, old, GATEWAY_RECOVERY_WINDOW_MS + 100)
+
+    expect(plan.attempts).toEqual([GATEWAY_RECOVERY_WINDOW_MS + 100])
+    expect(plan.recover).toBe(true)
+  })
+})