Class Shell

Source: shell.ts

A Unix-like shell emulator that handles command parsing, environment management, autocompletion, and process I/O.

Constructors

Constructor

new Shell(config: ShellConfig): Shell

Parameters

config

ShellConfig

Returns

Shell

Properties

state

state: ShellState

The reactive state of this shell.

---

config

config: ShellConfig

The configuration used to initialize this shell.

---

env

env: ShellEnvironment

The environment variable manager for this shell.

---

interpreter

interpreter: ShellInterpreter

The logic handler for parsing and executing command strings.

---

COMMAND_NOT_FOUND_ERROR

readonly static COMMAND_NOT_FOUND_ERROR: "Command not found" = "Command not found"

---

MISSING_ARGS_ERROR

readonly static MISSING_ARGS_ERROR: "requires at least 1 argument" = "requires at least 1 argument"

---

MISSING_OPTIONS_ERROR

readonly static MISSING_OPTIONS_ERROR: "requires at least 1 option" = "requires at least 1 option"

---

COMMAND_FAILED_ERROR

readonly static COMMAND_FAILED_ERROR: "Command failed" = "Command failed"

---

USAGE_ERROR

readonly static USAGE_ERROR: "Incorrect usage" = "Incorrect usage"

---

INVALID_PATH_ERROR

readonly static INVALID_PATH_ERROR: "No such file or directory" = "No such file or directory"

---

SUDO_COMMAND

readonly static SUDO_COMMAND: "sudo" = "sudo"

---

STRIP_ANSI_REGEX

readonly static STRIP_ANSI_REGEX: RegExp

Regex used to strip specific ANSI escape codes from the TTY buffer.

Methods

terminate()

terminate(signal: StreamSignal): void

Sends a signal to the shell or the currently active foreground process.

Parameters

signal

StreamSignal = "SIGTERM"

The signal to send. Defaults to "SIGTERM".

Returns

void

---

interrupt()

interrupt(): void

Convenience method to send the SIGINT (Interrupt) signal.

Returns

void

See

Shell.terminate

---

kill()

kill(): void

Convenience method to send the SIGKILL (Kill) signal, closing the shell.

Returns

void

See

Shell.terminate

---

updatePrompt()

updatePrompt(): void

Recalculates the prompt string based on the current user, hostname, and working directory.

Returns

void

---

setLine()

setLine(value: string | (prev: string) => string): void

Updates the text in the current input line.

Parameters

value

The new string value or a function that receives the previous value.

string | (prev: string) => string

Returns

void

---

pushHistory()

pushHistory(entry: HistoryEntry): void

Appends a new entry to the terminal history.

Parameters

entry

HistoryEntry

The history entry to add.

Returns

void

---

write()

write(text: string): void

Writes raw text to the shell, handling ANSI escape codes for screen clearing and alt buffers.

Parameters

text

string

The string data to write to the TTY.

Returns

void

---

run()

run(input: string): Promise<number>

Clears the current input line and executes the given command string.

Parameters

input

string

The command string to execute.

Returns

Promise<number>

A promise that resolves with the final exit code of the execution.

---

clearLine()

clearLine(): void

Clears the current input line and resets the history search offset.

Returns

void

---

historySearch()

historySearch(direction: number): void

Navigates through command history.

Parameters

direction

number

Positive to go back in time, negative to go forward.

Returns

void

---

setWorkingDirectory()

setWorkingDirectory(directory: VirtualFolder): void

Changes the current working directory and updates PWD/OLDPWD environment variables.

Parameters

directory

VirtualFolder

The virtual folder to switch to.

Returns

void

---

getCompletions()

getCompletions(): string[]

Calculates possible completions for the current input based on commands and file paths.

Returns

string[]

An array of string suggestions.

---

autoComplete()

autoComplete(): void

Performs an auto-completion action. If one match is found, it completes the line. If multiple are found, it lists them in the history.

Returns

void

---

writeError()

static writeError(stream: Stream, commandName: string, error: string | string[], exitCode: number): number

Utility to write a formatted error message to a stream and return an exit code.

Parameters

stream

Stream

The stream to receive the error output.

commandName

string

The name of the command reporting the error.

error

A single string or array of strings representing the error message.

string | string[]

exitCode

number = EXIT_CODE.generalError

The numerical exit code to return.

Returns

number

exitCode.

---

animate()

static animate(__namedParameters: Pick<ShellContext, "stdin" | "stdout"> & { render: (frame: number) => string; delay: number; clear?: boolean; stopOnBlank?: boolean; }): Promise<0>

Executes a frame-based animation in the terminal using the Alternate Screen Buffer.

Parameters

__namedParameters

Pick<ShellContext, "stdin" | "stdout"> & { render: (frame: number) => string; delay: number; clear?: boolean; stopOnBlank?: boolean; }

Returns

Promise<0>

A promise that resolves when the animation is stopped.

---

readInput()

static readInput(rawLine: string, stdin: Stream, callback: (data: string) => CommandOutput): Promise<CommandOutput>

Reads input data. If rawLine is provided, it processes it immediately via the callback. Otherwise, it waits for data from the stdin stream.

Parameters

rawLine

string

The pre-provided input string.

stdin

Stream

The input stream to fall back on.

callback

(data: string) => CommandOutput

Function to process the collected input data.

Returns

Promise<CommandOutput>