@silvery/term 0.3.0

package/src/non-tty.ts

@@ -0,0 +1,223 @@
+/**
+ * Non-TTY Mode Support for Silvery
+ *
+ * Provides detection and rendering modes for non-interactive environments:
+ * - Piped output (process.stdout.isTTY === false)
+ * - CI environments
+ * - TERM=dumb
+ *
+ * When in non-TTY mode, silvery avoids cursor positioning codes that garble
+ * output in non-interactive environments.
+ *
+ * Modes:
+ * - 'auto': Detect based on environment (default)
+ * - 'tty': Force TTY mode (normal cursor positioning)
+ * - 'line-by-line': Simple newline-separated output, no cursor movement
+ * - 'static': Single output at end (no updates)
+ * - 'plain': Strip all ANSI codes
+ */
+
+import { stripAnsi } from "./unicode"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Non-TTY rendering mode.
+ *
+ * - 'auto': Auto-detect based on environment
+ * - 'tty': Force TTY mode with cursor positioning
+ * - 'line-by-line': Output lines without cursor repositioning
+ * - 'static': Single final output only
+ * - 'plain': Strip all ANSI escape codes
+ */
+export type NonTTYMode = "auto" | "tty" | "line-by-line" | "static" | "plain"
+
+/**
+ * Options for non-TTY output.
+ */
+export interface NonTTYOptions {
+  /** The rendering mode. Default: 'auto' */
+  mode?: NonTTYMode
+  /** Output stream to check for TTY status. Default: process.stdout */
+  stdout?: NodeJS.WriteStream
+}
+
+/**
+ * Resolved non-TTY mode after auto-detection.
+ */
+export type ResolvedNonTTYMode = Exclude<NonTTYMode, "auto">
+
+// ============================================================================
+// Detection
+// ============================================================================
+
+/**
+ * Check if the environment is a TTY.
+ *
+ * Returns false if:
+ * - stdout.isTTY is false or undefined
+ * - TERM=dumb
+ * - CI environment variables are set
+ */
+export function isTTY(stdout: NodeJS.WriteStream = process.stdout): boolean {
+  // Check stdout.isTTY
+  if (!stdout.isTTY) {
+    return false
+  }
+
+  // Check TERM=dumb
+  if (process.env.TERM === "dumb") {
+    return false
+  }
+
+  // Check common CI environment variables
+  if (
+    process.env.CI ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.JENKINS_URL ||
+    process.env.BUILDKITE ||
+    process.env.CIRCLECI ||
+    process.env.TRAVIS
+  ) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Resolve the non-TTY mode based on options and environment.
+ *
+ * When mode is 'auto':
+ * - If TTY detected: returns 'tty'
+ * - If non-TTY detected: returns 'line-by-line'
+ */
+export function resolveNonTTYMode(options: NonTTYOptions = {}): ResolvedNonTTYMode {
+  const { mode = "auto", stdout = process.stdout } = options
+
+  if (mode !== "auto") {
+    return mode
+  }
+
+  // Auto-detect based on environment
+  return isTTY(stdout) ? "tty" : "line-by-line"
+}
+
+// Re-export stripAnsi from unicode.ts (canonical implementation)
+export { stripAnsi } from "./unicode"
+
+// ============================================================================
+// Line-by-Line Output
+// ============================================================================
+
+/**
+ * Convert buffer output to line-by-line format.
+ *
+ * Instead of using cursor positioning, outputs each line with a simple
+ * carriage return and clear-to-end-of-line sequence.
+ *
+ * @param content The rendered content (may contain ANSI codes but no cursor positioning)
+ * @param prevLineCount Number of lines in the previous frame (for clearing)
+ * @returns Output string suitable for non-TTY rendering
+ */
+export function toLineByLineOutput(content: string, prevLineCount: number): string {
+  const lines = content.split("\n")
+  let output = ""
+
+  // Move cursor up to overwrite previous content (if any)
+  if (prevLineCount > 0) {
+    // Move to start of first line
+    output += "\r"
+    // Move up
+    if (prevLineCount > 1) {
+      output += `\x1b[${prevLineCount - 1}A`
+    }
+  }
+
+  // Output each line
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0) {
+      output += "\n"
+    }
+    output += lines[i]
+    // Clear to end of line (removes leftover content from longer previous lines)
+    output += "\x1b[K"
+  }
+
+  // Clear any remaining lines from previous frame
+  const extraLines = prevLineCount - lines.length
+  if (extraLines > 0) {
+    for (let i = 0; i < extraLines; i++) {
+      output += "\n\x1b[K"
+    }
+    // Move cursor back up to end of content
+    output += `\x1b[${extraLines}A`
+  }
+
+  return output
+}
+
+/**
+ * Convert buffer output to plain text format.
+ *
+ * Strips all ANSI codes and outputs simple newline-separated text.
+ * No cursor movement or clearing.
+ *
+ * @param content The rendered content
+ * @param prevLineCount Number of lines in the previous frame (unused in plain mode)
+ * @returns Plain text output
+ */
+export function toPlainOutput(content: string, _prevLineCount: number): string {
+  // Strip ANSI codes
+  const plain = stripAnsi(content)
+
+  // Trim trailing whitespace from each line but preserve structure
+  const lines = plain.split("\n").map((line) => line.trimEnd())
+
+  // Remove trailing empty lines
+  while (lines.length > 0 && lines[lines.length - 1] === "") {
+    lines.pop()
+  }
+
+  return lines.join("\n")
+}
+
+// ============================================================================
+// Output Helpers
+// ============================================================================
+
+/**
+ * Create an output transformer based on the non-TTY mode.
+ *
+ * @param mode The resolved non-TTY mode
+ * @returns A function that transforms output based on the mode
+ */
+export function createOutputTransformer(mode: ResolvedNonTTYMode): (content: string, prevLineCount: number) => string {
+  switch (mode) {
+    case "tty":
+      // Pass through unchanged
+      return (content) => content
+
+    case "line-by-line":
+      return toLineByLineOutput
+
+    case "static":
+      // For static mode, we return empty string for intermediate renders
+      // The final render is handled by the caller
+      return () => ""
+
+    case "plain":
+      return toPlainOutput
+  }
+}
+
+/**
+ * Count the number of lines in a string.
+ */
+export function countLines(str: string): number {
+  if (!str) return 0
+  return str.split("\n").length
+}

