Merge pull request #7 from iokode/tools

Lay out the tool documents by entity and tool

Author: montyclt

README.md

@@ -39,7 +39,7 @@ It fetches the installer with its dependencies and runs it.
 
 ### Installer
 
-See [Installation Overview](docs/general/002-installation-overview.md) for what it asks and what it does, and [oparch-installer](docs/tools/oparch-installer/000-command.md) for the installer tool itself.
+See [Installation Overview](docs/general/002-installation-overview.md) for what it asks and what it does, and [oparch-installer](docs/tools/installer/unattended/000-command.md) for the installer tool itself.
 
 ## Repository layout
 

assets/plymouth/opinionatedarch/opinionatedarch.script

@@ -1,7 +1,7 @@
 # The unlock screen. It draws no text: everything it shows was composed into an
 # image beforehand by `oparch-return-message-render`, and the installed system
 # carries no font for this screen. What is drawn is decided by the return-message
-# theme, in `docs/tools/oparch-return-message-render/003-theme-format.md`.
+# theme, in `docs/tools/return-message/render/003-theme-format.md`.
 #
 # This file is the body of the script. Whoever installs the theme writes these
 # seven values above it, as literals, and the two together are the script the

docs/INDEX.md

@@ -33,32 +33,32 @@ Every document in this directory, by type. What the types are and what shape eac
 
 ## Tools
 
-- [oparch-installer](tools/oparch-installer/000-command.md)
-  - [Installer Configuration File Format](tools/oparch-installer/001-config-file-format.md)
-  - [Inputs and Bootstrap Baseline](tools/oparch-installer/002-inputs-and-bootstrap-baseline.md)
-  - [Input Sources](tools/oparch-installer/003-input-sources.md)
-- [oparch-installer-interactive](tools/oparch-installer-interactive/000-command.md)
-- [oparch-return-message-render](tools/oparch-return-message-render/000-command.md)
-  - [Return Message Template Package Format](tools/oparch-return-message-render/001-template-package-format.md)
-  - [Return Message Values Format](tools/oparch-return-message-render/002-values-format.md)
-  - [Return Message Theme Format](tools/oparch-return-message-render/003-theme-format.md)
-  - [Return Message Themes](tools/oparch-return-message-render/004-themes.md)
-- [oparch-dotfiles-sync](tools/oparch-dotfiles-sync/000-command.md)
-  - [Dotfiles Map Format](tools/oparch-dotfiles-sync/001-map-format.md)
-  - [Secret Store Archive](tools/oparch-dotfiles-sync/002-secret-store-archive.md)
-- [oparch-work-context-create](tools/oparch-work-context-create/000-command.md)
-- [oparch-work-context-remove](tools/oparch-work-context-remove/000-command.md)
-- [oparch-work-context-list](tools/oparch-work-context-list/000-command.md)
-- [oparch-work-context-interactive](tools/oparch-work-context-interactive/000-command.md)
-- [oparch-snapshot-system-create](tools/oparch-snapshot-system-create/000-command.md)
-- [oparch-snapshot-work-context-create](tools/oparch-snapshot-work-context-create/000-command.md)
-- [oparch-snapshot-automatic-create](tools/oparch-snapshot-automatic-create/000-command.md)
-- [oparch-snapshot-list](tools/oparch-snapshot-list/000-command.md)
-- [oparch-snapshot-remove](tools/oparch-snapshot-remove/000-command.md)
-- [oparch-snapshot-restore](tools/oparch-snapshot-restore/000-command.md)
-- [oparch-snapshot-interactive](tools/oparch-snapshot-interactive/000-command.md)
-- [oparch-password-rotate](tools/oparch-password-rotate/000-command.md)
-- [oparch-password-rotate-interactive](tools/oparch-password-rotate-interactive/000-command.md)
+- [oparch-installer](tools/installer/unattended/000-command.md)
+  - [Installer Configuration File Format](tools/installer/unattended/001-config-file-format.md)
+  - [Inputs and Bootstrap Baseline](tools/installer/unattended/002-inputs-and-bootstrap-baseline.md)
+  - [Input Sources](tools/installer/unattended/003-input-sources.md)
+- [oparch-installer-interactive](tools/installer/interactive/000-command.md)
+- [oparch-return-message-render](tools/return-message/render/000-command.md)
+  - [Return Message Template Package Format](tools/return-message/render/001-template-package-format.md)
+  - [Return Message Values Format](tools/return-message/render/002-values-format.md)
+  - [Return Message Theme Format](tools/return-message/render/003-theme-format.md)
+  - [Return Message Themes](tools/return-message/render/004-themes.md)
+- [oparch-dotfiles-sync](tools/dotfiles/sync/000-command.md)
+  - [Dotfiles Map Format](tools/dotfiles/sync/001-map-format.md)
+  - [Secret Store Archive](tools/dotfiles/sync/002-secret-store-archive.md)
+- [oparch-work-context-create](tools/work-context/create/000-command.md)
+- [oparch-work-context-remove](tools/work-context/remove/000-command.md)
+- [oparch-work-context-list](tools/work-context/list/000-command.md)
+- [oparch-work-context-interactive](tools/work-context/interactive/000-command.md)
+- [oparch-snapshot-system-create](tools/snapshot/system-create/000-command.md)
+- [oparch-snapshot-work-context-create](tools/snapshot/work-context-create/000-command.md)
+- [oparch-snapshot-automatic-create](tools/snapshot/automatic-create/000-command.md)
+- [oparch-snapshot-list](tools/snapshot/list/000-command.md)
+- [oparch-snapshot-remove](tools/snapshot/remove/000-command.md)
+- [oparch-snapshot-restore](tools/snapshot/restore/000-command.md)
+- [oparch-snapshot-interactive](tools/snapshot/interactive/000-command.md)
+- [oparch-password-rotate](tools/password/rotate/000-command.md)
+- [oparch-password-rotate-interactive](tools/password/rotate-interactive/000-command.md)
 
 The first four are written. The rest are specified and not implemented, which [Remaining](state/001-remaining.md) carries as the first work.
 

