import type { Bash, CommandContext } from "@everruns/bashkit-wasm"; import type { PtyProcess, RunningProcess } from "@nibling/kernel"; import type { SandboxKernel } from "@nibling/sandbox/client"; import { launch, resolve, type Launch } from "./launch.ts"; import { PROCESS_ENV, PROJECT_ROOT, kernelPath, type Sandbox } from "./sandbox.ts"; import type { Unsubscribe, Workbench } from "./shell/workbench.ts"; import { binFunctions, nodeBins } from "./terminal/bins.ts"; import { hostFs } from "./terminal/host-fs.ts"; import { initialLine, step } from "./terminal/line-editor.ts"; import { touch } from "./terminal/touch.ts"; const encoder = new TextEncoder(); /** The most output a session keeps for a view that connects later. */ const TRANSCRIPT_LIMIT = 1 << 20; let bashkit: Promise | undefined; /** bashkit and its wasm, loaded once and only when a terminal starts. */ const loadBashkit = () => (bashkit ??= Promise.all([import("@everruns/bashkit-wasm"), import("@everruns/bashkit-wasm/bashkit_wasm_bg.wasm?url")]).then(async ([module, wasm]) => { await module.initBashkit(wasm.default); return module; })); /** * A `\n` becomes `\r\n` unless a `\r` precedes it. pty output already carries its own, so this is a * no-op there. It works on bytes so piped binary output passes through, carrying the last byte * across chunks. */ function crlf() { let lastCR = false; return (bytes: Uint8Array) => { const out: number[] = []; for (let i = 0; i < bytes.length; i++) { const b = bytes[i]!; if (b === 0x0a && !(i === 0 ? lastCR : bytes[i - 1] === 0x0d)) out.push(0x0d); out.push(b); lastCR = b === 0x0d; } return new Uint8Array(out); }; } /** * `analyze` throws for input bash knows is unfinished (an open quote, an `if` with no `fi`, a * trailing `$(`). It accepts three other unfinished forms, which the session measures itself: a * trailing unescaped `\`, a trailing `&&` or `||`, and an open heredoc. */ const analyzeSaysIncomplete = (message: string) => /unexpected EOF|unexpected end of file|unterminated/i.test(message); function trailingBackslash(text: string): boolean { let n = 0; for (let i = text.length - 1; i >= 0 && text[i] === "\\"; i--) n++; return n % 2 === 1; } const trailingAndOr = (text: string) => /(?:&&|\|\|)\s*$/.test(text); function openHeredoc(text: string): boolean { const lines = text.split("\n"); for (const m of text.matchAll(/<<(-?)\s*(['"]?)([A-Za-z_]\w*)\2/g)) { const start = text.slice(0, m.index).split("\n").length - 1; if (!lines.slice(start + 1).some((line) => (m[1] ? line.replace(/^\t+/, "") : line) === m[3])) return true; } return false; } /** A trailing `\` continues the line without a break; anything else (a heredoc, a trailing `&&`) keeps it. */ const joinContinuation = (pending: string, line: string) => (trailingBackslash(pending) ? pending.slice(0, -1) + line : `${pending}\n${line}`); const LAUNCHED = new Set(["node", "npm", "npx"]); type State = /** Booting the kernel and bash; keys wait as typeahead. */ | { readonly tag: "starting" } /** The sandbox didn't start, so there is no shell. */ | { readonly tag: "dead" } /** The line editor has the keys. */ | { readonly tag: "idle" } /** A line is running: keys wait as typeahead and ^C interrupts it. */ | { readonly tag: "running" } /** A process on the pty has the keys. */ | { readonly tag: "foreground"; readonly proc: PtyProcess }; /** * One terminal's bash (bashkit) on the kernel's filesystem, headless so it outlives its view (D12). * `node`, `npm`, and `npx` run as kernel processes, a package's bin runs through `node` (see * terminal/bins.ts), and `open` and `preview` open panels on the workbench a view attached. It * speaks bytes both ways: `input` takes what a terminal emulator sends and `onOutput` gives what to * draw. A line made of one launched command runs on a pty, so it gets colors, raw keys, and ^C. */ export class TerminalSession { readonly sandbox: Sandbox; /** Where the shell started, in the project's namespace. */ readonly cwd: string; #chunks: Uint8Array[] = []; #size = 0; /** The last byte printed, so a prompt after output with no final newline starts on its own line. */ #last = 0x0a; #listeners = new Set<(chunk: Uint8Array) => void>(); #workbench: Workbench | undefined; #cols = 80; #rows = 24; #state: State = { tag: "starting" }; #bash: Bash | undefined; #kernel: SandboxKernel | undefined; #live = new Set(); #line = initialLine(); #pending: string | null = null; #typeahead = ""; /** Lines `run` was given that haven't been submitted yet, each with who waits for its exit status. */ #requested: { readonly line: string; readonly done: (code: number) => void }[] = []; #foregroundLine = false; #lastExit = 0; #pwd: string; #evals = 0; /** The cursor's row within the prompt and line being edited, counted from the prompt's row. */ #row = 0; constructor(sandbox: Sandbox, cwd: string) { this.sandbox = sandbox; this.cwd = cwd; this.#pwd = kernelPath(cwd) || "/"; void this.#start(); } /** Everything printed so far, up to the last megabyte, for a view to replay. */ get transcript(): readonly Uint8Array[] { return this.#chunks; } /** Whether a line is running or a process has the keys. */ get busy(): boolean { return this.#state.tag === "running" || this.#state.tag === "foreground"; } /** Calls `listener` with each chunk printed from now on. */ onOutput(listener: (chunk: Uint8Array) => void): Unsubscribe { this.#listeners.add(listener); return () => this.#listeners.delete(listener); } /** Where `open` and `preview` open their panels, until the returned function detaches it. */ attach(workbench: Workbench): Unsubscribe { this.#workbench = workbench; return () => { if (this.#workbench === workbench) this.#workbench = undefined; }; } /** The size of the terminal drawing this session, which a foreground process is told about. */ resize(cols: number, rows: number): void { if (cols === this.#cols && rows === this.#rows) return; this.#cols = cols; this.#rows = rows; if (this.#state.tag === "foreground") this.#state.proc.pty.resize(cols, rows); } /** Keys and pastes, as a terminal emulator sends them. */ input(data: string): void { const state = this.#state; switch (state.tag) { case "foreground": return state.proc.pty.write(data); case "running": // Keys typed while a line runs wait for whoever reads the tty next, a process that takes the // pty or the next prompt; ^C drops them, as ISIG does. if (!data.includes("\x03")) return void (this.#typeahead += data); this.#typeahead = ""; for (const proc of this.#live) proc.kill("SIGINT"); return this.#bash?.cancel(); case "starting": return void (this.#typeahead += data); case "dead": return; case "idle": return this.#edit(data); } } /** * Runs `line` as if it were typed at the prompt, replacing what was typed so far. `workbench` is * where `open` and `preview` go until a view attaches its own. Settles with the line's exit status. */ run(line: string, workbench: Workbench): Promise { this.#workbench ??= workbench; if (this.#state.tag === "dead") return Promise.resolve(127); const exited = new Promise((done) => this.#requested.push({ line, done })); if (this.#state.tag === "idle") { this.#edit("\x05"); this.#edit("\x15"); } this.input(`${line}\r`); return exited; } /** Ends every process the session started. */ dispose(): void { for (const proc of this.#live) proc.kill("SIGKILL"); } #write(chunk: Uint8Array | string): void { const bytes = typeof chunk === "string" ? encoder.encode(chunk) : chunk; if (!bytes.length) return; this.#chunks.push(bytes); this.#size += bytes.length; this.#last = bytes[bytes.length - 1]!; while (this.#size > TRANSCRIPT_LIMIT && this.#chunks.length > 1) this.#size -= this.#chunks.shift()!.length; for (const listener of this.#listeners) listener(bytes); } async #start(): Promise { const announced = !this.sandbox.ready; if (announced) this.#write("Starting sandbox…\r\n"); try { const [kernel, { Bash }] = await Promise.all([this.sandbox.kernel, loadBashkit()]); this.#kernel = kernel; this.#bash = new Bash({ // A terminal line runs as long as it runs (a dev server, a watcher); bashkit's default // profile ends any line after 30 seconds. profile: "interactive", timeoutMs: 2 ** 31 - 1, fs: hostFs(kernel.fs, (path) => this.sandbox.pull(path)), cwd: this.#pwd, env: { ...PROCESS_ENV, TERM: "xterm-256color", COLORTERM: "truecolor" }, commands: { node: (ctx) => this.#launch(ctx), npm: (ctx) => this.#launch(ctx), npx: (ctx) => this.#launch(ctx), open: (ctx) => this.#open(ctx, "editor"), preview: (ctx) => this.#open(ctx, "preview"), touch: (ctx) => this.#touch(ctx), }, }); } catch (error) { this.#state = { tag: "dead" }; return this.#write(`The sandbox did not start: ${error instanceof Error ? error.message : String(error)}\r\n`); } if (announced) { this.#write("\x1b[1A\x1b[2K"); this.#last = 0x0a; } this.#idle(); } #idle(): void { this.#state = { tag: "idle" }; this.#row = 0; // `printf hi`, or a ^C the pty echoed, leaves the cursor mid-line; the prompt redraws its own row. if (this.#last !== 0x0a) this.#write("\r\n"); this.#redraw(this.#line.buffer, this.#line.cursor); // A tty hands the shell typeahead one line per read, so each queued line runs, and enters // history, on its own; what follows a line that starts running waits for the next prompt. let keys = this.#typeahead; this.#typeahead = ""; while (keys && this.#state.tag === "idle") { const end = keys.indexOf("\r") + 1 || keys.length; this.#edit(keys.slice(0, end)); keys = keys.slice(end); } this.#typeahead = keys + this.#typeahead; } #prompt(): string { if (this.#pending !== null) return "> "; const shown = this.#pwd.replace(new RegExp(`^${PROJECT_ROOT}(?=/|$)`), "~"); return `\x1b[2m${shown}\x1b[0m \x1b[32m$\x1b[0m `; } /** * Repaints the prompt and `echo` from the prompt's row, clearing what a longer line left, then puts * the cursor `cursor` characters into `echo`. The line wraps at the terminal's width, so the * cursor's row and column are worked out from it. */ #redraw(echo: string, cursor: number): void { const cols = this.#cols; const prompt = this.#prompt(); const width = prompt.replace(/\x1b\[[\d;]*m/g, "").length; const end = width + echo.length; const at = width + cursor; let out = `${this.#row ? `\x1b[${this.#row}A` : ""}\r\x1b[J${prompt}${echo}`; // A line that fills its last row exactly leaves the cursor waiting at that row's end. const full = end > 0 && end % cols === 0; let row = full ? end / cols - 1 : Math.floor(end / cols); if (at === end && full) { out += "\r\n"; row++; } else if (at !== end) { const target = Math.floor(at / cols); out += `\r${row > target ? `\x1b[${row - target}A` : ""}${at % cols ? `\x1b[${at % cols}C` : ""}`; row = target; } this.#row = row; this.#write(out); } #edit(data: string): void { const result = step(this.#line, data); this.#line = result.state; if (result.clear) { this.#write("\x1b[2J\x1b[H"); this.#row = 0; return this.#redraw(result.echo, result.state.cursor); } if (result.interrupt) { this.#pending = null; this.#row = 0; return this.#write(`^C\r\n${this.#prompt()}`); } if (result.submit === undefined) return this.#redraw(result.echo, result.state.cursor); // A paste or replayed typeahead submits text that was never drawn key by key. const [first = "", ...more] = result.submit.split("\n"); this.#redraw(first, first.length); this.#write(more.map((line) => `\r\n> ${line}`).join("") + "\r\n"); this.#row = 0; this.#submit(result.submit); // Text typed after the last line break of a paste stays on the new prompt. if (this.#state.tag === "idle" && result.echo) this.#redraw(result.echo, result.state.cursor); } #submit(line: string): void { const bash = this.#bash!; const candidate = this.#pending === null ? line : joinContinuation(this.#pending, line); let names: string[] = []; let functions: string[] = []; let error: string | undefined; try { const analysis = bash.analyze(candidate); names = analysis.commandNames; functions = analysis.functions; this.#foregroundLine = analysis.commands.length === 1 && !analysis.redirects.length && !analysis.hasCommandSubstitution; } catch (e) { const message = e instanceof Error ? e.message : String(e); if (analyzeSaysIncomplete(message)) { this.#pending = candidate; return this.#write(this.#prompt()); } error = message; } if (error === undefined && (trailingBackslash(candidate) || trailingAndOr(candidate) || openHeredoc(candidate))) { this.#pending = candidate; return this.#write(this.#prompt()); } this.#pending = null; const requested = this.#requested[0]?.line === candidate ? this.#requested.shift() : undefined; // Reported from the line as typed, since the line that runs starts with `(exit n);`. if (error !== undefined) { this.#lastExit = 2; requested?.done(2); return this.#write(`bash: ${error}\r\n${this.#prompt()}`); } this.#state = { tag: "running" }; void this.#run(candidate, names, functions).finally(() => { this.#idle(); requested?.done(this.#lastExit); }); } async #run(text: string, names: string[], functions: string[]): Promise { const bash = this.#bash!; const out = crlf(); const err = crlf(); const candidates = names.filter((name) => !LAUNCHED.has(name) && !functions.includes(name)); const bins = candidates.length ? await nodeBins(this.#kernel!.fs, candidates, await this.#env("PATH"), this.#pwd) : new Map(); // A lone command that is a package's bin runs on the pty, as node itself would. if (this.#foregroundLine) this.#foregroundLine = LAUNCHED.has(names[0] ?? "") || bins.has(names[0] ?? ""); bash.clearCancel(); try { if (bins.size) await bash.execute(binFunctions(bins), { capture: 0 }); // Each execute starts `$?` at 0, so the line is seeded with the status the last one left. const result = await bash.execute(`(exit ${this.#lastExit}); ${text}`, { stdout: (bytes: Uint8Array) => this.#write(out(bytes)), stderr: (bytes: Uint8Array) => this.#write(err(bytes)), capture: 0, }); this.#lastExit = result.exitCode; } catch (e) { this.#write(err(encoder.encode(`bash: ${e instanceof Error ? e.message : String(e)}\n`))); this.#lastExit = 2; } finally { if (bins.size) await bash.execute(`unset -f ${[...bins.keys()].join(" ")}`, { capture: 0 }).catch(() => {}); } this.#pwd = (await this.#env("PWD")) || this.#pwd; } async #env(name: string): Promise { const result = await this.#bash!.execute(`printf %s "$${name}"`, { capture: 1 << 16 }); return result.stdout; } async #launch(ctx: CommandContext): Promise { const launched: Launch | undefined = launch([ctx.name, ...ctx.argv], ctx.cwd, () => ++this.#evals); if (!launched) return 127; if ("error" in launched) { await ctx.stderr.write(encoder.encode(`${launched.error}\n`)); return launched.code; } const kernel = this.#kernel!; if (launched.source !== undefined) await kernel.fs.writeFile(launched.entry, launched.source); try { return await this.#exec(kernel, ctx, launched.entry, [...launched.argv]); } finally { if (launched.source !== undefined) await kernel.fs.unlink(launched.entry).catch(() => {}); } } async #exec(kernel: SandboxKernel, ctx: CommandContext, entry: string, argv: string[]): Promise { const options = { argv, cwd: ctx.cwd, env: { ...ctx.env } }; if (this.#foregroundLine) { // One process per line gets the pty; a second launch on the same line (a bin that runs node) pipes. this.#foregroundLine = false; const proc = kernel.exec(entry, { ...options, pty: { cols: this.#cols, rows: this.#rows } }); this.#live.add(proc); this.#state = { tag: "foreground", proc }; // What was typed before the process started is the tty's input, so the process reads it first. if (this.#typeahead) proc.pty.write(this.#typeahead); this.#typeahead = ""; try { await pump(proc.stdout, ctx.stdout); return await proc.exited; } finally { this.#live.delete(proc); this.#state = { tag: "running" }; } } const proc = kernel.exec(entry, options); this.#live.add(proc); const stdin = (async () => { const writer = proc.stdin.getWriter(); for await (const chunk of ctx.stdin) await writer.write(chunk); await writer.close().catch(() => {}); })(); try { await Promise.all([pump(proc.stdout, ctx.stdout), pump(proc.stderr, ctx.stderr)]); return await proc.exited; } finally { stdin.catch(() => {}); this.#live.delete(proc); } } async #touch(ctx: CommandContext): Promise { const { status, errors, touched } = await touch(this.#kernel!.fs, ctx.argv, ctx.cwd); if (errors.length) await ctx.stderr.write(encoder.encode(errors.map((line) => `${line}\n`).join(""))); await Promise.all(touched.map((path) => this.sandbox.pull(path))); return status; } async #open(ctx: CommandContext, kind: "editor" | "preview"): Promise { const [target] = ctx.argv; const fail = async (message: string) => (await ctx.stderr.write(encoder.encode(`${ctx.name}: ${message}\n`)), 1); if (!target) return fail("usage: " + ctx.name + " "); const absolute = resolve(ctx.cwd, target); const path = absolute.startsWith(`${PROJECT_ROOT}/`) ? absolute.slice(PROJECT_ROOT.length + 1) : undefined; if (path === undefined || this.sandbox.files.read(path) === undefined) return fail(`${target}: No such file in the project`); if (!this.#workbench) return fail("no workbench to open it on"); this.#workbench.open({ kind, input: { path } }); return 0; } } async function pump(stream: ReadableStream, sink: { write(bytes: Uint8Array): Promise }): Promise { const reader = stream.getReader(); for (let read = await reader.read(); !read.done; read = await reader.read()) await sink.write(read.value); }