package/src/osc-markers.ts

@@ -0,0 +1,32 @@
+/**
+ * OSC 133 Semantic Prompt Markers
+ *
+ * Shell integration protocol that marks prompts and commands in terminal output.
+ * Terminals like iTerm2, Kitty, and WezTerm use these markers to provide
+ * "jump to previous/next prompt" navigation (Cmd+Up/Cmd+Down in iTerm2).
+ *
+ * Protocol: OSC 133
+ * - Prompt start:         ESC ] 133 ; A BEL     (before user input)
+ * - Prompt end:           ESC ] 133 ; B BEL     (after user input, before command output)
+ * - Command output start: ESC ] 133 ; C BEL     (before command output)
+ * - Command output end:   ESC ] 133 ; D ; N BEL (after command output, N = exit code)
+ *
+ * For a chat-style app, each "exchange" (user prompt + assistant response) maps to:
+ * - 133;A before the user's message
+ * - 133;B after the user's message
+ * - 133;C before the assistant's response
+ * - 133;D;0 after the assistant's response
+ *
+ * Supported by: iTerm2, Kitty, WezTerm, foot, Ghostty
+ */
+
+export const OSC133 = {
+  /** Mark prompt start (before user input) */
+  promptStart: "\x1b]133;A\x07",
+  /** Mark prompt end (after user input, before command output) */
+  promptEnd: "\x1b]133;B\x07",
+  /** Mark command output start */
+  commandStart: "\x1b]133;C\x07",
+  /** Mark command output end (exit code defaults to 0 = success) */
+  commandEnd: (exitCode?: number) => `\x1b]133;D;${exitCode ?? 0}\x07`,
+} as const

package/src/osc-palette.ts

