@agfpd/iapeer 0.1.0

package/src/cli/listTui.test.ts

@@ -0,0 +1,70 @@
+// list TUI — the PURE render + key state-machine (the raw-mode loop is live-verified).
+
+import { describe, expect, test } from 'bun:test'
+import { filterRows, handleListKey, renderListPanel, type TuiState } from './listTui.ts'
+import type { PeerListing } from './index.ts'
+
+function row(over: Partial<PeerListing>): PeerListing {
+  return {
+    personality: 'p',
+    default_runtime: 'claude',
+    intelligence: 'artificial',
+    description: '',
+    runtimes: [{ runtime: 'claude', status: 'asleep' }],
+    ...over,
+  }
+}
+const ROWS: PeerListing[] = [
+  row({ personality: 'arthur', default_runtime: 'telegram', description: 'owner' }),
+  row({ personality: 'boris', runtimes: [{ runtime: 'claude', status: 'live' }], last_active_runtime: 'claude' }),
+  row({ personality: 'doc' }),
+]
+const S0: TuiState = { cursor: 0, filter: '', filterMode: false }
+
+describe('filterRows', () => {
+  test('case-insensitive substring over personality + description', () => {
+    expect(filterRows(ROWS, 'BOR').map(r => r.personality)).toEqual(['boris'])
+    expect(filterRows(ROWS, 'owner').map(r => r.personality)).toEqual(['arthur']) // description match
+    expect(filterRows(ROWS, '').length).toBe(3) // empty → all
+  })
+})
+
+describe('renderListPanel', () => {
+  test('selected row carries the ❯ caret + reverse-video; others do not', () => {
+    const frame = renderListPanel(ROWS, { ...S0, cursor: 1 })
+    expect(frame).toContain('\x1b[7m❯ boris') // reverse + caret on the cursor row
+    expect(frame).toContain('arthur') // other rows present, no caret
+    expect(frame).not.toContain('❯ arthur')
+    expect(frame).toContain('● claude') // boris live glyph
+  })
+  test('filter narrows the rendered rows', () => {
+    const frame = renderListPanel(ROWS, { ...S0, filter: 'doc' })
+    expect(frame).toContain('doc')
+    expect(frame).not.toContain('arthur')
+  })
+})
+
+describe('handleListKey', () => {
+  const visible = ROWS
+  test('↓/↑ move the cursor, clamped to bounds', () => {
+    expect(handleListKey('\x1b[B', S0, visible).state.cursor).toBe(1) // down
+    expect(handleListKey('\x1b[A', S0, visible).state.cursor).toBe(0) // up clamped at 0
+    expect(handleListKey('\x1b[B', { ...S0, cursor: 2 }, visible).state.cursor).toBe(2) // down clamped at last
+  })
+  test('Enter → attach action with the selected peer', () => {
+    const r = handleListKey('\r', { ...S0, cursor: 1 }, visible)
+    expect(r.action).toEqual({ type: 'attach', personality: 'boris' })
+  })
+  test('q / Ctrl-C → quit', () => {
+    expect(handleListKey('q', S0, visible).action).toEqual({ type: 'quit' })
+    expect(handleListKey('\x03', S0, visible).action).toEqual({ type: 'quit' })
+  })
+  test('/ enters filter mode; typing edits the filter; Enter leaves it', () => {
+    const f = handleListKey('/', S0, visible)
+    expect(f.state.filterMode).toBe(true)
+    const typed = handleListKey('b', f.state, visible)
+    expect(typed.state.filter).toBe('b')
+    const left = handleListKey('\r', typed.state, visible)
+    expect(left.state.filterMode).toBe(false)
+  })
+})

package/src/cli/listTui.ts

