restic-manager/CLAUDE.md

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 <DataDir>/agent-binaries/ directory, and the systemd unit + the install script are fetched from <DataDir>/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.

# 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.