ops: make deploy should guard its own prerequisites (token + CLI version)

[BluegReeno]

Summary

make deploy failed twice on 2026-07-25 for reasons the Makefile could have caught itself, in
both cases after burning several minutes on a misleading error. Both are cheap to make
impossible. Documenting them (#79) helps whoever is already stuck; guarding them in the target
means nobody gets stuck.

Both guards belong to the same 14-line Makefile and the same deploy target, so they are one
issue and should be one PR — two PRs would collide on the same lines.

Guard 1 — missing token silently falls through to the wrong account

SUPABASE_ACCESS_TOKEN is loaded per-directory by direnv from .envrc. direnv does not fire
in a non-interactive shell, so any scripted or agent-driven make deploy runs with no token,
falls back to the personal account (SecondBrain org, no access to the project) and fails:

unexpected list functions status 403: Your account does not have the necessary privileges…

That message reads as a permissions problem with the account, not as a missing token — the
wrong diagnosis is the natural one.

Fix direction. Before deploying, if SUPABASE_ACCESS_TOKEN is unset and .envrc exists,
source it; if it is still unset, fail with a message naming the cause.

⚠️ Implementation trap: each line of a make recipe runs in its own sub-shell, so
source .envrc on one line and supabase functions deploy on the next will not share the
variable. Chain them in a single line (... && ...), or use .ONESHELL:. A fix that ignores
this will look right, pass review, and change nothing.

.envrc is gitignored and machine-specific, so the guard must degrade gracefully: an already-set
SUPABASE_ACCESS_TOKEN (CI, another machine) must be honoured and .envrc never required to
exist.

Guard 2 — an old CLI dies at bundling, after auth has already succeeded

supabase/functions/hal-mcp/deno.lock is lockfile version 5 (since c19bec9, June 2026).
CLI 2.72.7 cannot read it and aborts after a successful auth, which makes the failure look
unrelated to tooling:

Error: Failed reading lockfile at '.../deno.lock'
Caused by: Unsupported lockfile version '5'. Try upgrading Deno or recreating the lockfile

The CLI's own suggestion — "recreating the lockfile" — is the wrong move here: deno.lock
pins the exact dependency versions that ship to production. Regenerating it to silence the error
would change what gets deployed. Upgrading the CLI is the fix (2.72.7 → 2.109.1 worked).

Fix direction. Fail fast with a minimum-version check before invoking the deploy, printing
the required version and the brew upgrade supabase remedy. sort -V is enough for the
comparison; no need to be clever. Note that Homebrew now also refuses untrusted taps
(brew trust --formula supabase/tap/supabase) — worth naming in the error message.

Acceptance

• make deploy in a shell with no SUPABASE_ACCESS_TOKEN and no direnv either succeeds by
  sourcing .envrc, or fails naming the missing token — never a bare 403.
• An already-exported SUPABASE_ACCESS_TOKEN is used as-is; a missing .envrc is not an error
  when the token is already set.
• make deploy with a CLI below the minimum stops before bundling, with a message naming the
  required version and the upgrade command.
• Verified negatively for both guards: run with the token unset, and with an old CLI (or a
  temporarily raised minimum), and confirm each stops with its own message.
• docs/operations.md §2 updated so the prose and the guards do not disagree — see docs(operations): deploy prerequisites learned the hard way #79, which
  documents these same two obstacles and should be reconciled, not duplicated.

Related

• docs(operations): deploy prerequisites learned the hard way #79 — documents both obstacles in operations.md (the diagnostic half of the same problem)
• ci: hal-mcp unit tests never run — CI only type-checks #78 — the third obstacle of that deploy: CI never runs the hal-mcp unit tests

[BluegReeno]

✅ Issue Resolution Report

PR: #81 (#81) — open, draft, mergeable
Status: COMPLETE

---

Summary

make deploy's recipe is now a single logical shell invocation (\-continuation, not .ONESHELL:) that guards both prerequisites this issue asked for — CLI version and SUPABASE_ACCESS_TOKEN — before ever calling supabase functions deploy. .ONESHELL: was deliberately avoided: it would have silently changed test's two independent cd lines to shared-shell semantics. docs/operations.md §2 (from #79) was reconciled with the new guards rather than duplicated.

---

Changes Made

File	Change
Makefile	New MIN_SUPABASE_CLI := 2.109.1; deploy rewritten as one guarded shell invocation: CLI-version check (sort -V) → token check (source .envrc only if unset+present) → unchanged deploy call. verify/test untouched, deno.lock untouched.
docs/operations.md	§2 prose reconciled: manual .envrc-sourcing snippet scoped to Path B only; Path A now documents the automatic guard.
CLAUDE.md	Post-review self-fix: deploy summary bullet now describes the automatic guards instead of implying manual sourcing is still required.

---

Validation

✅ Type check (deno check, both edge functions) | ✅ Lint (ruff check) | ✅ Tests (157 passed, make test)

All three constraints from the issue verified live, not just read:

• already-exported SUPABASE_ACCESS_TOKEN → honoured as-is, .envrc never sourced
• missing .envrc + unset token → named error, exit 1, never a bare 403
• missing token + present .envrc → sourced in the same shell, deploy proceeds
• CLI below MIN_SUPABASE_CLI → named error + brew remedy, no deploy attempt (tested via make -e MIN_SUPABASE_CLI=99.0.0 deploy, no file edit needed)
• deno.lock confirmed untouched throughout

---

Review & Self-Fix

• 1 review finding addressed (MEDIUM — CLAUDE.md deploy summary was contradicting the shipped behavior)
• 1 doc updated (CLAUDE.md)
• 0 tests added — Makefile/docs-only change has no unit-test surface; verified instead via live guard execution (documented above and in the PR)

---

Unaddressed Items

Finding	Severity	Reason
README.md deploy bullet (L279, L303) slightly stale on auth-fallback nuance	LOW	Explicitly marked optional by review — still technically true, not contradictory

---

Suggested Follow-up Issues

No follow-up issues needed.

---

Resolved by Archon workflow d26b6e4648951267cb1817971f733286