@@ -0,0 +1,165 @@
+// list TUI — the interactive control-panel form of `iapeer list` (contract Примитивы
+// §list TUI): a peer overview with per-runtime liveness, ↑/↓ navigation, `/` filter,
+// `q` quit, and ENTER = attach to the selected peer. Scriptable `list` (non-tty /
+// --json) stays the table in cli/index.ts; this is the tty form.
+//
+// The RENDER and the KEY state-machine are PURE (unit-testable); only runListTui does
+// raw-mode terminal I/O, and on ENTER it hands off to attachPeer + tmux attach — the
+// same ensure-live+resume path the `attach` verb uses (so a live session is never torn).
+
+import { spawnSync } from 'child_process'
+import { attachPeer } from '../lifecycle/index.ts'
+import { listPeers, type PeerListing } from './index.ts'
+
+const GLYPH: Record<'live' | 'asleep' | 'stopped', string> = { live: '●', asleep: '○', stopped: '✕' }
+
+// ─── pure render ─────────────────────────────────────────────────────────────
+
+/** Rows that match the filter (case-insensitive substring over personality/description). */
+export function filterRows(rows: PeerListing[], filter: string): PeerListing[] {
+  const f = filter.trim().toLowerCase()
+  if (!f) return rows
+  return rows.filter(r => r.personality.toLowerCase().includes(f) || r.description.toLowerCase().includes(f))
+}
+
+export interface TuiState {
+  cursor: number
+  filter: string
+  filterMode: boolean
+}
+
+/** Render the panel frame (ANSI). `cursor` is an index into the FILTERED rows. */
+export function renderListPanel(rows: PeerListing[], state: TuiState): string {
+  const visible = filterRows(rows, state.filter)
+  const lines: string[] = []
+  lines.push('\x1b[2J\x1b[H') // clear + home
+  lines.push('  iapeer peers  —  ↑/↓ navigate · Enter attach · / filter · q quit')
+  lines.push('')
+  if (visible.length === 0) {
+    lines.push('  (no peers match)')
+  }
+  visible.forEach((r, i) => {
+    const status = r.runtimes.map(s => `${GLYPH[s.status]} ${s.runtime}`).join('  ')
+    const la = r.last_active_runtime ? `  ⤳${r.last_active_runtime}` : ''
+    const row = `${r.personality.padEnd(16)} ${r.default_runtime.padEnd(9)} ${r.intelligence.padEnd(11)} ${status}${la}`
+    // selected row → reverse video + ❯ caret
+    lines.push(i === state.cursor ? `\x1b[7m❯ ${row}\x1b[0m` : `  ${row}`)
+  })
+  lines.push('')
+  lines.push(state.filterMode ? `  /filter: ${state.filter}_` : state.filter ? `  filter: ${state.filter}` : '')
+  return lines.join('\r\n') + '\r\n'
+}
+
+// ─── pure key state-machine ──────────────────────────────────────────────────
+
+export type TuiAction =
+  | { type: 'none' }
+  | { type: 'redraw' }
+  | { type: 'attach'; personality: string }
+  | { type: 'quit' }
+
+const UP = '\x1b[A'
+const DOWN = '\x1b[B'
+const ENTER1 = '\r'
+const ENTER2 = '\n'
+const ESC = '\x1b'
+const CTRL_C = '\x03'
+const BACKSPACE = /^[\x7f\b]$/
+
+/**
+ * Advance the TUI state for a key. Pure: returns the next state + an action the loop
+ * performs (attach/quit/redraw). `visible` is the filtered row set (for bounds + the
+ * Enter target). In filter-mode, printable keys edit the filter; Enter/Esc leave it.
+ */
+export function handleListKey(key: string, state: TuiState, visible: PeerListing[]): { state: TuiState; action: TuiAction } {
+  if (state.filterMode) {
+    if (key === ENTER1 || key === ENTER2 || key === ESC) {
+      return { state: { ...state, filterMode: false, cursor: 0 }, action: { type: 'redraw' } }
+    }
+    if (BACKSPACE.test(key)) {
+      return { state: { ...state, filter: state.filter.slice(0, -1), cursor: 0 }, action: { type: 'redraw' } }
+    }
+    if (key >= ' ' && key.length === 1) {
+      return { state: { ...state, filter: state.filter + key, cursor: 0 }, action: { type: 'redraw' } }
+    }
+    return { state, action: { type: 'none' } }
+  }
+  if (key === 'q' || key === CTRL_C) return { state, action: { type: 'quit' } }
+  if (key === '/') return { state: { ...state, filterMode: true }, action: { type: 'redraw' } }
+  if (key === UP) return { state: { ...state, cursor: Math.max(0, state.cursor - 1) }, action: { type: 'redraw' } }
+  if (key === DOWN) {
+    return { state: { ...state, cursor: Math.min(Math.max(0, visible.length - 1), state.cursor + 1) }, action: { type: 'redraw' } }
+  }
+  if (key === ENTER1 || key === ENTER2) {
+    const target = visible[state.cursor]
+    return target ? { state, action: { type: 'attach', personality: target.personality } } : { state, action: { type: 'none' } }
+  }
+  return { state, action: { type: 'none' } }
+}
+
+// ─── raw-mode loop (the only impure part) ────────────────────────────────────
+
+/**
+ * Run the interactive list panel. Reads the registry once (read-only), renders, and
+ * loops on raw-mode key input. ENTER → attachPeer the selected peer (ensure-live +
+ * resume, last-active runtime), then exec `tmux attach` (TMUX unset, no nested error);
+ * the panel exits raw mode first so the operator drops cleanly into the session. `q` /
+ * Ctrl-C quit. Returns the process exit code.
+ */
+export async function runListTui(env: NodeJS.ProcessEnv = process.env): Promise<number> {
+  const rows = listPeers({ env })
+  let state: TuiState = { cursor: 0, filter: '', filterMode: false }
+  const stdin = process.stdin
+  const stdout = process.stdout
+  if (!stdin.isTTY) {
+    stdout.write('list TUI requires a terminal (use `iapeer list --json` for scripts)\n')
+    return 2
+  }
+  const draw = () => stdout.write(renderListPanel(rows, state))
+  stdin.setRawMode(true)
+  stdin.resume()
+  stdin.setEncoding('utf8')
+  draw()
+  try {
+    for (;;) {
+      const key = await nextKey(stdin)
+      const { state: next, action } = handleListKey(key, state, filterRows(rows, state.filter))
+      state = next
+      if (action.type === 'quit') return 0
+      if (action.type === 'redraw') draw()
+      if (action.type === 'attach') {
+        // leave raw mode and the panel before handing the terminal to tmux attach
+        stdin.setRawMode(false)
+        stdin.pause()
+        stdout.write('\x1b[2J\x1b[H')
+        const r = await attachPeer({ personality: action.personality, env })
+        if (!r.ok) {
+          stdout.write(`attach: ${r.reason}\n`)
+          return 1
+        }
+        stdout.write(`${r.woke ? 'woke + ' : ''}attaching ${r.identity}…\n`)
+        const attachEnv = { ...env }
+        delete attachEnv.TMUX
+        const a = spawnSync('tmux', ['-S', r.socketPath, 'attach', '-t', r.identity], {
+          stdio: 'inherit',
+          env: attachEnv as Record<string, string>,
+        })
+        return a.status ?? 0
+      }
+    }
+  } finally {
+    if (stdin.isTTY) stdin.setRawMode(false)
+    stdin.pause()
+  }
+}
+
+/** Resolve the next raw-mode keypress (one chunk = one key / escape sequence). */
+function nextKey(stdin: NodeJS.ReadStream): Promise<string> {
+  return new Promise(resolve => {
+    const onData = (chunk: string) => {
+      stdin.off('data', onData)
+      resolve(chunk)
+    }
+    stdin.on('data', onData)
+  })
+}

