boo-flash 0.1.1 → 0.1.2

package/README.md

@@ -1,302 +1,30 @@
-# Boo Flash
-
-A small macOS and Linux USB flasher for public qualified Boo releases and the repository
-owner's private GitHub candidate images.
-OpenTUI + Solid, using the welcome application's palette directly (the same
-13 colors as the native installer). It is **not included in Boo images** and is
-the repository's supported flasher.
+<p align="center">
+  <a href="https://os.boo">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://os.boo/boo-logo-dark.svg">
+      <img src="https://os.boo/boo-logo-light.svg" width="184" height="96" alt="Boo">
+    </picture>
+  </a>
+</p>
 
-## Run
+# Boo Flash
 
-The MIT-licensed npm package is `boo-flash`. Its tool version is
-independent of Boo image release versions such as `0.1.0+151`. Run it without a
-global install using either supported runtime:
+Flash [Boo](https://os.boo) to a USB drive from macOS or Linux.
 
 ```sh
-npx boo-flash   # Node.js 26.4 or later
-bunx boo-flash  # Bun 1.4 or later
+npx boo-flash
 ```
 
-The package contains JavaScript, not a bundled Node or Bun executable. Its small
-launcher selects a compatible Node installation first and supplies Node's required
-`--experimental-ffi`; otherwise it uses Bun. The npm artifact carries one
-runtime-neutral Solid bundle plus the matching package-installed OpenTUI native
-library. On Linux the launcher detects musl before OpenTUI loads
-and selects its musl artifact; an explicit valid `OPENTUI_LIBC` remains authoritative.
-
-Production flashing needs `curl` and `zstd`; Candidates add
-`gh` (GitHub CLI) and `unzip`. macOS can offer to install missing content tools
-through Homebrew. Existing commands on PATH or in `/opt/homebrew/bin` and
-`/usr/local/bin` are used directly, without changing shell configuration. If
-Homebrew is missing, follow [brew.sh](https://brew.sh), then press R to refresh.
-Linux never chooses a distribution or changes system packages: install reported
-missing commands with the distribution's package manager, then refresh. On Linux,
-every command is resolved to a root-owned executable beneath root-owned,
-non-writable directories; user-writable PATH shims are rejected.
-Only the Candidates screen requires your ordinary `gh auth login` with access
-to `anomalyco/boo`; Boo Flash does not manage authentication. Historical
-candidate artifacts carrying the repository's former name remain valid.
-macOS additionally uses `diskutil`, `plutil`, `ioreg`, `stat`, `sudo`, `dd`, and
-`sync`. Linux additionally uses `lsblk`, `findmnt`, `udevadm`, `sudo`, `umount`,
-`dd`, `sync`, and `udisksctl` from UDisks2. Run from a trusted checkout as your
-ordinary user, not root.
-
-For development from a checkout, use pinned Bun **1.4.0**:
+or
 
 ```sh
-cd tools/boo-flash
-bun install --frozen-lockfile
-bun start
+bunx boo-flash
 ```
 
-Dependency installation requires one **Install** confirmation, runs without
-sudo, and hands the terminal to Homebrew for output and any prerequisite
-guidance. Ctrl-C cancels and quits, including when Homebrew handles the interrupt
-through its own terminal and reports exit 130 or SIGINT. Boo Flash waits for its
-owned brew process to close before exiting; Homebrew manages its own children
-and cleanup, not a guarantee that every descendant has exited. SIGINT/SIGTERM
-sent only to Boo Flash request quit but do not actively cancel brew: Boo Flash
-still waits for it to finish, with no forced deadline. During that handoff,
-Q/Escape are not TUI controls.
-It does not bootstrap Homebrew, upgrade existing tools, or change shell files.
-Homebrew may install/update dependencies needed by the requested formulae.
-On failure, quit to read Homebrew's terminal output, resolve its reported issue
-(such as Xcode Command Line Tools), then retry. Partial installs are not undone.
-
-Select the **target GPU**, not the Mac's CPU. All three profiles are x86_64 UEFI
-images, not ARM images. Arrow keys choose, Enter continues, Escape goes back
-or cancels work, R refreshes, Q stops and quits. No USB is initially selected.
-The erase screen defaults to **Go back**. There is no typed phrase or countdown.
-
-The three GPU choices use the release identified by
-`https://images.os.boo/channels/main.json` and show its Boo version. **Candidates** is
-an additional choice: it checks the latest ten successful completed
-`candidate.yml` runs and lists up to ten unexpired image artifacts, each with
-its actual GPU profile, built-source SHA, run number/date and run title.
-Choose one to continue directly to USB selection; candidates need not provide
-all three profiles. They are **build-only, not boot/install/hardware qualified**.
-If none are available, **Go back** returns to the main choices; R refreshes the
-candidate list. Authentication/network errors are reported, not shown as empty.
-
-After confirmation, only the selected production `.raw.zst` is downloaded from
-its immutable release path (or reused from the verified cache). Candidates keep
-their authenticated GitHub artifact ZIP flow. Candidate flashing needs space for
-both the ZIP and compressed image; the raw image is always streamed, not staged.
-After verification, the UI releases the terminal for an ordinary `sudo -v`
-prompt. No password or GitHub token is read by the application. macOS runs only
-`dd` as root. Linux runs checked non-forced unmounts, `dd`, and UDisks safe
-power-off through `sudo -n`. No privileged app process, custom daemon, shell, or
-shell command string is used.
-
-Read-only live production metadata discovery (with no image download or software
-installation):
-
-```sh
-bun start --list-images
-```
-
-## Download Cache
-
-Verified production images and GitHub candidate ZIPs are kept across flashes
-and app restarts in
-`os.tmpdir()/boo-flash-cache-<UID>/`, privately owned by your normal user.
-The temporary parent is resolved normally, including platform symlinks. Each entry
-is `<build-or-artifact-ID>-<SHA256>.{raw.zst|zip}`, not a profile or `latest`
-alias. There is
-no automatic expiry or eviction, but the OS may purge temporary storage: this
-is not permanent storage or an offline image library. Discovery still needs
-the public Boo channel for production or GitHub authentication and a usable,
-unexpired artifact for candidates. Candidate source checks remain unchanged. No
-tokens, signed URLs, or release catalogs are cached.
-
-Only a download with matching expected size and SHA-256 is published, with an
-atomic exclusive hardlink. Existing completed bytes are never overwritten.
-A hit is privately hardlinked into operation staging and its owner, regular-file
-type, size and SHA-256 are checked again before the usual image validation.
-The UI says **Using cached image**, not downloading. Unsafe paths or corrupt payloads
-fail before disk writes, without silently deleting or redownloading them. Clear
-a corrupt payload and retry; unsafe ownership/permissions/symlinks require manual
-correction. If the temporary filesystem cannot hardlink safely, the operation
-reports an error before writing rather than pretending it retained the download.
-If publication fails, the verified payload stays in its private operation folder
-as `image.raw.zst` or `image.zip`; the error reports that path for manual
-recovery. It is not a cache hit location and is not automatically reused or
-removed by Clear. No authorization or disk write begins on publication failure.
-
-**Clear cached images** in the main menu defaults to **Go back**. It removes
-downloaded payloads only, never USB contents or active operation staging. Clear
-does not interrupt a pinned active flash; a pending download can publish afterward.
-For clearing without GitHub, authentication, dependency setup or UI discovery:
-
-```sh
-bun start --clear-cache
-```
-
-This explicit CLI action needs no confirmation. It reports the cache path and
-number removed. Demo mode never clears the real cache. Operation scratch and
-partial/unverified downloads are still cleaned when the operation finishes;
-verified cached payloads
-are retained even when subsequent validation/flashing fails or is cancelled.
-
-## Image Contract
-
-- Fetch `https://images.os.boo/channels/main.json` without caching, require its
-  exact version/revision/prefix contract, then fetch and cross-check the immutable
-  `releases/VERSION/release.json`. Require exactly Intel, AMD and NVIDIA metadata
-  with release filenames, compressed/raw sizes and SHA-256 digests.
-- Candidates instead require exact `boo-{intel|amd|nvidia}-candidate-{full_sha}`
-  image artifacts, never producer artifacts. The artifact SHA is the built
-  source, not the workflow's orchestration `head_sha`. The selected artifact
-  ID, name, run, expiry, size and ZIP digest are rechecked before download/reuse;
-  `build-info.json` must agree on revision, profile and candidate source identity.
-  Listing downloads no image payloads and does not browse older pages.
-- Stream only the selected production image from `images.os.boo`, measuring its
-  exact bytes and validating its release-manifest SHA-256. Candidates stream only
-  the chosen ZIP through authenticated `gh api` and validate the API size/digest.
-- For candidates, extract only exact, unique root basenames: the chosen `.raw.zst`,
-  `build-info.json`, `SHA256SUMS` and `SHA256SUMS.raw`. Stream file content into
-  newly created private files; never unpack arbitrary archive paths or symlinks.
-- Require schema 1, semantic version, build number, combined version, revision,
-  profile, exact `boo-VERSION-x86_64-PROFILE.raw.zst` release basename,
-  compressed byte count/hash and positive raw size/hash. Candidate `build-info`
-  additionally requires repository, clean source and checksum agreement;
-  candidates retain their existing basename and carry no release build number,
-  while candidates predating this metadata remain valid.
-- Check capacity against `raw_apparent_bytes`. Decompress with `zstd`, bound,
-  count and hash the raw stream, and await both decompressor and writer status.
-  Raw-stream verification finishes **after writing**, not before erasure, and
-  is **not device read-back verification**. A failure cannot restore old data.
-
-The progress bar is per-stage real byte progress, not an overall ETA or a timed
-fill. Write progress means backpressured bytes delivered to `dd`, not durable
-device bytes. A separate spinner covers activity; closing the writer, `sync`,
-and the platform safe-removal operation must all succeed before the real success
-screen says the USB is removable.
-
-## Disk Safety
-
-### macOS
-
-Selection requires structured `diskutil -plist` data converted with `plutil`,
-a physical whole disk, explicit external (`Internal=false`) USB transport,
-writable media with 512-byte logical sectors, and a unique current IOMedia
-`IORegistryEntryID` from `ioreg`. Current Boo images use a 512-byte-sector GPT:
-512e disks remain eligible, but 4096-byte logical-sector (4Kn) disks do not.
-Root, APFS System/Data, original user's home, working directory, app source,
-Bun executable, resolved runtime packages/native assets, `gh`/`zstd` binaries
-and image staging storage are protected.
-Real paths and macOS `stat -f %Sd` map files/firmlinks to their devices; APFS
-containers are followed to **all** physical stores, then whole physical disks.
-Unresolved protected mappings fail closed, including unsupported virtual/RAID
-storage. It never assumes that `disk0` is the system disk. External USB root
-storage is excluded too. System/Data installations and multi-store APFS
-containers are conservatively excluded even when not the running system.
-
-Attachment ID, size, device-tree path and media name are compared after the
-password prompt and again after checked, non-forced `unmountDisk` (which covers
-APFS virtual volumes too). Mounted target partitions/APFS volumes are rejected
-before writing. Paths are derived only from validated `diskN` identifiers;
-the UI cannot supply arbitrary device paths. Attachment is rechecked before
-eject. These are repeated checks, **not an atomic Disk Arbitration claim**:
-do not unplug, swap or mount devices while an operation is running.
-
-### Linux
-
-Selection uses explicit-column `lsblk --json` topology. A target must be a
-parentless whole block device with USB transport, writable media, a positive
-size, and 512-byte logical sectors. The device path must be the direct validated
-`/dev/ID` path. Devices with active swap, device-mapper, RAID, LVM, encrypted,
-multipath, or any other non-partition descendants are excluded rather than
-partially dismantled. Mounted ordinary partitions remain selectable so desktop
-auto-mount does not hide a USB.
-
-Root, standard system mount paths, home, working directory, app source, Bun
-executable, resolved runtime packages/native assets, tools, and image staging are resolved to filesystem
-major:minor identities with `findmnt`. `lsblk` parent relationships are followed
-to every physical disk, including multi-parent stacks. Attached block devices
-configured in `/etc/fstab` are also protected; every attached match for duplicated
-`UUID`, `LABEL`, `PARTUUID`, or `PARTLABEL` tags is included. Protected filesystem UUIDs expand
-to every attached member, and every member of an active shared-UUID filesystem
-is excluded even when `lsblk` reports its mountpoint on only one member. Discovery
-uses the util-linux 2.37 `SOURCE` column, not newer `SOURCES`. Unknown backing fails
-closed rather than assuming it cannot be a target. A Linux installation running
-from external USB is therefore excluded without assuming a device name.
-
-The selected attachment is identified by major:minor, capacity, udev device path,
-block-node device/inode/change time, a hardware-backed `/dev/disk/by-id` link,
-optional udev path/serial, and model. USBs without a current by-id route
-are not offered. Kernel sysfs resolves each whole block device to its nearest
-physical USB parent; every LUN is excluded when safe power-off would affect a
-sibling block device. Identity and eligibility are rechecked after authorization, after unmount, and
-before safe removal. Linux unmounts every mounted target filesystem with
-`umount --all-targets`, without force or lazy detach, then requires all target
-mounts to be gone. It writes through the revalidated by-id route using
-`dd bs=4M conv=fsync`, runs `sync`, refreshes sudo authorization, removes any
-post-write automounts without force, and requires `udisksctl power-off` to succeed
-before claiming the drive is safely powered off. UDisks2 may reject hardware it
-cannot safely power off; its service and selected block object are checked during
-discovery, and a later power-off rejection is reported as an incomplete outcome
-rather than a false success.
-
-These repeated checks are not an atomic kernel claim. Do not unplug, swap, or
-mount devices while an operation is running.
-
-Cancellation stops the decompressor/input stream, closes the writer's stdin,
-and **waits for the writer to finish its finite buffered tail** before cleanup
-or exit. It does not kill the sudo supervisor and orphan a root writer. If a
-device/driver stalls, stopping can take time: keep the USB connected and wait.
-No force/lazy unmount, forced exit deadline, or automatic safe removal follows
-failure. Use the host platform's safe-removal control for an incomplete USB.
-SIGKILL, power loss and device removal cannot be made safe by application cleanup.
-
-## Preview And Status
-
-```sh
-bun demo
-bun start --demo=empty
-bun start --demo=error
-bun start --demo=setup
-bun start --demo=setup-gh
-bun start --demo=setup-zstd
-bun start --demo=setup-error
-bun start --demo=setup-interrupted
-bun start --demo=no-homebrew
-bun run typecheck
-bun run test
-bun run test:package
-```
+Choose the target computer’s GPU and USB drive. Boo Flash downloads and verifies the latest qualified image, then erases and writes the selected drive.
 
-Demo modes use the **same actual Solid UI**, with in-memory images, non-device
-IDs, simulated progress and outcomes. They never run disk commands, sudo, a
-writer, Homebrew, package installation or image downloads. The header always
-says `DEMO - no disks written`. Setup previews also label simulated installation.
-These options are for manual UI review, not a test harness.
-`setup-interrupted` simulates a Homebrew interruption result without signaling
-Boo Flash; after the handoff it should quit, not return to setup or load images.
-The card fills compact terminals and is bounded/centered on large ones; below
-40 columns or 16 rows, choices are hidden and Enter cannot approve erasure.
+Requires Node.js 26.4+ or Bun 1.4+.
 
-The Linux topology policy has focused automated fixtures for system-disk
-protection, mounted USBs, post-unmount checks, multi-parent backing storage,
-complex holders, swap, read-only/4Kn/non-USB disks, malformed inventory, unknown
-backing devices, and ambiguous aliases. Typecheck, live production discovery,
-read-only live Linux host inventory, exact npm contents, and clean packed
-`npx`/Node and `bunx`/Bun native-renderer startup/exit are also verified. The
-published runtime dependency tree has zero known npm audit findings. **No macOS or Linux
-hardware flash, real payload write, or physical safe removal has been qualified.**
-Dependency setup and its terminal handoff are likewise only simulated on Linux;
-real Homebrew installation and interruption on macOS remain unqualified.
-Review the source and qualify on an explicitly chosen disposable USB on each host
-platform before relying on it for hardware use.
+## License
 
-Platform references: [diskutil manual](https://keith.github.io/xcode-man-pages/diskutil.8.html),
-[stat manual](https://keith.github.io/xcode-man-pages/stat.1.html),
-[Apple ioreg source](https://github.com/apple-oss-distributions/IOKitTools/blob/main/ioreg.tproj/ioreg.c),
-[Apple registry ID contract](https://github.com/apple-oss-distributions/IOKitUser/blob/main/IOKitLib.h),
-[sudo process/exit contract](https://www.sudo.ws/docs/man/sudo.man/),
-[lsblk manual](https://man7.org/linux/man-pages/man8/lsblk.8.html),
-[findmnt manual](https://man7.org/linux/man-pages/man8/findmnt.8.html),
-[umount manual](https://man7.org/linux/man-pages/man8/umount.8.html), and
-[UDisks documentation](https://storaged.org/doc/udisks2-api/latest/).
-Dependency references: [Homebrew installation](https://docs.brew.sh/Installation),
-[install options/environment](https://docs.brew.sh/Manpage#install-options-formulacask-).
+MIT © 2026 Anomaly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "boo-flash",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Flash qualified Boo images to USB drives on macOS and Linux",
   "license": "MIT",
   "type": "module",