buninu-linux 0.4.0 → 0.5.1

package/README.md

@@ -37,6 +37,7 @@
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
   * The bundled `jmi` editor, jsmdcui editor/terminal multitasking, and local JavaScript execution also work.
   * The graphical terminal `bunterm` draws on the framebuffer with CJK, colour emoji and kitty images; see [Showing images](#showing-images)
+    + Also has mouse click, wheel, and cursor drawing
 
 ---
 
@@ -310,6 +311,9 @@ buninu-help
 # Markdown view with its images in place
 # cfg.net first to show that GitHub image
 jsmdcui --allow-url README.md
+
+# The mouse works in bunterm; --no-mouse leaves /dev/input alone
+bunterm -e jsmdcui --allow-url README.md
 ```
 
 `bunterm` draws with Skia (CanvasKit) and understands the kitty graphics
@@ -333,18 +337,24 @@ needs a kernel with a framebuffer: build with `--linux-lts` or `--real`
 | `poweroff` | sync pending writes and power off through the Linux reboot system call | `poweroff --help` |
 | `reboot` | sync pending writes and restart through the shared Linux reboot logic | `reboot --help` |
 | `tar` | create, extract, or list tar archives with gzip and zstd compression through `Bun.Archive` | `tar --help` |
-| `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images; xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
+| `stripansi` | remove ANSI escape sequences from stdin, `-`, or one or more files and concatenate the results | — |
+| `chroot` | `chroot(2)` into another root directory, mounting `/proc`, `/sys`, `/dev`, `/dev/pts`, `/run`, `/tmp` and `/etc/resolv.conf` for you and unmounting them afterwards | `chroot --help` |
+| `bunterm` | a graphical terminal on the framebuffer: Skia (CanvasKit) text with CJK, colour emoji, seamless box drawing, kitty graphics images, with the mouse working, wheel scrollback included (`--no-mouse` turns it off); xterm.js's emulator core over Bun's built-in PTY | `bunterm --help` |
 
-Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes nine commands
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes eleven commands
 implemented as Bun scripts.
 
-The small `tar` follows the current `Bun.Archive` boundary: extraction
-restores directories and symbolic links, while hard links are skipped by Bun
-1.4.3. Creation stores regular files but not Unix metadata, links, or empty
-directories, and listing reports regular files only. It supports gzip and
-Bun's built-in zstd, not xz or bzip2.
+The small `tar` reads the archive's own headers for links and listing, so
+extraction restores directories, hard links and every symbolic link —
+including the absolute targets `Bun.Archive` refuses, which is what makes an
+unpacked Alpine root filesystem usable — and `-t` lists every member, not
+only regular files. Creation still follows the `Bun.Archive` boundary: it
+stores regular files but not Unix metadata, links, or empty directories. It
+supports gzip and Bun's built-in zstd, not xz or bzip2.
 
-`--help` renders each Markdown manual in the terminal. Common examples:
+`--help` renders each Markdown manual in the terminal. The `bun x` examples
+below require network access: `bun x` downloads the requested program from the
+npm registry and runs it without installing it permanently. Common examples:
 
 ```sh
 mount /dev/sda1 /mnt --mkdir
@@ -354,6 +364,34 @@ mount -t ntfs3 -o force /dev/sda3 /mnt/windows
 umount /mnt
 umount -R /mnt
 
+
+# Clone a Git repository through bunproot
+bun x bunproot --git clone https://github.com/jjtseng93/bunproot
+
+# Read bunproot's Git manual without ANSI formatting in jmi
+bunterm
+bun x bunproot --git --readme | stripansi | jmi
+
+
+
+# Download and enter an x64 Alpine minirootfs
+bun x bunproot --download-alpine-x64
+mkdir alpine
+cd alpine
+tar xvf ../alpine-minirootfs-*-x86_64.tar.gz
+cp $(which bun) bin
+chroot .
+apk add libgcc libstdc++
+
+
+# Enter a root filesystem on a disk. /proc, /sys, /dev, /dev/pts, /run, /tmp
+# and /etc/resolv.conf are mounted for you and removed again on exit
+chroot /mnt
+chroot /mnt /bin/bun --version
+chroot -n /mnt /bin/sh        # traditional: mount nothing
+
+
+
 ip link set eth0 up
 ip addr add 192.168.1.50/24 dev eth0
 ip route add default via 192.168.1.1
@@ -730,7 +768,8 @@ Two things to expect:
 
 The `/bin` commands described earlier are Bun scripts built on two shared
 modules in `/lib`. `--help` uses `Bun.markdown.ansi` to render the Markdown
-manual with hyperlinks. The shared pieces are:
+manual with hyperlinks, and prints the page's absolute path at the end so it
+can be read or edited directly. The shared pieces are:
 
 * `/lib/dlopen.js` — one `bun:ffi` binding to `/lib/libc.musl-x86_64.so.1`
   (`mount`, `umount2`, `ioctl`, `socket`, `sync`, `reboot`, `syscall`, …), `errno`/`strerror`,
@@ -812,7 +851,13 @@ was found.
 It installs signal handlers, loads a separate physical copy of musl through
 `bun:ffi`, mounts `/proc`, `/sys`, `/dev`, `/tmp` and `/dev/pts` (without
 the devpts mount every pty open fails with `ENODEV`, since `/dev/ptmx`
-resolves through `/dev/pts/ptmx`), prints a greeting, and starts `node:repl`.
+resolves through `/dev/pts/ptmx`), turns Num Lock on, prints a greeting, and
+starts `node:repl`. The kernel starts every virtual console with Num Lock
+off, so the keypad would type arrows instead of digits; init sets it through
+`KDSKBLED` on each console that exists, as the current state and as the state
+a console is reset to. A console first activated later — `Ctrl-Alt-F3` on a
+fresh boot — starts from the kernel default again, and `numlock()` in the REPL
+(or `numlock(false)`) applies the setting to every console again.
 Submitting an empty or whitespace-only REPL line prints the welcome message
 and the available `cfg` getters again. The loader and libc paths
 contain identical bytes but are deliberately distinct inodes:

package/fetch-alpine.sh

@@ -66,6 +66,12 @@ for module in failover net_failover virtio_net; do select_module "$module"; done
 for module in virtio_blk ext4 ext2 vfat exfat ntfs3 nls_utf8 nls_cp437 nls_iso8859-1; do
     select_module "$module"
 done
+# Pointing devices for `bunterm --mouse`, which reads /dev/input/event*.
+# evdev is the character-device interface to the input layer; psmouse drives
+# the PS/2 mouse every PC and QEMU's q35 machine has. A USB mouse needs the
+# usbhid stack, which only the --real image carries. init.js loads these two
+# at boot; nothing reads a pointer unless bunterm is asked to.
+for module in evdev psmouse; do select_module "$module"; done
 
 if [ "${REAL_MACHINE:-}" = 1 ]; then
     # USB keyboard for the console; common storage paths (SATA/AHCI HDD and

package/graphics.md

@@ -19,6 +19,7 @@ via Bun FFI.
  │   @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
@@ -130,6 +131,7 @@ Around those, `/lib/bunterm/` adds:
 | `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`.
@@ -150,7 +152,9 @@ Manual: `bunterm --help` / `initramfs/usr/share/doc/buninu-linux/bunterm.md`.
 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. Terminal
+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.
 
@@ -204,7 +208,8 @@ through its transmit / `a=p` / `a=d` sequence exactly as in the browser.
 
 ## Not done yet
 
-- Mouse, selection and scrollback viewing in `bunterm`.
+- 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

package/initramfs/bin/bunterm

@@ -6,7 +6,7 @@ import { runTerminal } from "../lib/bunterm/terminal.js";
 
 const usage = () => {
   console.error(`Usage:
-  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [-e command [argument...]]
+  bunterm [/dev/ttyN] [--font-size N] [--fb /dev/fb0] [--no-mouse] [-e command [argument...]]
   bunterm -h | --help`);
 };
 
@@ -46,6 +46,10 @@ const main = async () => {
       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 {

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;

package/initramfs/bin/tar

@@ -2,7 +2,8 @@
 // tar — a small tar/gzip/zstd CLI over Bun.Archive.
 
 import { lstat, readdir } from "node:fs/promises";
-import { basename, join, resolve } from "node:path";
+import { linkSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { showDocument } from "../lib/document.js";
 
 const fail = (message) => {
@@ -89,16 +90,186 @@ const archiveBytes = async () => {
   return zstd ? Bun.zstdDecompressSync(bytes) : bytes;
 };
 
+// ----------------------------------------------------------- tar headers --
+//
+// Bun.Archive extracts files, and symbolic links only when their target is
+// relative and stays inside the extraction directory, which drops every
+// absolute target (`/bin/busybox` — 306 of the 335 links in an Alpine
+// minirootfs), every hard link, and every non-regular entry in
+// `Archive.files()`. The header scan below reads the archive itself, so
+// listing is complete and the links can be restored afterwards. Formats:
+// POSIX ustar, GNU long names (`L`/`K`) and pax extended headers (`x`).
+
+const BLOCK = 512;
+const decoder = new TextDecoder();
+
+const text = (block, offset, length) => {
+  let end = offset;
+  const stop = offset + length;
+  while (end < stop && block[end] !== 0) end++;
+  return decoder.decode(block.subarray(offset, end));
+};
+
+const octal = (block, offset, length) => {
+  // GNU base-256 encoding for values that do not fit the octal field.
+  if (block[offset] & 0x80) {
+    let value = block[offset] & 0x7f;
+    for (let index = offset + 1; index < offset + length; index++) value = value * 256 + block[index];
+    return value;
+  }
+  const digits = text(block, offset, length).trim();
+  const value = Number.parseInt(digits, 8);
+  return Number.isFinite(value) ? value : 0;
+};
+
+// The header checksum is computed with its own field read as spaces. A
+// mismatch means this is not a tar header, so scanning stops there.
+const checksumMatches = (block) => {
+  let sum = 0;
+  for (let index = 0; index < BLOCK; index++) {
+    sum += index >= 148 && index < 156 ? 0x20 : block[index];
+  }
+  return sum === octal(block, 148, 8);
+};
+
+const paxRecords = (data) => {
+  const records = {};
+  let offset = 0;
+  const content = decoder.decode(data);
+  while (offset < content.length) {
+    const space = content.indexOf(" ", offset);
+    if (space === -1) break;
+    const length = Number.parseInt(content.slice(offset, space), 10);
+    if (!Number.isFinite(length) || length <= 0) break;
+    const record = content.slice(space + 1, offset + length).replace(/\n$/, "");
+    const equals = record.indexOf("=");
+    if (equals > 0) records[record.slice(0, equals)] = record.slice(equals + 1);
+    offset += length;
+  }
+  return records;
+};
+
+const entryKinds = {
+  "0": "file", "\0": "file", "1": "hardlink", "2": "symlink", "3": "character",
+  "4": "block", "5": "directory", "6": "fifo", "7": "file",
+};
+
+// Every member of the archive, in order, as { name, kind, target, size, mode,
+// mtime }. Returns null when the bytes do not parse as tar.
+const scanEntries = (bytes) => {
+  const entries = [];
+  let offset = 0;
+  let longName = null;
+  let longTarget = null;
+  let extended = {};
+  while (offset + BLOCK <= bytes.length) {
+    const block = bytes.subarray(offset, offset + BLOCK);
+    offset += BLOCK;
+    if (block.every((byte) => byte === 0)) break; // end-of-archive blocks
+    if (!checksumMatches(block)) return entries.length ? entries : null;
+    const flag = String.fromCharCode(block[156] || 0x30);
+    const size = extended.size !== undefined ? Number(extended.size) : octal(block, 124, 12);
+    const dataBlocks = Math.ceil(size / BLOCK) * BLOCK;
+    const data = bytes.subarray(offset, offset + size);
+    if (flag === "L" || flag === "K") {
+      const value = decoder.decode(data).replace(/\0+$/, "");
+      if (flag === "L") longName = value; else longTarget = value;
+      offset += dataBlocks;
+      continue;
+    }
+    if (flag === "x" || flag === "X") {
+      extended = { ...extended, ...paxRecords(data) };
+      offset += dataBlocks;
+      continue;
+    }
+    if (flag === "g") {
+      offset += dataBlocks;
+      continue;
+    }
+    const prefix = text(block, 345, 155);
+    const stored = text(block, 0, 100);
+    const name = extended.path ?? longName ?? (prefix ? `${prefix}/${stored}` : stored);
+    const target = extended.linkpath ?? longTarget ?? text(block, 157, 100);
+    entries.push({
+      name: name.replace(/^\.\//, ""),
+      kind: entryKinds[flag] ?? "file",
+      target,
+      size,
+      mode: octal(block, 100, 8) & 0o7777,
+      mtime: octal(block, 136, 12) * 1000,
+    });
+    longName = null;
+    longTarget = null;
+    extended = {};
+    offset += dataBlocks;
+  }
+  return entries;
+};
+
+const tarBytes = (bytes) => {
+  if (bytes[0] === 0x1f && bytes[1] === 0x8b) return Bun.gunzipSync(bytes);
+  if (bytes[0] === 0x28 && bytes[1] === 0xb5 && bytes[2] === 0x2f && bytes[3] === 0xfd) {
+    return Bun.zstdDecompressSync(bytes);
+  }
+  return bytes;
+};
+
+// Where a member lands, following GNU tar: a leading `/` is stripped, and a
+// name that climbs out with `..` is refused. A link's target is never
+// examined — an absolute symbolic link is a normal thing for a root
+// filesystem to contain — and since links are made after every file, nothing
+// is ever written through one.
+const memberName = (name) => {
+  const stripped = name.replace(/^\/+/, "");
+  const parts = stripped.split("/");
+  if (parts.includes("..")) return null;
+  return stripped || null;
+};
+
 const patterns = () => options.operands.flatMap((name) => {
   const clean = name.replace(/^\.\//, "").replace(/\/$/, "");
   return [clean, `${clean}/**`];
 });
 
-const verboseListing = (name, file) => {
-  const modified = Number.isFinite(file.lastModified) && file.lastModified > 0
-    ? new Date(file.lastModified).toISOString().replace("T", " ").slice(0, 16)
+const kindMarks = { directory: "/", symlink: "@", fifo: "|", character: "#", block: "#" };
+
+const verboseListing = (entry) => {
+  const modified = entry.mtime > 0
+    ? new Date(entry.mtime).toISOString().replace("T", " ").slice(0, 16)
     : "---- -- -- --:--";
-  return `${String(file.size).padStart(12)} ${modified} ${name}`;
+  const suffix = entry.kind === "symlink" ? ` -> ${entry.target}`
+    : entry.kind === "hardlink" ? ` link to ${entry.target}`
+    : "";
+  return `${String(entry.size).padStart(12)} ${modified} ${entry.name}${kindMarks[entry.kind] ?? ""}${suffix}`;
+};
+
+// Creates the links Bun.Archive left out. Files are already in place, so a
+// hard link finds its target and a symbolic link cannot be written through.
+const restoreLinks = (entries) => {
+  for (const entry of entries) {
+    if (entry.kind !== "symlink" && entry.kind !== "hardlink") continue;
+    const name = memberName(entry.name);
+    if (!name || !entry.target) continue;
+    const path = resolve(options.directory, name);
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      try {
+        if (entry.kind === "symlink") symlinkSync(entry.target, path);
+        else linkSync(resolve(options.directory, memberName(entry.target) ?? entry.target), path);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        // GNU tar replaces what is in the way rather than following it.
+        rmSync(path, { force: true });
+        if (entry.kind === "symlink") symlinkSync(entry.target, path);
+        else linkSync(resolve(options.directory, memberName(entry.target) ?? entry.target), path);
+      }
+    } catch (error) {
+      // A hard link whose target was filtered out by a member pattern is
+      // expected; anything else is worth reporting without stopping.
+      if (entry.kind === "hardlink" && error.code === "ENOENT" && options.operands.length) continue;
+      console.error(`tar: ${entry.name}: ${error.message}`);
+    }
+  }
 };
 
 if (options.operation === "x" || options.operation === "t") {
@@ -109,22 +280,26 @@ if (options.operation === "x" || options.operation === "t") {
     fail(error?.message || String(error));
   }
 
+  // The header scan is what makes listing and links complete; if the bytes
+  // do not parse as tar, fall back to what Bun.Archive reports.
+  const scanned = scanEntries(tarBytes(await archiveBytes()));
+  const wanted = options.operands.length ? patterns().map((pattern) => new Bun.Glob(pattern)) : null;
+  const members = scanned
+    ? scanned.filter((entry) => !wanted || wanted.some((glob) => glob.match(entry.name)))
+    : [...(await archive.files(options.operands.length ? patterns() : undefined))]
+      .map(([name, file]) => ({ name, kind: "file", target: "", size: file.size, mode: 0o644, mtime: file.lastModified }));
+
   if (options.operation === "t") {
-    try {
-      const files = await archive.files(options.operands.length ? patterns() : undefined);
-      for (const [name, file] of files) {
-        console.log(options.verbose ? verboseListing(name, file) : name);
-      }
-    } catch (error) {
-      fail(error?.message || String(error));
+    for (const entry of members) {
+      console.log(options.verbose ? verboseListing(entry) : entry.name);
     }
   } else {
     try {
       if (options.verbose) {
-        const files = await archive.files(options.operands.length ? patterns() : undefined);
-        for (const name of files.keys()) console.log(name);
+        for (const entry of members) console.log(entry.name);
       }
       await archive.extract(options.directory, options.operands.length ? { glob: patterns() } : undefined);
+      restoreLinks(members);
     } catch (error) {
       fail(error?.message || String(error));
     }