@puppuccino/term

Terminal capability detection and environment utilities.

Installation

npm install @puppuccino/term

Or install from GitHub:

npm install github:averagejoeslab/term

Features

• TTY Detection - Check if running in an interactive terminal
• Color Support - Detect color capability level (none, basic, 256, truecolor)
• Environment Detection - CI, Docker, SSH, WSL, and more
• Terminal Info - Size, type, and feature detection
• Input Handling - Raw mode and key event parsing

Usage

TTY Detection

import { isTTY, isInteractive } from '@puppuccino/term';

if (isTTY()) {
  console.log('Running in a terminal');
}

if (isInteractive()) {
  console.log('Can accept user input');
}

Color Support

import { getColorLevel, supportsColor, ColorLevel } from '@puppuccino/term';

const level = getColorLevel();

switch (level) {
  case ColorLevel.None:
    console.log('No color support');
    break;
  case ColorLevel.Basic:
    console.log('16 colors supported');
    break;
  case ColorLevel.Ansi256:
    console.log('256 colors supported');
    break;
  case ColorLevel.TrueColor:
    console.log('16 million colors supported');
    break;
}

// Quick check
if (supportsColor()) {
  console.log('\x1b[32mGreen text!\x1b[0m');
}

Environment Detection

import {
  isCI,
  isDocker,
  isSSH,
  isWSL,
  getTerminalName
} from '@puppuccino/term';

if (isCI()) {
  console.log('Running in CI environment');
}

if (isDocker()) {
  console.log('Running in Docker container');
}

if (isSSH()) {
  console.log('Connected via SSH');
}

if (isWSL()) {
  console.log('Running in Windows Subsystem for Linux');
}

console.log(`Terminal: ${getTerminalName()}`);
// e.g., "iTerm.app", "Terminal.app", "xterm", etc.

Terminal Size

import { getTerminalSize, onResize } from '@puppuccino/term';

const { columns, rows } = getTerminalSize();
console.log(`Terminal is ${columns}x${rows}`);

// Watch for resize events
const unsubscribe = onResize((cols, rows) => {
  console.log(`Resized to ${cols}x${rows}`);
});

// Later: stop watching
unsubscribe();

Terminal Capabilities

import { getCapabilities } from '@puppuccino/term';

const caps = getCapabilities();

console.log({
  color: caps.colorLevel,        // Color support level
  unicode: caps.unicode,          // Unicode support
  hyperlinks: caps.hyperlinks,    // OSC 8 hyperlinks
  images: caps.images,            // Inline images (iTerm2, Kitty)
  mouse: caps.mouse,              // Mouse support
  altScreen: caps.altScreen,      // Alternate screen buffer
  title: caps.title,              // Window title setting
});

Raw Mode Input

import { enableRawMode, disableRawMode, readKey } from '@puppuccino/term';

// Enable raw mode for character-by-character input
enableRawMode();

process.stdin.on('data', (data) => {
  const key = readKey(data);
  console.log('Key pressed:', key);

  if (key.name === 'c' && key.ctrl) {
    disableRawMode();
    process.exit();
  }
});

API Reference

TTY Functions

• isTTY(stream?) - Check if stream is a TTY
• isInteractive() - Check if terminal is interactive

Color Functions

• getColorLevel() - Get color support level
• supportsColor() - Quick color support check
• forceColor(level) - Override color detection

Environment Functions

• isCI() - Detect CI environment
• isDocker() - Detect Docker container
• isSSH() - Detect SSH session
• isWSL() - Detect WSL environment
• getTerminalName() - Get terminal application name

Terminal Functions

• getTerminalSize() - Get terminal dimensions
• onResize(callback) - Watch for size changes
• getCapabilities() - Get all terminal capabilities

Input Functions

• enableRawMode() - Enable raw input mode
• disableRawMode() - Disable raw input mode
• readKey(data) - Parse key from input data

Environment Variables

The following environment variables affect behavior:

• FORCE_COLOR - Force color support (0-3)
• NO_COLOR - Disable all colors
• TERM - Terminal type
• COLORTERM - Color terminal type
• CI - CI environment detection
• TERM_PROGRAM - Terminal application name

License

MIT