From 85e8342a74fa967a09d1278e88f245cabd15ce80 Mon Sep 17 00:00:00 2001 From: nvaldez Date: Thu, 19 Nov 2026 00:54:03 +0100 Subject: [PATCH] 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//spec.md, .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 --- CHANGELOG.md | 9 +- SPEC.md | 43 +++++++- bash/hello_bash.spec.md | 31 ++++++ python/src/gpgtools/spec.md | 197 ++++++++++++++++++++++++++++++++++++ python/src/hello/spec.md | 33 ++++++ 5 files changed, 308 insertions(+), 5 deletions(-) create mode 100644 bash/hello_bash.spec.md create mode 100644 python/src/gpgtools/spec.md create mode 100644 python/src/hello/spec.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e9020f..14aaddd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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, `.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 diff --git a/SPEC.md b/SPEC.md index 85ace25..237d455 100644 --- a/SPEC.md +++ b/SPEC.md @@ -77,13 +77,15 @@ daedalus/ │ ├── daedalus_logging/ # File + console logging (section 11) │ └── tests/ ├── python/ -│ ├── src// # Python scripts, one folder per script +│ ├── src// # Python scripts, one folder per script, +│ │ # holding .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 .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 .spec.md +├── batch/ # *.bat scripts (CRLF), each with .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//spec.md`. + - **6.11.2** A bash, PowerShell, or batch script's spec is a + sibling file named `.spec.md`: + `bash/.spec.md`, `powershell/.spec.md`, + `batch/.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 + ` 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: diff --git a/bash/hello_bash.spec.md b/bash/hello_bash.spec.md new file mode 100644 index 0000000..560c251 --- /dev/null +++ b/bash/hello_bash.spec.md @@ -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, (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. diff --git a/python/src/gpgtools/spec.md b/python/src/gpgtools/spec.md new file mode 100644 index 0000000..3a58ff7 --- /dev/null +++ b/python/src/gpgtools/spec.md @@ -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`. + + + +- [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) + + + +## 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 `, 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`), then keys.openpgp.org VKS + (`.../vks/v1/by-fingerprint/`), then keyserver.ubuntu.com + (`.../pks/lookup?op=get&search=0x`). 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-*) + [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`. 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, ": 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: `/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. diff --git a/python/src/hello/spec.md b/python/src/hello/spec.md new file mode 100644 index 0000000..300d372 --- /dev/null +++ b/python/src/hello/spec.md @@ -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 `, and + exit 0. It takes no arguments of its own. +- **1.2** `` 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.