AstraShell

A POSIX-style command-line shell built in Node.js. It parses and executes commands the way a real shell does — running external programs, handling pipelines and I/O redirection, managing background jobs, and providing an interactive REPL with tab completion and command history.

Development Status

AstraShell is an actively maintained project in early development.

The core shell is functional, and development is ongoing with a focus on stability, POSIX compatibility, performance, and improving the overall interactive experience.

What's being improved

• Command parsing and execution
• Pipelines and I/O redirection
• Background job handling
• History and tab completion
• Error handling and edge cases
• POSIX compatibility
• Test coverage and documentation

The API and behavior may evolve as the project matures. Contributions, feedback, and bug reports are welcome.

Features

• Command execution — resolves external programs via PATH and runs them with proper argument handling and quoting (single quotes, double quotes, and escape sequences).

• Builtins — cd, pwd, echo, type, exit, history, jobs, declare, and complete.

• Pipelines — chain commands with |, including select builtins (echo, pwd, cd, type) as pipeline stages, by re-invoking the shell as a subprocess so builtin output lands on the correct pipe.

• I/O redirection — >, >>, 2>, 2>>, with stdout and stderr each redirectable to independent targets.

• Background jobs — run commands with a trailing &, track them in a job table, and list them with jobs.

• Command history — in-memory history with history, plus HISTFILE support (history -r to load, -w to write, -a to append only new entries since the last write).

• Tab completion — completes builtin names and executables on PATH, completes filenames/directories for arguments, supports the classic "ring bell, then list all matches on second Tab" behavior, and can delegate to custom completion scripts registered via complete -C.

• Shell variables — declare NAME=VALUE with identifier validation.

Running it

Requires Node.js (v20+ recommended).

./run.sh

or

npm start

This drops you into an interactive prompt:

$ echo hello | tr a-z A-Z
HELLO

$ ls -la > out.txt

$ jobs

$ history

Project Structure

app/
  main.js    # shell REPL, parser, builtins, job control, tab completion
run.sh       # convenience script to run the shell locally

Design Notes

• The parser tokenizes commands respecting single/double quotes and backslash escapes before dispatching to builtins or external processes.
• Builtins that need to act as pipeline stages are re-invoked as a subprocess (node app/main.js --run-builtin ...) so their stdout/stderr can be wired directly into the pipe between commands, rather than threading raw file descriptors through in-process builtin logic.
• Background job numbers are reused once every prior job has been reaped, matching how real shells number jobs.
• Tab-completion state (last completed line, repeated-Tab count) is tracked across calls so the shell can distinguish a first Tab press (bell) from a second (list all matches), the same way bash does.