@volter/browser-toolbelt 0.1.5 → 0.1.6

package/dist/browser-shell.js

@@ -1,60 +1,158 @@
+import "./shell-buffer-global.js";
 import { Bash, defineCommand } from "just-bash/browser";
+import { commandNotFound } from "@volter/browser-runtime/browser-process-host.js";
+import { confineBrowserFileSystem, intersectProcessFilesystemPolicies, normalizeProcessFilesystemPolicy, requireProcessFilesystemPolicySupport, } from "@volter/browser-runtime/browser-process-filesystem-policy.js";
 import { BrowserShellFileSystem } from "./browser-shell-filesystem.js";
+import { browserRmCommand } from "./browser-rm.js";
 /** AST Bash, standard toolbelt, and a small persistent browser job table. */
 export class BrowserShell {
-    bash;
+    commands = new Map();
     virtualFilesystem;
     filesystem;
     jobs = new Map();
     registeredPrograms = new Set();
+    programBindings = new Map();
+    confinedShells = new Set();
+    capabilities = Object.freeze({ filesystemPolicy: true });
     streamingRuns = new WeakMap();
+    resolvers = [];
     nextPid = 1000;
-    constructor(filesystem) {
-        this.virtualFilesystem = filesystem;
-        this.filesystem = new BrowserShellFileSystem(filesystem);
+    /** `$!`: the job this shell last started; each command runs in a fresh interpreter, so the shell carries it. */
+    lastBackgroundPid = 0;
+    /**
+     * The container's processes, as Docker's `top` lists them: `kill` reaches
+     * a pid there that is not one of this shell's jobs, as a machine's kill
+     * reaches any process of its user. A confined shell has none.
+     */
+    processTable;
+    fixedPolicy;
+    constructor(filesystem, policy) {
+        this.fixedPolicy = policy === undefined ? undefined : normalizeProcessFilesystemPolicy(policy);
+        this.virtualFilesystem = this.fixedPolicy ? confineBrowserFileSystem(filesystem, this.fixedPolicy) : filesystem;
+        this.filesystem = new BrowserShellFileSystem(this.virtualFilesystem);
         this.ensureRuntimeDirectories();
-        this.bash = new Bash({
+        this.registerCommand(browserRmCommand);
+        this.registerShellExecutables();
+        this.registerJobCommands();
+        this.createBash();
+    }
+    createBash(env) {
+        return new Bash({
             fs: this.filesystem,
             cwd: "/",
             env: {
-                HOME: "/home/supercode",
-                USER: "supercode",
+                HOME: "/home/user",
+                USER: "user",
                 PATH: "/usr/local/bin:/usr/bin:/bin:/node_modules/.bin",
                 NODE_ENV: "development",
+                ...env,
             },
             processInfo: { pid: 1, ppid: 0, uid: 1000, gid: 1000 },
+            customCommands: [...this.commands.values()],
         });
-        this.registerShellExecutables();
-        this.registerJobCommands();
     }
-    registerProgram(name, runner) {
+    registerCommand(command) {
+        this.commands.set(command.name, command);
+    }
+    /**
+     * A word of a command line that no program claims may still be a command
+     * where it is typed, one a lane's ecosystem installed into a directory tree.
+     * Each resolver is asked with that directory; the first answer is registered
+     * as a program, whose runner resolves again at every call.
+     */
+    registerCommandResolver(resolver) {
+        this.resolvers.push(resolver);
+    }
+    resolveUnknownCommands(command, cwd) {
+        if (this.resolvers.length === 0)
+            return;
+        // Every identifier-shaped word of the line, operators and quotes aside: a
+        // name that resolves is a command; one that does not costs one lookup.
+        const words = command.match(/[A-Za-z0-9][\w.-]*/gu) ?? [];
+        for (const word of new Set(words)) {
+            if (this.registeredPrograms.has(word))
+                continue;
+            const resolved = this.resolvers.some((resolver) => resolver(word, cwd) !== undefined);
+            if (!resolved)
+                continue;
+            const name = word;
+            this.registerProgram(name, (argv, options) => {
+                const runner = this.resolvers.map((resolver) => resolver(name, options.cwd ?? cwd)).find(Boolean);
+                if (!runner)
+                    return Promise.resolve({ stdout: "", stderr: `bash: ${commandNotFound(name)}`, exitCode: 127 });
+                return runner(argv, options);
+            });
+        }
+    }
+    registerProgram(name, runner, capabilities = {}) {
         this.registeredPrograms.add(name);
-        this.bash.registerCommand(trustedCommand(name, async (args, context) => {
+        const declared = Object.freeze({ ...capabilities });
+        this.programBindings.set(name, { runner, capabilities: declared });
+        this.registerCommand(trustedCommand(name, async (args, context) => {
+            requireProcessFilesystemPolicySupport(this.fixedPolicy, declared);
             const streaming = context.signal ? this.streamingRuns.get(context.signal) : undefined;
             let streamedStdout = false;
             let streamedStderr = false;
+            // Where nothing streams this command onward (a pipe, a substitution),
+            // what the program streamed is its output: a program that only
+            // streams (git's remote helper) returns none of it in its result.
+            let collectedStdout = "";
+            let collectedStderr = "";
             const result = await runner([name, ...args], {
                 cwd: context.cwd,
-                env: Object.fromEntries(context.env),
+                ...(this.fixedPolicy ? { filesystemPolicy: this.fixedPolicy } : {}),
+                env: programEnvironment(context.exportedEnv),
                 stdin: context.stdin,
                 ...(context.signal ? { signal: context.signal } : {}),
-                ...(streaming?.onStdout ? { onStdout: (data) => {
-                        streamedStdout = true;
+                onStdout: (data) => {
+                    streamedStdout = true;
+                    if (streaming?.onStdout)
                         streaming.onStdout(data);
-                    } } : {}),
-                ...(streaming?.onStderr ? { onStderr: (data) => {
-                        streamedStderr = true;
+                    else
+                        collectedStdout += data;
+                },
+                onStderr: (data) => {
+                    streamedStderr = true;
+                    if (streaming?.onStderr)
                         streaming.onStderr(data);
-                    } } : {}),
+                    else
+                        collectedStderr += data;
+                },
             });
             return {
                 ...result,
-                stdout: streamedStdout ? "" : result.stdout,
-                stderr: streamedStderr ? "" : result.stderr,
+                stdout: streamedStdout ? collectedStdout : result.stdout,
+                stderr: streamedStderr ? collectedStderr : result.stderr,
             };
         }));
     }
     async run(command, options = {}) {
+        if (options.filesystemPolicy !== undefined || this.fixedPolicy !== undefined) {
+            const policy = this.fixedPolicy
+                ? intersectProcessFilesystemPolicies(this.fixedPolicy, options.filesystemPolicy)
+                : normalizeProcessFilesystemPolicy(options.filesystemPolicy);
+            if (!this.fixedPolicy || JSON.stringify(policy) !== JSON.stringify(this.fixedPolicy)) {
+                // One immutable view per invocation: overlapping commands, nested
+                // shells and detached jobs must never borrow another run's authority.
+                const child = new BrowserShell(this.virtualFilesystem, policy);
+                for (const [name, binding] of this.programBindings)
+                    child.registerProgram(name, binding.runner, binding.capabilities);
+                for (const resolver of this.resolvers)
+                    child.registerCommandResolver(resolver);
+                this.confinedShells.add(child);
+                try {
+                    return await child.run(command, { ...options, filesystemPolicy: policy });
+                }
+                finally {
+                    const jobs = [...child.jobs.values()].filter((job) => job.state === "running");
+                    if (jobs.length === 0)
+                        this.confinedShells.delete(child);
+                    else
+                        void Promise.allSettled(jobs.map((job) => job.promise)).then(() => this.confinedShells.delete(child));
+                }
+            }
+            options = { ...options, filesystemPolicy: policy };
+        }
         // Project restoration replaces the VFS contents after the shell is created.
         // Reassert process-owned directories at the command boundary so restores and
         // project resets cannot invalidate the shell environment.
@@ -64,15 +162,25 @@ export class BrowserShell {
             return changedDirectory;
         const sequence = splitBackgroundSequence(command);
         if (sequence) {
-            const background = this.startBackground(sequence.background, options);
+            const first = sequence.before ? await this.run(sequence.before, options) : undefined;
+            // what the list before it did to the shell (a cd, an export) the job starts in
+            const after = first
+                ? { ...options, ...(first.cwd ? { cwd: first.cwd } : {}), ...(first.env ? { env: first.env } : {}) }
+                : options;
+            // A job and what follows it run in interpreters of their own; the
+            // functions the list defined go with them, as a subshell inherits its
+            // parent's (`f() { …; }; f &`). Variables and the directory go as `after`.
+            const defined = functionDefinitions(sequence.before);
+            const withFunctions = (text) => (defined ? `${defined}\n${text}` : text);
+            const background = this.startBackground(withFunctions(sequence.background), after);
             // A background server commonly registers its port on a microtask. Let
             // that startup settle before the foreground dev server claims its own
             // port so process ownership remains deterministic.
             await new Promise((resolve) => globalThis.setTimeout(resolve, 0));
-            const foreground = await this.run(sequence.foreground, options);
+            const foreground = await this.run(withFunctions(sequence.foreground), after);
             return {
-                stdout: `${background.stdout}${foreground.stdout}`,
-                stderr: `${background.stderr}${foreground.stderr}`,
+                stdout: `${first?.stdout ?? ""}${background.stdout}${foreground.stdout}`,
+                stderr: `${first?.stderr ?? ""}${background.stderr}${foreground.stderr}`,
                 exitCode: foreground.exitCode,
                 ...(foreground.cwd ? { cwd: foreground.cwd } : {}),
                 ...(foreground.env ? { env: foreground.env } : {}),
@@ -84,13 +192,21 @@ export class BrowserShell {
         return this.runForeground(command, options);
     }
     terminate() {
-        for (const job of this.jobs.values())
-            job.controller.abort(new DOMException("Shell terminated", "AbortError"));
+        for (const shell of this.confinedShells)
+            shell.terminate();
+        this.confinedShells.clear();
+        for (const job of this.jobs.values()) {
+            // a job that survived a signal is ended now
+            if (job.controller.signal.aborted)
+                job.controller.signal.reason?.redeliver?.(9);
+            else
+                job.controller.abort(new DOMException("Shell terminated", "AbortError"));
+        }
         this.jobs.clear();
     }
     ensureRuntimeDirectories() {
         this.virtualFilesystem.mkdirSync("/tmp", { recursive: true });
-        this.virtualFilesystem.mkdirSync("/home/supercode", { recursive: true });
+        this.virtualFilesystem.mkdirSync("/home/user", { recursive: true });
     }
     async changeDirectory(command, options) {
         let words;
@@ -105,7 +221,7 @@ export class BrowserShell {
         if (words.length > 2)
             return { stdout: "", stderr: "bash: cd: too many arguments\n", exitCode: 1 };
         const current = options.cwd ?? "/";
-        const requested = words[1] ?? options.env?.HOME ?? "/home/supercode";
+        const requested = words[1] ?? options.env?.HOME ?? "/home/user";
         const destination = this.filesystem.resolvePath(current, requested);
         try {
             const value = await this.filesystem.stat(destination);
@@ -127,17 +243,26 @@ export class BrowserShell {
         if (options.signal?.aborted)
             return { stdout: "", stderr: "", exitCode: 130 };
         const cwd = options.cwd ?? "/";
+        this.resolveUnknownCommands(command, cwd);
         try {
-            const result = await this.bash.exec(command, {
+            // Just Bash exports constructor environment, but exec({env}) only adds
+            // shell variables and shares its export table. Each invocation needs its
+            // own interpreter so inherited variables export without crossing runs.
+            const bash = this.createBash(withNodeModuleBinPath(options.env, cwd));
+            seedLastBackgroundPid(bash, this.lastBackgroundPid);
+            const result = await bash.exec(withJobWait(command), {
                 cwd,
-                env: withNodeModuleBinPath(options.env, cwd),
                 ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
                 ...(options.signal ? { signal: options.signal } : {}),
                 rawScript: true,
             });
+            const stderr = teachUnknownCommands(result.stderr);
             options.onStdout?.(result.stdout);
-            options.onStderr?.(result.stderr);
-            return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode, env: result.env };
+            options.onStderr?.(stderr);
+            // A `cd` inside a list (`cd /tmp; ls`) moves the shell as in any sh; the
+            // interpreter's PWD is where it ended, and a subshell's cd never leaks.
+            const moved = result.env.PWD && result.env.PWD !== (options.env?.PWD ?? cwd) ? result.env.PWD : undefined;
+            return { stdout: result.stdout, stderr, exitCode: result.exitCode, env: result.env, ...(moved ? { cwd: moved } : {}) };
         }
         catch (cause) {
             if (options.signal?.aborted)
@@ -149,6 +274,7 @@ export class BrowserShell {
         if (!command)
             return { stdout: "", stderr: "bash: syntax error near unexpected token `&'\n", exitCode: 2 };
         const pid = this.nextPid++;
+        this.lastBackgroundPid = pid;
         const controller = new AbortController();
         const abortWithParent = () => {
             if (!controller.signal.aborted) {
@@ -166,23 +292,40 @@ export class BrowserShell {
             state: "running",
             promise: Promise.resolve({ stdout: "", stderr: "", exitCode: 0 }),
         };
+        // A job on a terminal writes to the terminal as it runs, past the line that
+        // started it; without one, what it printed is heard when it ends.
+        const device = options.terminal?.write;
+        const heard = device ? { ...options, onStdout: device, onStderr: device } : options;
         const streamProgram = isSimpleCommand(command)
             && this.registeredPrograms.has(parseWords(command)[0] ?? "");
         if (streamProgram)
-            this.streamingRuns.set(controller.signal, options);
+            this.streamingRuns.set(controller.signal, heard);
         const { onStdout: _onStdout, onStderr: _onStderr, ...jobOptions } = options;
         job.promise = this.runForeground(command, {
             ...jobOptions,
             signal: controller.signal,
-        }).then((result) => {
+        }).then((ran) => {
             options.signal?.removeEventListener("abort", abortWithParent);
+            // an interpreter stopped mid-script returns the last status it had; a
+            // job ended by a signal has 128 + that signal, as `wait` reports in bash;
+            // a program that handled the signal and exited reports its own status
+            const handled = controller.signal.reason?.handled === true;
+            const result = job.signal && !handled ? { ...ran, exitCode: 128 + job.signal } : ran;
             job.state = "done";
             job.result = result;
-            if (!streamProgram) {
-                options.onStdout?.(result.stdout);
-                options.onStderr?.(result.stderr);
-            }
-            options.onStderr?.(`[${pid}] Done (${result.exitCode}) ${command}\n`);
+            // A registered program run directly may stream its output through the
+            // listeners it was handed, or return it, as the browser Git does. The
+            // binding blanks what was streamed, so what remains in the result is
+            // what nobody has seen yet, and it goes to the listeners now; a bare
+            // `git status` printed nothing while `git status; true` printed
+            // everything, because only the shell's path emitted a returned result
+            // (measured 2026-09-20 in the vscode example's shell, and the same
+            // path answers the extension host's `git` calls).
+            if (result.stdout)
+                heard.onStdout?.(result.stdout);
+            if (result.stderr)
+                heard.onStderr?.(result.stderr);
+            heard.onStderr?.(`[${pid}] ${job.signal && !handled ? SIGNAL_REPORTS[job.signal] ?? `Signal ${job.signal}` : `Done (${result.exitCode})`} ${command}\n`);
             return result;
         });
         this.jobs.set(pid, job);
@@ -190,34 +333,79 @@ export class BrowserShell {
         options.onStdout?.(stdout);
         return { stdout, stderr: "", exitCode: 0 };
     }
+    /** Gives `kill` the container's processes (the runtime's table). */
+    setProcessTable(table) {
+        this.processTable = table;
+    }
     registerJobCommands() {
-        this.bash.registerCommand(trustedCommand("jobs", async () => ({
+        this.registerCommand(trustedCommand("jobs", async () => ({
             stdout: [...this.jobs.values()].map((job) => `[${job.pid}] ${job.state === "running" ? "Running" : "Done"} ${job.command}\n`).join(""),
             stderr: "",
             exitCode: 0,
         })));
-        this.bash.registerCommand(trustedCommand("kill", async (args) => {
-            const targets = args.filter((arg) => !arg.startsWith("-"));
+        this.registerCommand(trustedCommand("kill", async (args) => {
+            let signal = 15;
+            const targets = [];
+            for (let index = 0; index < args.length; index += 1) {
+                const arg = args[index];
+                const named = arg === "-s" || arg === "-n" ? args[++index] : arg.startsWith("-") ? arg.slice(1) : undefined;
+                if (named === undefined) {
+                    targets.push(arg);
+                    continue;
+                }
+                const number = signalNumber(named);
+                if (number === undefined)
+                    return { stdout: "", stderr: `kill: ${named}: invalid signal specification\n`, exitCode: 1 };
+                if (STOP_SIGNALS.has(number))
+                    return { stdout: "", stderr: `kill: ${named}: this shell cannot stop a job, only end it\n`, exitCode: 1 };
+                signal = number;
+            }
             if (targets.length === 0)
-                return { stdout: "", stderr: "kill: usage: kill PID...\n", exitCode: 2 };
+                return { stdout: "", stderr: "kill: usage: kill [-s sigspec | -n signum | -sigspec] pid ...\n", exitCode: 2 };
             let stderr = "";
             for (const target of targets) {
                 const pid = Number(target.replace(/^%/u, ""));
                 const job = this.jobs.get(pid);
-                if (!job || job.state !== "running")
+                const process = job ? undefined : this.processTable?.().find((entry) => entry.pid === pid && entry.state === "running");
+                if (process) {
+                    if (signal !== 0)
+                        process.kill(Object.assign(new DOMException(SIGNAL_REPORTS[signal] ?? `Signal ${signal}`, "AbortError"), { signal }));
+                }
+                else if (!job || job.state !== "running")
                     stderr += `kill: (${target}) - No such process\n`;
-                else
-                    job.controller.abort(new DOMException("Terminated", "AbortError"));
+                // signal 0 asks only whether the job is there
+                else if (signal !== 0) {
+                    job.signal = signal;
+                    // A job that handled an earlier signal is still running: the next
+                    // one reaches it through that abort's reason.
+                    if (job.controller.signal.aborted) {
+                        job.controller.signal.reason?.redeliver?.(signal);
+                        continue;
+                    }
+                    // the number rides on the reason, so a program that handles the signal (a WALI git) gets it
+                    job.controller.abort(Object.assign(new DOMException(SIGNAL_REPORTS[signal] ?? `Signal ${signal}`, "AbortError"), { signal }));
+                }
             }
             return { stdout: "", stderr, exitCode: stderr ? 1 : 0 };
         }));
-        this.bash.registerCommand(trustedCommand("wait", async (args) => {
-            const selected = args.length === 0
-                ? [...this.jobs.values()]
-                : args.map((arg) => this.jobs.get(Number(arg.replace(/^%/u, "")))).filter((job) => !!job);
-            if (args.length > 0 && selected.length !== args.length) {
+        this.registerCommand(trustedCommand(JOB_WAIT, async (args) => {
+            // `-n`: the first of them to end; `%N`: the Nth job this shell holds; a number: a pid
+            const any = args.includes("-n");
+            const specs = args.filter((arg) => arg !== "-n");
+            const held = [...this.jobs.values()];
+            const selected = specs.length === 0
+                ? held
+                : specs.map((arg) => (arg.startsWith("%") ? held[Number(arg.slice(1)) - 1] : this.jobs.get(Number(arg)))).filter((job) => !!job);
+            if (specs.length > 0 && selected.length !== specs.length) {
                 return { stdout: "", stderr: "wait: pid is not a child of this shell\n", exitCode: 127 };
             }
+            if (any) {
+                if (selected.length === 0)
+                    return { stdout: "", stderr: "", exitCode: 127 };
+                const first = await Promise.race(selected.map((job) => job.promise.then((result) => ({ job, result }))));
+                this.jobs.delete(first.job.pid);
+                return { stdout: "", stderr: "", exitCode: first.result.exitCode };
+            }
             const results = await Promise.all(selected.map((job) => job.promise));
             for (const job of selected)
                 this.jobs.delete(job.pid);
@@ -226,7 +414,7 @@ export class BrowserShell {
     }
     registerShellExecutables() {
         for (const name of ["bash", "sh", "zsh"]) {
-            this.bash.registerCommand(trustedCommand(name, async (args, context) => {
+            this.registerCommand(trustedCommand(name, async (args, context) => {
                 if (args.includes("--version")) {
                     return {
                         // Native harnesses use this as an executability probe and often
@@ -241,12 +429,19 @@ export class BrowserShell {
                 const script = commandIndex >= 0 ? args[commandIndex + 1] : context.stdin;
                 if (!script)
                     return { stdout: "", stderr: "", exitCode: 0 };
-                return this.bash.exec(script, {
+                // A package script that is more than one command (a loop, a list)
+                // arrives here as `sh -c`; its words resolve as a typed line's do.
+                this.resolveUnknownCommands(script, context.cwd);
+                const result = await this.createBash(context.exportedEnv).exec(script, {
                     cwd: context.cwd,
-                    env: Object.fromEntries(context.env),
+                    // A subshell receives only exports; do not reintroduce a default
+                    // (such as NODE_ENV) that its parent explicitly unexported or unset.
+                    env: context.exportedEnv ?? {},
+                    replaceEnv: true,
                     ...(context.signal ? { signal: context.signal } : {}),
                     rawScript: true,
                 });
+                return { ...result, stderr: teachUnknownCommands(result.stderr) };
             }));
         }
     }
@@ -276,9 +471,86 @@ function normalizeShellPath(value) {
     }
     return `/${parts.join("/")}`;
 }
+// Just Bash's own `wait` builtin returns at once, and a builtin is found
+// before any command the embedding registers; a function is found before a
+// builtin, as in bash, so a script that waits gets `wait` as a function over
+// this shell's job table. It is defined on the script's first line, so every
+// line keeps its number.
+const JOB_WAIT = "__browser_shell_wait";
+function withJobWait(command) {
+    return /(^|[^\w-])wait([^\w-]|$)/u.test(command) ? `wait() { ${JOB_WAIT} "$@"; }; ${command}` : command;
+}
+// Just Bash expands `$!` from its interpreter state and has no `&` of its own,
+// so nothing of its API sets it; the one door is that state. A release that
+// moves it fails here by name rather than expanding `$!` to 0.
+function seedLastBackgroundPid(bash, pid) {
+    if (pid === 0)
+        return;
+    const state = bash.state;
+    if (!state || typeof state.lastBackgroundPid !== "number") {
+        throw new Error("just-bash no longer keeps lastBackgroundPid in its state: $! cannot be set");
+    }
+    state.lastBackgroundPid = pid;
+}
+// A job is stopped by abort, whose reason names the signal: a WALI program
+// that installed a handler for it runs the handler and ends as it chooses;
+// every other program ends.
+const STOP_SIGNALS = new Set([19, 20, 21, 22]);
+const SIGNALS = { STOP: 19, TSTP: 20, TTIN: 21, TTOU: 22, HUP: 1, INT: 2, QUIT: 3, KILL: 9, USR1: 10, USR2: 12, PIPE: 13, ALRM: 14, TERM: 15 };
+const SIGNAL_REPORTS = { 1: "Hangup", 2: "Interrupt", 3: "Quit", 9: "Killed", 10: "User defined signal 1", 12: "User defined signal 2", 13: "Broken pipe", 14: "Alarm clock", 15: "Terminated" };
+function signalNumber(spec) {
+    if (/^\d+$/u.test(spec)) {
+        const number = Number(spec);
+        return number === 0 || SIGNAL_REPORTS[number] || STOP_SIGNALS.has(number) ? number : undefined;
+    }
+    return SIGNALS[spec.toUpperCase().replace(/^SIG/u, "")];
+}
+/** `before; background & foreground`: bash backgrounds only the list after the last `;`. */
+/** The function definitions among a list's top-level commands, joined as one text. */
+function functionDefinitions(list) {
+    if (!list)
+        return "";
+    const items = [];
+    let quote = "";
+    let depth = 0;
+    let start = 0;
+    const flush = (end) => { const item = list.slice(start, end).trim(); if (item)
+        items.push(item); };
+    for (let index = 0; index < list.length; index += 1) {
+        const character = list[index];
+        if (quote) {
+            if (character === quote)
+                quote = "";
+            continue;
+        }
+        if (character === "\\") {
+            index += 1;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "(" || character === "{")
+            depth += 1;
+        else if (character === ")" || character === "}")
+            depth = Math.max(0, depth - 1);
+        else if (depth === 0 && (character === ";" || character === "\n")) {
+            flush(index);
+            start = index + 1;
+        }
+    }
+    flush(list.length);
+    return items.filter((item) => /^(?:function\s+[A-Za-z_][\w-]*\s*(?:\(\s*\))?|[A-Za-z_][\w-]*\s*\(\s*\))\s*[{(]/u.test(item)).join("\n");
+}
 function splitBackgroundSequence(command) {
+    // Only the top level is split: a `;` or `&` inside `( )`, `{ }`, `$( )`
+    // or backquotes belongs to the group, which runs whole as one job.
     let quote = "";
+    let depth = 0;
+    let listStart = 0;
     let escaped = false;
+    const wordEdge = (at) => at < 0 || at >= command.length || /[\s;&|]/u.test(command[at]);
     for (let index = 0; index < command.length; index += 1) {
         const character = command[index];
         if (escaped) {
@@ -294,18 +566,41 @@ function splitBackgroundSequence(command) {
                 quote = "";
             continue;
         }
-        if (character === "'" || character === '"') {
+        if (character === "'" || character === '"' || character === "`") {
             quote = character;
             continue;
         }
+        if (character === "(") {
+            depth += 1;
+            continue;
+        }
+        if (character === ")") {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (character === "{" && wordEdge(index - 1) && wordEdge(index + 1)) {
+            depth += 1;
+            continue;
+        }
+        if (character === "}" && wordEdge(index - 1) && wordEdge(index + 1)) {
+            depth = Math.max(0, depth - 1);
+            continue;
+        }
+        if (depth > 0)
+            continue;
+        if (character === ";" || character === "\n") {
+            listStart = index + 1;
+            continue;
+        }
         if (character !== "&" || command[index - 1] === "&" || command[index + 1] === "&"
             || command[index - 1] === ">" || !/\s/u.test(command[index - 1] ?? "")
             || !/\s/u.test(command[index + 1] ?? ""))
             continue;
-        const background = command.slice(0, index).trim();
+        const before = command.slice(0, listStart).trim().replace(/;$/u, "").trim();
+        const background = command.slice(listStart, index).trim();
         const foreground = command.slice(index + 1).trim();
         if (background && foreground)
-            return { background, foreground };
+            return { before, background, foreground };
     }
     return;
 }
@@ -368,13 +663,22 @@ function parseWords(command) {
     let word = "";
     let quote = "";
     let escaped = false;
-    for (const character of command.trim()) {
+    const characters = [...command.trim()];
+    for (let index = 0; index < characters.length; index += 1) {
+        const character = characters[index];
         if (escaped) {
             word += character;
             escaped = false;
             continue;
         }
         if (character === "\\" && quote !== "'") {
+            // Inside double quotes a backslash is literal unless it escapes one of
+            // $ ` " \ or a newline, as sh reads it.
+            const next = characters[index + 1];
+            if (quote === '"' && (next === undefined || !"$`\"\\\n".includes(next))) {
+                word += character;
+                continue;
+            }
             escaped = true;
             continue;
         }
@@ -409,4 +713,29 @@ function parseWords(command) {
 function trustedCommand(name, execute) {
     return { ...defineCommand(name, execute), trusted: true };
 }
+/**
+ * What a program receives from the shell. just-bash exports its own
+ * parameters beside the user's variables: `?`, `$`, `!` and IFS, whose default
+ * value is a newline. No process could receive those as environment
+ * variables, and the WALI engine refuses an environment it cannot write to
+ * its env file, so a script's spawn of any native program failed with
+ * "Invalid WALI environment entry: IFS". Keep what an environment can carry:
+ * identifier names, values without NUL or a line break.
+ */
+export function programEnvironment(exported) {
+    const environment = {};
+    for (const [name, value] of Object.entries(exported ?? {})) {
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) && !/[\u0000\r\n]/u.test(value))
+            environment[name] = value;
+    }
+    return environment;
+}
+/**
+ * Just Bash reports a word nothing answers as `bash: <name>: command not
+ * found`, which reads as a Linux machine missing a package. The tab's
+ * programs are its page's and image's, so the line says that instead.
+ */
+function teachUnknownCommands(stderr) {
+    return stderr.replace(/^bash: ([^:\n]+): command not found$\n?/gmu, (_line, name) => `bash: ${commandNotFound(name)}`);
+}
 //# sourceMappingURL=browser-shell.js.map