soleprint/rig/docs/notes/standalone.md

ctrl/standalone.sh

Purpose

Generates the standalone kits: single-file versions of rig's own tools, one folder per profile, for machines the full rig is not going to.

A kit is a pure function of rig as it is right now. It gains nothing rig lacks and loses nothing rig has: improve rig, regenerate, and every kit follows. Nothing in standalone/<profile>/ is ever edited by hand.

The contract

What this file does NOT know, on purpose: which tools rig has, what they are called, how its libraries are split, where configuration lives or what it contains. Rig will change shape (scripts get split, renamed and grow new libraries), and a generator that encoded today's layout would quietly produce a wrong kit the first time it did. So it works from a contract a script opts into, and from nothing else:

1. A marker comment, alone on a line near the top, declares an entry point: (hash) rig:standalone <kit-name> <default-verb>. The default verb must only REPORT: it is run as a smoke test.
2. Every source an entry point makes names a .sh file by a path that resolves relative to the entry point. Libraries may source further libraries however they like; bash follows those itself.
3. Configuration enters through load_config, and the libraries provide config_profiles, config_freeze <profile|--current> (which prints a replacement load_config with that resolution frozen in) and, for an export, config_current_profile and config_left_out. How config is layered, stored, derived or frozen is rig's business; the generator only asks, and embeds the answer without interpreting it.

Bash does the resolving

Bash does the resolving, not a parser in the generator. Libraries are sourced in a clean shell and read back with declare -f and declare -p, so any structure bash can load, this can flatten.

Every kit is proven before it is written

Every kit is PROVEN to stand alone before it is written: no source left, no path into rig's tree in its code, bash -n clean, and its default verb run in an empty directory with nothing from rig present. A shape the generator has never seen either passes that, or generation stops and names the kit, the file, the line and what is wrong. It never writes a kit that only looks finished.

Usage: write, check, export

• standalone.sh write: generate every kit into standalone/<profile>/.
• standalone.sh check: generate into a scratch dir and fail if any kit differs.
• standalone.sh export DIR: ONE kit for the configuration this machine runs (its profile plus the choices in its local config, WITHOUT its credentials), written outside the repo.

write and check are what gets committed: one kit per profile, identical on any machine. export answers the other question, "take the setup I have here somewhere else", so it reflects this machine, and for exactly that reason it never lands in the repository.