@alumbwe/anvil 1.0.0

package/src/utils/terminal-images.ts

@@ -0,0 +1,229 @@
+/**
+ * Terminal image rendering utilities
+ * Supports iTerm2 inline images protocol and Kitty graphics protocol
+ */
+
+import { getCliEnv } from './env'
+
+import type { CliEnv } from '../types/env'
+
+export type TerminalImageProtocol = 'iterm2' | 'kitty' | 'sixel' | 'none'
+
+let cachedProtocol: TerminalImageProtocol | null = null
+
+/**
+ * Detect which image protocol the terminal supports
+ */
+export function detectTerminalImageSupport(
+  env: CliEnv = getCliEnv(),
+): TerminalImageProtocol {
+  if (cachedProtocol !== null) {
+    return cachedProtocol
+  }
+
+  // Check for iTerm2
+  if (env.TERM_PROGRAM === 'iTerm.app') {
+    cachedProtocol = 'iterm2'
+    return cachedProtocol
+  }
+
+  // Check for Kitty
+  if (
+    env.TERM === 'xterm-kitty' ||
+    env.KITTY_WINDOW_ID !== undefined
+  ) {
+    cachedProtocol = 'kitty'
+    return cachedProtocol
+  }
+
+  // Check for Sixel support (less common)
+  if (
+    env.TERM?.includes('sixel') ||
+    env.SIXEL_SUPPORT === 'true'
+  ) {
+    cachedProtocol = 'sixel'
+    return cachedProtocol
+  }
+
+  cachedProtocol = 'none'
+  return cachedProtocol
+}
+
+/**
+ * Check if terminal supports inline images
+ */
+export function supportsInlineImages(): boolean {
+  return detectTerminalImageSupport() !== 'none'
+}
+
+/**
+ * Generate iTerm2 inline image escape sequence
+ * @param base64Data - Base64 encoded image data
+ * @param options - Display options
+ */
+function generateITerm2ImageSequence(
+  base64Data: string,
+  options: {
+    width?: number | string // cells or 'auto'
+    height?: number | string // cells or 'auto'
+    preserveAspectRatio?: boolean
+    inline?: boolean
+    name?: string
+  } = {},
+): string {
+  const {
+    width = 'auto',
+    height = 'auto',
+    preserveAspectRatio = true,
+    inline = true,
+    name,
+  } = options
+
+  // Build the parameter string
+  const params: string[] = []
+
+  if (inline) {
+    params.push('inline=1')
+  }
+
+  if (width !== 'auto') {
+    params.push(`width=${width}`)
+  }
+
+  if (height !== 'auto') {
+    params.push(`height=${height}`)
+  }
+
+  if (!preserveAspectRatio) {
+    params.push('preserveAspectRatio=0')
+  }
+
+  if (name) {
+    params.push(`name=${Buffer.from(name).toString('base64')}`)
+  }
+
+  // Add size parameter (required)
+  params.push(`size=${base64Data.length}`)
+
+  const paramString = params.join(';')
+
+  // Format: ESC ] 1337 ; File = [params] : base64data BEL
+  // Using \x1b for ESC and \x07 for BEL
+  return `\x1b]1337;File=${paramString}:${base64Data}\x07`
+}
+
+/**
+ * Generate Kitty graphics protocol escape sequence
+ * @param base64Data - Base64 encoded image data
+ * @param options - Display options
+ */
+function generateKittyImageSequence(
+  base64Data: string,
+  options: {
+    width?: number // cells
+    height?: number // cells
+    id?: number
+  } = {},
+): string {
+  const { width, height, id } = options
+
+  // Build key-value pairs for the control data
+  const kvPairs: string[] = [
+    'a=T', // action: transmit and display
+    'f=100', // format: PNG (100) - let Kitty auto-detect
+    't=d', // transmission: direct (data follows)
+  ]
+
+  if (width) {
+    kvPairs.push(`c=${width}`) // columns
+  }
+
+  if (height) {
+    kvPairs.push(`r=${height}`) // rows
+  }
+
+  if (id) {
+    kvPairs.push(`i=${id}`) // image id
+  }
+
+  const controlData = kvPairs.join(',')
+
+  // Kitty requires chunked transmission for large images
+  // For simplicity, we'll send in one chunk if small enough
+  const CHUNK_SIZE = 4096
+
+  if (base64Data.length <= CHUNK_SIZE) {
+    // Single chunk: ESC _ G <control> ; <data> ESC \
+    return `\x1b_G${controlData};${base64Data}\x1b\\`
+  }
+
+  // Multi-chunk transmission
+  const chunks: string[] = []
+  for (let i = 0; i < base64Data.length; i += CHUNK_SIZE) {
+    const chunk = base64Data.slice(i, i + CHUNK_SIZE)
+    const isLast = i + CHUNK_SIZE >= base64Data.length
+    const chunkControl = isLast ? controlData : `${controlData},m=1` // m=1 means more chunks coming
+    chunks.push(`\x1b_G${chunkControl};${chunk}\x1b\\`)
+  }
+
+  return chunks.join('')
+}
+
+/**
+ * Render an image inline in the terminal
+ * @param base64Data - Base64 encoded image data
+ * @param options - Display options
+ * @returns The escape sequence string, or null if not supported
+ */
+export function renderInlineImage(
+  base64Data: string,
+  options: {
+    width?: number
+    height?: number
+    filename?: string
+  } = {},
+): string | null {
+  const protocol = detectTerminalImageSupport()
+
+  switch (protocol) {
+    case 'iterm2':
+      return generateITerm2ImageSequence(base64Data, {
+        width: options.width,
+        height: options.height,
+        name: options.filename,
+      })
+
+    case 'kitty':
+      return generateKittyImageSequence(base64Data, {
+        width: options.width,
+        height: options.height,
+      })
+
+    case 'sixel':
+      // Sixel is more complex and requires actual image decoding
+      // For now, return null and fall back to metadata display
+      return null
+
+    case 'none':
+    default:
+      return null
+  }
+}
+
+/**
+ * Get a user-friendly description of the terminal image support
+ */
+export function getImageSupportDescription(): string {
+  const protocol = detectTerminalImageSupport()
+
+  switch (protocol) {
+    case 'iterm2':
+      return 'iTerm2 inline images'
+    case 'kitty':
+      return 'Kitty graphics protocol'
+    case 'sixel':
+      return 'Sixel graphics'
+    case 'none':
+      return 'No inline image support'
+  }
+}

