samios/README.md

SamiOS — A Custom Arch Linux Distribution

Overview

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 (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

# On Arch Linux
sudo pacman -S archiso git shellcheck

Clone and Build

git clone https://git.sami/sami7777/samios.git
cd samios/packaging/archiso
sudo ./build.sh

Installation

From ISO

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:

   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:

   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.

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:

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:

# 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

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:

make test           # just the tests
make lint           # just shellcheck
make check          # both (the CI entry point)

Individual tests can be run directly:

bash tests/test_voice_bridge.sh --verbose

CLI Tool

The samios command provides system management:

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 and 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 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 and the current phase, and docs/developer-guide.md for build/test/release workflows.

License

TBD