boo-flash 0.1.0 → 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` version `0.1.0`. 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 separate
-Node- and Bun-compiled Solid entry points 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/THIRD_PARTY_NOTICES

@@ -37,3 +37,27 @@ Redistributions in binary form must reproduce the above copyright notice, this l
 
 THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
 EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+solid-js
+--------
+MIT License
+
+Copyright (c) 2016-2025 Ryan Carniato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.