buninu-linux 0.2.1 → 0.3.1

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

@@ -0,0 +1,155 @@
+# mount — mount a filesystem
+
+`/bin/mount` is a Bun script. It calls `mount(2)` through `/lib/dlopen.js`
+and loads the kernel modules a filesystem or a disk needs through
+`/lib/modprobe.js`, because on Buninu Linux there is no `/sbin/modprobe` for
+the kernel to ask.
+
+## Synopsis
+
+```sh
+mount                                   # list mounted filesystems
+mount [-fv] [-t TYPE] [-o OPTIONS] SOURCE TARGET
+mount -L LABEL | -U UUID [-o OPTIONS] TARGET
+mount --bind | --rbind | --move OLD NEW
+mount -o remount[,ro|rw] TARGET
+mount -h | --help                       # this page
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-t TYPE` | Filesystem type. Omitted or `auto`: read the superblock of SOURCE and pick one. |
+| `-o OPTIONS` | Comma-separated list, see below. May be repeated. |
+| `-r`, `--read-only` | Same as `-o ro`. |
+| `-w`, `--rw` | Same as `-o rw`. |
+| `-L LABEL`, `-U UUID` | Find the block device by label or UUID (ext2/3/4, FAT, exFAT, NTFS serial). |
+| `-B`, `--bind` | Bind-mount a directory or file somewhere else. |
+| `-R`, `--rbind` | Bind, including everything mounted below OLD. |
+| `-M`, `--move` | Move a mount to a new place. |
+| `--make-shared`, `--make-private`, `--make-rshared`, `--make-rprivate` | Change mount propagation of TARGET. |
+| `--mkdir` | Create TARGET first. |
+| `-v` | Say what is being loaded and mounted. |
+| `-f`, `--fake` | Show the `mount(2)` call and stop. |
+
+`-f` and `-v` may be combined as `-fv` or `-vf`; this probes and reports the
+filesystem without performing the mount.
+
+### `-o` words
+
+Flags: `ro` `rw` `nosuid` `suid` `nodev` `dev` `noexec` `exec` `sync` `async`
+`dirsync` `noatime` `atime` `nodiratime` `relatime` `strictatime` `lazytime`
+`nosymfollow` `remount` `bind` `rbind` `move` `shared` `private` `slave`
+`unbindable` `defaults`.
+
+Anything else (`size=64M`, `iocharset=utf8`, `uid=1000`, `force`, ...) goes
+to the filesystem driver unchanged.
+
+## Examples
+
+### tmpfs
+
+```sh
+mount -t tmpfs tmpfs /mnt/scratch
+mount -t tmpfs -o size=64M,mode=1777 tmpfs /tmp/big
+mount -t tmpfs -o remount,size=256M tmpfs /tmp/big   # grow it later
+```
+
+### ext4 (a Linux disk or partition)
+
+```sh
+mount /dev/vda2 /mnt                  # type detected, ext4 + jbd2 loaded
+mount -t ext4 -o ro,noatime /dev/vda2 /mnt
+mount -L rootfs /mnt                  # by label
+mount -U 3f2a...-...  /mnt            # by UUID
+mount -o remount,rw /mnt              # flip an ro mount to rw
+```
+
+`ext3` volumes mount with the ext4 driver; `ext2` uses its own module.
+
+### A Windows disk (NTFS)
+
+```sh
+mount /dev/sda3 /mnt/windows                     # ntfs3, read-write
+mount -t ntfs3 -o ro /dev/sda3 /mnt/windows      # look, don't touch
+mount -t ntfs3 -o force /dev/sda3 /mnt/windows   # volume left dirty by Windows
+mount -t ntfs3 -o windows_names,uid=1000,gid=1000 /dev/sda3 /mnt/windows
+```
+
+Windows Fast Startup and hibernation leave the volume marked dirty; ntfs3
+then refuses to mount read-write. Either boot Windows and shut it down
+fully, mount `-o ro`, or pass `force`. `windows_names` rejects names Windows
+could not open. The type name `ntfs` is accepted as an alias for `ntfs3`.
+
+### The EFI system partition, USB sticks, SD cards (FAT / exFAT)
+
+```sh
+mount /dev/vda1 /mnt/efi                                 # vfat, detected
+mount -t vfat -o iocharset=utf8,umask=022 /dev/sdb1 /mnt/usb
+mount -t exfat -o uid=1000,gid=1000 /dev/sdb1 /mnt/card
+```
+
+FAT and exFAT need NLS tables (`nls_utf8`, `nls_cp437`, `nls_iso8859-1`);
+`mount` loads them before calling the kernel, and also whatever
+`iocharset=`/`codepage=` names, if the module is shipped.
+
+### Bind mounts and moves
+
+```sh
+mount --bind /tmp/home /buninu/home
+mount --bind -o ro /usr/share/doc /mnt/doc   # bind, then remount read-only
+mount --rbind / /mnt/root                    # with all submounts
+mount --move /mnt/usb /media/usb
+```
+
+### Pseudo filesystems
+
+```sh
+mkdir -p /dev/pts && mount -t devpts -o gid=5,mode=620,ptmxmode=666 devpts /dev/pts
+mount -t proc proc /proc
+mount -t sysfs sysfs /sys
+mount -t devtmpfs devtmpfs /dev
+mount -t cgroup2 none /sys/fs/cgroup
+mount -t debugfs none /sys/kernel/debug
+```
+
+`/dev/pts` matters: since Linux 4.7 opening `/dev/ptmx` goes through
+`/dev/pts/ptmx`, so without this mount every pty open fails with `ENODEV`.
+`init.js` mounts it at boot.
+
+### Listing
+
+```sh
+mount                     # SOURCE on TARGET type TYPE (OPTIONS), from /proc/self/mounts
+cat /proc/self/mountinfo  # the long form
+```
+
+## How devices and drivers are found
+
+- A missing `/dev/vd*`, `/dev/sd*` or `/dev/nvme*` node makes `mount` load
+  `virtio_blk`, `sd_mod` (+ `ahci`, `usb_storage`) or `nvme` and wait up to
+  3 s for devtmpfs to create it.
+- The filesystem driver is loaded when `/proc/filesystems` does not list the
+  type; `modules.alias` turns `fs-ntfs` into `ntfs3`, `fs-ext3` into `ext4`.
+- Which modules are in the image is decided by `fetch-alpine.sh` in the
+  build tree; `--real` adds `sd_mod`, `ahci`, `nvme` and `usb-storage`.
+
+## Exit status
+
+`0` mounted, `1` bad usage, `32` the mount itself failed. Messages follow
+util-linux wording, and `dmesg` usually has the kernel's reason for `EINVAL`.
+
+## See also
+
+- `umount --help`, `ip --help`
+- [mount(2)](https://man7.org/linux/man-pages/man2/mount.2.html),
+  [mount(8)](https://man7.org/linux/man-pages/man8/mount.8.html)
+- [tmpfs](https://docs.kernel.org/filesystems/tmpfs.html),
+  [ext4](https://docs.kernel.org/admin-guide/ext4.html),
+  [ntfs3](https://docs.kernel.org/filesystems/ntfs3.html),
+  [vfat](https://docs.kernel.org/filesystems/vfat.html),
+  [devpts](https://docs.kernel.org/filesystems/devpts.html)
+- Source: `initramfs/bin/mount`, `initramfs/lib/dlopen.js`,
+  `initramfs/lib/modprobe.js` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

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

@@ -0,0 +1,15 @@
+# poweroff — power off Buninu Linux
+
+`poweroff` flushes pending filesystem writes with `sync(2)`, then requests
+`LINUX_REBOOT_CMD_POWER_OFF` through Linux `reboot(2)`. It does not invoke a
+service manager or another command.
+
+## Usage
+
+```sh
+poweroff
+poweroff --help
+```
+
+The caller needs the kernel's `CAP_SYS_BOOT` capability. Buninu's root shell
+has it; otherwise the command reports `Operation not permitted` and exits.

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

@@ -0,0 +1,94 @@
+# ps — list processes
+
+`/bin/ps` is a small Bun script that reads `/proc`. Its primary interface is
+the full-command-line table consumed by bunmsh's `pspa` and coloured `pspac`
+builtins.
+
+The file is also an importable module. It exports `readProcessSnapshot()`,
+`prepareProcessFormat()`, `formatProcessHeader()`, and
+`formatProcessLine()`. `/bin/top` uses these exports, so process discovery and
+single-row formatting have one implementation.
+
+## Synopsis
+
+```sh
+ps
+ps -e | -A [-o pid,args]
+ps -eo pid,args
+ps -ef | ps aux | ps ax
+ps -h | --help                       # this page
+```
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-e`, `-A`, `--all` | List every process instead of the default same-UID/same-TTY selection. |
+| `-o FIELDS` | Select and order comma- or space-separated output fields. See below. |
+| `-ef` | Full Unix view: UID, PID/PPID, CPU, start, TTY, accumulated time, and command. |
+| `-eF` | Extra-full Unix view, adding `SZ`, `RSS`, and current processor (`PSR`). |
+| `aux`, `-aux` | BSD view with user, CPU/memory percentages, VSZ/RSS, TTY, state, start, time, and command. |
+| `ax`, `-ax` | Compact BSD view with PID, TTY, state, time, and command. |
+| `-h`, `--help` | Render this page. |
+
+`-e` and `-o` may be combined as `-eo pid,args`, which is the form bunmsh
+uses. Rows are sorted numerically by PID. A process with an empty cmdline is
+shown using its `/proc/PID/comm` name in brackets, as for a kernel thread.
+With no `-o` or extended view, the standard columns are `PID TTY TIME CMD`,
+and `CMD` is the short process name. The default selection is the caller's
+effective UID and terminal, excluding session leaders. `-e`/`-A` selects all;
+`a`, `x`, `-a`, and `-x` apply their usual BSD or Unix selection rules.
+
+Plain `ps` excludes processes carrying Linux's `PF_KTHREAD` flag. This matters
+on boot consoles where the shell and kernel threads may all be UID 0 without a
+controlling TTY. Explicit all-process forms such as `ps -e`, `ps -A`, and
+`ps -eo ...` include kernel threads.
+
+### `-o` fields
+
+Supported names are:
+
+```text
+pid ppid uid user euser comm args cmd command tty tt stat state c
+%cpu pcpu %mem pmem vsz rss sz time etime etimes
+start stime lstart ni nice pri psr
+```
+
+They may be combined and reordered, for example:
+
+```sh
+ps -eo pid,ppid,user,comm
+ps -eo pid,stat,%cpu,%mem,rss,args
+ps -o pid,tty,time,comm
+```
+
+`comm` is the kernel's short process name; `args` is the complete command
+line. The exact `pid,args` layout remains the interface consumed by bunmsh.
+
+## Examples
+
+```sh
+ps
+ps -eo pid,args
+ps -ef                         # common LLM/tutorial spelling
+ps aux
+pspac                         # bunmsh: the same table with syntax colours
+```
+
+## Limits
+
+Values come from `/proc/PID/stat`, `/proc/PID/status`, `/proc/uptime`, and
+`/proc/meminfo`; user names come from `/etc/passwd`. CPU percentages are the
+process's average since it started, and memory percentage is resident memory
+over `MemTotal`. Forest display, custom column headings, and less common
+procps fields remain outside this minimal command. `/proc` must be mounted.
+
+## Exit status
+
+`0` success, `1` bad usage or `/proc` could not be read.
+
+## See also
+
+- `ip --help`
+- Source: `initramfs/bin/ps` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

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

@@ -0,0 +1,15 @@
+# reboot — restart Buninu Linux
+
+`reboot` flushes pending filesystem writes with `sync(2)`, then requests
+`LINUX_REBOOT_CMD_RESTART` through Linux `reboot(2)`. It shares its
+implementation with `poweroff` and does not invoke a service manager.
+
+## Usage
+
+```sh
+reboot
+reboot --help
+```
+
+The caller needs the kernel's `CAP_SYS_BOOT` capability. Buninu's root shell
+has it; otherwise the command reports `Operation not permitted` and exits.

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

@@ -0,0 +1,73 @@
+# tar — create and extract archives
+
+`/bin/tar` is a small Bun script over `Bun.Archive`. It handles uncompressed
+tar archives plus gzip and zstd without invoking another program.
+
+## Synopsis
+
+```sh
+tar -cf ARCHIVE FILE...
+tar -czf ARCHIVE FILE...
+tar --zstd -cf ARCHIVE FILE...
+tar -xf ARCHIVE [-C DIR] [MEMBER...]
+tar -tf ARCHIVE [MEMBER...]
+tar -h | --help                         # this page
+```
+
+Use `-` as ARCHIVE to read from standard input or write to standard output.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-c` | Create an archive. |
+| `-x` | Extract an archive. |
+| `-t` | List archive members. |
+| `-f ARCHIVE`, `--file=ARCHIVE` | Archive file, or `-` for standard input/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. |
+
+Short options can be combined, for example `-xzvf` or `-czf`.
+For the traditional first option word, the leading hyphen is optional, so
+`tar tf`, `tar xf`, and `tar cf` are equivalent to `tar -tf`, `tar -xf`, and
+`tar -cf`.
+
+## Examples
+
+```sh
+tar -czf source.tar.gz src README.md
+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
+```
+
+## Current Bun.Archive limits
+
+Creation stores regular files only. Symbolic links are rejected rather than
+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`.
+
+Appending with `-r`/`rvf` is not supported. `Bun.Archive` has no append API;
+rebuilding an existing archive through `Archive.files()` would silently lose
+its directories, links, ownership, and modes, so this command refuses instead.
+
+## Exit status
+
+`0` success, `2` bad usage or an archive/file operation failed.
+
+## See also
+
+- [Bun.Archive](https://bun.com/docs/runtime/archive)
+- [tar(1)](https://man7.org/linux/man-pages/man1/tar.1.html)
+- Source: `initramfs/bin/tar` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

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

@@ -0,0 +1,23 @@
+# top
+
+`top` periodically reads the process snapshot exported by `/bin/ps`. Process
+discovery and row formatting are shared with `ps`; `top` only calculates CPU
+changes between refreshes, sorts rows, and redraws the screen.
+
+## Usage
+
+```sh
+top
+top -d 1
+top -b -n 1
+```
+
+- `-d SECONDS` sets the refresh interval (default: 3).
+- `-n COUNT` exits after that many snapshots.
+- `-b` uses batch output without terminal control sequences.
+- `-h`, `--help` displays this document.
+
+While running interactively, press `q` to quit, `P` to sort by CPU, `M` to
+sort by memory, or `N` to sort by PID. The first screen shows the lifetime CPU
+average available from `ps`; later screens show usage during the refresh
+interval.

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

@@ -0,0 +1,48 @@
+# umount — unmount a filesystem
+
+`/bin/umount` is a Bun script that calls `umount2(2)` through
+`/lib/dlopen.js`.
+
+## Synopsis
+
+```sh
+umount [-f] [-l] [-R] [-v] TARGET...
+umount -h | --help
+```
+
+TARGET is a mount point. Naming the device (`umount /dev/vda1`) is not
+supported; use `mount` with no arguments to see where it is mounted.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `-l`, `--lazy` | Detach now, clean up when the last user goes away (`MNT_DETACH`). |
+| `-f`, `--force` | Force, for unreachable network filesystems (`MNT_FORCE`). |
+| `-R`, `--recursive` | Also unmount everything mounted below TARGET, deepest first. |
+| `-v` | Report each successful unmount. |
+
+## Examples
+
+```sh
+umount /mnt
+umount -l /mnt/windows        # something still has a file open
+umount -R /mnt/root           # a tree made with mount --rbind
+umount /tmp/big /mnt/usb      # several at once
+```
+
+"target is busy" means a process has its working directory or an open file
+inside the mount. On the Bun REPL, `process.chdir("/")` is usually the fix;
+`-l` is the escape hatch.
+
+## Exit status
+
+`0` all targets unmounted, `1` bad usage, `32` at least one failed.
+
+## See also
+
+- `mount --help`
+- [umount(2)](https://man7.org/linux/man-pages/man2/umount.2.html),
+  [umount(8)](https://man7.org/linux/man-pages/man8/umount.8.html)
+- Source: `initramfs/bin/umount` in
+  [buninu-linux](https://github.com/jjtseng93/buninu-linux)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buninu-linux",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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": "node --check ./index.js && node --check ./initramfs/init.js"
+    "check": "for f in ./index.js ./initramfs/init.js ./initramfs/lib/document.js ./initramfs/lib/dlopen.js ./initramfs/lib/modprobe.js ./initramfs/lib/power.js ./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"
   }
 }