IF Commons GitHub

Boot plugin: the commands

0002Active

0002-boot-command · owner if · domain commons

Requirements

FR-001checkpassing

The plugin MUST contribute the branch boot with the verbs prepare, arm, disarm, status and serve to the program it is given (archon by default); the variables it reads MUST be the program's name in capitals with _BOOT_STATE, _BOOT_ASSETS and _SECRETS, the state file defaulting to a file in the person's own configuration folder named for the program (never in a repository).

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Written in: archon-boot/src/config.ts, archon-boot/src/mod.ts

Tests: passed: suite/command.test.ts the plugin composes into the command with the verbs prepare, arm, disarm, status and serve

FR-002checkpassing

prepare and arm MUST ask the fleet for the asset first and, where the fleet refuses it (an asset that is adopted, or that another system installs), MUST end with the exit the fleet gave and name its code and words, and MUST write and arm nothing.

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Written in: archon-boot/src/boot.ts, archon-boot/src/commands.ts

Tests: passed: suite/command.test.ts an asset that may not be installed is refused by prepare and by arm with the fleet's code,

FR-003checkpassing

prepare MUST render the install with the install dialect and the playbook with the playbook dialect, each from the requirements it carries, as generated files in the folder the fleet names that hold no secret and are the same text every time, and say each file written.

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Written in: archon-boot/src/boot.ts, archon-boot/src/commands.ts

Tests: passed: suite/command.test.ts prepare renders the autoinstall and the playbook with the fleet's two dialects, as generat

FR-004checkpassing

arm MUST record that the asset's next network boot may install it, with a token, and that it may erase a disk that holds data only if --confirm-destroy yes was given, in a state file readable by its owner alone; disarm MUST take it out; status MUST show what is armed, what installed, the latest progress and the boot files that are missing or do not match their pins.

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Written in: archon-boot/src/boot.ts, archon-boot/src/commands.ts

Tests: passed: suite/command.test.ts arm, status and disarm keep their state in the file given: an arming says whether it may e

FR-005checkpassing

serve MUST run the TFTP and HTTP boot server over the pinned files with the fleet's provider and the secrets folder, and MUST NOT start where a boot file is missing or does not match its pin (ending with 3 and saying how to get the files).

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Written in: archon-boot/src/boot.ts, archon-boot/src/commands.ts

Tests: passed: suite/command.test.ts serve does not start where a boot file is missing or does not match its pin, and says how

FR-006checkpassing

arm, status and serve MUST take the boot profile of the distribution to serve (--profile, the fleet's default or Ubuntu 26.04 where none is given), MUST serve its pinned files, and MUST refuse a profile that does not exist with the profiles there are and the usage exit; arm MUST refuse, with the usage exit, a profile whose installer cannot run the blank-disk guard unless --confirm-destroy yes says that the install may erase a disk.

Enforced (check): .github: cd commons/archon-boot && bun run verify — suite/command.test.ts

Proved by: archon-boot/suite/command.test.ts

Tests: passed: suite/command.test.ts arm refuses a profile whose installer cannot run the guard unless it is told that a disk m; passed: suite/command.test.ts status and serve take the profile of the distribution: an unknown one is refused with the

Acceptance scenarios

  1. Given an asset the fleet refuses, When arm is run, Then nothing is armed and the fleet's words are said, per FR-002.

Out of scope

  • Which assets there are, their requirements and who may install them: the fleet's.

Edge cases

  • A machine whose disks hold data is stopped by the guard of netboot unless it was armed with --confirm-destroy yes, per FR-004.

Assumptions

  • The pinned boot files are fetched with --fetch yes and each is checked against its pin, per FR-005.

Open questions

  • None.

Key entities

  • Install, Arming, Boot server.

Success criteria

SC-001success criterion

A blank machine is installed from a render that holds no secret, only when an owner armed it.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Titles, headings, exports, tables, columns and requirements. Esc closes.