300 lines
14 KiB
Markdown
300 lines
14 KiB
Markdown
# EGB-713: Version-skew nudge Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:executing-plans / subagent-driven-development. Steps use `- [ ]`.
|
|
|
|
**Goal:** Warn (non-fatally) when the active store was last written by a newer `secrets` version than the running client, so a behind user is told to update — the loud counterpart to EGB-712's quiet forcing function.
|
|
|
|
**Architecture:** Stamp the store with the highest writer `VERSION` seen (`$SECRETS_DIR/.secrets-writer-version`, committed, monotonic) on every store-committing write. On any store command, compare that stamp to the client's own `VERSION` (read from `$SCRIPT_DIR/VERSION`); if the stamp is newer, print a one-time stderr nudge. Legacy stores with no stamp are silent.
|
|
|
|
**Tech Stack:** bash 3.2 (`secrets`); bats. Spec/idea: ticket **EGB-713**.
|
|
|
|
## Background (verified against `main`, post-EGB-712)
|
|
- `SCRIPT_DIR` already defined at `secrets:21` (`$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)`). The repo-root `VERSION` file lives next to the script.
|
|
- Store-committing write sites (each does `git -C "$SECRETS_DIR" add -A`): `commit_and_push_secrets()` `secrets:1265` (push), rekey `secrets:1822`, migrate copy-forward `secrets:2215`, finalize no-v1 `secrets:2305`, finalize drop `secrets:2340`. Plus `cmd_init` (born store) and `cmd_rm`.
|
|
- `ensure_store_protections()` (`secrets:1144`) is shared with pull (read) — do NOT stamp there.
|
|
- `check_initialized()` (`secrets:54`) early-returns when `$SECRETS_DIR/.git` exists and is called by push/pull/list/rm/rekey/verify/migrate — the natural warning hook.
|
|
- `cmd_which()` (`secrets:1945`) prints `format: v$(_store_format)` — add the writer-version line here.
|
|
- `.gitignore` only ignores `key.txt`, so `.secrets-writer-version` commits normally.
|
|
- VERSION currently `0.7.0.0` → bump to `0.7.1.0`.
|
|
- Baseline: `bats test/` = 246 passing. New tests land in a new file `test/version.bats`.
|
|
|
|
---
|
|
|
|
## Task 1: Version helpers + comparator (TDD)
|
|
|
|
**Files:** `secrets`, `test/version.bats` (new).
|
|
|
|
- [ ] Step 1: Create `test/version.bats` testing the comparator via a tiny harness that sources the script's functions is awkward (the script runs main). Instead test through observable behavior in later tasks; for the comparator, add a hidden debug subcommand is overkill. Use this approach: test `_version_gt` indirectly by exporting it is not possible. So test the comparator by adding the helpers and a **`secrets __vercmp <a> <b>`** internal is overkill too. Decision: test the comparator's *effect* in Task 3 (warning) and Task 2 (stamp monotonicity), which exercise it end-to-end. For Task 1, write the helpers and verify with a one-off `bash -c` sourcing guard.
|
|
|
|
Add to `test/version.bats`:
|
|
```bash
|
|
load test_helper
|
|
|
|
# Exercises the comparator through a bash subshell that defines the same logic
|
|
# the script uses, guarding the numeric (not lexical) ordering contract.
|
|
@test "version comparator orders 0.7.0.0 < 0.10.0.0 numerically" {
|
|
run bash -c '
|
|
_version_gt() {
|
|
local a="$1" b="$2" i ai bi; local -a af bf
|
|
IFS=. read -r -a af <<< "$a"; IFS=. read -r -a bf <<< "$b"
|
|
for i in 0 1 2 3; do
|
|
ai=${af[$i]:-0}; ai=${ai//[!0-9]/}; [ -n "$ai" ] || ai=0
|
|
bi=${bf[$i]:-0}; bi=${bi//[!0-9]/}; [ -n "$bi" ] || bi=0
|
|
if [ "$((10#$ai))" -gt "$((10#$bi))" ]; then return 0; fi
|
|
if [ "$((10#$ai))" -lt "$((10#$bi))" ]; then return 1; fi
|
|
done; return 1
|
|
}
|
|
_version_gt 0.10.0.0 0.7.0.0 && echo "10gt7"
|
|
_version_gt 0.7.0.0 0.10.0.0 || echo "7not_gt_10"
|
|
_version_gt 0.7.0.0 0.7.0.0 || echo "equal_not_gt"
|
|
'
|
|
[ "$status" -eq 0 ]
|
|
[[ "$output" == *"10gt7"* ]] || false
|
|
[[ "$output" == *"7not_gt_10"* ]] || false
|
|
[[ "$output" == *"equal_not_gt"* ]] || false
|
|
}
|
|
```
|
|
|
|
- [ ] Step 2: Run `bats test/version.bats` → PASS (pins the contract the script must match).
|
|
|
|
- [ ] Step 3: Add the helpers to `secrets` (near `_store_format`, after `SCRIPT_DIR`/version constants — place after the `MANIFEST_VERSION=2` area or near `_store_format`):
|
|
```bash
|
|
# The running client's own version, read from the VERSION file shipped beside
|
|
# the script. Empty/"0.0.0.0" if absent (e.g. an odd install) — treated as
|
|
# "unknown/oldest" so a missing VERSION never triggers a spurious nudge.
|
|
_client_version() {
|
|
local v=""
|
|
[ -f "$SCRIPT_DIR/VERSION" ] && v=$(head -1 "$SCRIPT_DIR/VERSION" 2>/dev/null | tr -d '\r\n[:space:]')
|
|
printf '%s' "${v:-0.0.0.0}"
|
|
}
|
|
|
|
# Numeric four-field (MAJOR.MINOR.PATCH.MICRO) compare. Returns 0 iff $1 > $2.
|
|
# Per-field numeric (so 0.10.0.0 > 0.7.0.0); missing/garbage fields → 0.
|
|
_version_gt() {
|
|
local a="$1" b="$2" i ai bi; local -a af bf
|
|
IFS=. read -r -a af <<< "$a"; IFS=. read -r -a bf <<< "$b"
|
|
for i in 0 1 2 3; do
|
|
ai=${af[$i]:-0}; ai=${ai//[!0-9]/}; [ -n "$ai" ] || ai=0
|
|
bi=${bf[$i]:-0}; bi=${bi//[!0-9]/}; [ -n "$bi" ] || bi=0
|
|
if [ "$((10#$ai))" -gt "$((10#$bi))" ]; then return 0; fi
|
|
if [ "$((10#$ai))" -lt "$((10#$bi))" ]; then return 1; fi
|
|
done
|
|
return 1
|
|
}
|
|
|
|
WRITER_VERSION_FILE_NAME=".secrets-writer-version"
|
|
# Highest client version recorded as having written to the store (empty if the
|
|
# store predates this feature — "minus the initial builds", silent by design).
|
|
_store_writer_version() {
|
|
local f="$SECRETS_DIR/$WRITER_VERSION_FILE_NAME"
|
|
[ -f "$f" ] && head -1 "$f" 2>/dev/null | tr -d '\r\n[:space:]'
|
|
}
|
|
```
|
|
|
|
- [ ] Step 4: `bash -n secrets` parses; `bats test/` still 246 + 1 (the comparator test) = 247.
|
|
- [ ] Step 5: Commit: `git add secrets test/version.bats && git commit -m "feat: version helpers + numeric comparator (EGB-713)"`
|
|
|
|
---
|
|
|
|
## Task 2: Stamp the writer-version on write (TDD)
|
|
|
|
**Files:** `secrets`, `test/version.bats`.
|
|
|
|
- [ ] Step 1: Add tests:
|
|
```bash
|
|
@test "push stamps the store writer-version with the client version" {
|
|
init_with_remote
|
|
create_project_dir wvstamp
|
|
"$SECRETS_BIN" push wvstamp >/dev/null 2>&1
|
|
[ -f "$SECRETS_DIR/.secrets-writer-version" ]
|
|
run cat "$SECRETS_DIR/.secrets-writer-version"
|
|
[ "$output" = "$(cat "$(dirname "$SECRETS_BIN")/VERSION")" ]
|
|
}
|
|
|
|
@test "writer-version stamp is monotonic (a push never lowers a higher stamp)" {
|
|
init_with_remote
|
|
create_project_dir wvmono
|
|
printf '9.9.9.9\n' > "$SECRETS_DIR/.secrets-writer-version"
|
|
"$SECRETS_BIN" push wvmono >/dev/null 2>&1
|
|
run cat "$SECRETS_DIR/.secrets-writer-version"
|
|
[ "$output" = "9.9.9.9" ] # not lowered to the client's version
|
|
}
|
|
|
|
@test "writer-version stamp is committed, not gitignored" {
|
|
init_with_remote
|
|
create_project_dir wvcommit
|
|
"$SECRETS_BIN" push wvcommit >/dev/null 2>&1
|
|
run bash -c "git -C $SECRETS_DIR ls-files | grep -qx .secrets-writer-version"
|
|
[ "$status" -eq 0 ]
|
|
}
|
|
```
|
|
|
|
- [ ] Step 2: Run `bats test/version.bats -f "stamp"` → FAIL (no stamping yet).
|
|
|
|
- [ ] Step 3: Add the stamp helper (after `_store_writer_version`):
|
|
```bash
|
|
# Raise the store's recorded writer-version to the client's version (monotonic;
|
|
# never lowers it). Called right before each store-committing `git add -A` so
|
|
# the stamp rides the same commit. Read paths (pull) never call this.
|
|
_stamp_writer_version() {
|
|
local cur cli
|
|
cur=$(_store_writer_version)
|
|
cli=$(_client_version)
|
|
if [ -z "$cur" ] || _version_gt "$cli" "$cur"; then
|
|
printf '%s\n' "$cli" > "$SECRETS_DIR/$WRITER_VERSION_FILE_NAME"
|
|
fi
|
|
}
|
|
```
|
|
|
|
- [ ] Step 4: Call `_stamp_writer_version` immediately before each store-committing `git -C "$SECRETS_DIR" add -A`:
|
|
- `secrets:1265` (in `commit_and_push_secrets`, before `git add -A`)
|
|
- `secrets:1822` (rekey)
|
|
- `secrets:2215` (migrate copy-forward)
|
|
- `secrets:2305` (finalize, no-v1 path)
|
|
- `secrets:2340` (finalize, drop path)
|
|
Also in `cmd_init`, after the store repo is created and before its first commit (so a born store records its version), and in `cmd_rm` before its commit.
|
|
Each insertion is the single line ` _stamp_writer_version` at the matching indentation directly above the `git ... add -A` (or before the `git ... commit` where there's no add -A, e.g. rm/init — there, stamp then ensure it's staged via the existing add/commit).
|
|
|
|
- [ ] Step 5: `bats test/version.bats` → all pass. `bats test/` → 250 (247 + 3).
|
|
- [ ] Step 6: Commit: `git add secrets test/version.bats && git commit -m "feat: stamp store writer-version on write, monotonic (EGB-713)"`
|
|
|
|
---
|
|
|
|
## Task 3: Skew warning on command (TDD)
|
|
|
|
**Files:** `secrets`, `test/version.bats`.
|
|
|
|
- [ ] Step 1: Add tests:
|
|
```bash
|
|
@test "a store written by a newer version warns on a command (non-fatal)" {
|
|
init_with_remote
|
|
create_project_dir skewwarn
|
|
"$SECRETS_BIN" push skewwarn >/dev/null 2>&1
|
|
printf '99.0.0.0\n' > "$SECRETS_DIR/.secrets-writer-version"
|
|
run "$SECRETS_BIN" list
|
|
[ "$status" -eq 0 ] # non-fatal
|
|
[[ "$output" == *"newer"* || "$output" == *"update"* ]] || false
|
|
}
|
|
|
|
@test "a store at the same/older version is silent" {
|
|
init_with_remote
|
|
create_project_dir noskew
|
|
"$SECRETS_BIN" push noskew >/dev/null 2>&1 # stamp == client version
|
|
run "$SECRETS_BIN" list
|
|
[ "$status" -eq 0 ]
|
|
[[ "$output" != *"update your secrets"* ]] || false
|
|
}
|
|
|
|
@test "a store with no writer-version marker is silent (legacy store)" {
|
|
init_with_remote
|
|
create_project_dir legacynostamp
|
|
"$SECRETS_BIN" push legacynostamp >/dev/null 2>&1
|
|
rm -f "$SECRETS_DIR/.secrets-writer-version"
|
|
run "$SECRETS_BIN" list
|
|
[ "$status" -eq 0 ]
|
|
[[ "$output" != *"update your secrets"* ]] || false
|
|
}
|
|
```
|
|
|
|
- [ ] Step 2: Run `bats test/version.bats -f "skew\|silent\|legacy"` → the "newer" test FAILS (no warning yet).
|
|
|
|
- [ ] Step 3: Add the skew check (after `_stamp_writer_version`):
|
|
```bash
|
|
# Warn ONCE per invocation if the store was last written by a newer client than
|
|
# us. Non-fatal (read/write paths keep their exit codes). Silent when the store
|
|
# carries no writer-version (legacy) or is same/older than us.
|
|
_VERSION_SKEW_WARNED=0
|
|
_check_store_version_skew() {
|
|
[ "$_VERSION_SKEW_WARNED" = 1 ] && return 0
|
|
local sv cv
|
|
sv=$(_store_writer_version)
|
|
[ -n "$sv" ] || return 0
|
|
cv=$(_client_version)
|
|
if _version_gt "$sv" "$cv"; then
|
|
_VERSION_SKEW_WARNED=1
|
|
echo "NOTE: this store was last written by secrets v$sv; you're on v$cv." >&2
|
|
echo " Update your secrets tool: git -C \"$SCRIPT_DIR\" pull" >&2
|
|
fi
|
|
return 0
|
|
}
|
|
```
|
|
|
|
- [ ] Step 4: Hook it into `check_initialized` — change `secrets:55-57`:
|
|
```bash
|
|
if [ -d "$SECRETS_DIR/.git" ]; then
|
|
return
|
|
fi
|
|
```
|
|
to:
|
|
```bash
|
|
if [ -d "$SECRETS_DIR/.git" ]; then
|
|
_check_store_version_skew
|
|
return
|
|
fi
|
|
```
|
|
|
|
- [ ] Step 5: `bats test/version.bats` → all pass. `bats test/` → 253.
|
|
- [ ] Step 6: Commit: `git add secrets test/version.bats && git commit -m "feat: warn on store version skew (once per invocation, EGB-713)"`
|
|
|
|
---
|
|
|
|
## Task 4: `secrets which` surfaces the writer-version (TDD)
|
|
|
|
**Files:** `secrets`, `test/version.bats`.
|
|
|
|
- [ ] Step 1: Add test:
|
|
```bash
|
|
@test "which prints the store writer-version and a behind note" {
|
|
init_with_remote
|
|
create_project_dir whichwv
|
|
"$SECRETS_BIN" push whichwv >/dev/null 2>&1
|
|
printf '99.0.0.0\n' > "$SECRETS_DIR/.secrets-writer-version"
|
|
run "$SECRETS_BIN" which
|
|
[ "$status" -eq 0 ]
|
|
[[ "$output" == *"written-by: v99.0.0.0"* ]] || false
|
|
[[ "$output" == *"behind"* || "$output" == *"update"* ]] || false
|
|
}
|
|
```
|
|
|
|
- [ ] Step 2: Run → FAIL (which doesn't print written-by).
|
|
|
|
- [ ] Step 3: In `cmd_which`, after the `echo "format: v$(_store_format)"` line (`secrets:1951`), add:
|
|
```bash
|
|
local _wv; _wv=$(_store_writer_version)
|
|
if [ -n "$_wv" ]; then
|
|
local _cv; _cv=$(_client_version)
|
|
if _version_gt "$_wv" "$_cv"; then
|
|
echo "written-by: v$_wv (you're on v$_cv — behind; run: git -C \"$SCRIPT_DIR\" pull)"
|
|
else
|
|
echo "written-by: v$_wv"
|
|
fi
|
|
fi
|
|
```
|
|
Note: `cmd_which` calls `resolve_store` but may not call `check_initialized`, so this also avoids double-printing the skew NOTE; the `which` line is the dedicated surface.
|
|
|
|
- [ ] Step 4: `bats test/version.bats` → pass. `bats test/` → 254.
|
|
- [ ] Step 5: Commit: `git add secrets test/version.bats && git commit -m "feat: secrets which shows store writer-version + behind note (EGB-713)"`
|
|
|
|
---
|
|
|
|
## Task 5: Docs + version bump
|
|
|
|
**Files:** `secrets` (cmd_help unchanged unless adding a note), `CLAUDE.md`, `README.md`, `VERSION`, `CHANGELOG.md`.
|
|
|
|
- [ ] Step 1: `CLAUDE.md` — add to the "Store format" bullet a sentence on the writer-version: a committed `.secrets-writer-version` records the highest client `VERSION` that has written (monotonic, stamped on store-committing writes); commands warn once (stderr, non-fatal) when the store's stamp exceeds the running client, and `secrets which` shows `written-by: vN`. Legacy stores (no marker) are silent. (EGB-713.)
|
|
- [ ] Step 2: `README.md` — under the upgrading section, note that an out-of-date `secrets` prints a one-line "update" nudge when it touches a store newer than itself.
|
|
- [ ] Step 3: `VERSION` → `0.7.1.0`.
|
|
- [ ] Step 4: `CHANGELOG.md` — new `## [0.7.1.0] - 2026-06-08` with an Added entry for the version-skew nudge + `secrets which` writer-version line.
|
|
- [ ] Step 5: `bats test/` → all green (254). `./secrets which` against a scratch store renders (covered by tests).
|
|
- [ ] Step 6: Commit: `git add secrets CLAUDE.md README.md VERSION CHANGELOG.md && git commit -m "docs: version-skew nudge + writer-version; bump 0.7.1.0 (EGB-713)"`
|
|
|
|
---
|
|
|
|
## Self-review vs ticket AC
|
|
- "Newer stamp → nudge; same/older → silent" → Task 3.
|
|
- "No marker → silent (legacy)" → Task 3 + `_store_writer_version` empty.
|
|
- "Monotonic, committed" → Task 2.
|
|
- "Numeric comparator (0.7.0.0 < 0.10.0.0)" → Task 1.
|
|
- "Non-fatal, never changes read/pull exit codes" → Task 3 (`_check_store_version_skew` always `return 0`).
|
|
- "`which` surfaces it" → Task 4. "Warn once per invocation" → `_VERSION_SKEW_WARNED` guard.
|
|
- bash 3.2: `read -a`, `local -a`, `10#`, parameter strips — all 3.2-safe.
|