buninu-linux 0.4.0 → 0.6.0

package/initramfs/lib/bunterm/terminal.js

@@ -50,6 +50,7 @@ export const createSession = ({
   theme = defaultTheme,
   scrollback = 1000,
   cursorBlink = true,
+  mouse = true,
   env = {},
   onError = (error) => console.error(`bunterm: ${error?.stack ?? error}`),
 }) => {
@@ -82,13 +83,24 @@ export const createSession = ({
   let frameTimer = null;
   let blinkOn = true;
   const cursorHidden = () => Boolean(term._core?.coreService?.isCursorHidden);
+  // Only set when a pointer is attached; without one the renderer is called
+  // exactly as before.
+  let pointer = null;
   const paint = () => {
     if (frameTimer) clearTimeout(frameTimer);
     frameTimer = null;
     const buffer = term.buffer.active;
+    // cursorY counts from the buffer's base, so a scrolled-back viewport
+    // moves the cursor down the screen and eventually off it.
+    const row = buffer.baseY + buffer.cursorY - buffer.viewportY;
     return renderer.render(term, {
-      cursor: { x: buffer.cursorX, y: buffer.cursorY, visible: blinkOn && !cursorHidden() },
+      cursor: {
+        x: buffer.cursorX,
+        y: row,
+        visible: blinkOn && !cursorHidden() && row >= 0 && row < renderer.rows,
+      },
       images: images.visible(),
+      pointer,
     });
   };
   const requestFrame = () => {
@@ -137,10 +149,102 @@ export const createSession = ({
     const applicationCursorKeys = Boolean(term._core?.coreService?.decPrivateModes?.applicationCursorKeys);
     const text = translateKeys(bytes.toString("latin1"), { applicationCursorKeys });
     backend.write(Buffer.from(text, "latin1"));
+    // Typing returns to the live screen, as every terminal does.
+    if (term.buffer.active.viewportY !== term.buffer.active.baseY) {
+      term.scrollToBottom();
+      renderer.invalidate();
+    }
     resetBlink();
     requestFrame();
   };
 
+  // Turns a pointer report from mouse.js into the mouse sequences the
+  // program asked for. xterm.js's CoreMouseService owns the protocol: it
+  // knows which events the program enabled (DECSET 1000/1002/1003), encodes
+  // them (SGR 1006 or the default form) and sends them through onData, so
+  // nothing here builds an escape sequence. Reports arrive only while a
+  // pointer is open, and this is the only place the terminal sees one.
+  const CoreMouseButton = { LEFT: 0, MIDDLE: 1, RIGHT: 2, NONE: 3, WHEEL: 4 };
+  const CoreMouseAction = { UP: 0, DOWN: 1, LEFT: 2, RIGHT: 3, MOVE: 32 };
+  const heldButton = (buttons) => (buttons.left ? CoreMouseButton.LEFT
+    : buttons.middle ? CoreMouseButton.MIDDLE
+    : buttons.right ? CoreMouseButton.RIGHT
+    : CoreMouseButton.NONE);
+
+  // Scrolls the viewport when the program is not reading the mouse itself:
+  // through the scrollback on the normal screen, and as arrow keys on the
+  // alternate screen, which has no scrollback and is what a pager expects.
+  const wheelScroll = (notches) => {
+    const lines = notches * 3;
+    if (term.buffer.active.type === "alternate") {
+      const application = Boolean(term._core?.coreService?.decPrivateModes?.applicationCursorKeys);
+      const key = `\u001b${application ? "O" : "["}${lines > 0 ? "A" : "B"}`;
+      backend.write(Buffer.from(key.repeat(Math.abs(lines)), "latin1"));
+      return;
+    }
+    const before = term.buffer.active.viewportY;
+    term.scrollLines(-lines);
+    if (term.buffer.active.viewportY !== before) {
+      // Every row on screen is different now, and identical text at the same
+      // row would otherwise hash the same as before.
+      renderer.invalidate();
+      requestFrame();
+    }
+  };
+
+  const reportMouse = (report) => {
+    pointer = { x: report.x, y: report.y };
+    requestFrame();
+    const service = term._core?.coreMouseService;
+    if (!service?.areMouseEventsActive) {
+      if (report.wheel) wheelScroll(report.wheel);
+      return;
+    }
+    const column = Math.floor((report.x - renderer.offsetX) / renderer.cellWidth);
+    const row = Math.floor((report.y - renderer.offsetY) / renderer.cellHeight);
+    const send = (button, action) => {
+      try {
+        service.triggerMouseEvent({ col: column, row, button, action, ctrl: false, alt: false, shift: false });
+      } catch (error) {
+        onError(error);
+      }
+    };
+    for (const name of report.released) {
+      send(CoreMouseButton[name.toUpperCase()], CoreMouseAction.UP);
+    }
+    for (const name of report.pressed) {
+      send(CoreMouseButton[name.toUpperCase()], CoreMouseAction.DOWN);
+    }
+    if (report.moved) send(heldButton(report.buttons), CoreMouseAction.MOVE);
+    for (let notch = 0; notch < Math.abs(report.wheel); notch++) {
+      send(CoreMouseButton.WHEEL, report.wheel > 0 ? CoreMouseAction.UP : CoreMouseAction.DOWN);
+    }
+    for (let notch = 0; notch < Math.abs(report.hwheel); notch++) {
+      send(CoreMouseButton.WHEEL, report.hwheel > 0 ? CoreMouseAction.RIGHT : CoreMouseAction.LEFT);
+    }
+  };
+
+  // The pointer is opened only when asked for, by a module that is imported
+  // only then, so a machine without one — or a broken input layer — cannot
+  // affect a plain session.
+  let pointerDevice = null;
+  const attachPointer = async () => {
+    if (!mouse) return null;
+    const { openPointer, findPointers } = await import("./mouse.js");
+    const devices = findPointers();
+    if (!devices.length) throw new Error("no pointing device in /dev/input (is the evdev module loaded?)");
+    pointerDevice = openPointer({
+      devices,
+      width: screen.width,
+      height: screen.height,
+      onSync: reportMouse,
+      onError,
+    });
+    pointer = { x: pointerDevice.state.x, y: pointerDevice.state.y };
+    paint();
+    return pointerDevice;
+  };
+
   // Waits until every byte received so far has been parsed, then paints.
   const settle = async () => {
     await queue;
@@ -154,13 +258,18 @@ export const createSession = ({
     if (frameTimer) clearTimeout(frameTimer);
     frameTimer = null;
     backend.close();
+    pointerDevice?.close();
+    pointerDevice = null;
     images.delete();
     renderer.delete();
     term.dispose();
   };
 
   paint();
-  return { term, backend, renderer, images, kitty, paint, requestFrame, settle, input, exited, close };
+  return {
+    term, backend, renderer, images, kitty,
+    paint, requestFrame, settle, input, exited, close, attachPointer, reportMouse, wheelScroll,
+  };
 };
 
 // Runs a session on the framebuffer with the console in graphics mode and
@@ -193,6 +302,18 @@ export const runTerminal = async ({ console: consoleDevice = null, device = "/de
         },
       });
       onRestore(() => keyboard.close());
+      if (options.mouse !== false) {
+        // A pointer that cannot be opened is reported and the session
+        // continues as a keyboard-only terminal.
+        try {
+          const attached = await session.attachPointer();
+          if (attached?.devices.length) {
+            console.error(`bunterm: mouse: ${attached.devices.map((device) => device.name).join(", ")}`);
+          }
+        } catch (error) {
+          console.error(`bunterm: mouse: ${error.message}`);
+        }
+      }
       return await session.exited;
     } finally {
       keyboard?.close();

package/initramfs/lib/dlopen.js

@@ -85,6 +85,10 @@ export const libc = dlopen(libcPath, {
     args: [FFIType.i32, FFIType.ptr, FFIType.i32],
     returns: FFIType.i32,
   },
+  chroot: {
+    args: [FFIType.ptr],
+    returns: FFIType.i32,
+  },
 });
 
 export const cString = (value) => new TextEncoder().encode(`${value}\0`);

package/initramfs/lib/document.js

@@ -1,6 +1,10 @@
 // Shared renderer for /usr/share/doc/buninu-linux/<name>.md command manuals.
+import { resolve } from "node:path";
+
 export const showDocument = async (name) => {
-  const path = `${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`;
+  const path = resolve(`${import.meta.dir}/../usr/share/doc/buninu-linux/${name}.md`);
   const rendered = Bun.markdown.ansi(await Bun.file(path).text(), { hyperlinks: true });
   process.stdout.write(rendered.endsWith("\n") ? rendered : `${rendered}\n`);
+  // Where the page lives, for anyone who wants to read or edit the source.
+  process.stdout.write(`\u001b[2m${path}\u001b[0m\n`);
 };

package/initramfs/usr/share/doc/buninu-linux/bunterm.md

@@ -10,6 +10,7 @@ bunterm                      # run /bin/sh on the console you are on
 bunterm /dev/tty1            # use virtual console 1 for graphics and keys
 bunterm --font-size 20
 bunterm -e bun /buninu/apps/jsmdcui/src/index.js --demo
+bunterm --no-mouse          # keyboard only
 bunterm -h
 ```
 
@@ -28,6 +29,7 @@ text mode and `bunterm` exits with its status.
 | `--line-height F` | Multiplies the cell height (default 1). |
 | `--fb /dev/fbN` | The framebuffer device (default `/dev/fb0`). |
 | `--no-blink` | A steady cursor. |
+| `--no-mouse` | Do not attach a pointing device; nothing then reads `/dev/input`. |
 
 ## What is drawn
 
@@ -59,13 +61,44 @@ screen. A few console-specific
 sequences are rewritten to xterm's (`F1`–`F5`, `Home`, `End`), and arrow keys
 follow the program's application cursor mode.
 
+## Mouse
+
+Every pointing device under `/dev/input/event*` is opened and an arrow is
+drawn on the screen. Clicks, drags and wheel notches reach the program as
+the xterm mouse sequences it asked for: nothing is sent unless the program
+enabled reporting (`DECSET 1000`, `1002` or `1003`), and what is sent follows
+the mode it chose, SGR (`1006`) included. `jsmdcui`, `micro`, `htop`, `vim`
+and anything else that speaks the protocol work with no configuration.
+
+When the program is not reading the mouse, the wheel scrolls instead: back
+through the scrollback on the normal screen, three lines per notch, and as
+arrow keys on the alternate screen, which has no scrollback and is what a
+pager expects. Typing returns to the live screen, and the text cursor is
+hidden while it is scrolled out of view.
+
+`--no-mouse` turns all of this off: the terminal then never looks at
+`/dev/input` and never loads the mouse module.
+
+`init.js` loads `evdev` and `psmouse` at boot, so a PS/2 mouse — which is
+what QEMU's q35 machine and most PCs present — has a device node ready. The
+aarch64 image loads `virtio_input` in place of `psmouse`, for QEMU's
+`virtio-tablet-pci` and `virtio-keyboard-pci`. A USB
+mouse also needs the `usbhid` stack, which a `--real` image carries and
+`cfg.all` loads. The pointer follows relative devices (a mouse) and absolute
+ones (a tablet or touchscreen) alike; a device that cannot be opened is
+reported and the session continues without it.
+
 ## Limits
 
 - Needs a framebuffer: `linux-lts` has one built in, while the default
   `linux-virt` builds it as modules the image does not ship, so build with
   `--linux-lts` or `--real` (efifb/simpledrm from UEFI).
-- No mouse, no selection, no scrollback viewing (the buffer keeps 1000
-  lines for programs that query it).
+- The aarch64 image has no framebuffer yet: `run-qemu.sh` gives QEMU's
+  `virt` machine no display device, so there is no `/dev/fb0` to draw on.
+- No selection, and no keyboard way to scroll back: the wheel is it. The
+  buffer keeps 1000 lines. A program that does not enable mouse reporting
+  sees no clicks — the arrow still moves, so the pointer is visibly alive.
+  `--no-mouse` removes the pointer entirely.
 - A program that prints a terminal reply while the tty echoes (that is, one
   not in raw mode) will see the reply echoed, as on any terminal.
 - Kitty images are drawn above text; `z` ordering below text and animation

package/initramfs/usr/share/doc/buninu-linux/chroot.md

@@ -0,0 +1,105 @@
+# chroot — run a command inside another root directory
+
+`/bin/chroot` is a Bun script that calls `chroot(2)` and `mount(2)` through
+`/lib/dlopen.js`.
+
+Unlike the traditional `chroot`, it prepares the new root first, so a
+freshly unpacked root filesystem is usable straight away, and it undoes
+every mount it made when the command exits.
+
+## Synopsis
+
+```sh
+chroot NEWROOT [COMMAND [ARGUMENT...]]
+chroot [-n] [-k] [-v] NEWROOT [COMMAND [ARGUMENT...]]
+chroot -h | --help
+```
+
+With no COMMAND it runs `$SHELL` if that exists inside NEWROOT, otherwise
+`/bin/sh`, interactively when the terminal is one.
+
+## What it mounts
+
+| Inside NEWROOT | What | Why |
+|---|---|---|
+| `/proc` | a fresh `proc` | path resolution, `ps`, anything reading `/proc/self` |
+| `/sys` | a fresh `sysfs` | device and network information |
+| `/dev` | recursive bind of the host's `/dev`, made a slave mount | every device node, including `/dev/ptmx`, without a second devtmpfs |
+| `/dev/pts` | `devpts`, only if the bind brought none | pseudo-terminals for shells and editors |
+| `/run` | `tmpfs` | runtime state |
+| `/tmp` | `tmpfs` | scratch space that does not touch the root filesystem |
+| `/etc/resolv.conf` | bind of the host's file | name resolution, without editing anything inside |
+
+A mount point that already exists as a mount is left alone. A directory that
+is missing is created; if the root filesystem is read-only and that fails,
+that one mount is skipped and the rest still happen — use `-v` to see which.
+
+Making `/dev` a slave mount means mounts appearing inside the root do not
+propagate back to the host, and unmounting it afterwards cannot take the
+host's `/dev` with it.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-n`, `--no-mount` | Do not mount anything: the behaviour of the traditional `chroot`. Note that Bun itself cannot start without `/proc` and `/dev/urandom`, so `-n` suits statically linked programs. |
+| `-k`, `--keep-mounts` | Leave the mounts in place after the command exits, to enter the same root again cheaply. Clean up later with `umount -R`. |
+| `-v`, `--verbose` | Report every mount and unmount. |
+| `--` | End of options; everything after it is NEWROOT and COMMAND. |
+
+## Examples
+
+```sh
+# Mount a disk and enter the system on it
+mount /dev/vda2 /mnt --mkdir
+chroot /mnt
+
+# Run one command and leave
+chroot /mnt /bin/bun --version
+
+# Watch what is set up and taken down
+chroot -v /mnt /bin/sh -c 'ls /proc | head -3'
+
+# Traditional behaviour: nothing is mounted for you
+chroot -n /mnt /bin/sh
+
+# Keep the mounts for repeated visits
+chroot -k /mnt /bin/sh -c 'true'
+chroot -k /mnt
+umount -R /mnt
+```
+
+## Cleanup
+
+When the command exits, every mount this invocation made is unmounted,
+deepest first, including anything that appeared under the recursive `/dev`
+bind. A mount that is still busy — a process left running inside, a shell
+with its working directory there — is detached instead (`MNT_DETACH`), so
+the kernel releases it once its last user goes away. The same cleanup runs
+if `chroot(2)` itself fails or the command cannot be started, and on
+`SIGTERM` or `SIGHUP`.
+
+`Ctrl-C` goes to the command, not to `chroot`, so the mounts are still
+removed after an interrupted program.
+
+## Limits
+
+- Needs to be superuser: `chroot(2)` requires `CAP_SYS_CHROOT`, and the
+  mounts require `CAP_SYS_ADMIN`. Buninu normally runs as root.
+- The new root must contain the program you ask for and whatever it links
+  against; `chroot /mnt /bin/sh` fails with "not found" if `/mnt/bin/sh`
+  is not there.
+- Only the filesystem view changes. Processes, network, users and the
+  hostname are shared with the host; this is not a container.
+- `-k` leaves mounts behind on purpose. `umount -R NEWROOT` removes them.
+
+## Exit status
+
+The command's own status, or `125` if `chroot` itself failed, `126` if the
+command was found but could not be run, and `127` if it was not found.
+
+## See also
+
+- Source: `/bin/chroot`
+- `mount --help`, `umount --help`
+- Shared native binding: `/lib/dlopen.js`

package/initramfs/usr/share/doc/buninu-linux/tar.md

@@ -27,7 +27,9 @@ Use `-` as ARCHIVE to read from standard input or write to standard output.
 | `-C DIR`, `--directory=DIR` | Read input files from DIR, or extract into DIR. |
 | `-z`, `--gzip` | Create gzip-compressed tar, or explicitly identify gzip input. |
 | `--zstd` | Create or read a zstd-compressed tar. A `.zst` or `.tzst` input is also detected by name. |
-| `-v` | Print names while creating/extracting; with `-t`, also show each regular file's size and modification time. |
+| `-v` | Print names while creating/extracting; with `-t`, also show each member's size, modification time, kind and link target. |
+| `-o`, `--no-same-owner`, `--no-same-permissions`, `--overwrite` | GNU tar compatibility for extraction; these already match Bun.Archive's behaviour. |
+| `--exclude=PATTERN` | Accepted for js-udocker compatibility. Device nodes are not extracted and js-udocker removes whiteout files separately. |
 
 Short options can be combined, for example `-xzvf` or `-czf`.
 For the traditional first option word, the leading hyphen is optional, so
@@ -42,8 +44,34 @@ tar -xzf source.tar.gz -C /tmp/source
 tar -tf source.tar.gz
 tar --zstd -cf backup.tar.zst home
 tar --zstd -xf backup.tar.zst -C /mnt/restore
+
+# An Alpine root filesystem, symbolic links and all; then enter it
+tar -xzf alpine-minirootfs-3.24.1-x86_64.tar.gz -C /mnt/alpine
+chroot /mnt/alpine
 ```
 
+## Links
+
+Extraction restores symbolic links exactly as the archive records them,
+including absolute targets such as `/bin/busybox` and targets that do not
+exist yet, and it restores hard links. This is what GNU tar does, and it is
+what an unpacked root filesystem needs: an Alpine minirootfs is 335 symbolic
+links, 306 of them absolute, and without them the result has no `/bin/sh`.
+
+`Bun.Archive` creates only the symbolic links whose target is relative and
+stays inside the extraction directory, and skips hard links entirely, so
+this command reads the archive's own headers (ustar, GNU `L`/`K` long names,
+pax `x` records) and creates the rest itself once every file is in place.
+Nothing is ever written through a link, because the links are made last.
+
+A member's own name still follows GNU tar's rule: a leading `/` is dropped
+and a name containing `..` is refused, so an archive cannot write outside
+the extraction directory.
+
+The same header scan backs listing, so `-t` reports every member —
+directories, links, devices — and not just regular files. A symbolic link
+shows its target, a hard link the file it points at.
+
 ## Current Bun.Archive limits
 
 Creation stores regular files only. Symbolic links are rejected rather than
@@ -51,11 +79,9 @@ silently archived as the wrong type; modes, ownership, hard links, and empty
 directories are not preserved. Bun 1.4.3 also requires file contents to be
 materialized in memory before archive creation.
 
-Extraction restores directories and symbolic links, but Bun 1.4.3 skips hard
-links. Listing and verbose extraction use `Archive.files()`, so they report
-regular files only. Verbose listing can show their size and modification time,
-but not the unavailable mode or owner. Bun provides gzip and zstd codecs but no xz or bzip2 codec,
-so this command does not accept `.tar.xz` or `.tar.bz2`.
+Extraction does not restore modes, ownership or timestamps. Bun provides gzip
+and zstd codecs but no xz or bzip2 codec, so this command does not accept
+`.tar.xz` or `.tar.bz2`.
 
 Appending with `-r`/`rvf` is not supported. `Bun.Archive` has no append API;
 rebuilding an existing archive through `Archive.files()` would silently lose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A Linux distribution running Bun as PID 1 with the Buninu userspace.",
   "type": "module",
   "main": "./index.js",
@@ -37,6 +37,6 @@
     "fetch": "./index.js -f",
     "pack": "./index.js -b",
     "start": "./index.js -r",
-    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/document.js ./initramfs/lib/dlopen.js ./initramfs/lib/fbdev.js ./initramfs/lib/canvas.js ./initramfs/lib/bunterm/glyphs.js ./initramfs/lib/bunterm/renderer.js ./initramfs/lib/bunterm/images.js ./initramfs/lib/bunterm/input.js ./initramfs/lib/bunterm/terminal.js ./initramfs/lib/modprobe.js ./initramfs/lib/power.js ./initramfs/bin/bunterm ./initramfs/bin/mount ./initramfs/bin/umount ./initramfs/bin/ip ./initramfs/bin/ps ./initramfs/bin/top ./initramfs/bin/poweroff ./initramfs/bin/reboot ./initramfs/bin/tar; do node --check \"$f\" || exit 1; done"
+    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/document.js ./initramfs/lib/dlopen.js ./initramfs/lib/fbdev.js ./initramfs/lib/canvas.js ./initramfs/lib/bunterm/glyphs.js ./initramfs/lib/bunterm/renderer.js ./initramfs/lib/bunterm/images.js ./initramfs/lib/bunterm/input.js ./initramfs/lib/bunterm/mouse.js ./initramfs/lib/bunterm/terminal.js ./initramfs/lib/modprobe.js ./initramfs/lib/power.js ./initramfs/bin/bunterm ./initramfs/bin/chroot ./initramfs/bin/mount ./initramfs/bin/umount ./initramfs/bin/ip ./initramfs/bin/ps ./initramfs/bin/top ./initramfs/bin/poweroff ./initramfs/bin/reboot ./initramfs/bin/tar ./initramfs/bin/stripansi; do node --check \"$f\" || exit 1; done"
   }
 }

package/run-qemu.sh

@@ -2,19 +2,68 @@
 
 cd "$(dirname "$0")"
 
-test -f vda.img || ./build-image.sh
-
-if [ -z "$PREFIX" ] ; then
-  PREFIX=/usr
+# The guest is whatever build-uki.sh last put in vda/EFI/BOOT (it leaves only
+# one architecture there), unless BUNINU_ARCH (index.js --arch) names one.
+if [ -z "$BUNINU_ARCH" ] && [ -f vda/EFI/BOOT/BOOTAA64.EFI ]; then
+    BUNINU_ARCH=aarch64
 fi
+. ./scripts/arch.sh
+
+test -f vda.img || ./build-image.sh || exit 1
+test -f "vda/EFI/BOOT/$efi_boot_name" || {
+    echo "error: vda.img holds no $arch UKI; build one with ./index.js -b --arch $arch" >&2
+    exit 1
+}
+
+qemu="qemu-system-$arch"
+command -v "$qemu" >/dev/null || {
+    echo "error: $qemu not found (macOS: brew install qemu; Debian: apt install qemu-system)" >&2
+    exit 1
+}
 
-ovmf_filepath="$PREFIX"/share/qemu/edk2-x86_64-code.fd
+case $arch in
+    x86_64) machine=q35 distro_firmware=/usr/share/OVMF/OVMF_CODE_4M.fd ;;
+    aarch64) machine=virt distro_firmware=/usr/share/AAVMF/AAVMF_CODE.fd ;;
+esac
+
+# UEFI firmware: OVMF_FILE if set; then the edk2 build QEMU ships next to its
+# own binary (Termux's $PREFIX/share/qemu, Homebrew's share/qemu, ...); then
+# the distribution packages (Debian ovmf / qemu-efi-aarch64).
+qemu_share="$(dirname "$(command -v "$qemu")")/../share/qemu"
+ovmf_filepath=
+for candidate in "$OVMF_FILE" "$distro_firmware" "$qemu_share/edk2-$arch-code.fd" \
+    "/usr/share/qemu/edk2-$arch-code.fd"; do
+    if [ -n "$candidate" ] && [ -f "$candidate" ]; then
+        ovmf_filepath=$candidate
+        break
+    fi
+done
+test -n "$ovmf_filepath" || {
+    echo "error: no $arch UEFI firmware found; set OVMF_FILE to an edk2-$arch-code.fd" >&2
+    exit 1
+}
 
-if [ -f /usr/share/OVMF/OVMF_CODE_4M.fd ] ; then
-  ovmf_filepath=/usr/share/OVMF/OVMF_CODE_4M.fd
-elif [ -f "$OVMF_FILE" ] ; then
-  ovmf_filepath=$OVMF_FILE
+# Hardware acceleration needs the guest to match the host CPU: KVM on Linux,
+# Hypervisor.framework on macOS (Apple Silicon runs the aarch64 guest natively,
+# an Intel Mac the x86_64 one). Anything else, such as the x86_64 guest on
+# Apple Silicon or on an Android phone, is emulated with TCG. ACCEL overrides
+# the choice, e.g. ACCEL=tcg to rule acceleration out while debugging.
+case "$(uname -m)" in
+    arm64 | aarch64) host_arch=aarch64 ;;
+    *) host_arch=$(uname -m) ;;
+esac
+if [ -z "$ACCEL" ]; then
+    ACCEL=tcg
+    if [ "$host_arch" = "$arch" ]; then
+        case "$(uname -s)" in
+            Linux) [ -r /dev/kvm ] && [ -w /dev/kvm ] && ACCEL=kvm ;;
+            Darwin) [ "$(sysctl -n kern.hv_support 2>/dev/null)" = 1 ] && ACCEL=hvf ;;
+        esac
+    fi
 fi
+# TCG emulates every feature it knows; KVM and HVF pass the host CPU through.
+if [ "$ACCEL" = tcg ]; then cpu=max; else cpu=host; fi
+echo "run-qemu.sh: $arch guest on $machine, accel=$ACCEL, firmware $ovmf_filepath" >&2
 
 # User-mode networking is NAT: the guest can reach out, nothing reaches in
 # unless a port is forwarded. PORTS lists them, space-separated, as
@@ -31,9 +80,9 @@ for port in ${PORTS:-}; do
     nic="$nic,hostfwd=tcp:127.0.0.1:$host-:$guest"
 done
 
-exec qemu-system-x86_64 \
-    -machine q35,accel=tcg \
-    -cpu max \
+exec "$qemu" \
+    -machine "$machine,accel=$ACCEL" \
+    -cpu "$cpu" \
     -m 1G \
     -drive if=pflash,format=raw,readonly=on,file="$ovmf_filepath" \
     -drive if=virtio,format=raw,file=vda.img \

package/scripts/arch.sh

@@ -0,0 +1,113 @@
+# Sourced by the fetch, build and run scripts; not executable on its own.
+#
+# Everything that differs between the two guest architectures lives here:
+# the pinned packages and their SHA-256, the file names inside them, the EFI
+# removable-media name, the PE-aware objcopy that assembles the UKI and the
+# serial console. BUNINU_ARCH (index.js --arch) picks one; x86_64 is the
+# default. LINUX_FLAVOR (virt or lts) and REAL_MACHINE are read here too.
+#
+# Fetched and extracted files are kept per architecture, so both guests can
+# be built from one checkout without refetching:
+#
+#   downloads/<arch>/  the pinned archives (both repos use the same names)
+#   kernel/<arch>/     vmlinuz-<flavor> and the UKI stub
+#   native/<arch>/     bun, musl, libgcc/libstdc++ and kernel modules;
+#                      scripts/pack-initramfs.sh lays it over initramfs/
+
+case "${BUNINU_ARCH:-x86_64}" in
+    x86_64 | amd64 | x64) arch=x86_64 ;;
+    aarch64 | arm64) arch=aarch64 ;;
+    *)
+        echo "error: unsupported BUNINU_ARCH=$BUNINU_ARCH (use x86_64 or aarch64)" >&2
+        exit 1
+        ;;
+esac
+
+linux_flavor=${LINUX_FLAVOR:-virt}
+case $linux_flavor in
+    virt | lts) ;;
+    *)
+        echo "error: unsupported LINUX_FLAVOR=$linux_flavor (use virt or lts)" >&2
+        exit 1
+        ;;
+esac
+
+if [ "${REAL_MACHINE:-}" = 1 ] && [ "$arch" != x86_64 ]; then
+    echo "error: --real images are x86_64 only; its module set is PC hardware" >&2
+    exit 1
+fi
+
+# The Alpine repository keeps only the newest build of a package, so a pin
+# stops downloading when Alpine bumps it; the hashes below then fail loudly
+# rather than silently taking the new build. ALPINE_MIRROR swaps the host for
+# a closer mirror; the SHA-256 check is the same either way.
+alpine_mirror=${ALPINE_MIRROR:-https://dl-cdn.alpinelinux.org/alpine}
+alpine_base="$alpine_mirror/v3.24/main/$arch"
+
+kernel_version=6.18.53
+kernel_release="$kernel_version-0-$linux_flavor"
+linux_package="linux-$linux_flavor-$kernel_version-r0.apk"
+musl_package=musl-1.2.6-r2.apk
+stub_package=systemd-efistub-260.2-r0.apk
+libstdcpp_package=libstdc++-15.2.0-r5.apk
+libgcc_package=libgcc-15.2.0-r5.apk
+bun_version=1.4.2
+
+downloads_dir="downloads/$arch"
+kernel_dir="kernel/$arch"
+kernel_image="$kernel_dir/vmlinuz-$linux_flavor"
+native_dir="native/$arch"
+modules_root="$native_dir/lib/modules/$kernel_release"
+musl_loader="ld-musl-$arch.so.1"
+musl_libc="libc.musl-$arch.so.1"
+
+case $arch in
+    x86_64)
+        linux_virt_sha256=cad859cc46342e18002621fdde166bf2cd520dfec5e781d241de7d13e53970d6
+        linux_lts_sha256=8e3cfdd1d98e0e70c2e70a8c299ed3cd1e0939d60ad7bbd1da1cf241d794490b
+        musl_sha256=573712e2f49c15bfc20a2699f204acdfc74c772722b15e7353d768057fae0e71
+        stub_sha256=8e64a5a3afee5f930e6e6716be726dc6d405530ac7f8fa5be6251dae68671ec9
+        libstdcpp_sha256=14c987b556f5385a5db18376e788c75f37d85321b8dc1920d926ea7daac1d6f6
+        libgcc_sha256=393dcd32629f06d7d85409c272d142d0c082772d10b87ef55ee82f47de3be637
+        # Bun ships one x64 musl build; -baseline is an alias (NOTICE.md).
+        bun_build=bun-linux-x64-musl-baseline
+        bun_sha256=76e1db84e98f22f78de0a87e309bfbbf297732847f9720db36750646c85c8c18
+        efi_stub=linuxx64.efi.stub
+        efi_boot_name=BOOTX64.EFI
+        uki_objcopy=x86_64-w64-mingw32-objcopy
+        uki_objdump=x86_64-w64-mingw32-objdump
+        uki_binutils_package=binutils-mingw-w64-x86-64
+        # COM1 on q35 and on PCs.
+        serial_console=ttyS0
+        serial_major=4
+        ;;
+    aarch64)
+        linux_virt_sha256=fea61b7fd5e72e626d771f9798df56c83db658d0e221044f06fc28aacf5a118b
+        linux_lts_sha256=46885041022ea11afa1e07c40199c74146bf72d362368a844338af0c162e365c
+        musl_sha256=5e9674b7f41152fe2119093b5cb4c13eaaadb19c2d5422b2d7267913e663ee6e
+        stub_sha256=a1823d2d7082db555d528f82c1809f276c818aeb5b40f198f4565f104e055c38
+        libstdcpp_sha256=2302e766d4e4926038ec166ecb85837ee884576115236ddb565e3a5fca4a11d7
+        libgcc_sha256=369aaa6e9d099a737bad6dd3e6c2fe7bb1547ca26d22b94ee0411228f709b403
+        bun_build=bun-linux-aarch64-musl
+        bun_sha256=71760b6c8ea30623b81a4907cb815d48e2ea266f2e73e751534a44a0607950df
+        efi_stub=linuxaa64.efi.stub
+        efi_boot_name=BOOTAA64.EFI
+        # The aarch64 ELF binutils also read and write pei-aarch64-little:
+        # native binutils on an arm64 Debian, the cross package on amd64.
+        uki_objcopy=aarch64-linux-gnu-objcopy
+        uki_objdump=aarch64-linux-gnu-objdump
+        uki_binutils_package=binutils-aarch64-linux-gnu
+        # The PL011 UART of QEMU's virt machine.
+        serial_console=ttyAMA0
+        serial_major=204
+        ;;
+esac
+
+if [ "$linux_flavor" = lts ]; then
+    linux_sha256=$linux_lts_sha256
+else
+    linux_sha256=$linux_virt_sha256
+fi
+
+bun_zip="$bun_build-$bun_version.zip"
+bun_url="https://github.com/oven-sh/bun/releases/download/bun-v$bun_version/$bun_build.zip"