@alumbwe/anvil 1.0.0 → 1.0.1

package/src/utils/terminal-images.ts

@@ -1,229 +0,0 @@
-/**
- * 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

@@ -1,85 +0,0 @@
-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

@@ -1,173 +0,0 @@
-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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * 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)
-}