feat(integration): Day 5 — Supabase agent tools + sandbox env injection

[lhz960904]

Summary

Day 5 of the BYO publish + DB plan. After Day 4 wired Supabase OAuth, this PR teaches the agent to actually use the connection — auto-provision a project under the user's org, run schema/RLS/seed SQL against it, and have the generated Vite app read the project URL + anon key straight out of import.meta.env.

• supabase_create_project tool — idempotent provisioning. Calls Management API POST /v1/projects, polls GET /v1/projects/{ref} until ACTIVE_HEALTHY (~30–60s, 90s timeout), persists supabase_project_ref + supabase_url + supabase_anon_key on the conversation row, writes .env.local to the running sandbox. If a project already exists for the conversation, returns the existing one and just refreshes .env.local.
• supabase_sql tool — runs SQL via POST /v1/projects/{ref}/database/query under the user's OAuth Bearer; no service-role key needed. 100-row truncation on returns.
• supabase-client.ts — adds createSupabaseProject / getSupabaseProject / getSupabaseProjectKeys / runSupabaseSql / listSupabaseOrganizations + 3 typed errors (SupabaseManagementApiError, SupabaseProjectProvisionTimeoutError, SupabaseProjectInitFailedError). All gated through getValidSupabaseAccessToken(userId).
• acquireConversationSandbox — re-writes .env.local on every acquire from the conversation row so disconnect/rotate/reconnect propagates automatically. Cold starts (sandbox evicted, restart from snapshots) get .env.local back without an agent turn.
• file-tracker — ignores .env.local + .env.*.local so platform-managed env doesn't pollute fileSnapshots (and therefore doesn't get re-restored on cold start, which would race the new injection).
• Prompts — PROJECT_CONVENTIONS gains a Supabase chapter: when to call supabase_create_project (persistence/auth/storage/realtime only), import.meta.env.VITE_SUPABASE_* is platform-injected (don't write .env.local yourself), always ENABLE ROW LEVEL SECURITY + auth.uid() policies, service-role key is not exposed.
• Schema — conversations += supabase_url + supabase_anon_key (nullable text). Applied via db:push.

Architectural notes

• Why Management API + OAuth Bearer instead of service-role key: the OAuth scope already includes Database(RW), so SQL via /v1/projects/{ref}/database/query is enough. Avoids the security footgun of pulling service-role keys into the platform / sandbox.
• Why store supabase_url + supabase_anon_key on the conversation row: acquireConversationSandbox runs on every cold start and reload; we don't want a Management API round-trip there. Anon key is public-by-design (RLS is the security boundary), so persisting it next to the project ref is fine.
• Why ignore .env.local in file-tracker: if it landed in fileSnapshots, cold-start would restore the snapshot version while T7's injection writes the current version — order race + stale env. Cleaner to make the platform the sole writer.

Test plan

• Backend types still pass (bunx tsc --noEmit ✅, run locally to confirm)
• Backend tests still pass (bun run test — 36/36 pass locally)
• Manual e2e: open a fresh conversation, ask the agent to "build a todo app with login, persisted to Supabase"
  • Agent calls supabase_create_project → ~30–60s wait → returns ref + URL
  • Agent calls supabase_sql to CREATE TABLE + ENABLE ROW LEVEL SECURITY + CREATE POLICY ... auth.uid() = user_id
  • Agent kills + restarts dev session; preview shows working signup → CRUD
  • In the user's supabase.com dashboard: project exists, table has the expected rows
• Idempotency: run supabase_create_project a second time on the same conversation → returns the existing ref, no new project created
• Disconnect Supabase from Settings → trigger supabase_create_project → tool returns the typed error message asking the user to reconnect (not a cryptic 401)
• Sandbox cold start: restart backend with a conversation that already has a supabase_project_ref → .env.local is re-written before bootstrap fires
• .env.local does NOT appear in fileSnapshots for any test conversation

Out of scope (planned for later)

• Day 5.5 (5/9): Database panel UI — full CRUD table editor in workspace right panel
• Day 6 (5/10): Fullstack deploy with @hono/vercel + build-time env injection (.env.production)
• Day 7 (5/11–12): E2E across 3 project archetypes + README + demo video

🤖 Generated with Claude Code

[lhz960904]

Addressed review point 1 in cc3cb06: moved the Supabase chapter out of PROJECT_CONVENTIONS and into a proper skill at sandbox-template/skills/supabase/SKILL.md.

Why this matters: every conversation was paying prompt tokens for the 2-paragraph Supabase block, even when building static sites that don't touch Supabase. Skills are loaded on-demand by description triggers — pure-static conversations now pay zero.

Skill design highlights:

• Workflow opens with the rule Haoze called out: "ALWAYS supabase_create_project first, every time you touch data — it's idempotent so this is the cheapest way to guarantee env is wired." Agent doesn't track provisioning state.
• Concrete recipes for the 80% case (RLS templates, sign-up/in, storage bucket creation, realtime channel + ALTER PUBLICATION).
• "Don'ts" section codifies the platform contract: don't write .env.local, don't try service-role, don't skip RLS, don't add a server-side SUPABASE_SECRET_KEY client to the generated app's Hono backend.

Still on the table for follow-up (review point 2 was deferred):

• Move the kill-dev-session responsibility from agent to platform, so the skill drops the manual kill_shell step.
• Day 6 will mirror .env.local to .env.production at deploy time, completing the symmetric "platform owns env files, agent only sees import.meta.env" architecture.

Note: the skill source ships in sandbox-template/skills/, which gets baked into the E2B image via e2b.Dockerfile's COPY skills /opt/skills. Deploying this change end-to-end requires rebuilding + uploading the sandbox template — same flow as adding hono-fullstack originally.