CHANGELOG.md

Changelog

All notable changes to Terminal. Full commit history in chronological order.

Format inspired by Keep a Changelog.

---

Unreleased

None

0.2.0 - 2026-05-22

Added

• Native process hardening options via child_process.spawn():
  • uid/gid config and per-execution options for privilege dropping via setuid/setgid
  • killSignal config and per-execution option (default: SIGTERM)
  • windowsHide config option to hide subprocess console window on Windows
  • windowsVerbatimArguments config option to disable argument quoting on Windows
  • validateSpawnOptions() for validating uid, gid, and killSignal
• Stream listener deduplication in Terminal.stream() to prevent duplicate callbacks
• Auto-cleanup via close and error event handlers in Manager.registerProcess()
• Manager.removeProcess() for explicit process registry cleanup
• Centralized interfaces for previously inline types:
  • SpawnSecurityOptions - Extracted from Validator.validateSpawnOptions() parameter
  • StreamListeners - Extracted from ProcessInfo.streamListeners inline object
  • ProcessRegistrationInput - Extracted from Manager.registerProcess() Omit<ProcessInfo, 'id'> & { id? } parameter
• llm-prompt.md documentation - Safety guard for AI agents executing commands

Changed

• Error messages rewritten across entire codebase to remove colons and describe what is wrong:
  • 'Command not allowed: rm' → 'The command "rm" is not in the allowed list'
  • 'Too many arguments: 5 > max 3' → 'Expected at most 3 arguments but received 5'
  • 'Invalid timeout: ...' → 'Timeout must be a non-negative finite number'
  • 'Workspace not allowed: ...' → 'Workspace "..." is not allowed. Allowed workspaces are ...'
  • All config validation errors now prefixed with 'Config ...' instead of 'Invalid config: ...'
• Method ordering in Terminal, Validator, and Manager classes reorganized by visibility: properties first, then non-private methods A-Z, then private methods A-Z
• validSignals whitelist removed from Validator - Node.js now handles invalid signal validation naturally at the OS level
• resolvePath() in Validator now uses realpathSync() with fallback to resolve() for symlink resolution
• Platform detection switched from Deno.build.os to process.platform in workspace validation
• Workspace validation now checks for null bytes and empty/whitespace-only paths
• Argument validation now checks maxArgs for finite non-negative value before comparing
• Environment variable filtering now skips entries with null bytes in key or value
• Path traversal check now runs before shell metacharacter check in argument validation
• Manager.killProcess() refactored to track abort state and schedule SIGKILL fallback more reliably
• Manager.setProcessTimeout() now guards against non-finite and non-positive timeouts
• Terminal.execute() now validates env is a plain object (not array or primitive)
• Terminal.execute() now validates timeout is a non-negative finite number
• Terminal.execute() now validates spawn options before command parsing
• Terminal.execute() now checks for null bytes in the command string

Documentation

• security.md significantly expanded with native process hardening, threat model, and 8-layer defense-in-depth stack
• configuration.md updated with new spawn options (uid, gid, killSignal, windowsHide, windowsVerbatimArguments)
• interpreter-usage.md streamlined with clearer solutions for running interpreters safely
• examples.md AI Agent Integration example hardened with specific command allowlist, interpreter blocking, and privilege dropping
• llm-prompt.md added to docs with safety guard for AI command execution
• README.md updated with LLM Prompt link in table of contents

Fixed

• Tests updated to match new error message formats across terminal.test.ts, security.test.ts, and validator.test.ts
• Workspace validation test updated for new error message format

0.1.0 - 2026-04-26

Added

• Initial release of @neabyte/terminal
• Terminal class with static methods:
  • execute() - Execute command with security validation
  • kill() - Terminate running process
  • getOutput() - Retrieve captured stdout/stderr
  • getList() - List all tracked processes
  • getExitCode() - Get process exit code
  • stream() - Attach real-time output callbacks
  • initialize() - Configure security policies
  • getConfig() - Get current configuration
  • setConfig() - Update configuration dynamically
• Manager class for process lifecycle:
  • Process registry with unique IDs (term_<uuid>)
  • Background execution support (non-blocking)
  • killAllProcesses() - Bulk termination
  • isProcessRunning() - Status checking
  • setProcessTimeout() - Per-process timeout scheduling
  • Auto-cleanup 5s after process exit
• Validator class for security:
  • ACL pattern matching with wildcards (*)
  • Deny-first priority (deny overrides allow)
  • Command whitelist/denylist
  • Workspace path validation with traversal detection
  • Environment variable filtering (allow/deny patterns)
  • Argument count limiting (maxArgs)
  • Shell metacharacter detection (;, |, &, etc.)
  • Path traversal prevention (../, ..\)
  • Null byte injection protection
• Command execution features:
  • Quoted argument parsing (single and double quotes)
  • Per-command timeout override
  • Real-time streaming callbacks (onStdout, onStderr, onExit)
  • SIGTERM to SIGKILL escalation (2s grace period)
  • AbortController cancellation support
  • shell: false direct execution (no shell interpolation)
  • detached: false for parent group tracking
• TypeScript interfaces:
  • TerminalConfig - Complete configuration types
  • ExecuteOptions - Per-command options
  • ExecuteResult - Execution return type
  • ProcessInfo - Process metadata
  • ValidationResult - Validation return types
• Test suites:
  • Security tests (injection, traversal, bypass attempts)
  • Functional tests (process management, execution)
  • Validator unit tests (patterns, environment, workspace)

Security

• Enforce shell: false to prevent shell metacharacter injection
• Validate all arguments against dangerous characters (;, |, &, `, $(), etc.)
• Block path traversal attempts (../) in arguments and paths
• Restrict execution to configured workspaces only
• Filter environment variables with allow/deny lists
• Limit maximum argument count to prevent abuse
• Use detached: false to keep processes in parent group for tracking

---