Terminal / Shell

A stateful shell engine for terminal UIs: it tracks cwd and env across commands, handles a few builtins in JS, and routes node and script lines to fast paths.

Create a session

const shell = nano.shell({
  cwd: "/root",
  env: { LANG: "en_US.UTF-8" },
  captureStderr: true, // keep stderr separate (costs a redirect)
});

Persistent state

cwd and env persist across run() calls — cd and export update them, and reads expand them.

await shell.run("export GREETING=hi");
const r = await shell.run("echo $GREETING");
console.log(r.stdout); // "hi"
console.log(shell.cwd); // tracks cd

Builtins & routing

• pwd — returns the tracked cwd (no spawn).
• clear — emits a terminal reset sequence.
• export — mutates env on the JS side.
• node … (no operators) — routes straight to nano.node().
• script <source> — runs a host-side Boa engine, when exposed.

Result

run() resolves to a ShellResult — an ExecResult plus cwd, an output alias for stdout, and an optional stderr when captureStderr is enabled.

Wiring to a terminal

async function onEnter(line) {
  await shell.run(line, { onData: (c) => term.write(c) });
  renderPrompt(shell.cwd);
}