package/src/codec/codec.test.ts

@@ -0,0 +1,271 @@
+import { describe, expect, test } from 'bun:test'
+import { buildEnvelope, decodeEnvelope, extractEnvelopes, type EnvelopeInput } from './index.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WITNESS: faithful copy of the OLD telegram-runtime decoder (cli.ts:867-935).
+// These reproduce the pre-fix behaviour so each adversarial test shows a real
+// delta: the witness FAILS the assertion the new codec PASSES. (Brief: "тест,
+// падающий ДО фикса и проходящий ПОСЛЕ".)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function oldUnescapeAttr(value: string): string {
+  return value
+    .replace(/"/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+}
+function oldDecodeCdata(inner: string): string {
+  if (!inner.startsWith('<![CDATA[') || !inner.endsWith(']]>')) return inner
+  return inner.slice('<![CDATA['.length, -']]>'.length).replaceAll(']]]]><![CDATA[>', ']]>')
+}
+function oldTagContent(xml: string, tag: string): string | undefined {
+  const re = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`)
+  const m = re.exec(xml)
+  return m ? oldDecodeCdata(m[1]) : undefined
+}
+function oldParseMessage(xml: string): string | undefined {
+  xml = xml.replace(/\r\n?/g, '\n') // the CR→LF fold the codec must NOT do
+  return oldTagContent(xml, 'message')
+}
+function oldExtractEnvelopes(buffer: string): { envelopes: string[]; rest: string } {
+  const envelopes: string[] = []
+  let rest = buffer
+  while (true) {
+    const start = rest.indexOf('<iap ')
+    if (start < 0) return { envelopes, rest: rest.slice(Math.max(0, rest.length - 8)) }
+    if (start > 0) rest = rest.slice(start)
+    const end = rest.indexOf('</iap>') // naive: not CDATA-aware
+    if (end < 0) return { envelopes, rest }
+    const envelopeEnd = end + '</iap>'.length
+    envelopes.push(rest.slice(0, envelopeEnd))
+    rest = rest.slice(envelopeEnd)
+  }
+}
+
+const base: Omit<EnvelopeInput, 'message'> = {
+  fromPersonality: 'arthur',
+  fromRuntime: 'telegram',
+  fromIntelligence: 'natural',
+  topic: 'Ф0 фундамента',
+}
+
+function roundTripMessage(message: string, extra: Partial<EnvelopeInput> = {}): string {
+  const xml = buildEnvelope({ ...base, ...extra, message })
+  const { envelopes, rest } = extractEnvelopes(xml)
+  expect(envelopes).toHaveLength(1)
+  expect(rest).toBe('')
+  return decodeEnvelope(envelopes[0]).message
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Basic round-trip
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('codec round-trip (field-semantic equivalence)', () => {
+  test('preserves all fields', () => {
+    const input: EnvelopeInput = {
+      fromPersonality: 'boris',
+      fromRuntime: 'claude',
+      fromIntelligence: 'artificial',
+      topic: 'checkpoint',
+      attachments: ['/tmp/a.txt', '/tmp/b with space.png'],
+      message: 'plain multi\nline\nmessage',
+    }
+    const decoded = decodeEnvelope(buildEnvelope(input))
+    expect(decoded.fromPersonality).toBe(input.fromPersonality)
+    expect(decoded.fromRuntime).toBe(input.fromRuntime)
+    expect(decoded.fromIntelligence).toBe(input.fromIntelligence)
+    expect(decoded.topic).toBe(input.topic)
+    expect(decoded.attachments).toEqual([...input.attachments!])
+    expect(decoded.message).toBe(input.message)
+  })
+
+  test('attr special chars (<, >, &, ") survive in personality and topic', () => {
+    const xml = buildEnvelope({
+      fromPersonality: 'arthur',
+      fromRuntime: 'telegram',
+      fromIntelligence: 'natural',
+      topic: 'a < b & c > d "quoted"',
+      message: 'hi',
+    })
+    const d = decodeEnvelope(xml)
+    expect(d.topic).toBe('a < b & c > d "quoted"')
+  })
+
+  test('empty message round-trips', () => {
+    expect(roundTripMessage('')).toBe('')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adversarial: message contains </iap>  → extractEnvelopes must not truncate
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('adversarial: </iap> in message', () => {
+  const message = 'see the closing tag </iap> right here'
+
+  test('NEW codec: single envelope, message intact', () => {
+    expect(roundTripMessage(message)).toBe(message)
+  })
+
+  test('WITNESS: old naive indexOf truncates the envelope', () => {
+    const xml = buildEnvelope({ ...base, message })
+    const oldFirst = oldExtractEnvelopes(xml).envelopes[0]
+    // old splits at the inner </iap>, producing a shorter, broken envelope
+    expect(oldFirst.length).toBeLessThan(xml.length)
+    // ...and the new extractor produces the full envelope
+    expect(extractEnvelopes(xml).envelopes[0]).toBe(xml)
+  })
+
+  test('NEW codec: two real envelopes, first message holds a fake </iap>', () => {
+    const e1 = buildEnvelope({ ...base, message: 'fake </iap> inside' })
+    const e2 = buildEnvelope({ ...base, fromPersonality: 'darwin', message: 'second' })
+    const { envelopes, rest } = extractEnvelopes(e1 + '\n' + e2)
+    expect(envelopes).toHaveLength(2)
+    expect(rest).toBe('')
+    expect(decodeEnvelope(envelopes[0]).message).toBe('fake </iap> inside')
+    expect(decodeEnvelope(envelopes[1]).message).toBe('second')
+    // witness: old truncates the first envelope at the inner </iap>, so its
+    // first fragment is NOT the real e1 (and no longer decodes to a message)
+    const oldFirst = oldExtractEnvelopes(e1 + '\n' + e2).envelopes[0]
+    expect(oldFirst).not.toBe(e1)
+    expect(oldTagContent(oldFirst, 'message')).toBeUndefined()
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adversarial: message contains </message>  → tag-content must not truncate
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('adversarial: </message> in message', () => {
+  const message = 'a </message> b </message> c'
+
+  test('NEW codec: message intact', () => {
+    expect(roundTripMessage(message)).toBe(message)
+  })
+
+  test('WITNESS: old non-greedy regex truncates at inner </message>', () => {
+    const xml = buildEnvelope({ ...base, message })
+    expect(oldParseMessage(xml)).not.toBe(message)
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adversarial: message contains ]]>  → CDATA split must reconstruct
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('adversarial: ]]> in message', () => {
+  test('NEW codec: literal ]]> reconstructed', () => {
+    expect(roundTripMessage('a]]>b')).toBe('a]]>b')
+    expect(roundTripMessage('edge ]]> at ]]> several ]]> places')).toBe(
+      'edge ]]> at ]]> several ]]> places',
+    )
+    expect(roundTripMessage(']]>')).toBe(']]>')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Adversarial: literal CR  → codec must NOT fold (transport's job)
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('adversarial: literal CR is preserved (no fold in codec)', () => {
+  const message = 'line1\rline2\r\nline3'
+
+  test('NEW codec: CR survives round-trip', () => {
+    expect(roundTripMessage(message)).toBe(message)
+  })
+
+  test('WITNESS: old decoder folds CR→LF and loses it', () => {
+    const xml = buildEnvelope({ ...base, message })
+    const folded = oldParseMessage(xml)
+    expect(folded).not.toBe(message)
+    expect(folded).toBe('line1\nline2\nline3') // proof of the lossy fold
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Headline: all four adversarial features at once
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('adversarial: combined </iap> </message> ]]> CR', () => {
+  const message = 'X </iap> Y </message> Z ]]> W\rtail\nend'
+
+  test('NEW codec: full round-trip by field semantics', () => {
+    const input: EnvelopeInput = {
+      ...base,
+      attachments: ['/path/with ]]> weird', '/second </iap> path'],
+      message,
+    }
+    const xml = buildEnvelope(input)
+    const { envelopes, rest } = extractEnvelopes(xml)
+    expect(envelopes).toHaveLength(1)
+    expect(rest).toBe('')
+    const d = decodeEnvelope(envelopes[0])
+    expect(d.message).toBe(message)
+    expect(d.attachments).toEqual(['/path/with ]]> weird', '/second </iap> path'])
+    expect(d.fromPersonality).toBe('arthur')
+    expect(d.fromIntelligence).toBe('natural')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// extractEnvelopes streaming semantics
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('extractEnvelopes streaming', () => {
+  test('incomplete envelope kept in rest, completed on next chunk', () => {
+    const xml = buildEnvelope({ ...base, message: 'streamed' })
+    const cut = Math.floor(xml.length / 2)
+    const first = extractEnvelopes(xml.slice(0, cut))
+    expect(first.envelopes).toHaveLength(0)
+    const second = extractEnvelopes(first.rest + xml.slice(cut))
+    expect(second.envelopes).toHaveLength(1)
+    expect(decodeEnvelope(second.envelopes[0]).message).toBe('streamed')
+  })
+
+  test('mid-CDATA cut does not falsely close on inner </iap>', () => {
+    const xml = buildEnvelope({ ...base, message: 'pre </iap> post' })
+    // cut right after the inner </iap> but before the CDATA terminator
+    const innerIap = xml.indexOf('</iap>')
+    const cut = innerIap + 3
+    const first = extractEnvelopes(xml.slice(0, cut))
+    expect(first.envelopes).toHaveLength(0) // must NOT emit a truncated envelope
+    const second = extractEnvelopes(first.rest + xml.slice(cut))
+    expect(second.envelopes).toHaveLength(1)
+    expect(decodeEnvelope(second.envelopes[0]).message).toBe('pre </iap> post')
+  })
+
+  test('leading noise before <iap is discarded', () => {
+    const xml = buildEnvelope({ ...base, message: 'm' })
+    const { envelopes } = extractEnvelopes('garbage text\n' + xml)
+    expect(envelopes).toHaveLength(1)
+    expect(decodeEnvelope(envelopes[0]).message).toBe('m')
+  })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Decoder error surface
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('decodeEnvelope errors', () => {
+  test('missing <iap throws', () => {
+    expect(() => decodeEnvelope('no envelope here')).toThrow()
+  })
+  test('missing message throws', () => {
+    expect(() => decodeEnvelope('<iap from-personality="a" from-runtime="claude"></iap>')).toThrow()
+  })
+  test('unknown from-intelligence is dropped, not invented', () => {
+    const xml =
+      '<iap from-personality="a" from-runtime="claude" from-intelligence="bogus">\n<message><![CDATA[x]]></message>\n</iap>'
+    const d = decodeEnvelope(xml)
+    expect(d.fromIntelligence).toBeUndefined()
+    expect(d.message).toBe('x')
+  })
+
+  test('READ-COMPAT: legacy from-intelligence="human" decodes to natural', () => {
+    const xml =
+      '<iap from-personality="arthur" from-runtime="telegram" from-intelligence="human">\n<message><![CDATA[hi]]></message>\n</iap>'
+    expect(decodeEnvelope(xml).fromIntelligence).toBe('natural')
+  })
+})