docs/README.md

@@ -37,7 +37,7 @@ Section order:
 
 ## Tool
 
-Documents defining one tool each. Every tool has its own directory, named after the command, and its documents are numbered inside it: `tools/<tool-name>/<number>-<name>.md`.
+Documents defining one tool each. They are laid out the way the sources of the tools are, as [Repository Layout](development/002-repository-layout.md) lays those out: a directory for each entity, named after it, and inside it a directory for each tool, named after what follows the entity in the tool's name. `oparch-snapshot-restore` is `tools/snapshot/restore/`, and the installer's two are `tools/installer/unattended/` and `tools/installer/interactive/`. A tool's documents are numbered inside its directory: `tools/<entity>/<tool>/<number>-<name>.md`.
 
 The first document of a tool is its command document, `000-command.md`, with this section order:
 

docs/decisions/009-preboot-ownership-message.md

@@ -10,7 +10,7 @@ The return message is optional. When enabled, it is shown at the disk unlock pro
 
 ### The message
 
-The wording of the message, the languages it offers and the data it needs are not fixed by this project: they come from a template package, which the operator may supply and which the project ships one of. Its format is [Return Message Template Package Format](../tools/oparch-return-message-render/001-template-package-format.md).
+The wording of the message, the languages it offers and the data it needs are not fixed by this project: they come from a template package, which the operator may supply and which the project ships one of. Its format is [Return Message Template Package Format](../tools/return-message/render/001-template-package-format.md).
 
 A package is data. Nothing in it is executed, and its text is escaped wherever it is embedded, so a package obtained from a URL cannot introduce anything that runs during boot.
 
@@ -22,7 +22,7 @@ The message is rendered to images, and those images are what the unlock screen d
 
 The rendered images reach the edges of the screen. Their content does not: the renderer composes them with a margin around it.
 
-What the message looks like, and how the languages are arranged, are the theme's, as decided in [Return Message Themes](../tools/oparch-return-message-render/004-themes.md).
+What the message looks like, and how the languages are arranged, are the theme's, as decided in [Return Message Themes](../tools/return-message/render/004-themes.md).
 
 Everything the unlock screen needs is on the machine before the initramfs is built. Nothing is fetched at boot.
 
