buninu-linux 0.3.0 → 0.3.1

package/README.md

@@ -25,14 +25,17 @@
 
 ---
 
+- [Table of contents](#contents)
+- .
 - Still in the early stages
 - [Video here](https://www.reddit.com/r/bun/comments/1wkpraj/buninu_linux_a_distro_with_bun_as_pid_1): Booted successfully on real x86-64 UEFI hardware with `--real`:
   * Bun reaches its interactive REPL
   * start() starts the Buninu userspace shell
   * `cfg.disk` + shell `mount` mounts local disks
-  * `cfg.net` loads common wired NIC drivers
+  * `cfg.net` loads common wired NIC and Android USB-tethering drivers
+  * Android phone USB tethering over RNDIS has been tested successfully, allowing Buninu Linux to access the Internet through an Android phone
   * IP addresses and routes are configured manually because the image does not yet include a DHCP client.
-  * The bundled `jmi` editor, `jsmdcui` app runtime, and local JavaScript execution also work.
+  * The bundled `jmi` editor, jsmdcui editor/terminal multitasking, and local JavaScript execution also work.
 
 ---
 
@@ -130,20 +133,20 @@ whitespace-only line prints the welcome and current `cfg.*` getter list again.
 Load only the subsystem needed, then enter the Buninu shell:
 
 ```js
-cfg.net       // wired NIC drivers
+cfg.net       // wired NIC and Android USB-tethering drivers
 cfg.disk      // SATA/NVMe/USB storage drivers and detected block devices
 cfg.power     // battery, AC, button and thermal drivers
 start()
 ```
 
 There is no DHCP client yet; configure a detected wired interface with `ip` as
-described under [Real hardware](#real-hardware). Run `poweroff` for a synced
+described under [Basic configuration](#basic-configuration). Run `poweroff` for a synced
 shutdown. After editing the initramfs, `bun ./index.js -b --real --export` rebuilds the
 image; `-h` lists all flags.
 
-## Running
+## Using Buninu Linux
 
-### Real hardware
+### Basic configuration
 
 Real hardware is the primary target. Boot the USB drive with Secure Boot
 disabled unless you have signed the UKI yourself. The physical display and USB
@@ -157,7 +160,7 @@ cfg.disk
 cfg.power
 ```
 
-`cfg.net` loads the packaged wired-network drivers and prints detected
+`cfg.net` loads the packaged wired-network and Android USB-tethering drivers and prints detected
 interfaces and MAC addresses. There is no DHCP client yet, so configure the
 interface manually after entering the Buninu shell with `start()`:
 
@@ -178,6 +181,8 @@ mount -fv /dev/sda1 /mnt
 
 Run `poweroff` for a synced shutdown.
 
+### Editor quick start
+
 The bundled `jmi` terminal editor works without a network connection:
 
 ```sh
@@ -203,19 +208,107 @@ After leaving the editor with `Ctrl-Q`, run it locally:
 bun hlw.js
 ```
 
-- Sometimes `Enters` in some scenarios don't directly work; if that's the case, try `Ctrl-J` or `Ctrl-M`
+If `Enter` is not recognized in a particular terminal, try `Ctrl-J` or
+`Ctrl-M`.
+
+### Panes, terminals, and tabs
+
+`jmi` and jsmdcui can keep editors and terminal sessions open together. Press
+`Ctrl-E`, type `term`, and press `Enter` to open the default Buninu shell in a
+terminal pane. `term COMMAND` starts a specific command instead. Use `vsplit`,
+`hsplit`, or `tab` from the same `Ctrl-E` command prompt to create another
+editor pane or tab; each command optionally accepts a filename. From an editor
+pane, `Ctrl-T` is the direct shortcut for a new empty tab.
+
+#### Pane and tab controls
+
+| Input | Result |
+| --- | --- |
+| Click a pane | Focus that editor or terminal pane. |
+| `Ctrl-T` in an editor pane | Open a new empty tab. |
+| `Ctrl-W` once | Move to the next pane in the current tab, from either an editor or terminal pane. |
+| `Alt-T` | Move to the next tab. |
+| **`Ctrl-W` twice quickly** | **Important escape hatch:** move to the next tab like `Alt-T`, or create an editor tab when needed. See the detailed explanation below. |
+| `Esc` in a terminal pane | Close that terminal pane and return to its previous editor buffer |
+| `Ctrl-Q` or `Alt-Q` in an editor pane | Close the current editor UI. |
+
+**Why this escape hatch is important:** A terminal pane must forward almost every key combination unchanged to the
+shell or application running inside it. `Ctrl-W` is therefore the one
+multitasking escape key that jsmdcui intercepts: it lets you leave the active
+terminal without terminating the work inside it. Press it once to move to the
+next pane in the current tab. Press it twice quickly to move to the next tab.
+
+The double press is especially important in an all-terminal workspace. When
+the current tab is the rightmost tab and every existing tab contains only
+terminal panes, it creates a new editor tab instead of wrapping back to the
+first terminal tab. In every other case it performs the normal next-tab cycle.
+Use `Esc` only when you actually want to close the current terminal pane.
+
+### Using Bun Modern Shell
+
+bunmsh is the dependency-free, mksh-inspired shell bundled with Buninu. Its
+main features are:
+
+- Lines beginning with `Bun.*` run as JavaScript; returned values are printed
+  and promises are awaited automatically. Use `Bun.e;` or `Bun.e,` for
+  arbitrary JavaScript.
+- Lightweight cwd tabs keep several working directories ready. In bunmsh,
+  `Ctrl-T` creates or cycles right through tabs, while `Alt-T` cycles left.
+  * Also useful cmds: `tab n`, `tab c`(Alt-C)
+- Shell variables and JavaScript share a live variable table by `$.`, and `Bun.sha`
+  can retain JavaScript values across commands and cwd tabs.
+- Saved history, Bash/Fish history import, completions, and ghost suggestions
+  are available interactively.
+- `serve [directory]` starts a browsable HTTP file server. Together with
+  Android USB tethering, it provides a simple way to transfer files between
+  Buninu Linux and the connected phone.
+- Cross-platform builtins and PATH-fallback commands.
+- `Ctrl-U` removes and saves the text before the cursor; press it again at the
+  beginning of the line to restore it. `Ctrl-K` independently toggles the text
+  after the cursor when at the end of the line.
+- Unquoted pathname patterns use `Bun.Glob` and follow directory symbolic
+  links used as intermediate path components, as traditional shells do. This
+  matters for sysfs, where class entries are normally links. For example:
 
-## Commands inside /bin
+```sh
+ls /sys/class/net/*/device
+```
+
+For a readable process overview, run:
+
+```sh
+pspac
+```
+
+`pspac` shows the real `PID COMMAND` process table and highlights each command
+line as shell syntax with micro's Monokai colours. Leading directories are
+dimmed so the program name stands out. Use `pspa` for the same table as plain
+text.
+
+See the [bunmsh repository](https://github.com/jjtseng93/bunmsh) for its full
+syntax, interactive controls, builtins, and current compatibility details.
 
-Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes four commands
-implemented as Bun scripts:
+## Commands inside /bin
 
 | command | does | manual |
 | --- | --- | --- |
 | `mount` | `mount(2)` with type detection, `-o` parsing, `LABEL=`/`UUID=`, bind/move/remount; loads required filesystem and disk modules | `mount --help` → `/usr/share/doc/buninu-linux/mount.md` |
 | `umount` | `umount2(2)` with `-l`, `-f`, `-R` | `umount --help` |
 | `ip` | iproute2 grammar over `SIOC*` ioctls and `/proc/net`: `link`, `addr`, `route`, `neigh` | `ip --help` |
+| `ps` | composable process fields from `/proc`; also exports its snapshot and single-row formatter for other commands | `ps --help` |
+| `top` | periodically refreshes the process snapshot and rows supplied by `ps` | `top --help` |
 | `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` |
+
+Besides `bun` (and `sh`/`node` pointing at it), `/bin` includes eight 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.
 
 `--help` renders each Markdown manual in the terminal. Common examples:
 
@@ -224,6 +317,8 @@ mount /dev/sda1 /mnt --mkdir
 mount -fv /dev/sda1 /mnt
 mount -t tmpfs -o size=64M tmpfs /tmp/x
 mount -t ntfs3 -o force /dev/sda3 /mnt/windows
+umount /mnt
+umount -R /mnt
 
 ip link set eth0 up
 ip addr add 192.168.1.50/24 dev eth0
@@ -233,7 +328,23 @@ ip -br addr && ip route
 ip addr replace 192.168.1.50/24 dev eth0
 ip route replace default via 192.168.1.1
 
+ps -eo pid,args
+ps -ef
+ps aux
+pspac
+top
+top -b -n 1
+
 poweroff
+reboot
+
+tar cvf /tmp/buninu.tar README.md package.json
+tar tvf /tmp/buninu.tar
+mkdir -p /tmp/buninu-copy
+tar xvf /tmp/buninu.tar -C /tmp/buninu-copy
+
+# Add z to create a gzip-compressed archive
+tar czvf /tmp/buninu.tar.gz README.md package.json
 ```
 
 ## Environment and dependencies
@@ -340,6 +451,8 @@ bun ./index.js -fb --real --export
 `index.js` is the single entry point (`npm run fetch` and `npm run pack` call
 it too). Its physical-image stages run as fetch → build:
 
+#### Build flags
+
 | flag | runs | use it when |
 | --- | --- | --- |
 | `-f`, `--fetch` | `fetch-alpine.sh`, `fetch-bun.sh` | first clone, or after bumping a pinned version |
@@ -356,8 +469,8 @@ bun x buninu-linux -fb --real --export
 
 `--linux-lts` selects Alpine's general-purpose LTS kernel. `--real` implies
 `--linux-lts` and builds for physical hardware: it makes `tty0` the primary
-console and includes xHCI/USB HID, common wired network, storage and ACPI power
-modules needed by typical laptops and desktops.
+console and includes xHCI/USB HID, common wired NIC, Android USB-tethering,
+storage and ACPI power modules needed by typical laptops and desktops.
 
 For real hardware, `-fb --real` is the complete image pipeline and
 `-b --real` is the edit-and-rebuild loop. Before starting, `index.js` checks
@@ -396,6 +509,8 @@ The primary `bun ./index.js -fb --real` pipeline runs the steps below in order;
 each writes files the next one reads. When selected, `--export` runs afterward
 and copies the final `vda.img` to the invocation directory.
 
+##### Pipeline inputs and outputs
+
 | script | reads | writes |
 | --- | --- | --- |
 | `fetch-alpine.sh` | Alpine CDN | `kernel/vmlinuz-lts`, `kernel/linuxx64.efi.stub`, musl, and the selected network, storage, input, power and filesystem modules with trimmed module indexes |
@@ -423,6 +538,8 @@ boot.
 `build-uki.sh` appends sections to systemd's `linuxx64.efi.stub` with
 `objcopy`, at hand-picked VMAs because `objcopy` will not lay them out for you:
 
+##### UKI sections
+
 | section | offset from image base | contents | size |
 | --- | --- | --- | --- |
 | `.text` | +0x0 | the stub itself | 66 KB |
@@ -589,7 +706,7 @@ Which modules the image carries is the list in `fetch-alpine.sh`; the
 `select_module` helper there pulls in dependencies from Alpine's
 `modules.dep`, and `--real` adds common storage paths (`sd_mod`, `ahci`,
 `ata_generic`, `pata_acpi`, `nvme`, Intel `vmd`, `usb-storage` and `uas`),
-the wired NICs and the ACPI power drivers. Alpine's
+the wired NICs, Android USB-tethering drivers and the ACPI power drivers. Alpine's
 kernels build all of these as modules; a self-built kernel with them `=y`
 works the same way, the loaders just find nothing to load.
 
@@ -685,8 +802,10 @@ loads the packaged SATA/PATA/SCSI, NVMe/VMD and USB storage stacks so
 their disks and partitions appear in `/dev`, then lists `/sys/class/block`. `cfg.all`
 unconditionally attempts every packaged module and recursively loads its
 declared dependencies. `--real` ships Intel `e1000`/`e1000e`/`igb`/`igc`,
-Realtek `r8169`, Atheros `alx`, Broadcom `tg3` and the `r8152`/`ax88179_178a`/
-`cdc_ether` USB dongles. `cfg.power` loads the ACPI
+Realtek `r8169`, Atheros `alx`, Broadcom `tg3`, common USB dongles, and
+`rndis_host`/`cdc_ether`/`cdc_ncm`/`cdc_eem`/`cdc_subset`/`zaurus` for Android
+USB tethering. `cfg.net` unconditionally attempts all of these packaged
+network modules. `cfg.power` loads the ACPI
 `battery`, `ac`, `button` and `thermal` modules through `/lib/modprobe.js`
 and lists `/sys/class/power_supply` (a desktop without a battery simply
 reports nothing registered). Nothing loads them at boot. PID 1 also installs
@@ -694,12 +813,48 @@ reports nothing registered). Nothing loads them at boot. PID 1 also installs
 `Promise.reject()` at the prompt makes Bun exit, which is a kernel panic
 (`Attempted to kill init!`).
 
-The REPL exposes a global `bunmsh()` function. Calling it creates
-`/tmp/bunmsh-runtime`, installs the pinned `bunmsh@0.3.6` package there, and
-directly runs its `src/main.js` with a small explicit environment. The calls
-are synchronous so bunmsh exclusively owns the terminal until `exit` returns
-to the Bun REPL. `start()` launches Buninu with the current process environment
-preserved, while overriding `PATH` and `HOME` for the userspace session.
+`start()` launches the bundled Buninu userspace and its bunmsh (Bun Modern Shell) with
+the current process environment preserved, while overriding `PATH` and `HOME`
+for the userspace session.
+
+## Contents
+
+- [Quick start](#quick-start)
+  * [Steps](#steps)
+    + [Build directly with bun x](#build-directly-with-bun-x)
+    + [Or build from a source checkout](#or-build-from-a-source-checkout)
+    + [Write the image to a USB drive](#write-the-image-to-a-usb-drive)
+    + [Booting from the USB drive](#booting-from-the-usb-drive)
+- [Using Buninu Linux](#using-buninu-linux)
+  * [Basic configuration](#basic-configuration)
+  * [Editor quick start](#editor-quick-start)
+  * [Panes, terminals, and tabs](#panes-terminals-and-tabs)
+    + [Pane and tab controls](#pane-and-tab-controls)
+  * [Using Bun Modern Shell](#using-bun-modern-shell)
+- [Commands inside /bin](#commands-inside-bin)
+- [Environment and dependencies](#environment-and-dependencies)
+  * [Build environment](#build-environment)
+  * [Buninu Linux (Section 2)](#buninu-linux-section-2)
+  * [Hello world (Section 1)](#hello-world-section-1)
+  * [Retired native bootstrap](#retired-native-bootstrap)
+- [Implementation details](#implementation-details)
+  * [1. Hello world](#1-hello-world)
+  * [2. Buninu Linux – Bun as PID 1](#2-buninu-linux-bun-as-pid-1)
+    + [Build flags](#build-flags)
+    + [Build pipeline](#build-pipeline)
+      - [Pipeline inputs and outputs](#pipeline-inputs-and-outputs)
+    + [UKI layout](#uki-layout)
+      - [UKI sections](#uki-sections)
+    + [Disk layout](#disk-layout)
+    + [Real-hardware boot details](#real-hardware-boot-details)
+    + [QEMU development](#qemu-development)
+      - [QEMU networking](#qemu-networking)
+    + [Command implementation](#command-implementation)
+    + [Reaching JavaScript with nothing mounted](#reaching-javascript-with-nothing-mounted)
+    + [What init.js does](#what-initjs-does)
+- [Authorship](#authorship)
+- [License](#license)
+  * [Bundled component licenses](#bundled-component-licenses)
 
 ## Authorship
 
@@ -721,6 +876,8 @@ The repository also commits four third-party platform binaries under
 `initramfs/lib/`, and the built image redistributes several more. Each stays
 under its own terms, with the full texts in [`LICENSES/`](LICENSES/):
 
+### Bundled component licenses
+
 | Component | License | Where |
 |---|---|---|
 | musl (`ld-musl-x86_64.so.1`, `libc.musl-x86_64.so.1`) | MIT | committed |

package/fetch-alpine.sh

@@ -79,10 +79,15 @@ if [ "${REAL_MACHINE:-}" = 1 ]; then
         select_module "$module"
     done
     # Wired NICs: Intel (e1000/e1000e/igb/igc), Realtek (r8169 plus its PHY
-    # driver), Qualcomm Atheros (alx), Broadcom (tg3), and USB dongles
-    # (Realtek r8152, ASIX ax88179, CDC Ethernet). cfg.net in init.js
-    # matches them to hardware through the pci:/usb: lines of modules.alias.
-    for module in e1000 e1000e igb igc r8169 realtek alx tg3 r8152 ax88179_178a cdc_ether; do
+    # driver), Qualcomm Atheros (alx), Broadcom (tg3), and USB dongles.
+    # Android USB tethering commonly presents RNDIS, CDC ECM/NCM/EEM, or an
+    # older CDC subset/zaurus-compatible gadget. Selecting the leaf drivers
+    # recursively includes usbnet, mii, usbcore and usb-common from
+    # modules.dep. cfg.net unconditionally attempts every packaged
+    # kernel/drivers/net module, then matches USB and PCI modaliases.
+    for module in e1000 e1000e igb igc r8169 realtek alx tg3 \
+                  r8152 ax88179_178a cdc_ether rndis_host cdc_ncm cdc_eem \
+                  cdc_subset zaurus; do
         select_module "$module"
     done
 fi

package/initramfs/bin/ip

@@ -9,7 +9,8 @@
 // shown but not configured.
 
 import { readdirSync, readFileSync } from "node:fs";
-import { cString, ptr, withInetSocket, Errno, SysError, showDocument } from "../lib/dlopen.js";
+import { cString, ptr, withInetSocket, Errno, SysError } from "../lib/dlopen.js";
+import { showDocument } from "../lib/document.js";
 
 const fail = (message, status = 1) => {
   console.error(`ip: ${message}`);

package/initramfs/bin/mount

@@ -10,7 +10,8 @@
 // is not there yet.
 
 import { existsSync, mkdirSync, openSync, readSync, closeSync, readdirSync, readFileSync } from "node:fs";
-import { libc, cString, ptr, errno, strerror, Errno, SysError, showDocument } from "../lib/dlopen.js";
+import { libc, cString, ptr, errno, strerror, Errno, SysError } from "../lib/dlopen.js";
+import { showDocument } from "../lib/document.js";
 import { modprobe, tryModprobe, modulesDirectory, ModuleNotFound } from "../lib/modprobe.js";
 
 const fail = (message, status = 32) => {

package/initramfs/bin/poweroff

@@ -1,31 +1,10 @@
 #!/bin/bun
 // poweroff — sync filesystems and power off through Linux reboot(2).
 
-import { libc, check, showDocument } from "../lib/dlopen.js";
+import { LINUX_REBOOT_CMD_POWER_OFF, runPowerCommand } from "../lib/power.js";
 
-const LINUX_REBOOT_CMD_POWER_OFF = 0x4321fedc;
-const arguments_ = process.argv.slice(2);
-
-if (arguments_.length === 1 && (arguments_[0] === "-h" || arguments_[0] === "--help")) {
-  await showDocument("poweroff");
-  process.exit(0);
-}
-
-if (arguments_.length !== 0) {
-  console.error("Usage: poweroff [-h | --help]");
-  process.exit(1);
-}
-
-console.log("poweroff: syncing filesystems");
-libc.symbols.sync();
-console.log("poweroff: powering off");
-try {
-  check("reboot(LINUX_REBOOT_CMD_POWER_OFF)", libc.symbols.reboot(LINUX_REBOOT_CMD_POWER_OFF));
-} catch (error) {
-  console.error(`poweroff: ${error.message}`);
-  process.exit(1);
-}
-
-// A successful reboot(2) never returns.
-console.error("poweroff: reboot returned without powering off");
-process.exit(1);
+await runPowerCommand({
+  name: "poweroff",
+  command: { name: "LINUX_REBOOT_CMD_POWER_OFF", value: LINUX_REBOOT_CMD_POWER_OFF },
+  action: "powering off",
+});

package/initramfs/bin/ps

@@ -0,0 +1,256 @@
+#!/bin/bun
+// ps — a /proc process snapshot, formatter, and command-line frontend.
+
+import { readdirSync, readFileSync } from "node:fs";
+import { showDocument } from "../lib/document.js";
+
+export const CLOCK_TICKS = 100;
+
+const read = (path) => readFileSync(path, "utf8");
+const numberFrom = (text, pattern) => Number(pattern.exec(text)?.[1] ?? 0);
+
+const ttyName = (number) => {
+  if (!number) return "?";
+  const device = number >>> 0;
+  const major = (device >>> 8) & 0xfff;
+  const minor = (device & 0xff) | ((device >>> 12) & 0xfff00);
+  if (major >= 136 && major <= 143) return `pts/${minor}`;
+  if (major === 4 && minor < 64) return `tty${minor}`;
+  if (major === 5 && minor === 0) return "tty";
+  return `${major}:${minor}`;
+};
+
+const cpuTime = (seconds) => {
+  const whole = Math.max(0, Math.floor(seconds));
+  const hours = Math.floor(whole / 3600);
+  const minutes = Math.floor(whole % 3600 / 60);
+  const secs = whole % 60;
+  return hours
+    ? `${hours}:${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`
+    : `${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+};
+
+const elapsedTime = (seconds) => {
+  const whole = Math.max(0, Math.floor(seconds));
+  const days = Math.floor(whole / 86400);
+  const clock = [Math.floor(whole % 86400 / 3600), Math.floor(whole % 3600 / 60), whole % 60]
+    .map((part) => String(part).padStart(2, "0")).join(":");
+  return days ? `${days}-${clock}` : clock;
+};
+
+const startText = (started, short = false) => {
+  const date = new Date(started);
+  const now = new Date();
+  if (date.toDateString() === now.toDateString())
+    return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+  if (short || date.getFullYear() === now.getFullYear())
+    return date.toLocaleString("en-US", { month: "short", day: "2-digit" }).replace(" ", "");
+  return String(date.getFullYear());
+};
+
+const readUsers = () => {
+  const users = new Map();
+  try {
+    for (const line of read("/etc/passwd").split("\n")) {
+      const fields = line.split(":");
+      if (/^\d+$/.test(fields[2] ?? "") && !users.has(Number(fields[2])))
+        users.set(Number(fields[2]), fields[0]);
+    }
+  } catch {}
+  return users;
+};
+
+const readMemory = () => {
+  const result = {};
+  try {
+    for (const match of read("/proc/meminfo").matchAll(/^(\w+):\s+(\d+)/gm))
+      result[match[1]] = Number(match[2]);
+  } catch {}
+  return result;
+};
+
+const readCpu = () => {
+  try {
+    const values = read("/proc/stat").match(/^cpu\s+(.+)$/m)?.[1].trim().split(/\s+/).map(Number) ?? [];
+    const total = values.reduce((sum, value) => sum + value, 0);
+    return { total, idle: (values[3] ?? 0) + (values[4] ?? 0), count: Math.max(1, read("/proc/stat").match(/^cpu\d+\s/gm)?.length ?? 1) };
+  } catch { return { total: 0, idle: 0, count: 1 }; }
+};
+
+export function readProcessSnapshot() {
+  const users = readUsers();
+  const memory = readMemory();
+  let uptime = 0;
+  let bootSeconds = 0;
+  let loadAverage = [0, 0, 0];
+  try { uptime = Number(read("/proc/uptime").split(/\s+/)[0]); } catch {}
+  try { bootSeconds = numberFrom(read("/proc/stat"), /^btime\s+(\d+)/m); } catch {}
+  try { loadAverage = read("/proc/loadavg").trim().split(/\s+/).slice(0, 3).map(Number); } catch {}
+  const bootTime = bootSeconds ? bootSeconds * 1000 : Date.now() - uptime * 1000;
+  let pids = [];
+  try {
+    pids = readdirSync("/proc", { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && /^\d+$/.test(entry.name))
+      .map((entry) => Number(entry.name)).sort((a, b) => a - b);
+  } catch (error) { throw new Error(`cannot read /proc: ${error.message}`); }
+
+  const processes = [];
+  for (const pid of pids) {
+    try {
+      let args = readFileSync(`/proc/${pid}/cmdline`).toString("utf8").replace(/\0/g, " ").replace(/[\r\n]+/g, " ").trimEnd();
+      if (!args) args = `[${read(`/proc/${pid}/comm`).trim().replace(/[\r\n]+/g, " ")}]`;
+      const status = read(`/proc/${pid}/status`);
+      const stat = read(`/proc/${pid}/stat`);
+      const close = stat.lastIndexOf(")");
+      if (close < 0) continue;
+      const open = stat.indexOf("(");
+      const fields = stat.slice(close + 2).trim().split(/\s+/);
+      const command = stat.slice(open + 1, close);
+      const uid = numberFrom(status, /^Uid:\s+(\d+)/m);
+      const vmSize = numberFrom(status, /^VmSize:\s+(\d+)/m);
+      const rss = numberFrom(status, /^VmRSS:\s+(\d+)/m);
+      const ppid = Number(fields[1]);
+      const session = Number(fields[3]);
+      const ttyNumber = Number(fields[4]);
+      // /proc/PID/stat field 9 is flags. `fields` starts at field 3, so
+      // index 6 contains PF_KTHREAD and does not rely on guessing from argv.
+      const kernelThread = (Number(fields[6]) & 0x00200000) !== 0;
+      const ticks = Number(fields[11]) + Number(fields[12]);
+      const nice = Number(fields[16]);
+      const threads = Number(fields[17]);
+      const started = bootTime + Number(fields[19]) / CLOCK_TICKS * 1000;
+      const elapsed = Math.max(0.01, (Date.now() - started) / 1000);
+      let state = fields[0];
+      if (nice < 0) state += "<"; else if (nice > 0) state += "N";
+      if (session === pid) state += "s";
+      if (threads > 1) state += "l";
+      if (Number(fields[5]) > 0 && Number(fields[5]) === Number(fields[2])) state += "+";
+      processes.push({
+        pid, ppid, uid, user: users.get(uid) ?? String(uid), args, command,
+        tty: ttyName(ttyNumber), ttyNumber, session, state, kernelThread,
+        processor: Number(fields[36] ?? 0), priority: Number(fields[15]), nice, threads, ticks,
+        cpu: ticks / CLOCK_TICKS / elapsed * 100,
+        memory: memory.MemTotal ? rss / memory.MemTotal * 100 : 0,
+        vmSize, rss, size: Math.ceil(Number(fields[20]) / 4096),
+        time: cpuTime(ticks / CLOCK_TICKS), elapsed, started,
+      });
+    } catch {}
+  }
+  return { processes, memory, cpu: readCpu(), uptime, loadAverage, at: Date.now() };
+}
+
+export const processFieldDefinitions = {
+  pid: { header: "PID", numeric: true, minimum: 5, value: (r) => r.pid },
+  ppid: { header: "PPID", numeric: true, minimum: 5, value: (r) => r.ppid },
+  uid: { header: "UID", numeric: true, minimum: 5, value: (r) => r.uid },
+  user: { header: "USER", value: (r) => r.user }, euser: { header: "EUSER", value: (r) => r.user },
+  comm: { header: "COMMAND", value: (r) => r.command }, args: { header: "COMMAND", value: (r) => r.args },
+  cmd: { header: "CMD", value: (r) => r.args }, command: { header: "COMMAND", value: (r) => r.args },
+  tty: { header: "TT", value: (r) => r.tty }, tt: { header: "TT", value: (r) => r.tty },
+  stat: { header: "STAT", value: (r) => r.state }, state: { header: "S", value: (r) => r.state[0] },
+  c: { header: "C", numeric: true, value: (r) => Math.floor(r.cpu) },
+  "%cpu": { header: "%CPU", numeric: true, value: (r) => r.cpu.toFixed(1) }, pcpu: { header: "%CPU", numeric: true, value: (r) => r.cpu.toFixed(1) },
+  "%mem": { header: "%MEM", numeric: true, value: (r) => r.memory.toFixed(1) }, pmem: { header: "%MEM", numeric: true, value: (r) => r.memory.toFixed(1) },
+  vsz: { header: "VSZ", numeric: true, value: (r) => r.vmSize }, rss: { header: "RSS", numeric: true, value: (r) => r.rss },
+  sz: { header: "SZ", numeric: true, value: (r) => r.size }, time: { header: "TIME", numeric: true, value: (r) => r.time },
+  etime: { header: "ELAPSED", numeric: true, value: (r) => elapsedTime(r.elapsed) }, etimes: { header: "ELAPSED", numeric: true, value: (r) => Math.floor(r.elapsed) },
+  start: { header: "STARTED", value: (r) => startText(r.started) }, stime: { header: "STIME", value: (r) => startText(r.started, true) },
+  lstart: { header: "STARTED", value: (r) => new Date(r.started).toString().slice(0, 24) },
+  ni: { header: "NI", numeric: true, value: (r) => r.nice }, nice: { header: "NI", numeric: true, value: (r) => r.nice },
+  pri: { header: "PRI", numeric: true, value: (r) => r.priority }, psr: { header: "PSR", numeric: true, value: (r) => r.processor },
+};
+
+export function prepareProcessFormat(rows, fields) {
+  const names = Array.isArray(fields) ? fields : fields.toLowerCase().split(/[\s,]+/).filter(Boolean);
+  if (!names.length) throw new Error("empty -o format");
+  return names.map((name) => {
+    const definition = processFieldDefinitions[name];
+    if (!definition) throw new Error(`unsupported output field '${name}'`);
+    const width = Math.max(definition.minimum ?? 0, definition.header.length,
+      ...rows.map((row) => String(definition.value(row)).length));
+    return { name, ...definition, width };
+  });
+}
+
+export const formatProcessHeader = (format) => format.map((f) =>
+  f.numeric ? f.header.padStart(f.width) : f.header.padEnd(f.width)).join(" ").trimEnd();
+
+export const formatProcessLine = (row, format) => format.map((f, index) => {
+  const value = String(f.value(row));
+  if (index === format.length - 1 && !f.numeric) return value;
+  return f.numeric ? value.padStart(f.width) : value.padEnd(f.width);
+}).join(" ").trimEnd();
+
+export function formatProcessTable(rows, fields) {
+  const format = prepareProcessFormat(rows, fields);
+  return [formatProcessHeader(format), ...rows.map((row) => formatProcessLine(row, format))];
+}
+
+const formatPresetTable = (rows, fields, headers = {}) => {
+  const format = prepareProcessFormat(rows, fields).map((field) => {
+    const header = headers[field.name] ?? field.header;
+    return { ...field, header, width: Math.max(field.width, header.length) };
+  });
+  return [formatProcessHeader(format), ...rows.map((row) => formatProcessLine(row, format))];
+};
+
+export function selectProcesses(rows, { all = false, selection = "default" } = {}) {
+  if (all) return rows;
+  const own = rows.find((row) => row.pid === process.pid);
+  const ownUid = own?.uid ?? process.geteuid?.() ?? process.getuid?.() ?? 0;
+  const ownTty = own?.ttyNumber ?? 0;
+  return rows.filter((row) => {
+    // A boot-console shell and kernel threads can all be UID 0 and have no
+    // controlling TTY. Plain ps must not accidentally behave like ps -e.
+    if (row.kernelThread) return false;
+    if (selection === "unix-a") return row.ttyNumber !== 0 && row.session !== row.pid;
+    if (selection === "any-with-tty") return row.ttyNumber !== 0;
+    if (selection === "own-any-tty") return row.uid === ownUid;
+    return row.uid === ownUid && row.ttyNumber === ownTty && row.session !== row.pid;
+  });
+}
+
+const usage = () => { throw new Error("Usage: ps | ps -e|-A [-o fields] | ps -ef | ps aux | ps ax\nTry 'ps --help' for the full manual."); };
+
+async function main(argv) {
+  let fields = null, view = "default", all = false, selection = "default";
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "-h" || argument === "--help") return showDocument("ps");
+    if (["-e", "-A", "--all"].includes(argument)) { all = true; continue; }
+    if (["-f", "-ef", "-Af"].includes(argument)) { view = "full"; if (argument !== "-f") all = true; continue; }
+    if (["-F", "-eF", "-AF"].includes(argument)) { view = "extra-full"; if (argument !== "-F") all = true; continue; }
+    if (["aux", "-aux"].includes(argument)) { view = "aux"; all = true; continue; }
+    if (["ax", "-ax"].includes(argument)) { view = "bsd"; all = true; continue; }
+    if (argument === "a") { view = "bsd"; selection = "any-with-tty"; continue; }
+    if (argument === "x") { view = "bsd"; selection = "own-any-tty"; continue; }
+    if (argument === "-a") { selection = "unix-a"; continue; }
+    if (argument === "-x") { selection = "own-any-tty"; continue; }
+    if (argument === "-o" || argument === "--format") { fields = argv[++index] ?? usage(); view = "basic"; continue; }
+    if (argument.startsWith("--format=")) { fields = argument.slice(9); view = "basic"; continue; }
+    const combined = /^-([eA]*)o(.*)$/.exec(argument);
+    if (combined) { fields = combined[2] || argv[++index] || usage(); view = "basic"; if (combined[1]) all = true; continue; }
+    usage();
+  }
+  const rows = selectProcesses(readProcessSnapshot().processes, { all, selection });
+  const presets = {
+    full: ["user", "pid", "ppid", "c", "stime", "tty", "time", "args"],
+    "extra-full": ["user", "pid", "ppid", "c", "sz", "rss", "psr", "stime", "tty", "time", "args"],
+    aux: ["user", "pid", "%cpu", "%mem", "vsz", "rss", "tty", "stat", "start", "time", "args"],
+    bsd: ["pid", "tty", "stat", "time", "args"], default: ["pid", "tty", "time", "comm"],
+  };
+  try {
+    const headers = view === "default" ? { tty: "TTY", comm: "CMD" }
+      : view === "full" || view === "extra-full" ? { user: "UID", tty: "TTY", args: "CMD" }
+      : view === "aux" ? { tty: "TTY", start: "START" }
+      : view === "bsd" ? { tty: "TTY" } : {};
+    for (const line of fields
+      ? formatProcessTable(rows, fields)
+      : formatPresetTable(rows, presets[view], headers)) console.log(line);
+  } catch (error) { throw new Error(`ps: ${error.message}`); }
+}
+
+if (import.meta.main) {
+  try { await main(process.argv.slice(2)); }
+  catch (error) { console.error(error.message); process.exit(1); }
+}