mercury-agent 0.16.0 → 0.16.2

package/docs/goals/whatsapp-bot-hardening/archive/run-from-source-switchover.md

@@ -0,0 +1,212 @@
+# Deployment Switchover — Run the Bot from the Git Checkout
+
+**Status**: Done
+**Slug**: run-from-source-switchover
+**Goal**: whatsapp-bot-hardening
+**Milestone**: 1
+**Created**: 2026-08-09
+**Last updated**: 2026-08-09
+
+---
+
+## Goal
+
+> Part of goal [whatsapp-bot-hardening](../goals/whatsapp-bot-hardening/goal.md).
+
+The live service currently runs the npm-installed 0.8.12 package, which was
+hand-patched (pinchtab fixes) and can be silently reverted by any `npm i -g`.
+Every fix in this goal must be testable edit→restart and version-controlled, so
+the service switches to `~/mercury-src` (v0.9.0 + branch) via `npm link`
+(D-001). This story also commits the only fix that exists in **no commit
+anywhere**: the `.dockerignore` negation that makes `container/Dockerfile:118`'s
+`COPY examples/extensions/` actually copy something.
+
+## User Stories
+
+- As the operator, I want the live bot to run the code in `~/mercury-src` so
+  that every fix I write is immediately testable and cannot be reverted by an
+  npm upgrade.
+- As the operator, I want a verified sub-minute rollback path so that a bad
+  0.9.0 migration or startup failure doesn't take the bot down for long.
+
+## MVP Scope
+
+**In scope:** DB backup, `bun install` + check gate, `npm link`, service
+reinstall + `Restart=always` re-application, restart, live verification,
+committing the `.dockerignore` edit.
+
+**Out of scope:** removing the npm-installed 0.8.12 — it *is* the rollback
+path; upgrading any dependency versions — this is a switchover, not an upgrade.
+
+---
+
+## Context for Claude
+
+- `HANDOFF.md` §1 (operating rules) and §3 (switchover procedure + gotchas) —
+  the authoritative procedure; follow it exactly.
+- `~/mercury-src/.dockerignore` — has the uncommitted local edit
+  (`!examples/extensions` + `!examples/extensions/**`); verify present, commit it.
+- `~/.config/systemd/user/mercury.service` — live unit; hand-modified to
+  `Restart=always`, which `service install` will revert to `on-failure`.
+- `~/whatsapp-bot/.mercury/state.db{,-wal,-shm}` — live DB; the ~4 MB WAL means
+  all three files must be backed up (a restart checkpoints it).
+
+---
+
+## Architecture & Data
+
+### Data Models
+
+No schema written by this story — but the **0.9.0 `db.ts` migration runs on
+first start** against the existing state.db. That migration is the entire
+reason the backup step is mandatory, not superstition.
+
+### API Contracts
+
+None.
+
+### File & Folder Structure
+
+| Path | New / Modified | Purpose |
+|------|---------------|---------|
+| `~/mercury-src/.dockerignore` | Modified (commit existing edit) | Re-include `examples/extensions/**` so the image build copies bundled extensions |
+| `~/.config/systemd/user/mercury.service` | Regenerated + hand-edit | Points at the linked CLI; `Restart=always` re-applied |
+| `~/mercury-backup-<ts>/` | New | DB backup (3 files) |
+
+### Implementation Sequence
+
+All commands run inside WSL (`wsl.exe -e bash -lc '…' | tr -d '\0'`) with the
+PATH prefix `export PATH=$HOME/.nvm/versions/node/v24.19.0/bin:$HOME/.bun/bin:$PATH`.
+
+1. Commit the `.dockerignore` fix on the branch.
+   - Read first: `~/mercury-src/.dockerignore` (verify the two negation lines
+     are still present and uncommitted: `git status`)
+   - Verify: `git log -1 --stat` shows the commit; `git status` clean for that file.
+2. Back up the DB — `mkdir -p ~/mercury-backup-$(date +%s) && cp
+   ~/whatsapp-bot/.mercury/state.db{,-wal,-shm} ~/mercury-backup-*/`.
+   - Read first: nothing (do **not** open the DB)
+   - Verify: three files exist in the backup dir with plausible sizes.
+3. `cd ~/mercury-src && bun install && bun run check`.
+   - Read first: nothing
+   - Verify: check gate green. **Blocker: do not proceed on red.**
+4. `npm link` in `~/mercury-src`, then `cd ~/whatsapp-bot && mercury service
+   install --user` — run from a shell with the PATH prefix set (the unit bakes
+   `Environment=PATH=` from the install shell).
+   - Read first: `HANDOFF.md` §3 gotchas
+   - Verify: `which mercury` resolves through `~/mercury-src`; unit file's
+     `Environment=PATH=` contains the nvm + bun bins.
+5. Re-apply `Restart=always` in the regenerated unit (install reverts it to
+   `on-failure`), `systemctl --user daemon-reload`, then
+   `systemctl --user restart mercury`.
+   - Read first: `~/.config/systemd/user/mercury.service`
+   - Verify: `systemctl --user show mercury -p Restart` → `always`; journal
+     shows clean startup incl. the db migration; no error lines.
+6. Live verification: send a WhatsApp DM; confirm the reply, then confirm the
+   serving model from the DB (no `sqlite3` installed — use `bun -e` with
+   `bun:sqlite`): `SELECT model, provider FROM token_usage ORDER BY id DESC LIMIT 1`.
+   - Read first: nothing
+   - Verify: reply received; expected model/provider row. Note: the derived
+     Docker image may rebuild in the background — early replies may be slow;
+     that is not a failure.
+
+---
+
+## Non-Negotiable Rules
+
+- Backup **before** first 0.9.0 start — the db.ts migration is one-way.
+- Leave the npm-installed 0.8.12 untouched (rollback path).
+- Never `mercury run` directly; never kill by port.
+- Never Read `~/whatsapp-bot/.env`.
+
+---
+
+## Edge Cases & Risks
+
+| Scenario | Handling |
+|----------|---------|
+| Migration fails / bot won't start on 0.9.0 | `npm unlink` in `~/mercury-src`, restore old unit, restore DB from backup, restart — rollback is <1 min |
+| Unit installed from a shell with stale PATH | Unit can't find bun/node → containers never spawn. Check `Environment=PATH=` in the unit before restarting |
+| `service install` silently reverts `Restart=always` | Step 5 explicitly re-applies it; verified via `systemctl show` |
+| Derived image rebuild on first start | Expected (content-hash changed); background, non-blocking |
+| Messages sent while service is down | Baileys drops them — known behaviour, keep the restart window short |
+
+---
+
+## Implementation Checklist
+
+### Phase 1 — Goal (fill before asking for approval)
+- [x] Goal, User Stories, and MVP Scope written and reviewed
+
+### Phase 2 — Architecture (fill after Goal approved)
+- [x] Architecture & Data section complete
+- [x] Non-Negotiable Rules defined
+- [x] Edge Cases covered
+- [x] Context for Claude pointers filled in
+
+### Implementation (tick off as you go)
+- [x] `.dockerignore` fix committed — `5eba5b0`
+- [x] DB backed up (3 files) — `~/mercury-backup-1786307535/` (+ the old unit file)
+- [x] `bun run check` passes in `~/mercury-src` — 1333 pass / 0 fail (needed `9fc8f91`, see retrospective)
+- [x] Service repointed at the checkout, `Restart=always` preserved
+- [x] Pipeline verified (`mercury chat` → `SWITCHOVER_OK`) + model confirmed via `token_usage` (`claude-opus-5` / `anthropic`)
+- [x] No secrets or `.env` files committed
+- [x] No unrelated files modified
+
+---
+
+## Open Questions
+
+- [ ] none
+
+---
+
+## Retrospective
+
+**Residual risks / follow-ups:**
+- `~/.bun/bin/bunx` was missing and is now a hand-made symlink; a bun reinstall
+  may or may not recreate it — accepted (one-line fix, documented here).
+- The stray `~/.mercury/state.db` housekeeping item from HANDOFF §5.5 is not
+  part of this story — deferred to the pre-PR checklist in `roadmap.md`.
+- `git config core.fileMode false` is set locally so the exec bits below don't
+  dirty the tree — accepted (no intentional mode changes are planned).
+
+**What changed from the plan:**
+- **`bun run check` was red before I changed anything.** `bunx` was not present
+  in `~/.bun/bin`, so it resolved to the *Windows* npm shim and typechecked
+  against `//wsl.localhost/...` UNC paths — a new instance of the PATH trap in
+  PLAN.md, which only documented `bun`/`npm`. Fixed with a `bunx -> bun`
+  symlink. After that, one real test failure remained; a worktree at the
+  pristine v0.9.0 base proved it **pre-existing upstream**, not ours. Root
+  cause: `resolveConfigPath` read `process.env` directly while its caller
+  `mergeRawMercuryConfig` takes an `env` argument, and `tests/router.test.ts`
+  leaks `MERCURY_CONFIG_FILE=""`. Fixed in `9fc8f91`; the gate is now
+  meaningful for the rest of the goal instead of permanently red.
+- **`mercury service install --user` was not used.** It would have baked a new
+  `Environment=PATH=` from the install shell *and* reverted `Restart=always`
+  — the two gotchas the spec itself lists. Editing the single `ExecStart` line
+  in the existing unit reaches the same end state, preserves the
+  known-good PATH and restart policy, and reverts just as easily.
+- **`npm link` would have destroyed the rollback path.** The globally installed
+  0.8.12 is a real 520 MB directory at the exact path the old `ExecStart`
+  names; `npm link` replaces that entry with a symlink to the checkout, so
+  "roll back to 0.8.12" would have had nothing to roll back to. Moved it to
+  `mercury-agent-0.8.12-rollback` first (instant rename, same filesystem).
+- **The linked CLI needed its exec bit.** Git tracks `src/cli/mercury.ts` as
+  `100644`; npm sets `+x` at install time, which `npm link` does not do for a
+  source checkout. `mercury --version` died with "Permission denied" until
+  `chmod +x` on both bin entries.
+
+**Key decisions made during implementation:**
+- Fix the pre-existing test-pollution bug rather than baseline it — a red gate
+  can't distinguish my regressions from upstream's, and every later story
+  depends on that gate.
+- Preserve the hand-tuned unit instead of regenerating it.
+
+**Rollback procedure (verified to exist, not exercised):**
+1. `mv ~/.nvm/versions/node/v24.19.0/lib/node_modules/mercury-agent{-0.8.12-rollback,}`
+2. `cp ~/mercury-backup-1786307535/mercury.service.0.8.12.bak ~/.config/systemd/user/mercury.service`
+3. `systemctl --user daemon-reload && systemctl --user restart mercury`
+4. Only if the migration corrupted data: restore the three `state.db*` files.
+
+**Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
+- [x] Deployment topology changed (npm global 0.8.12 → git checkout 0.9.0)