@@ -54,7 +54,7 @@ If the boot splash fails, unlock still falls back to a text-mode prompt.
 
 - Contact data is intentionally public on the pre-boot screen.
 - The rendered message is an image, so it carries no selectable text. This is accepted: at this point there is no operating system and no assistive tooling, and what a finder sees is pixels either way.
-- Changing the message on an installed system means rendering it again with [oparch-return-message-render](../tools/oparch-return-message-render/000-command.md).
+- Changing the message on an installed system means rendering it again with [oparch-return-message-render](../tools/return-message/render/000-command.md).
 - Return-message readability must be validated on the real display resolutions used by the target machines.
-- What the rendered message looks like is a theme's, decided in [Return Message Themes](../tools/oparch-return-message-render/004-themes.md).
+- What the rendered message looks like is a theme's, decided in [Return Message Themes](../tools/return-message/render/004-themes.md).
 

docs/decisions/014-dotfiles.md

@@ -8,7 +8,7 @@
 
 The configuration of the machine is one source, and every work context takes what it needs from it. There is no second copy of a file for a second context.
 
-What one context or one machine needs and another does not is declared, not kept apart: a rule says which contexts and which machines it applies to, and the same source produces all of them. The syntax of those rules is [Dotfiles Map Format](../tools/oparch-dotfiles-sync/001-map-format.md).
+What one context or one machine needs and another does not is declared, not kept apart: a rule says which contexts and which machines it applies to, and the same source produces all of them. The syntax of those rules is [Dotfiles Map Format](../tools/dotfiles/sync/001-map-format.md).
 
 `/dotfiles` is owned `root:dotfiles` with mode `2775`.
 
