docs: per-script local specs + spec-first change order (SPEC 6.11, 6.12)

Every script gets a complete spec.md sectionized like SPEC.md
(python/src/<name>/spec.md, <name>.spec.md for shell scripts).
Change order becomes spec -> tests -> code. Specs added for
gpgtools, hello, hello_bash; CHANGELOG under Unreleased.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 00:54:03 +01:00
parent fef68a84c9
commit 85e8342a74
5 changed files with 308 additions and 5 deletions
+8 -1
View File
@@ -8,7 +8,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
## [Unreleased]
- Nothing yet.
### Added
- Per-script local specs (SPEC items 6.11, 6.12): every script gets a
spec that completely describes it — `spec.md` in a Python script's
folder, `<name>.spec.md` beside bash/PowerShell/batch scripts — in
the sectionized format of SPEC.md. Script work is spec first, then
tests, then code (SPEC item 6.12). First specs added:
`gpgtools`, `hello`, `hello_bash`.
## [0.6.0] - 2026-11-18
+39 -4
View File
@@ -77,13 +77,15 @@ daedalus/
│ ├── daedalus_logging/ # File + console logging (section 11)
│ └── tests/
├── python/
│ ├── src/<name>/ # Python scripts, one folder per script
│ ├── src/<name>/ # Python scripts, one folder per script,
│ │ # holding <name>.py and spec.md (SPEC item 6.11)
│ └── tests/ # pytest tests for python/src, .ps1, .bat
├── bash/ # *.sh scripts (SPEC item 6.10 interface)
├── bash/ # *.sh scripts (SPEC item 6.10 interface),
│ # each with a <name>.spec.md sibling
│ ├── daedalus_common.sh # shared helper: daedalus_bash_dispatch, help() routing
│ └── tests/ # pytest tests that run them
├── powershell/ # *.ps1 scripts
├── batch/ # *.bat scripts (CRLF)
├── powershell/ # *.ps1 scripts, each with <name>.spec.md
├── batch/ # *.bat scripts (CRLF), each with <name>.spec.md
├── ci/ # sanity.py, checks.py, with tests
├── autotest.py # Runs every check (local and CI)
├── pyproject.toml # Package, version, entry point, package data
@@ -496,6 +498,39 @@ SCRIPTS: dict[str, Script] = {
registered `.sh` script (source line, `help()`, `main()`, the
dispatch call) and tests the helper behavior directly.
- **6.11** Every script has a local spec that completely
describes it.
- **6.11.1** A Python script's spec is `spec.md` inside its
own folder: `python/src/<name>/spec.md`.
- **6.11.2** A bash, PowerShell, or batch script's spec is a
sibling file named `<name>.spec.md`:
`bash/<name>.spec.md`, `powershell/<name>.spec.md`,
`batch/<name>.spec.md`.
- **6.11.3** The local spec follows the sectionized format of
this file: every heading and list item has a stable numbered
id (`- **N.M**`), sub-items continue the numbering
(`N.M.K`), and items are cited as
`<name> spec item N.M`.
- **6.11.4** The local spec is complete enough to rebuild the
script from it alone: purpose, commands and arguments,
observable behavior (steps, validation, output), exit
codes, files written, error handling, and testing approach.
- **6.11.5** The local spec does not repeat this file; where it
relies on a repository rule it cites the SPEC item instead.
- **6.12** The change order for script work is spec first, then
tests, then code.
- **6.12.1** Create or modify the script's local spec (SPEC
item 6.11) until it describes the intended behavior - a
change that contradicts an existing spec item updates that
item in the same change.
- **6.12.2** Add or change tests that fail without the
behavior.
- **6.12.3** Make the smallest change that makes the tests
pass, then refactor with them green.
- **6.12.4** Spec, tests, code, README, and CHANGELOG land in
the same change; the version bump follows SPEC item 9.8.
## 7. Quality gates
- **7.1** `python autotest.py [CHECK...]` runs the named checks (default:
+31
View File
@@ -0,0 +1,31 @@
# hello_bash specification
Complete description of `bash/hello_bash.sh`. The sample bash
script of the template: it exercises the SPEC item 6.10 shared
interface end to end. Items are cited as `hello_bash spec item
N.M`.
## 1. Purpose
- **1.1** Print one hello line per name argument, defaulting to
`world` when no argument is given, and exit via the interface:
`hello, <name> (from daedalus bash)`.
## 2. Behavior
- **2.1** The script sources `daedalus_common.sh` once, defines
`help()` (usage text) and `main()` (the printing), and ends
with `daedalus_bash_dispatch "$@"` (SPEC item 6.10).
- **2.2** `daedalus hello_bash me` prints `hello, me (from
daedalus bash)`; `daedalus hello_bash a b` prints one line
per name; no arguments prints the line for `world`.
- **2.3** `help`, `-h`, and `--help` route to `help()` and exit
0; every other invocation routes to `main` unchanged.
- **2.4** Nothing is read or written; the script takes names only.
## 3. Testing approach
- **3.1** `bash/tests/test_hello_bash.py` runs the script through
`runners.find_bash()` (skip when bash is missing) and covers
the default name, multiple names, the help routing, and the
completion words.
+197
View File
@@ -0,0 +1,197 @@
# gpgtools specification
Complete description of `python/src/gpgtools/gpgtools.py`. Change
this file first, then tests, then code (SPEC items 6.11 and 6.12).
Items are cited as `gpgtools spec item N.M`.
<!-- toc-start: headings 2..6 -->
- [1. Purpose](#1-purpose)
- [2. Commands](#2-commands)
- [3. initialize_yubikey behavior](#3-initialize_yubikey-behavior)
- [4. send_pubkey behavior](#4-send_pubkey-behavior)
- [5. Exit codes](#5-exit-codes)
- [6. Runner contract and injectability](#6-runner-contract-and-injectability)
- [7. Files written](#7-files-written)
- [8. Testing approach](#8-testing-approach)
- [9. References](#9-references)
<!-- toc-end -->
## 1. Purpose
- **1.1** gpgtools automates the YubiKey SSH flow documented in the
owner's wiki guide
(`~/repositories/vibe-wiki/wiki/queries/yubikey-ssh-guide.md`):
`initialize_yubikey` covers guide steps 1-4 (fresh machine ready
for GPG), `send_pubkey` covers steps 5-6 (key to a server).
Guide step 7 (per-host `~/.ssh/config`) is out of scope.
- **1.2** Hard constraint: the YubiKey's OpenPGP applet is never
written - no `gpg --card-edit`, no `keytocard`, no applet reset.
Only public card data is read; the card PIN is typed by its
owner into pinentry, never passed through this script.
- **1.3** The user's real GNUPGHOME is written only where section
7 says so; remote public-key imports go to a throwaway home
(item 4.5).
- **1.4** Standard library only; Python 3.11+ (SPEC item 9.6).
## 2. Commands
- **2.1** `daedalus gpgtools` with no subcommand prints the
overview of both subcommands and exits 0.
- **2.2** `daedalus gpgtools initialize_yubikey [--dry-run]
[--gnupg-home DIR]` - prepares this machine (section 3).
- **2.3** `daedalus gpgtools send_pubkey
(--yubikey | --url URL | --fingerprint FP | --pubkey LINE)
[--no-verify] [--dry-run] you@server` - resolves one SSH
public key, proves possession of the private half, appends it
to the target (section 4). The four source flags are mutually
exclusive and exactly one is required; `you@server` is
required.
- **2.4** `--dry-run` on either subcommand prints what would
happen and writes nothing; on `send_pubkey` it resolves and
prints the key but never verifies and never connects.
## 3. initialize_yubikey behavior
- **3.1** Step 1 - gnupg: `gpg --version`. When it fails, the
package manager is detected (`shutil.which` over apt-get, dnf,
pacman) and gnupg installed via `sudo`; no known manager is
exit 3. A failed install is exit 2.
- **3.2** Step 2 - card: `gpg --card-status` parsed for the
`Application type`/`OpenPGP` markers; absent card (including
gpg error text) is exit 4 with the pcscd hint
`systemctl enable --now pcscd`.
- **3.3** Card fields: serial (`Serial number`), authentication
subkey presence (`Authentication key` with a non-`[none]`
value), key URL (`URL of public key`, `[not set]` is None),
keyring pairing (`General key info` non-`[none]`).
- **3.4** Step 3 - public key: when unpaired and a URL exists,
`gpg --fetch-keys <url>`, then re-parse the card; still
unpaired is exit 5. Unpaired without a URL is exit 6 with the
manual-import hint.
- **3.5** A missing `[A]` subkey logs a warning (SSH via
gpg-agent will not work; GPG signing/decryption will) but is
not an error.
- **3.6** Step 4 - agent: the homedir is created at mode 700;
`gpg-agent.conf` gains `enable-ssh-support` and, only when its
key is absent, `default-cache-ttl 600` and `max-cache-ttl
7200`; existing lines, including user TTLs, are kept verbatim
and never duplicated. `gpgconf --kill gpg-agent` restarts the
agent. Exit 0.
## 4. send_pubkey behavior
- **4.1** Sources (exactly one per run):
- **4.1.1** `--yubikey`: the gpg ssh socket from
`gpgconf --list-dirs agent-ssh-socket` (bare path or prefixed
form), `SSH_AUTH_SOCK` set to it, `ssh-add -L`. No socket is
exit 8 with the `initialize_yubikey` hint; no keys is exit 8
with "is the YubiKey plugged in?"; several keys refuses with
the list and the `--pubkey` hint rather than guessing.
- **4.1.2** `--url`: fetch the armored OpenPGP public key,
convert via item 4.5.
- **4.1.3** `--fingerprint`: normalize (strip spaces and `0x`,
case-insensitive, exactly 40 hex chars, else exit 8); resolve
through the store chain, first hit wins: local keyring (`gpg
--export-ssh-key 0x<FP>`), then keys.openpgp.org VKS
(`.../vks/v1/by-fingerprint/<FP>`), then keyserver.ubuntu.com
(`.../pks/lookup?op=get&search=0x<FP>`). Every store result is
fingerprint-checked before use; a mismatch skips the store.
All exhausted is exit 8 naming the stores.
- **4.1.4** `--pubkey`: the literal line, validated by item 4.2;
exit 8 when invalid.
- **4.2** Key line validation: `ssh-(ed25519|rsa|dss|ecdsa-sha2-*)
<base64> [comment]`, full line; anything else is rejected.
- **4.3** Key material (type + base64, comment ignored) is the
key's identity for deduplication and reporting.
- **4.4** Proof of possession (default, skipped only with
`--no-verify`): a random hex challenge is signed via
`ssh-keygen -Y sign -U` (the private half - card, PIN prompt
included - must sign) and verified via `ssh-keygen -Y verify`
against the candidate line with an allowed_signers file. Any
failure prints that nothing was sent and exits 10; the ssh
target is never contacted.
- **4.5** Remote conversion: armored keys are imported into a
throwaway `--homedir` via `gpg --import`, fingerprints listed
with `--list-keys --with-colons`, and the ssh line exported with
`gpg --export-ssh-key 0x<FP>`. The real keyring is not touched;
the throwaway home is removed afterwards.
- **4.6** Send: `ssh you@server "cat ~/.ssh/authorized_keys
2>/dev/null"` to read, then - only when the key material is
absent - append the line via stdin with perms forced
(`mkdir -p`, `chmod 700 ~/.ssh`, `chmod 600 authorized_keys`).
Present is reported, not re-appended. Any ssh failure is exit 7;
nothing is appended on failure.
- **4.7** Both ssh calls run without an interactive terminal: the
target must be reachable with existing non-interactive
credentials (agent, passphrase-less key, or ControlMaster
socket). First contact to a brand-new server by password is out
of scope - gain access once manually, then send the key.
## 5. Exit codes
| Code | Meaning |
| --- | --- |
| 0 | success (initialize ready; send appended or already present) |
| 2 | package install failed (initialize) |
| 3 | gpg missing and no known package manager (initialize) |
| 4 | no OpenPGP card found (initialize) |
| 5 | public-key fetch did not pair the keyring (initialize) |
| 6 | keyring unpaired and the card carries no URL (initialize) |
| 7 | ssh to the target failed; nothing stored (send) |
| 8 | no source resolved a usable key (send) |
| 10 | proof-of-possession verification failed; nothing sent (send) |
## 6. Runner contract and injectability
- **6.1** Everything external goes through
`run_command(cmd, input_text="", env=None) -> (code,
stdout+stderr)`: env variables are merged over `os.environ`,
`input_text` is piped to stdin, a missing binary returns
`(127, "<cmd>: not found")`.
- **6.2** `initialize_yukikey(home, run_cmd)`,
`verify_possession(line, workdir, run_cmd)`,
`send_key(line, target, run_cmd)`, and the `source_*`
functions accept the runner; `source_url`,
`source_fingerprint`, and `cmd_send_pubkey` also accept a
`fetch(url) -> bytes | None`. Tests inject fakes; defaults are
`run_command` and `fetch_bytes` (urllib, 30 s timeout, None on
any fetch error).
- **6.3** ssh-keygen signature namespaces and identity are the
constants `daedalus-gpgtools` and `daedalus@verify`.
## 7. Files written
- **7.1** initialize: `<gnupg-home>/gpg-agent.conf` (merge per
item 3.6); the homedir permissions set to 700. Nothing else.
- **7.2** send: scratch dirs (throwaway GNUPGHOME, challenge
workspace) are created under the system temp dir and removed in
`finally`. The only persistent write is the target's
`authorized_keys` append via ssh (item 4.6).
## 8. Testing approach
- **8.1** Tests live in `python/tests/test_gpgtools.py` and never
need hardware, a network, or an interactive terminal (SPEC item
6.6): all flows take an injected runner; fetchers and runners
are fakes scripted per test by command prefix.
- **8.2** Covered groups: card-status parsing (present/absent,
no URL, no auth subkey, unpaired), config merge (empty,
preserving, complete), manager mapping and detection,
GNUPGHOME resolution, the initialize flow's success, failure,
warning, and persistence branches, the four sources including
the store chain and fingerprint mismatch, challenge
sign/verify success and refusal, send idempotence by material,
and the CLI wiring, guards, and dry runs.
- **8.3** The change order is spec item 6.12: this spec first,
then failing tests, then the smallest implementation.
## 9. References
- **9.1** The wiki guide behind items 1.1:
`~/repositories/vibe-wiki/wiki/queries/yubikey-ssh-guide.md`
(steps 1-13; automation notes in section 13).
- **9.2** Repository rules: SPEC items 6.6 (tests), 6.9
(argcomplete opt-in after the parser), 9.8 (version bump).
- **9.3** History: `CHANGELOG.md` entries 0.5.0 and 0.6.0.
+33
View File
@@ -0,0 +1,33 @@
# hello specification
Complete description of `python/src/hello/hello.py`. The sample
Python script of the template: it exercises the registry, the
`test` category, and the run_python_script entry end to end.
Items are cited as `hello spec item N.M`.
## 1. Purpose
- **1.1** Print one line, `hello from daedalus <version>`, and
exit 0. It takes no arguments of its own.
- **1.2** `<version>` comes from `app_version()`: the installed
daedalus metadata (`importlib.metadata.version("daedalus")`),
else the `version` field of the checkout's `pyproject.toml`
(resolved relative to the script file), else the literal
`unknown`.
## 2. Behavior
- **2.1** `daedalus hello` prints the line and exits 0;
`daedalus test hello` does the same through the category
prefix.
- **2.2** The parser opts in to argcomplete (SPEC item 6.9) with
a guarded import; without argcomplete nothing changes.
- **2.3** No files are read besides `pyproject.toml` in the
fallback; nothing is written.
## 3. Testing approach
- **3.1** `python/tests/test_hello.py` covers both version
resolutions (metadata and pyproject fallback, monkeypatched),
the printed line, `--help`, and end-to-end runs through the
CLI.