feat: CI mode with GitHub Actions annotations and --fail-on flag

[jasdeepkhalsa]

Summary

Adds first-class CI support to supaforge diff via two new flags:

• --ci — emits GitHub Actions ::error/::warning annotation lines for every drift issue (shows inline on the PR diff view), then outputs a structured JSON summary
• --fail-on=critical|warning|any — controls the exit code threshold (default: critical, preserving existing behaviour)

Also ships a reusable GitHub Actions workflow template at packages/cli/templates/drift-check.yml that teams can drop into their repos with zero additional tooling.

Competitive context

Neither pg-delta (Supabase's own alpha) nor migra (the tool Supabase CLI wraps) has GitHub Actions integration. Atlas has it behind a paywall. This makes Supaforge the only free tool with native CI/CD drift detection for Supabase.

New files

File	Purpose
packages/cli/src/ci.ts	formatAnnotation(), formatGitHubAnnotations(), computeCiExitCode(), formatCiSummary()
packages/cli/templates/drift-check.yml	Ready-to-copy GitHub Actions workflow
packages/cli/test/ci.test.ts	20 unit tests covering all annotation formats and exit code logic

Modified files

File	Change
packages/cli/src/commands/diff.ts	Adds --ci and --fail-on flags; CI mode branch emits annotations, skips preflight/progress, calls this.exit(exitCode)

Exit code semantics

Code	Meaning
0	No drift above the --fail-on threshold
1	Drift detected above threshold
2	Scan error (DB unreachable, auth failure, etc.)

GitHub Actions annotation format

For every drift issue, the command writes to stdout:

::error title=Missing RLS policy: users_read::Policy "users_read" on public.users exists in source but is missing from target. This is a CVE-2025-48757 risk pattern.

GitHub Actions picks these up and shows them as inline PR annotations — no extra action needed.

Usage examples

# In CI (default: fail on critical only)
supaforge diff --ci

# Fail on any warning or critical
supaforge diff --ci --fail-on=warning

# Fail on any drift (info included)
supaforge diff --ci --fail-on=any

GitHub Actions workflow (template)

- name: Run drift check
  env:
    SUPAFORGE_SOURCE_DB_URL: ${{ secrets.SUPAFORGE_SOURCE_DB_URL }}
    SUPAFORGE_TARGET_DB_URL: ${{ secrets.SUPAFORGE_TARGET_DB_URL }}
  run: supaforge diff --ci --fail-on=critical

Test plan

• formatAnnotation — critical → ::error, warning/info → ::warning
• Newlines in description escaped as %0A, carriage returns as %0D
• Commas in title escaped as \, (GitHub Actions requirement)
• formatGitHubAnnotations returns one line per issue across all checks
• computeCiExitCode returns 0 for clean scan
• Returns 2 when any check has status: 'error' (error takes precedence over drift)
• fail-on=critical: 1 on critical, 0 on warning/info
• fail-on=warning: 1 on critical or warning, 0 on info
• fail-on=any: 1 on any issue including info
• Default threshold is critical
• formatCiSummary groups critical/warning separately, omits info
• Summary includes score and timestamp

---

Generated by Claude Code