From 7e49b62e0e30e88ceb8199511e9be3ddc0f8804a Mon Sep 17 00:00:00 2001 From: Steve Cliff Date: Sat, 2 May 2026 13:33:20 +0100 Subject: [PATCH] Add CLAUDE.md with project-specific rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three rules to date: * After every make build, restage the agent binary + install assets into /tmp/rm-smoke/data/ and replace the running agent on this dev box. Plain `make build` doesn't reach either, and forgetting has bitten the smoke env twice today (stale agent without mergeRestCreds; stale unit without User=root). * Migrations: prefer ALTER TABLE DROP/RENAME COLUMN (SQLite 3.35+) over the rebuild dance. With foreign_keys=ON in the DSN, DROP TABLE on a parent with ON DELETE CASCADE children wipes every dependent table — and PRAGMA foreign_keys=OFF inside a migration is a no-op (PRAGMA can only change outside a tx). * Don't slog restic's merged URL. The user:pass@-embedded form exists only inside envSlice() at exec time; if any URL needs to be operator-visible, route it through restic.RedactURL. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6ccb760 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# CLAUDE.md + +Project-specific rules for Claude when working in this repo. + +## After building a new binary, also stage it for the smoke env + +The smoke / dev environment runs the server out of `bin/` directly, +but the **agent** is fetched by the install script from the server's +`/agent-binaries/` directory, and the **systemd unit** + the +**install script** are fetched from `/install/`. Plain +`make build` doesn't touch any of those — the source-of-truth files +in the working tree (`deploy/install/*`, `bin/restic-manager-agent`) +must be copied into `/tmp/rm-smoke/data/...` *and* the running agent +on this dev host needs replacing if the change touches agent code or +the unit file. + +This has bitten the smoke env twice (stale agent without +`mergeRestCreds`; stale unit without `User=root` + capabilities). +Both produced confusing test failures that looked like bugs in the +new code but were actually "old binary still running." + +**Rule: after every `make build`, run the full restage block before +asking the operator to test.** + +```sh +# 1. Restage what the install script serves (binary + unit + script). +cp bin/restic-manager-agent \ + /tmp/rm-smoke/data/agent-binaries/restic-manager-agent-linux-amd64 +cp deploy/install/install.sh \ + /tmp/rm-smoke/data/install/install.sh +cp deploy/install/restic-manager-agent.service \ + /tmp/rm-smoke/data/install/restic-manager-agent.service + +# 2. Replace the running agent on this dev box and restart the +# service. Skip only when the change is server-side only AND +# doesn't include a unit-file edit. +sudo -n install -m 0755 bin/restic-manager-agent \ + /usr/local/bin/restic-manager-agent +sudo -n install -m 0644 deploy/install/restic-manager-agent.service \ + /etc/systemd/system/restic-manager-agent.service +sudo -n systemctl daemon-reload +sudo -n systemctl restart restic-manager-agent + +# 3. The server runs from the working tree; restart it manually +# after a build that touches server code: +pkill -f restic-manager-server +RM_LISTEN=:8080 RM_DATA_DIR=/tmp/rm-smoke/data \ +RM_BASE_URL=http://127.0.0.1:8080 \ +RM_SECRET_KEY_FILE=/tmp/rm-smoke/data/secret.key \ +RM_COOKIE_SECURE=false \ +./bin/restic-manager-server >> /tmp/rm-smoke/server.log 2>&1 & +``` + +A `make smoke-deploy` target that bundles all of this would be a +good follow-up. + +## Migrations: prefer column-level ALTERs over table rebuilds + +SQLite ≥ 3.35 supports `ALTER TABLE ... DROP COLUMN` and +`ALTER TABLE ... RENAME COLUMN`. Use them. The +"rename-old + create-new + copy + drop-old" pattern is unsafe in +this codebase because the connection DSN sets +`PRAGMA foreign_keys=ON`, and `DROP TABLE` on a parent with +`ON DELETE CASCADE` children **wipes every dependent table**. We +hit this in migration 0007 (first draft) and lost the entire +smoke env's schedules / jobs / snapshots / host_credentials. + +`PRAGMA foreign_keys = OFF` inside a migration is a no-op — that +PRAGMA can only change outside a transaction, and migrations run +in one. So the cascade-trap can't be defused that way; just avoid +the rebuild pattern when there are inbound FKs. + +If a column-level ALTER won't do what you need (e.g. tightening a +CHECK), use the safe rebuild order: **create new with a temp name +→ copy → DROP old → ALTER new RENAME TO old**. Never rename the +original first; that propagates the rename into dependent FKs and +leaves them dangling after the eventual drop. + +## Don't slog the merged rest-server URL + +`restic.Env.RepoURL` is bare (no creds). The `user:pass@`-embedded +form is built only inside `envSlice()` at the moment of +`exec.Command` and is fed straight to the subprocess. Never store +it on a struct field. Never pass it to `slog`. If a URL needs to +appear in any operator-readable surface, run it through +`restic.RedactURL()` first — that mirrors restic's own `***` +substitution.