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:
+8
-1
@@ -8,7 +8,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
|
|||||||
|
|
||||||
## [Unreleased]
|
## [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
|
## [0.6.0] - 2026-11-18
|
||||||
|
|
||||||
|
|||||||
@@ -77,13 +77,15 @@ daedalus/
|
|||||||
│ ├── daedalus_logging/ # File + console logging (section 11)
|
│ ├── daedalus_logging/ # File + console logging (section 11)
|
||||||
│ └── tests/
|
│ └── tests/
|
||||||
├── python/
|
├── 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
|
│ └── 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
|
│ ├── daedalus_common.sh # shared helper: daedalus_bash_dispatch, help() routing
|
||||||
│ └── tests/ # pytest tests that run them
|
│ └── tests/ # pytest tests that run them
|
||||||
├── powershell/ # *.ps1 scripts
|
├── powershell/ # *.ps1 scripts, each with <name>.spec.md
|
||||||
├── batch/ # *.bat scripts (CRLF)
|
├── batch/ # *.bat scripts (CRLF), each with <name>.spec.md
|
||||||
├── ci/ # sanity.py, checks.py, with tests
|
├── ci/ # sanity.py, checks.py, with tests
|
||||||
├── autotest.py # Runs every check (local and CI)
|
├── autotest.py # Runs every check (local and CI)
|
||||||
├── pyproject.toml # Package, version, entry point, package data
|
├── pyproject.toml # Package, version, entry point, package data
|
||||||
@@ -496,6 +498,39 @@ SCRIPTS: dict[str, Script] = {
|
|||||||
registered `.sh` script (source line, `help()`, `main()`, the
|
registered `.sh` script (source line, `help()`, `main()`, the
|
||||||
dispatch call) and tests the helper behavior directly.
|
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. Quality gates
|
||||||
|
|
||||||
- **7.1** `python autotest.py [CHECK...]` runs the named checks (default:
|
- **7.1** `python autotest.py [CHECK...]` runs the named checks (default:
|
||||||
|
|||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
@@ -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.
|
||||||
Reference in New Issue
Block a user