@@ -0,0 +1,169 @@
+/**
+ * OSC 4 Terminal Color Palette Query/Set
+ *
+ * Provides functions to query and set terminal color palette entries (indices 0-255)
+ * via the OSC 4 protocol. This enables runtime introspection of the terminal's
+ * actual color scheme.
+ *
+ * Protocol: OSC 4
+ * - Query:    ESC ] 4 ; <index> ; ? BEL
+ * - Set:      ESC ] 4 ; <index> ; <color> BEL
+ * - Response: ESC ] 4 ; <index> ; rgb:RRRR/GGGG/BBBB ST
+ *
+ * The response format uses 4-digit hex per channel (e.g., rgb:ffff/0000/ffff).
+ * Some terminals may use 2-digit hex (rgb:ff/00/ff). Both are handled.
+ *
+ * Terminators: BEL (\x07) or ST (ESC \) — both are accepted in responses.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, iTerm2, foot, Alacritty, rxvt-unicode
+ *
+ * ## Theme Detection Potential (km-tui integration)
+ *
+ * This module provides the primitives needed to auto-detect terminal color schemes:
+ *
+ * 1. Query colors 0-15 (ANSI 16 palette) on startup with queryMultiplePaletteColors()
+ * 2. Parse responses with parsePaletteResponse()
+ * 3. Derive dark/light mode from background luminance:
+ *    - Query OSC 11 (background color) or use palette color 0 as proxy
+ *    - Convert to relative luminance: L = 0.2126*R + 0.7152*G + 0.0722*B
+ *    - L > 0.5 → light theme, L <= 0.5 → dark theme
+ * 4. Optionally adjust theme colors based on actual palette values
+ *    (e.g., map $primary to the terminal's blue if it's close enough)
+ *
+ * This is NOT implemented here — just the raw OSC 4 primitives.
+ * The km-tui theme system would consume these to adapt its ThemeProvider.
+ */
+
+const ESC = "\x1b"
+const BEL = "\x07"
+
+// ============================================================================
+// Query
+// ============================================================================
+
+/**
+ * Write an OSC 4 query sequence for a single palette color index.
+ *
+ * The terminal will respond with:
+ *   ESC ] 4 ; <index> ; rgb:RRRR/GGGG/BBBB ST
+ *
+ * Use parsePaletteResponse() to decode the response.
+ *
+ * @param index Palette index (0-255)
+ * @param write Function to write data to the terminal (e.g., stdout.write.bind(stdout))
+ */
+export function queryPaletteColor(index: number, write: (data: string) => void): void {
+  if (index < 0 || index > 255) throw new RangeError(`Palette index must be 0-255, got ${index}`)
+  write(`${ESC}]4;${index};?${BEL}`)
+}
+
+/**
+ * Write OSC 4 query sequences for multiple palette color indices.
+ *
+ * Sends one query per index. Terminals process these sequentially
+ * and respond with one OSC 4 response per query.
+ *
+ * @param indices Array of palette indices (each 0-255)
+ * @param write Function to write data to the terminal
+ */
+export function queryMultiplePaletteColors(indices: number[], write: (data: string) => void): void {
+  for (const index of indices) {
+    queryPaletteColor(index, write)
+  }
+}
+
+// ============================================================================
+// Set
+// ============================================================================
+
+/**
+ * Write an OSC 4 sequence to set a palette color.
+ *
+ * The color can be in any X11 color format accepted by the terminal:
+ * - `rgb:RR/GG/BB` or `rgb:RRRR/GGGG/BBBB` (X11 rgb spec)
+ * - `#RRGGBB` (CSS hex — widely supported)
+ * - Named colors (e.g., `red`, `blue` — terminal-dependent)
+ *
+ * @param index Palette index (0-255)
+ * @param color Color specification string
+ * @param write Function to write data to the terminal
+ */
+export function setPaletteColor(index: number, color: string, write: (data: string) => void): void {
+  if (index < 0 || index > 255) throw new RangeError(`Palette index must be 0-255, got ${index}`)
+  write(`${ESC}]4;${index};${color}${BEL}`)
+}
+
+// ============================================================================
+// Response Parsing
+// ============================================================================
+
+/** OSC 4 response prefix */
+const OSC4_PREFIX = `${ESC}]4;`
+
+/**
+ * Regex for the OSC 4 response body: `<index>;rgb:<R>/<G>/<B>`
+ * Captures: index, R, G, B (each 1-4 hex digits)
+ */
+const OSC4_BODY_RE = /^(\d+);rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})$/
+
+/**
+ * Parse an OSC 4 palette color response.
+ *
+ * Handles both standard 4-digit hex (rgb:RRRR/GGGG/BBBB) and
+ * abbreviated 2-digit hex (rgb:RR/GG/BB) formats.
+ *
+ * Handles both BEL (\x07) and ST (ESC \) terminators.
+ *
+ * @param input Raw terminal input string
+ * @returns Parsed result with index and normalized color string, or null if not an OSC 4 response
+ */
+export function parsePaletteResponse(input: string): { index: number; color: string } | null {
+  const prefixIdx = input.indexOf(OSC4_PREFIX)
+  if (prefixIdx === -1) return null
+
+  const bodyStart = prefixIdx + OSC4_PREFIX.length
+
+  // Find terminator: BEL (\x07) or ST (ESC \)
+  let bodyEnd = input.indexOf(BEL, bodyStart)
+  if (bodyEnd === -1) {
+    bodyEnd = input.indexOf(`${ESC}\\`, bodyStart)
+  }
+  if (bodyEnd === -1) return null
+
+  const body = input.slice(bodyStart, bodyEnd)
+  const match = OSC4_BODY_RE.exec(body)
+  if (!match) return null
+
+  const index = Number.parseInt(match[1]!, 10)
+  if (index < 0 || index > 255) return null
+
+  // Normalize color channels to 2-digit hex (scale 4-digit to 2-digit)
+  const r = normalizeHexChannel(match[2]!)
+  const g = normalizeHexChannel(match[3]!)
+  const b = normalizeHexChannel(match[4]!)
+
+  return { index, color: `#${r}${g}${b}` }
+}
+
+/**
+ * Normalize a hex color channel to 2-digit hex.
+ *
+ * - 1-digit: repeat (e.g., "f" -> "ff")
+ * - 2-digit: as-is
+ * - 3-digit: take first 2 (e.g., "fff" -> "ff")
+ * - 4-digit: take first 2 (e.g., "ffff" -> "ff", "1a2b" -> "1a")
+ */
+function normalizeHexChannel(hex: string): string {
+  switch (hex.length) {
+    case 1:
+      return hex + hex
+    case 2:
+      return hex
+    case 3:
+      return hex.slice(0, 2)
+    case 4:
+      return hex.slice(0, 2)
+    default:
+      return hex.slice(0, 2)
+  }
+}