buninu-linux 0.3.1 → 0.5.1

package/graphics.md

@@ -0,0 +1,218 @@
+# The Buninu Linux graphics stack
+
+Buninu Linux draws on the screen without X11, Wayland, a GPU or any native
+graphics library: the Linux framebuffer is mapped into Bun, Skia (compiled to
+WebAssembly as CanvasKit) rasterizes into it, and `bunterm` puts an
+xterm-compatible terminal on top. Everything is JavaScript or WebAssembly
+except the kernel's `/dev/fb0`, reached through a few `ioctl`s and one `mmap`
+via Bun FFI.
+
+```
+ ┌──────────────────────────────────────────────────────────────────────┐
+ │ programs on a PTY:  bunmsh, jsmdcui, bun scripts, kitten icat …      │
+ └───────────────▲───────────────────────────────┬──────────────────────┘
+        keyboard │ (raw console bytes)            │ output bytes + kitty APC
+ ┌───────────────┴───────────────────────────────▼──────────────────────┐
+ │ /bin/bunterm  →  /lib/bunterm/terminal.js                             │
+ │   BunPtyBackend (jsgotty) ─ Bun.spawn({ terminal })    ← Bun's PTY    │
+ │   KittyGraphicsParser (jsgotty) ─ splits ESC _ G … ESC \ packets      │
+ │   @xterm/headless Terminal ─ VT parser, screen buffer, attributes     │
+ │   images.js ─ kitty placements as Skia images anchored to lines       │
+ │   input.js ─ /dev/ttyN raw mode, console→xterm key sequences          │
+ │   mouse.js ─ /dev/input/event* pointer, unless --no-mouse             │
+ │   renderer.js ─ cells → glyphs (fonts) or vectors (glyphs.js)         │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ Skia draw calls
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ /lib/canvas.js  ─ CanvasKit 0.41.1 (Skia in wasm, /lib/canvaskit/)    │
+ │   openCanvas(): MakeRasterDirectSurface in the framebuffer's own      │
+ │   pixel format (BGRA_8888 / RGBA_8888 / RGB_565) inside the wasm heap │
+ │   loadFontSet(): /usr/share/fonts/fonts.json → Typefaces + FontMgr    │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ one memcpy per frame
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ /lib/fbdev.js  ─ Framebuffer: FBIOGET_*SCREENINFO, mmap, KDSETMODE    │
+ │   runGraphics(): graphics mode + restore on exit/signal               │
+ │   JS drawing (drawLine, fillPolygon …) and blitImageData() fallback   │
+ └───────────────────────────────────────────────┬──────────────────────┘
+                                                 │ ioctl / mmap (bun:ffi, /lib/dlopen.js)
+ ┌───────────────────────────────────────────────▼──────────────────────┐
+ │ Linux: /dev/fb0 (efifb / simpledrm from the UEFI GOP), /dev/ttyN      │
+ └──────────────────────────────────────────────────────────────────────┘
+```
+
+## Layers
+
+### 1. Framebuffer — `/lib/fbdev.js`
+
+`Framebuffer` opens `/dev/fb0`, reads the variable and fixed screen info
+(size, stride, bits per pixel, the red/green/blue bit offsets) and `mmap`s
+the device. Drawing goes to a JavaScript back buffer laid out exactly like
+the device; `flush()` copies it row by row into the mapping. Nothing draws
+straight into the mapping: on efifb the memory is write-combining, reads are
+very slow, and drawing there would tear.
+
+`runGraphics(draw)` wraps a graphical program: it switches the virtual
+console to `KD_GRAPHICS` (otherwise the kernel's text console keeps
+overwriting the screen), runs `draw`, and restores `KD_TEXT` whether the
+call returns, throws, exits, or is killed by a catchable signal. Given a
+specific `/dev/ttyN`, it `VT_ACTIVATE`s that console first and switches
+back to the previous one at the end; while drawing it takes `VT_PROCESS`
+mode, so Ctrl-Alt-Fn still switches consoles and `onAcquire` lets the
+program repaint when its console returns.
+
+Manual: `fbdev --help` / `initramfs/usr/share/doc/buninu-linux/fbdev.md`.
+
+### 2. Skia — `/lib/canvas.js` and `/lib/canvaskit/`
+
+CanvasKit is Google's Skia compiled to WebAssembly (the same npm package the
+browser uses). WebAssembly can only write its own linear memory, so Skia
+cannot draw into the `mmap` directly. Instead `openCanvas()` allocates a
+buffer in the wasm heap and creates a `MakeRasterDirectSurface` on it in the
+framebuffer's native pixel layout (`pickColorType()` maps the kernel's
+bitfields to `BGRA_8888` for the usual XRGB8888, or `RGBA_8888` /
+`RGB_565`). The `Framebuffer`'s `pixels` view is pointed at that buffer, so
+`flush()` is the same single `memcpy` as before and the JavaScript drawing
+functions keep working on the same frame. A 24-bit or paletted device falls
+back to CanvasKit's HTML-canvas emulation plus `blitImageData()`, which
+converts per pixel.
+
+Skia is CPU-only here (no GPU, no WebGL); the whole 1080p frame is a few
+milliseconds to copy and cells are cached by Skia's glyph cache. The wasm
+heap starts at 128 MiB and grows as fonts are loaded into it, which is why
+QEMU is now started with `-m 1G`.
+
+`loadFontSet()` reads `/usr/share/fonts/fonts.json` and builds the typefaces
+and a `FontMgr` for a named set (`terminal`, `ui`). Noto Sans CJK is a
+collection; the manager registers all five faces and the set's preferred
+face (`Noto Sans CJK TC`) is the one handed out, so Taiwanese glyph forms
+are used without relying on `locl`.
+
+Manual: `initramfs/usr/share/doc/buninu-linux/canvas.md`.
+
+### 3. Fonts — `/usr/share/fonts/`
+
+| File | Role | License |
+|---|---|---|
+| `DejaVuSansMono.ttf`, `-Bold.ttf` | terminal grid font: 0.6 em wide, 1.16 em tall, box drawing, arrows, `☐☒✓`, Braille-free but everything jsmdcui draws | Bitstream Vera |
+| `NotoSansCJK-Regular.ttc` | 32 MiB variable collection: JP/KR/SC/TC/HK faces, ~21 000 unified ideographs, ext. A, part of ext. B, kana, bopomofo, hangul, full-width forms | OFL 1.1 |
+| `NotoColorEmoji.ttf`, `NotoColorEmojiFlags.ttf` | CBDT bitmap colour emoji; Skia's FreeType port renders them in colour | OFL 1.1 |
+| `NotoSansSymbols-Regular-Subsetted.ttf`, `-Subsetted2.ttf` | arrows, math, geometric shapes, dingbats, Braille, musical symbols, cards | OFL 1.1 |
+| `Roboto-Regular.ttf` | variable Latin/Greek/Cyrillic for non-terminal UI (`ui` set) | Apache 2.0 |
+
+The Noto and Roboto files are the ones Android ships; DejaVu comes from
+Debian. Each license text sits next to the fonts and in `LICENSES/`.
+
+### 4. Terminal — `/bin/bunterm` and `/lib/bunterm/`
+
+`bunterm` reuses three finished components instead of writing a terminal
+from scratch:
+
+- **PTY**: jsgotty's `BunPtyBackend`, which is `Bun.spawn(cmd, { terminal:
+  { cols, rows, data, exit } })` — Bun's built-in pseudo-terminal, no
+  node-pty, no FFI. jsgotty now exports the class for this.
+- **Emulation**: `@xterm/headless`, the xterm.js core (VT parser, screen
+  and scrollback buffers, SGR attributes, terminal replies, markers) with
+  its DOM renderer removed. `@xterm/addon-unicode-graphemes` makes 🇹🇼,
+  ZWJ sequences and combining marks occupy one cell.
+- **Images**: jsgotty's `KittyGraphicsParser`, which splits the kitty
+  graphics APC packets out of the byte stream, reassembles chunked
+  transfers, inflates `o=z`, and produces placement / delete / query events
+  and the replies to send back. (Two small changes to the vendored jsgotty:
+  the export, and later chunks of a transfer whose first chunk named `i=`
+  now continue that transfer, as the protocol allows — to be carried back
+  to the jsgotty repository.)
+
+Around those, `/lib/bunterm/` adds:
+
+| File | Does |
+|---|---|
+| `renderer.js` | Paints `term.buffer` cell by cell. Cell size comes from DejaVu Sans Mono; every glyph is looked up in the regular font, then the fallbacks (colour emoji first for emoji-presentation code points, monochrome symbols first otherwise) and centred in its one or two cells; oversized fallback glyphs are scaled to fit. Multi-code-point graphemes are shaped by Skia's `Paragraph` and cached. Only rows whose content hash changed since the last frame, the cursor rows, and rows under moved images are repainted. 16/256/24-bit colour, bold (with bright base colours), italic, dim, underline, strikethrough, inverse, invisible. |
+| `glyphs.js` | Box drawing (U+2500–257F incl. double, dashed, rounded, mixed-weight), block elements and shades (U+2580–259F), Powerline (U+E0A0–E0BF) and legacy computing (U+1FB70–1FB97) drawn as Skia paths, so they meet seamlessly at any size. The shape tables are xterm.js's `CustomGlyphs.ts` (MIT); coordinates snap to pixel centres for crisp 1-px lines. |
+| `images.js` | Kitty placements: decodes PNG (`f=100`) with Skia or raw RGB/RGBA (`f=24/32`), with `Bun.Image` as a transcoder for other encodings; anchors each placement to an xterm marker so it scrolls with its line and disappears with it (on the alternate screen, where xterm.js issues no markers, to a fixed row that is dropped when that screen ends); sizes in cells (`c,r`) or from pixel size; crops (`x,y,w,h`), cell offsets (`X,Y`), `p=` placement ids, `a=d` deletion scopes, and the cursor move after a placement. |
+| `input.js` | Raw mode on the console (`TCGETS`/`TCSETS` through the shared libc binding) and translation of the kernel's "linux" key sequences to xterm's, honouring DECCKM. |
+| `mouse.js` | `/dev/input/event*` through the input layer: finds pointing devices by their sysfs capability bitmaps, decodes the 24-byte `input_event` records (relative deltas, absolute axes read with `EVIOCGABS`, buttons, wheel) and reports a pointer position per `EV_SYN`. Not loaded under `--no-mouse`; otherwise the session draws an arrow and hands each report to xterm.js's `CoreMouseService`, which decides what the program enabled and encodes it. A wheel notch the program is not asking for scrolls the viewport instead — `scrollLines()` on the normal screen, arrow keys on the alternate one. |
+| `terminal.js` | `createSession()` wires PTY → parser → emulator → renderer with a coalesced ~60 Hz frame timer and a serialized output queue, so a kitty packet always sees the cursor position left by the text before it. `runTerminal()` adds `runGraphics()` and the keyboard. |
+
+Manual: `bunterm --help` / `initramfs/usr/share/doc/buninu-linux/bunterm.md`.
+
+## Data flow of one frame
+
+1. The program writes to the PTY; Bun delivers the bytes to `BunPtyBackend`'s
+   `data` callback.
+2. `KittyGraphicsParser.consume()` returns plain-text runs and kitty packets
+   in order. Plain runs go to `term.write()` (awaited, so the buffer is
+   current); each packet is parsed with the cursor position at that point,
+   handed to `ImageStore`, and acknowledged back to the PTY if the client
+   asked.
+3. A frame is requested. Sixteen milliseconds later `Renderer.render()`
+   hashes each visible row, repaints the changed ones (background rect,
+   glyph or vector, underline), draws the cursor block, and re-draws the
+   parts of image placements that intersect the repainted rows.
+4. `screen.flush()` finishes Skia's work and copies the wasm-heap frame into
+   the `/dev/fb0` mapping.
+
+Keyboard bytes travel the other way: console → `input.js` → PTY, and with
+the mouse on, pointer reports go `/dev/input/event*` → `mouse.js` → the arrow on
+screen and xterm.js's `CoreMouseService` → PTY. Terminal
+replies (cursor position, device attributes, kitty acks) go from the
+emulator straight to the PTY.
+
+## Sizes
+
+| Component | Raw | In the gzip initramfs |
+|---|---|---|
+| CanvasKit wasm + js | 7.3 MB | ~2.7 MB |
+| xterm headless + graphemes addon | 0.2 MB | ~0.05 MB |
+| Fonts | 39.9 MB | ~24 MB |
+| Total added | ~47 MB | ~27 MB |
+
+The initramfs grew from 44.7 MB to 71.8 MB compressed; the UKI is 84.5 MB and
+the 127 MB EFI system partition keeps 46 MB free. The initramfs is unpacked
+into RAM, and CanvasKit copies the fonts it uses into its heap, so the guest
+needs about 1 GB.
+
+## Trying it
+
+The framebuffer needs a kernel that provides one. Alpine's `linux-lts` has
+`CONFIG_FB`, `CONFIG_FB_EFI` and `CONFIG_DRM_SIMPLEDRM` built in; the default
+`linux-virt` builds them as modules, and the image ships only the network,
+storage, USB and HID modules, so there `/dev/fb0` never appears. Build with
+`./index.js -b --linux-lts` (or `--real`); under QEMU the lts kernel gets a
+1280×800 `simpledrm` framebuffer from the UEFI GOP even with `-display none`,
+and the monitor's `screendump` shows it. From a virtual console in the guest:
+
+```sh
+bunterm                                  # /bin/sh on this console
+bunterm /dev/tty1 --font-size 20         # from a serial console, use VT 1
+bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
+bun /lib/fbdev.js                        # the plain-framebuffer triangle
+```
+
+To render off-screen on the build host (no framebuffer), give `openCanvas()`
+a plain object with `width`, `height`, `stride`, `bitsPerPixel`, `fields` and
+a `pixels` `Uint8Array`, replace `screen.flush`, and snapshot the surface —
+that is how the renderer and the kitty pipeline were tested during
+development (`BUNINU_LIBC=/lib/aarch64-linux-gnu/libc.so.6` lets `dlopen.js`
+load the host libc).
+
+Verified in QEMU (lts kernel, `-vga std`, 1 GB): the attribute/CJK/emoji
+sample, a kitty PNG placement, an interactive bunmsh with keys sent through
+the console, and the jsmdcui editor demo all render as on the host;
+`bunterm /dev/tty2` from the serial REPL switches the display to tty2 and
+back to tty1 on exit, and Ctrl-Alt-F2 / Ctrl-Alt-F1 during a session
+switch away and repaint on return. On the
+host, `jsmdcui --tui` on a Markdown file with a JPEG (bunterm sets
+`JSMDCUI_KITTY_MODE=extended` for the program it runs) places the image
+through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
+
+## Not done yet
+
+- Selection and scrollback viewing in `bunterm` (the pointer itself works,
+  and `--no-mouse` turns it off).
+- Kitty `z < 0` (images behind text), animation frames, Unicode
+  placeholders, and shared-memory transmission.
+- Text run shaping with ligatures for single-code-point cells (each cell is
+  one glyph; Paragraph shaping is only used for grapheme clusters).
+- Non-terminal UI on `canvas.js` (the `ui` font set and Roboto are there for
+  it).

package/initramfs/bin/bunterm

@@ -0,0 +1,70 @@
+#!/bin/bun
+// bunterm — a graphical terminal emulator on the Linux framebuffer.
+
+import { showDocument } from "../lib/document.js";
+import { runTerminal } from "../lib/bunterm/terminal.js";
+
+const usage = () => {
+  console.error(`Usage:
+  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [--no-mouse] [-e command [argument...]]
+  bunterm -h | --help`);
+};
+
+const main = async () => {
+  const options = { argv: [] };
+  const arguments_ = process.argv.slice(2);
+  for (let index = 0; index < arguments_.length; index++) {
+    const argument = arguments_[index];
+    if (argument === "-h" || argument === "--help") {
+      await showDocument("bunterm");
+      return 0;
+    }
+    if (argument === "-e") {
+      if (index + 1 >= arguments_.length) {
+        usage();
+        throw new Error("-e needs a command");
+      }
+      options.command = arguments_[index + 1];
+      options.argv = arguments_.slice(index + 2);
+      break;
+    }
+    const valued = (name) => {
+      const value = argument.startsWith(`${name}=`) ? argument.slice(name.length + 1) : arguments_[++index];
+      if (value === undefined) {
+        usage();
+        throw new Error(`${name} needs a value`);
+      }
+      return value;
+    };
+    if (argument === "--font-size" || argument.startsWith("--font-size=")) {
+      options.fontSize = Number(valued("--font-size"));
+      if (!Number.isFinite(options.fontSize) || options.fontSize < 6) throw new Error("--font-size must be a number of at least 6");
+    } else if (argument === "--line-height" || argument.startsWith("--line-height=")) {
+      options.lineHeight = Number(valued("--line-height"));
+      if (!Number.isFinite(options.lineHeight) || options.lineHeight <= 0) throw new Error("--line-height must be a positive number");
+    } else if (argument === "--fb" || argument.startsWith("--fb=")) {
+      options.device = valued("--fb");
+    } else if (argument === "--no-blink") {
+      options.cursorBlink = false;
+    } else if (argument === "--mouse") {
+      options.mouse = true;
+    } else if (argument === "--no-mouse") {
+      options.mouse = false;
+    } else if (argument.startsWith("/dev/")) {
+      options.console = argument;
+    } else {
+      usage();
+      throw new Error(`unexpected argument: ${argument}`);
+    }
+  }
+  return runTerminal(options);
+};
+
+let status = 1;
+try {
+  status = await main();
+} catch (error) {
+  console.error(`bunterm: ${error?.message ?? error}`);
+}
+// A pending console read would otherwise keep the process alive.
+process.exit(status);

package/initramfs/bin/chroot

@@ -0,0 +1,213 @@
+#!/bin/bun
+// chroot — run a command inside another root directory. `chroot --help`
+// renders /usr/share/doc/buninu-linux/chroot.md.
+//
+// A Bun script over the chroot(2) and mount(2) bindings in /lib/dlopen.js.
+// Unlike chroot(8) it prepares the new root before entering it: /proc, /sys,
+// a recursive bind of /dev, /dev/pts, tmpfs on /run and /tmp, and the host's
+// /etc/resolv.conf, so `chroot /mnt/rootfs` lands in a usable system. Every
+// mount it makes is undone when the command exits.
+
+import { existsSync, mkdirSync, realpathSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { libc, cString, ptr, errno, strerror, Errno } from "../lib/dlopen.js";
+import { showDocument } from "../lib/document.js";
+
+const MS = { RDONLY: 1n, NOSUID: 2n, NODEV: 4n, NOEXEC: 8n, BIND: 4096n, REC: 16384n, SLAVE: 1n << 19n };
+const MNT_DETACH = 2;
+
+const fail = (message, status = 125) => {
+  console.error(`chroot: ${message}`);
+  process.exit(status);
+};
+
+const usage = () => {
+  console.error(`Usage:
+  chroot NEWROOT [COMMAND [ARGUMENT...]]
+  chroot [-n] [-k] [-v] NEWROOT [COMMAND [ARGUMENT...]]
+  chroot -h | --help          full manual (chroot.md)`);
+  process.exit(125);
+};
+
+// ------------------------------------------------------------- arguments --
+
+const options = { mount: true, keep: false, verbose: false };
+const positional = [];
+const argv = process.argv.slice(2);
+for (let index = 0; index < argv.length; index++) {
+  const argument = argv[index];
+  if (positional.length > 0) { positional.push(argument); continue; }
+  if (argument === "--") { positional.push(...argv.slice(index + 1)); break; }
+  if (argument === "-h" || argument === "--help") { await showDocument("chroot"); process.exit(0); }
+  else if (argument === "-n" || argument === "--no-mount") options.mount = false;
+  else if (argument === "-k" || argument === "--keep-mounts") options.keep = true;
+  else if (argument === "-v" || argument === "--verbose") options.verbose = true;
+  else if (argument.startsWith("-") && argument.length > 1) { console.error(`chroot: unknown option ${argument}`); usage(); }
+  else positional.push(argument);
+}
+if (positional.length === 0) usage();
+
+const [target, ...command] = positional;
+let root;
+try {
+  root = realpathSync(target);
+  if (!statSync(root).isDirectory()) fail(`cannot change root directory to ${target}: not a directory`);
+} catch (error) {
+  fail(`cannot change root directory to ${target}: ${error.code === "ENOENT" ? "no such directory" : error.message}`);
+}
+if (root === "/") fail("refusing to chroot to /");
+
+const report = (message) => { if (options.verbose) console.error(`chroot: ${message}`); };
+
+// ---------------------------------------------------------------- mounts --
+
+const mountPoints = () => {
+  try {
+    return readFileSync("/proc/self/mounts", "utf8").split("\n").filter(Boolean).map((line) =>
+      line.split(" ")[1].replace(/\\([0-7]{3})/g, (_, code) => String.fromCharCode(parseInt(code, 8))));
+  } catch {
+    return [];
+  }
+};
+
+const mountSyscall = (source, point, type, flags, data = null) =>
+  libc.symbols.mount(ptr(cString(source)), ptr(cString(point)), ptr(cString(type)), flags,
+    data === null ? null : ptr(cString(data)));
+
+// Mount points this command made, innermost last, as paths inside the new
+// root; they are undone in reverse order when the command is done.
+const made = [];
+
+// Prepares one mount. `inside` is the path within the new root. A target that
+// is already a mount point, or that cannot be created on a read-only root, is
+// left alone rather than treated as a failure: the command may still run.
+const prepare = ({ inside, source, type, flags = 0n, data, file = false }) => {
+  const point = `${root}${inside}`;
+  if (mountPoints().includes(point)) {
+    report(`${inside} is already mounted`);
+    return;
+  }
+  if (!existsSync(point)) {
+    try {
+      if (file) writeFileSync(point, "");
+      else mkdirSync(point, { recursive: true, mode: 0o755 });
+    } catch (error) {
+      report(`cannot create ${inside}: ${error.message}; skipped`);
+      return;
+    }
+  }
+  if (mountSyscall(source, point, type, flags, data) === -1) {
+    report(`mount ${inside}: ${strerror(errno())}; skipped`);
+    return;
+  }
+  made.push(inside);
+  report(`mounted ${inside}`);
+};
+
+if (options.mount) {
+  prepare({ inside: "/proc", source: "proc", type: "proc", flags: MS.NOSUID | MS.NODEV | MS.NOEXEC });
+  prepare({ inside: "/sys", source: "sysfs", type: "sysfs", flags: MS.NOSUID | MS.NODEV | MS.NOEXEC });
+  // /dev is bound rather than mounted fresh so the devices, the pty
+  // multiplexer and anything the host added are all there. The bind is then
+  // made a slave: mounts appearing inside do not propagate back to the host,
+  // and unmounting it later does not take the host's /dev with it.
+  prepare({ inside: "/dev", source: "/dev", type: "none", flags: MS.BIND | MS.REC });
+  if (made.includes("/dev")) {
+    if (mountSyscall("none", `${root}/dev`, "none", MS.REC | MS.SLAVE) === -1) {
+      report(`making /dev a slave mount: ${strerror(errno())}`);
+    }
+    // Only needed when the host has no /dev/pts of its own to bring along.
+    if (!existsSync(`${root}/dev/pts/ptmx`)) {
+      prepare({ inside: "/dev/pts", source: "devpts", type: "devpts", flags: MS.NOSUID | MS.NOEXEC, data: "gid=5,mode=620,ptmxmode=666" });
+    }
+  }
+  prepare({ inside: "/run", source: "tmpfs", type: "tmpfs", flags: MS.NOSUID | MS.NODEV, data: "mode=755" });
+  prepare({ inside: "/tmp", source: "tmpfs", type: "tmpfs", flags: MS.NOSUID | MS.NODEV, data: "mode=1777" });
+  // A bound file, so name resolution inside follows the host's configuration
+  // and nothing inside the root is modified.
+  if (existsSync("/etc/resolv.conf") && existsSync(`${root}/etc`)) {
+    prepare({ inside: "/etc/resolv.conf", source: "/etc/resolv.conf", type: "none", flags: MS.BIND, file: true });
+  }
+}
+
+// Mount points are recorded by their path inside the new root. Until
+// chroot(2) has happened they are reached through this prefix; afterwards
+// that is how /proc/self/mounts names them too.
+let prefix = root;
+
+// Unmounts everything this command mounted, deepest first, including whatever
+// appeared under a recursive bind. A busy mount is detached instead: the
+// kernel finishes it once its last user is gone.
+const cleanup = () => {
+  if (options.keep || made.length === 0) return;
+  const points = mountPoints();
+  const targets = new Set();
+  for (const inside of made) {
+    const point = `${prefix}${inside}`;
+    targets.add(point);
+    for (const below of points) if (below.startsWith(`${point}/`)) targets.add(below);
+  }
+  for (const point of [...targets].sort((a, b) => b.length - a.length)) {
+    if (libc.symbols.umount2(ptr(cString(point)), 0) === 0) {
+      report(`unmounted ${point}`);
+      continue;
+    }
+    const code = errno();
+    if (code === Errno.EINVAL) continue; // not mounted any more
+    if (libc.symbols.umount2(ptr(cString(point)), MNT_DETACH) === 0) {
+      report(`detached ${point} (was busy)`);
+      continue;
+    }
+    console.error(`chroot: unmount ${point}: ${strerror(errno())}`);
+  }
+  made.length = 0;
+};
+
+process.on("exit", cleanup);
+
+// ----------------------------------------------------------------- enter --
+
+if (libc.symbols.chroot(ptr(cString(root))) === -1) {
+  const code = errno();
+  cleanup();
+  fail(`cannot change root directory to ${target}: ${code === Errno.EPERM ? "must be superuser" : strerror(code)}`);
+}
+prefix = "";
+process.chdir("/");
+
+const shell = process.env.SHELL && existsSync(process.env.SHELL) ? process.env.SHELL : "/bin/sh";
+// chroot(8) runs an interactive shell when no command is given.
+const run = command.length ? command : [shell, ...(process.stdin.isTTY ? ["-i"] : [])];
+
+// The command owns the terminal while it runs: a Ctrl-C reaches it through
+// the foreground process group, and this process stays alive to unmount.
+const signalNumbers = {
+  SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGILL: 4, SIGTRAP: 5, SIGABRT: 6, SIGBUS: 7,
+  SIGFPE: 8, SIGKILL: 9, SIGUSR1: 10, SIGSEGV: 11, SIGUSR2: 12, SIGPIPE: 13,
+  SIGALRM: 14, SIGTERM: 15,
+};
+const ignored = ["SIGINT", "SIGQUIT", "SIGTSTP"];
+const ignore = () => {};
+for (const signal of ignored) process.on(signal, ignore);
+
+let status = 0;
+try {
+  const child = Bun.spawn(run, {
+    cwd: "/",
+    env: { PATH: "/bin:/usr/bin:/sbin:/usr/sbin", ...process.env },
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const forward = (signal) => { try { child.kill(signal); } catch {} };
+  for (const signal of ["SIGTERM", "SIGHUP"]) process.on(signal, forward);
+  await child.exited;
+  status = child.exitCode ?? (128 + (signalNumbers[child.signalCode] ?? 0));
+} catch (error) {
+  console.error(`chroot: failed to run ${run[0]}: ${error.message}`);
+  status = error.code === "ENOENT" ? 127 : 126;
+} finally {
+  for (const signal of ignored) process.off(signal, ignore);
+  cleanup();
+}
+
+process.exit(status);

package/initramfs/bin/stripansi

@@ -0,0 +1,27 @@
+#!/bin/bun
+// stripansi — concatenate text inputs after removing ANSI escape sequences.
+
+const operands = process.argv.slice(2);
+const inputs = operands.length === 0
+  ? ["-"]
+  : operands[0] === "--" ? operands.slice(1) : operands;
+
+let stdinText;
+let failed = false;
+
+const readInput = async (operand) => {
+  if (operand !== "-") return Bun.file(operand).text();
+  stdinText ??= Bun.stdin.text();
+  return stdinText;
+};
+
+for (const operand of inputs) {
+  try {
+    process.stdout.write(Bun.stripANSI(await readInput(operand)));
+  } catch (error) {
+    console.error(`stripansi: ${operand}: ${error.message}`);
+    failed = true;
+  }
+}
+
+if (failed) process.exitCode = 1;