sami7777/samios
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[grade=A] Expand README with VERSION SSOT section, test suite table, repo layout, voice-bridge prototype status
SamiOS CI / lint-and-test (push) Successful in 10s
Details

Browse Source
This commit is contained in:
Sami Ahmed
2026-08-12 00:56:18 -07:00
parent 70e9b94030
commit c8a286ff19
1 changed files with 215 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+215 -18
View File
@@ -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=<your-version>
```
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 "<NEW>" > 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=<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<VERSION>` — 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