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

```bash
# On Arch Linux
sudo pacman -S archiso git shellcheck
```

### Clone and Build

```bash
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:
   ```bash
   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`](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 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 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`](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