@@ -22,9 +22,9 @@ Content an installation places under `/dotfiles` is left with directories at `27
 
 `/dotfiles` is listed in git's system-wide `safe.directory`.
 
-Secret values are not kept in `/dotfiles`. They live in a store of their own, `/etc/oparch/dotfiles-sync/secrets/`, owned `root:root` with mode `0700`, which the `dotfiles` group does not reach. What that store holds and how it is read is [Dotfiles Map Format](../tools/oparch-dotfiles-sync/001-map-format.md).
+Secret values are not kept in `/dotfiles`. They live in a store of their own, `/etc/oparch/dotfiles-sync/secrets/`, owned `root:root` with mode `0700`, which the `dotfiles` group does not reach. What that store holds and how it is read is [Dotfiles Map Format](../tools/dotfiles/sync/001-map-format.md).
 
-A change under `/dotfiles` reaches a linked target at once, because that target is a link to it. Everything the map copies or renders is produced by [oparch-dotfiles-sync](../tools/oparch-dotfiles-sync/000-command.md), and changes when it is run.
+A change under `/dotfiles` reaches a linked target at once, because that target is a link to it. Everything the map copies or renders is produced by [oparch-dotfiles-sync](../tools/dotfiles/sync/000-command.md), and changes when it is run.
 
 ## Why
 
@@ -41,5 +41,5 @@ A change under `/dotfiles` reaches a linked target at once, because that target
 
 - `/dotfiles` is a Git repository only when the package it was installed from was one. A package taken as a directory or an archive leaves files, and the restore path [Disk Layout](001-disk-layout.md) describes does not exist on that machine until someone makes it a repository.
 - The `dotfiles` group is a boundary between the accounts of one person and not between people, as [Work Contexts and Accounts](000-work-contexts-and-accounts.md) establishes. Shared write access to shared configuration is the point of it, not a concession.
-- What [oparch-dotfiles-sync](../tools/oparch-dotfiles-sync/000-command.md) writes is the targets a map declares and its own state under `/var/lib/oparch/`. Its permission to read `/dotfiles` is the group's, and nothing here asks it to write there.
+- What [oparch-dotfiles-sync](../tools/dotfiles/sync/000-command.md) writes is the targets a map declares and its own state under `/var/lib/oparch/`. Its permission to read `/dotfiles` is the group's, and nothing here asks it to write there.
 

docs/development/002-repository-layout.md

@@ -57,7 +57,7 @@ An entity is added by creating its directory and its library. A tool is added by
 
 The domain logic of an entity belongs to its library, whichever of its tools first needed it, and stays there when a project outside the entity needs it too. That project symlinks the namespace exactly as it symlinks a shared one.
 
-The return-message template package and its values format are the case: they belong to the return message, and they are specified under `oparch-return-message-render` in `docs/`. They live in `tools/return-message/lib/baml_src/ns_return_message/`, and the installer links them from there, because it asks for the fields a package declares and validates the same values in its own configuration file.
+The return-message template package and its values format are the case: they belong to the return message, and they are specified under `docs/tools/return-message/render/`. They live in `tools/return-message/lib/baml_src/ns_return_message/`, and the installer links them from there, because it asks for the fields a package declares and validates the same values in its own configuration file.
 
 The project of a tool holds its interface and no domain logic: the arguments it reads and what it prints, or the screens it draws and whatever the interface does to the system so it can be used.
 

docs/development/005-baml-working-notes.md

@@ -51,7 +51,7 @@ Three things about the generated entry point:
 
 ## The standard library
 
-- `baml.yaml.parse` requires **string mapping keys**: a mapping keyed by numbers fails with `YAML mappings must use string keys to fit baml.json.json`. A format that wants to key entries by a number has to quote them, which is why `arrangement` in [Return Message Theme Format](../tools/oparch-return-message-render/003-theme-format.md) is written `"1":`.
+- `baml.yaml.parse` requires **string mapping keys**: a mapping keyed by numbers fails with `YAML mappings must use string keys to fit baml.json.json`. A format that wants to key entries by a number has to quote them, which is why `arrangement` in [Return Message Theme Format](../tools/return-message/render/003-theme-format.md) is written `"1":`.
 - `baml.sys.exec`'s `ProcessOptions.env` **replaces the environment rather than adding to it**. `PATH` survives, `HOME` does not. Anything the child needs has to be passed.
 - `baml.sys.exec` takes the program and its arguments separately, so nothing built from a template package or a theme is ever parsed by a shell.
 

docs/development/006-end-to-end-testing.md

@@ -2,7 +2,7 @@
 
 End-to-end tests boot this project's installation image under QEMU and let the installer inside it build a machine on a disposable disk. Everything below the installer — `pacstrap`, `arch-chroot`, `cryptsetup`, `sgdisk` — is the genuine article, and the result is verified by booting the disk that was just installed.
 
-This document describes the harness and the cases it runs. It does not describe the installer, which is documented in [oparch-installer](../tools/oparch-installer/000-command.md).
+This document describes the harness and the cases it runs. It does not describe the installer, which is documented in [oparch-installer](../tools/installer/unattended/000-command.md).
 
 The **harness** is neither the thing under test nor the assertions: it is what makes running them possible at all. The word is the one used for a wiring harness, the thing that connects and drives, and not for anything to do with the tools this project is written with.
 

docs/development/007-installation-checks.md

@@ -18,7 +18,7 @@ Run against the machine that was just installed, once it boots.
 | Every directory under `/dotfiles` is `2775` and every file `664`                                                    | A copy carries the modes it came from, so this is the half the ACL cannot do. Wrong, the operator can read the shared configuration and change none of it.                                              |
 | `/etc/gitconfig` names `/dotfiles` as a safe directory                                                              | The tree is root's and the operator is not, so git refuses to work in it without this. It is written rather than set with `git config`, so nothing else would fail if it were missing — until someone runs git there. |
 | `/etc/oparch/dotfiles-sync/secrets` is `0700 root:root`, and each file in it `0600`                                 | The values in it are credentials rendered into configuration afterwards. Loosened, every work context can read every secret the dotfiles carry, which the store exists to prevent.                        |
-| `ipxe` is installed                                                                                                 | The netboot binary comes from the package rather than from a download, as [Installer Inputs and Bootstrap Baseline](../tools/oparch-installer/002-inputs-and-bootstrap-baseline.md) decides.                                                     |
+| `ipxe` is installed                                                                                                 | The netboot binary comes from the package rather than from a download, as [Installer Inputs and Bootstrap Baseline](../tools/installer/unattended/002-inputs-and-bootstrap-baseline.md) decides.                                                     |
 | `/boot/EFI/OpinionatedArch/netbootx64.efi` is there, and its checksum equals `/usr/share/ipxe/x86_64/ipxe-arch.efi` | That the file on the EFI partition is the one the package shipped, and not something fetched.                                                                                                           |