package/src/utils/terminal-io.ts

@@ -0,0 +1,85 @@
+import { closeSync, constants, openSync, writeSync } from 'fs'
+
+/** Write every byte to an already-open file descriptor before returning. */
+export function writeFileDescriptorSync(fd: number, value: string): boolean {
+  try {
+    const bytes = Buffer.from(value)
+    let offset = 0
+    while (offset < bytes.length) {
+      const written = writeSync(fd, bytes, offset, bytes.length - offset)
+      if (written === 0) return false
+      offset += written
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Report a fatal error without relying on async logging or console capture. */
+export function reportFatalErrorSync(
+  label: string,
+  error: unknown,
+  stderrFd: number = process.stderr.fd,
+): void {
+  const detail = formatFatalError(error)
+  if (writeFileDescriptorSync(stderrFd, `${label}: ${detail}\n`)) return
+
+  try {
+    console.error(`${label}:`, error)
+  } catch {
+    // The process is already failing and stderr may be closed.
+  }
+}
+
+/** Fatal boundaries must also survive values whose inspection itself throws. */
+function formatFatalError(error: unknown): string {
+  try {
+    if (error instanceof Error) {
+      for (const property of ['stack', 'message', 'name'] as const) {
+        try {
+          const value = error[property]
+          if (!value) continue
+          const formatted = stringifyFatalValue(value)
+          if (formatted !== undefined) return formatted
+        } catch {}
+      }
+    }
+  } catch {}
+  return stringifyFatalValue(error) ?? '<unprintable error>'
+}
+
+function stringifyFatalValue(value: unknown): string | undefined {
+  try {
+    return String(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Write terminal control bytes synchronously to the controlling terminal.
+ * OpenTUI may capture stdout, so control sequences use /dev/tty (or CON on
+ * Windows) instead of the process.stdout stream.
+ */
+export function writeTerminalControlSync(
+  value: string,
+  ttyPath = process.platform === 'win32' ? 'CON' : '/dev/tty',
+): boolean {
+  let fd: number | null = null
+
+  try {
+    fd = openSync(ttyPath, constants.O_WRONLY)
+    return writeFileDescriptorSync(fd, value)
+  } catch {
+    return false
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd)
+      } catch {
+        // The process is exiting; there is nothing useful to recover here.
+      }
+    }
+  }
+}

package/src/utils/terminal-protocol-controller.ts

@@ -0,0 +1,173 @@
+import { writeTerminalControlSync } from './terminal-io'
+
+import type { CliRenderer } from '@opentui/core'
+
+const ENABLE_FOCUS_REPORTING = '\x1b[?1004h'
+const DISABLE_FOCUS_REPORTING = '\x1b[?1004l'
+const FOCUS_EVENT_RE = /\x1b\[(I|O)/g
+type TerminalProtocolRenderer = Pick<
+  CliRenderer,
+  'prependInputHandler' | 'removeInputHandler'
+>
+
+type FocusSubscriber = {
+  onFocusChange: (focused: boolean) => void
+  onSupportDetected?: () => void
+}
+
+export interface TerminalProtocolControllerOptions {
+  writeControl?: (sequence: string) => boolean
+  onError?: (error: unknown) => void
+}
+
+/** Return the last complete focus report in a terminal input sequence. */
+export function parseFocusState(data: string): boolean | null {
+  if (!data.includes('\x1b[')) return null
+
+  let focused: boolean | null = null
+  FOCUS_EVENT_RE.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = FOCUS_EVENT_RE.exec(data)) !== null) {
+    focused = match[1] === 'I'
+  }
+  return focused
+}
+
+/**
+ * Single owner for terminal protocols that can emit unsolicited input.
+ *
+ * OpenTUI owns normal rendering and mouse input. This controller only enables,
+ * parses, and disables focus reports for subscribers.
+ */
+export class TerminalProtocolController {
+  private readonly writeControl: (sequence: string) => boolean
+  private readonly onError: (error: unknown) => void
+  private readonly focusSubscribers = new Set<FocusSubscriber>()
+  private focusSupported = false
+  private lastFocusState: boolean | null = null
+  private disposed = false
+
+  constructor(
+    private readonly renderer: TerminalProtocolRenderer,
+    options: TerminalProtocolControllerOptions = {},
+  ) {
+    this.writeControl = options.writeControl ?? writeTerminalControlSync
+    this.onError = options.onError ?? (() => {})
+    renderer.prependInputHandler(this.handleInput)
+  }
+
+  private reportError(error: unknown): void {
+    try {
+      this.onError(error)
+    } catch {
+      // Diagnostics must never turn a recoverable terminal transition into an
+      // input-handler or command-lifecycle failure.
+    }
+  }
+
+  private setFocusReporting(enabled: boolean, failureMessage: string): boolean {
+    try {
+      if (
+        this.writeControl(
+          enabled ? ENABLE_FOCUS_REPORTING : DISABLE_FOCUS_REPORTING,
+        )
+      ) {
+        return true
+      }
+      this.reportError(new Error(failureMessage))
+    } catch (error) {
+      this.reportError(error)
+    }
+    return false
+  }
+
+  private readonly handleInput = (sequence: string): boolean => {
+    const focused = parseFocusState(sequence)
+    if (focused === null) return false
+
+    if (!this.focusSupported) {
+      this.focusSupported = true
+      for (const subscriber of this.focusSubscribers) {
+        try {
+          subscriber.onSupportDetected?.()
+        } catch (error) {
+          this.reportError(error)
+        }
+      }
+    }
+
+    if (focused !== this.lastFocusState) {
+      this.lastFocusState = focused
+      for (const subscriber of this.focusSubscribers) {
+        try {
+          subscriber.onFocusChange(focused)
+        } catch (error) {
+          this.reportError(error)
+        }
+      }
+    }
+
+    return false
+  }
+
+  subscribeToFocus(subscriber: FocusSubscriber): () => void {
+    if (this.disposed) return () => {}
+    const isFirstSubscriber = this.focusSubscribers.size === 0
+    this.focusSubscribers.add(subscriber)
+
+    if (isFirstSubscriber) {
+      this.setFocusReporting(true, 'Could not enable terminal focus reporting')
+    }
+
+    if (this.focusSupported) {
+      try {
+        subscriber.onSupportDetected?.()
+        if (this.lastFocusState !== null) {
+          subscriber.onFocusChange(this.lastFocusState)
+        }
+      } catch (error) {
+        this.reportError(error)
+      }
+    }
+
+    let unsubscribed = false
+    return () => {
+      if (unsubscribed) return
+      unsubscribed = true
+      this.focusSubscribers.delete(subscriber)
+      if (this.disposed) return
+      if (this.focusSubscribers.size === 0) {
+        this.setFocusReporting(
+          false,
+          'Could not disable terminal focus reporting',
+        )
+      }
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.focusSubscribers.clear()
+    this.renderer.removeInputHandler(this.handleInput)
+    if (activeController === this) activeController = null
+  }
+}
+
+let activeController: TerminalProtocolController | null = null
+
+export function installTerminalProtocolController(
+  renderer: TerminalProtocolRenderer,
+  options: TerminalProtocolControllerOptions = {},
+): TerminalProtocolController {
+  if (activeController) {
+    throw new Error('terminal protocol controller is already installed')
+  }
+  const controller = new TerminalProtocolController(renderer, options)
+  activeController = controller
+  return controller
+}
+
+export function getTerminalProtocolController(): TerminalProtocolController | null {
+  return activeController
+}

package/src/utils/terminal-reset-sequences.ts

@@ -0,0 +1,33 @@
+/**
+ * Terminal escape sequences to reset terminal state.
+ * Shared by the in-process cleanup handlers (renderer-cleanup.ts) and the
+ * sacrificial watchdog process (terminal-watchdog.ts).
+ *
+ * Keep this list in sync with the modes OpenTUI enables (see the enable
+ * sequences in @opentui/core's native lib) and with
+ * SAFE_TERMINAL_RESET_SEQUENCES in the npm release launcher
+ * (cli/release-core/launcher.js).
+ *
+ * Sequences:
+ * - \x1b[?1049l: Exit alternate screen buffer (restores main screen)
+ * - \x1b[?1000l: Disable X10 mouse mode
+ * - \x1b[?1002l: Disable button event mouse mode
+ * - \x1b[?1003l: Disable any-event mouse mode (all motion tracking)
+ * - \x1b[?1006l: Disable SGR extended mouse mode
+ * - \x1b[?1004l: Disable focus reporting
+ * - \x1b[?2004l: Disable bracketed paste mode
+ * - \x1b[<u:     Pop the kitty keyboard protocol flags OpenTUI pushes
+ * - \x1b[>4;0m:  Reset xterm modifyOtherKeys (OpenTUI sets [>4;1m)
+ * - \x1b[?25h:   Show cursor (safety measure)
+ */
+export const TERMINAL_RESET_SEQUENCES =
+  '\x1b[?1049l' + // Exit alternate screen buffer
+  '\x1b[?1000l' + // Disable X10 mouse mode
+  '\x1b[?1002l' + // Disable button event mouse mode
+  '\x1b[?1003l' + // Disable any-event mouse mode (all motion)
+  '\x1b[?1006l' + // Disable SGR extended mouse mode
+  '\x1b[?1004l' + // Disable focus reporting
+  '\x1b[?2004l' + // Disable bracketed paste mode
+  '\x1b[<u' + // Pop kitty keyboard protocol flags
+  '\x1b[>4;0m' + // Reset modifyOtherKeys
+  '\x1b[?25h' // Show cursor

package/src/utils/terminal-title.ts

@@ -0,0 +1,84 @@
+/**
+ * Terminal title utilities using OSC (Operating System Command) escape sequences.
+ *
+ * OSC sequence format for setting title:
+ * - `\x1b]0;${title}\x07` - Sets both window title and icon name
+ * - `\x1b` is ESC, `]0;` starts the title command, `\x07` (BEL) ends it
+ *
+ * We write directly to /dev/tty to bypass OpenTUI's stdout capture,
+ * similar to how clipboard.ts handles OSC52 sequences.
+ */
+
+import { IS_FREEBUFF } from './constants'
+import { getCliEnv } from './env'
+import { writeTerminalControlSync } from './terminal-io'
+
+const MAX_TITLE_LENGTH = 60
+const TITLE_PREFIX = IS_FREEBUFF ? 'Freebuff: ' : 'Anvil: '
+const OSC_TERMINATOR = '\x07' // BEL
+
+function isInTmux(env: ReturnType<typeof getCliEnv>): boolean {
+  return Boolean(env.TMUX)
+}
+
+function isInScreen(env: ReturnType<typeof getCliEnv>): boolean {
+  if (env.STY) return true
+  const term = env.TERM ?? ''
+  return term.startsWith('screen') && !isInTmux(env)
+}
+
+/**
+ * Build the OSC title sequence with tmux/screen passthrough if needed
+ */
+function buildTitleSequence(title: string, env: ReturnType<typeof getCliEnv>): string {
+  const osc = `\x1b]0;${title}${OSC_TERMINATOR}`
+
+  // tmux passthrough: wrap in DCS and double ESC characters
+  if (isInTmux(env)) {
+    const escaped = osc.replace(/\x1b/g, '\x1b\x1b')
+    return `\x1bPtmux;${escaped}\x1b\\`
+  }
+
+  // GNU screen passthrough: wrap in DCS
+  if (isInScreen(env)) {
+    return `\x1bP${osc}\x1b\\`
+  }
+
+  return osc
+}
+
+/**
+ * Set the terminal window title.
+ * Works on most modern terminal emulators, including through tmux and screen.
+ *
+ * @param title - The title to set (will be truncated if too long)
+ */
+export function setTerminalTitle(title: string): void {
+  // Sanitize: remove control characters and newlines
+  const sanitized = title.replace(/[\x00-\x1f\x7f]/g, ' ').trim()
+  if (!sanitized) return
+
+  // Truncate to reasonable length
+  const maxInputLength = MAX_TITLE_LENGTH - TITLE_PREFIX.length
+  const truncated =
+    sanitized.length > maxInputLength
+      ? sanitized.slice(0, maxInputLength - 1) + '…'
+      : sanitized
+
+  const fullTitle = `${TITLE_PREFIX}${truncated}`
+  const env = getCliEnv()
+  const sequence = buildTitleSequence(fullTitle, env)
+
+  writeTerminalControlSync(sequence)
+}
+
+/**
+ * Reset the terminal title to the default.
+ * Call this when the CLI exits to restore the terminal to a clean state.
+ */
+export function resetTerminalTitle(): void {
+  // Empty title resets to terminal's default behavior
+  const env = getCliEnv()
+  const sequence = buildTitleSequence('', env)
+  writeTerminalControlSync(sequence)
+}