feat(ops): add a read-only backend drift check by Programcode · Pull Request #79 · Programcode/DebateOwl

Programcode · 2026-10-01T08:52:03Z

What

npm run backend:status shows what the current commit has that a Supabase project lacks. Vercel ships the frontend on merge, but migrations and Edge Functions are deployed by hand. On 2026-09-30 production lacked two migrations and ran pre-#75 functions, and nothing in the repo would have shown it.

It runs supabase migration list and supabase functions list, nothing else, and compares their output with the tree committed at HEAD. It reports:

migrations on the commit that are not applied, and applied migrations the commit lacks;
functions that are not deployed;
functions deployed before the last first-parent commit that touched them or any file they import (following relative imports into _shared/);
deployed verify_jwt that differs from supabase/config.toml;
deployed functions the commit does not have.

Flags: --project-ref <ref> targets another project (the staging work in plan item 8 uses this), and --check exits 1 when a migration is not applied. Exit 2 means the check itself failed. CLI errors are shown with connection-string passwords redacted.

docs/operations.md gains a "Backend drift check" section and makes the command step 1 of every backend deploy. supabase/README.md and AGENTS.md point to it.

Not done: the prod-canary step

I did not add a prod-canary.yml step. --check is ready for one, but it would need a Supabase access token and database access in Actions, which is a production credential. That's Adam's decision.

Evidence

New src/test/scripts/backend-status.test.ts (5 tests) builds a throwaway git repo with dated commits and a fake supabase binary. It checks the report, that only the two list commands are called (with --linked by default, --project-ref when given), the --check exit codes, argument rejection and redaction. Flipping the staleness comparison makes it fail.
Local: npm run docs:check, npm run lint, npm run typecheck and npm test -- --coverage (110 files, 1112 tests) all pass.
Live, read-only, against production at fe6100a: 38 of 38 migrations applied, 12 of 13 functions deployed. The missing one is workspace-invites, which is expected because Collaborative Workspace is hidden.
Live, read-only, against staging: migrations current, but stripe-webhook was deployed 2026-05-20 and changed on main on 2026-08-21 (12951b6). Staging's webhook is stale. I have not redeployed it.

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- Added a read-only backend status check that compares the linked Supabase project with the current commit and reports migration, function, and configuration differences.
- Check mode returns distinct exit codes for pending migrations and operational errors.
Documentation
- Updated deployment guidance to check backend status before deployment and rerun the check afterward.
- Added guidance to use the status check when investigating frontend errors involving Supabase.

Vercel ships the frontend on merge, but migrations and Edge Functions are deployed by hand, and nothing in the repo showed when production fell behind. On 2026-09-30 it lacked two migrations and ran pre-#75 functions. `npm run backend:status` runs `supabase migration list` and `supabase functions list` and compares them with the migrations and function folders committed at HEAD. It reports unapplied migrations, undeployed functions, functions deployed before the last commit that touched them or a file they import, and verify_jwt drift from config.toml. `--project-ref <ref>` targets another project, and `--check` exits 1 when a migration is not applied. docs/operations.md makes it the first step of every backend deploy. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

vercel · 2026-10-01T08:52:09Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
debate-navigator	Ready	Preview	Oct 1, 2026 4:16pm UTC

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

coderabbitai · 2026-10-01T08:52:16Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 402c07b9-e7a7-43f9-bc28-f4d7d04a8c8e

📥 Commits

Reviewing files that changed from the base of the PR and between d6c7dca and eb5ae65.

📒 Files selected for processing (3)

docs/operations.md
scripts/backend-status.mjs
src/test/scripts/backend-status.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

docs/operations.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Walkthrough

Adds a read-only npm run backend:status command. It compares backend state committed at HEAD with a Supabase project, reports migration and function differences, and supports a --check mode. Deployment guidance and integration tests cover the command.

Changes

Backend status check

Layer / File(s)	Summary
Read committed backend state `scripts/backend-status.mjs`	The script parses command options and reads migration, function, import, and configuration data from `HEAD`. It also looks up first-parent change dates for backend files.
Compare and report backend status `scripts/backend-status.mjs`, `package.json`, `src/test/scripts/backend-status.test.ts`	The command queries the selected project and reports migration and function differences. `--check` returns 1 when committed migrations are pending; argument and operational errors return 2. Integration tests cover reports, project targeting, read-only commands, exit behavior, and sanitized errors.
Add status checks to deployment guidance `AGENTS.md`, `docs/operations.md`, `supabase/README.md`	Deployment guidance documents when to run the check and directs operators to confirm intended changes are no longer pending. Operations guidance also documents command behavior, limitations, and an incident troubleshooting step.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  actor Operator
  participant Npm as npm run backend:status
  participant Script as backend-status.mjs
  participant Git
  participant SupabaseCLI as Supabase CLI
  Operator->>Npm: Run status command
  Npm->>Script: Execute script
  Script->>Git: Read committed backend state at HEAD
  Script->>SupabaseCLI: List project migrations and functions
  Git-->>Script: Return committed migrations and function configuration
  SupabaseCLI-->>Script: Return deployed migration and function data
  Script-->>Operator: Print backend status report

Architecture Summary

Architecture risk: 🔵 Low · up to eb5ae

The change affects 6 systems.

Changed systems: AGENTS.md, docs, package.json, scripts, src, supabase

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

observed — AGENTS.md (service) was modified; 1 changed file maps to changed impact.
observed — docs (service) was modified; 1 changed file maps to changed impact.
observed — package.json (service) was modified; 1 changed file maps to changed impact.
observed — scripts (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

observed — Modified behavior in AGENTS.md: The Deployment guidance adds a read-only npm run backend:status check before backend deployment and states that it lists missing items in the linked project.
observed — Modified behavior in package.json: Added the backend:status package script to execute scripts/backend-status.mjs with Node.
observed — Modified behavior in supabase/README.md: The second deployment-checklist step now adds a pending-changes check using npm run backend:status and links to the backend drift-check instructions.
observed — Modified behavior in docs/operations.md: Adds documentation for npm run backend:status: it inspects the CLI-resolved project, or an explicitly supplied project ref, without changing schema, data, functions, or secrets; the CLI creates a short-lived login role to connect. It compares the committed HEAD tree with project migrations and functions, including deployment status, commit-relative function dates, and verify_jwt configuration. The documentation notes first-parent merge dating, the stale-checkout limitation, shallow-clone behavior, expected absence of workspace-invites in production, and --check exit codes 1 for unapplied migrations and 2 for check failure. It also documents why scheduled production checks await a decision.

Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}

Programcode · 2026-10-01T08:54:57Z

@coderabbitai full review

coderabbitai · 2026-10-01T08:55:06Z

⚠️ Action not completed

Review rate limited.

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 57 minutes.

Conversation

Programcode commented Oct 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Not done: the prod-canary step

Evidence

Summary by CodeRabbit

Uh oh!

vercel Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Architecture Summary

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Programcode commented Oct 1, 2026

Uh oh!

Programcode commented Oct 1, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading