From c8a286ff19882dfddca90f660e5439d2ac19de6b Mon Sep 17 00:00:00 2001 From: Sami Ahmed Date: Wed, 12 Aug 2026 00:56:18 -0700 Subject: [PATCH] [grade=A] Expand README with VERSION SSOT section, test suite table, repo layout, voice-bridge prototype status --- README.md | 233 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 215 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 58ec8d2..b269e1a 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,34 @@ -# SamiOS - A Custom Arch Linux Distribution +# SamiOS — A Custom Arch Linux Distribution ## Overview -SamiOS is a custom Linux distribution based on Arch Linux, designed as a Windows replacement for personal use. + +SamiOS is a custom Linux distribution based on Arch Linux, designed as a +personal daily-driver desktop OS. It ships a custom CLI (`samios`), an +automated disk installer, a single-source-of-truth version system, and +a voice-bridge prototype for hands-free OS control via Hermes. ## Features -- Rolling release (Arch-based) -- Custom CLI tool (`samios`) for system management -- Automated installation scripts -- Custom branding and configuration -- Font policy: excludes fonts with "7777" in the name + +- **Rolling release** Arch-based +- **Custom CLI** (`samios`) for system management — version, status, update, install, remove, services, fonts +- **Automated installer** (`samios-installer.sh`) — UEFI/BIOS, partitioning, pacstrap, GRUB, user creation +- **VERSION single-source-of-truth** — one file drives every component +- **Custom branding** — GRUB theme, MOTD, bashrc, zshrc, pacman welcome message +- **Font policy** — excludes fonts with "7777" in the filename (personal branding) +- **Voice bridge prototype** — `voice-bridge.py` listens to SamiType transcripts and routes to Hermes (command mode) or `xdotool` (dictation mode) +- **CI** — Gitea Actions runs `make check` on pushes to `master` / `main` and on pull requests targeting those branches ## Building from Source ### Prerequisites + ```bash # On Arch Linux -sudo pacman -S archiso git +sudo pacman -S archiso git shellcheck ``` ### Clone and Build + ```bash git clone https://git.sami/sami7777/samios.git cd samios/packaging/archiso @@ -28,30 +38,217 @@ sudo ./build.sh ## Installation ### From ISO -1. Boot from the generated ISO -2. Run the automated installer: + +1. Boot the generated ISO. The ISO ships the live environment, the + `samios` package-management CLI, and `/etc/samios-version` (the + mirrored VERSION file). It does **not** ship + `samios-installer.sh` automatically — that script lives in + `packaging/scripts/` in the source repo and is invoked manually + after boot (or copied into the live environment first). +2. To install SamiOS to disk from the live ISO, run the installer: ```bash - samios install + sudo /root/samios-installer.sh # if you copied it into the live env + # — or — + sudo bash /path/to/samios-installer.sh + ``` + The installer is interactive by default; pass `--disk`, `--user`, + and `--password` to drive it non-interactively from automation: + ```bash + sudo /path/to/samios-installer.sh --disk /dev/sda --user sami --password ... ``` +> **Note:** `samios install` (the CLI subcommand on the live system +> and on the installed OS) is the **package** installer — e.g. +> `samios install firefox`. It does **not** invoke the OS installer. +> The OS installer is the `samios-installer.sh` script. + ### Manual Installation -See `docs/installation.md` for detailed instructions. + +See [`docs/installation.md`](docs/installation.md) for detailed +instructions. + +## Repository Layout + +``` +samios/ +├── VERSION # Single source of truth for the release version +├── Makefile # Targets: test, lint, check, version, version-set, version-sync, build, clean, help (see "Makefile Targets" below) +├── README.md # This file +├── branding/ # GRUB theme, pacman welcome, fonts +├── docs/ # roadmap, installation, voice-to-Hermes design +├── packaging/ +│ ├── archiso/ # The archiso profile (profiledef.sh, packages, airootfs overlay) +│ │ └── airootfs/ +│ │ ├── etc/samios-version # Mirrored from /VERSION by `make version-sync` +│ │ └── usr/local/bin/samios # The CLI tool (installed) +│ ├── packages/ +│ │ └── samios-branding/ # PKGBUILD (also reads ../../../VERSION) +│ └── scripts/ +│ ├── samios-installer.sh # The disk installer +│ ├── samios-desktop-setup.sh # Post-install KDE/desktop setup +│ └── voice-bridge.py # Voice command/dictation bridge prototype +└── tests/ # Test suite (see "Test Suite" below) +``` + +## VERSION Single Source of Truth + +There is exactly **one** authoritative source for the release version: +the `VERSION` file at the repo root. Each consumer resolves it via +its own mechanism: + +- **`samios` CLI** (`packaging/archiso/airootfs/usr/local/bin/samios`) — + walks up from `$0` to find `./VERSION`, falls back to + `/etc/samios-version`, then to a documented placeholder. +- **`samios-installer.sh`** (`packaging/scripts/samios-installer.sh`) — + walks up from `$0` to find `./VERSION`, falls back to + `/etc/samios-version`, then to a documented placeholder. Same + algorithm as the CLI it emits. +- **`voice-bridge.py`** (`packaging/scripts/voice-bridge.py`) — + walks up from its own location to find `./VERSION`, falls back to + `/etc/samios-version`, then to a documented placeholder. +- **`profiledef.sh`** (`packaging/archiso/profiledef.sh`) — + walks up from `$0` to find `./VERSION`, then to the documented + placeholder. (No `/etc/samios-version` fallback — this runs at + ISO *build* time, not at runtime.) +- **`PKGBUILD`** (`packaging/packages/samios-branding/PKGBUILD`) — + reads `$startdir/../../../VERSION` first, falls back to + `../../../VERSION`, then **fails loudly** with `exit 1`. There is + no walk-up and no placeholder — the SSOT invariant is absolute: a + release build without VERSION is a build error. +- **`.bashrc` / `.zshrc`** (in the airootfs overlay — run in the live + ISO when root opens a shell) — read `/etc/samios-version` directly; + fall back to the documented placeholder. (No walk-up: the live ISO + ships `/etc/samios-version` via `make version-sync`. Note: the + installer does **not** copy these root dotfiles to installed + systems — it writes its own `/etc/bash.bashrc` instead.) + +The `test_version.sh` suite enforces this invariant: any X.Y.Z literal +introduced into a production file fails CI. To bump the version: + +```bash +make version-set NEW= +``` + +That edits `./VERSION` and mirrors it into +`packaging/archiso/airootfs/etc/samios-version` (the on-system anchor +that installed systems read at runtime). Then commit and push. + +If you prefer editing manually: + +```bash +# Write your target version to the SSOT file: +echo "" > VERSION +# Mirror into the airootfs overlay: +make version-sync +# Verify the SSOT invariant still holds: +make check +``` + +(The exact X.Y.Z string is intentionally omitted from this README — +the version lives in the `VERSION` file, not in documentation.) + +## Makefile Targets + +```bash +make help # Show all targets +make version # Print current SamiOS VERSION +make version-set NEW= # Bump VERSION (semver-ish, X.Y.Z[-suffix]) +make version-sync # Mirror VERSION into the airootfs overlay +make test # Run the test suite +make lint # Run shellcheck on all shell scripts +make check # Run lint + test (CI entry point) +make build # Build the SamiOS ISO (requires archiso + root) +make clean # Remove build artifacts +``` + +## Test Suite + +The test suite lives under `tests/` and is wired into +`tests/run_tests.sh`. It contains **142+ assertions across 8 test files**: + +| Test file | What it covers | +|-----------|----------------| +| `test_profiledef.sh` | archiso profiledef.sh — script presence, package lists, hooks | +| `test_packages.sh` | package list shape and required packages | +| `test_pacman_conf.sh` | pacman.conf configuration | +| `test_samios_cli.sh` | the installed `samios` CLI — syntax, --help, version, status, fonts | +| `test_font_policy.sh` | 7777-exclusion font policy | +| `test_version.sh` | VERSION single-source-of-truth — 55+ assertions across all 7 components | +| `test_installer.sh` | `samios-installer.sh` — syntax, SSOT, heredoc-emitted CLI | +| `test_voice_bridge.sh` | `voice-bridge.py` — 20 hermetic behavioral assertions | + +Run them with: + +```bash +make test # just the tests +make lint # just shellcheck +make check # both (the CI entry point) +``` + +Individual tests can be run directly: + +```bash +bash tests/test_voice_bridge.sh --verbose +``` ## CLI Tool + The `samios` command provides system management: + ```bash -samios status # Show system status -samios update # Update system -samios install # Install packages -samios fonts # Manage fonts +samios version # Show SamiOS version +samios status # Show system status (disk, memory, network) +samios update # Update system packages +samios install # Install a package +samios remove # Remove a package +samios services # List running services +samios fonts # Check installed fonts and the 7777-exclusion policy samios help # Show all commands ``` +The CLI walks up at runtime to find `./VERSION` (or `/etc/samios-version` +on a freshly installed system) so the version is never duplicated. + +## Voice Bridge (Prototype) + +`packaging/scripts/voice-bridge.py` is an early prototype of the +voice-to-Hermes pipeline. It listens for transcripts on stdin +(eventually from SamiType's STT socket), parses them, and: + +- If the transcript starts with the wake word **"computer"**, strips the + wake word and POSTs the remainder to the Hermes API at + `http://localhost:8765/command`. +- If the transcript is **"start dictation"**, enters dictation mode and + routes subsequent phrases to `xdotool type` (with `xdotool key` for + dictation commands like "new paragraph", "tab", "scratch that"). +- If the transcript is **"stop dictation"**, exits dictation mode. + +The script also exposes `--version` / `-V` which prints +`SamiOS voice-bridge v` — the version comes from the same +`./VERSION` walk-up resolver used by every other component. + +The bridge is a **prototype**: it does not yet connect to a real +SamiType socket, does not implement TTS feedback, and uses +`localhost:8765` as a placeholder Hermes endpoint. See +[`docs/voice-hermes-pipeline.md`](docs/voice-hermes-pipeline.md) and +[`docs/voice-integration-architecture.md`](docs/voice-integration-architecture.md) +for the design direction. The 20 behavioral assertions in +`tests/test_voice_bridge.sh` guard the version SSOT, the wake-word +routing, the dictation mode state machine, and the documented fallbacks. + ## Font Policy -SamiOS excludes any fonts with "7777" in the filename as these are personal branding fonts. + +SamiOS excludes any fonts with "7777" in the filename as these are +personal branding fonts. `samios fonts` enforces this at runtime; the +CI test `test_font_policy.sh` enforces it at build time. ## Development -This project is under active development. See `docs/roadmap.md` for planned features. + +This project is under active development. See +[`docs/roadmap.md`](docs/roadmap.md) for planned features and the +current phase, and [`docs/developer-guide.md`](docs/developer-guide.md) +for build/test/release workflows. ## License + TBD