@rtrentjones/greenlight 0.4.1 → 0.5.1

package/assets/skills/provider-supabase/SKILL.md

@@ -1,28 +1,29 @@
 ---
 name: provider-supabase
-description: How Supabase works in a Greenlight setup — the `data: supabase` store (Postgres + auth + storage + realtime), single-project-schema-per-env model, the pause trap solved by keepalive, Management API token, and the read-only Supabase MCP. Use when wiring a tool's database, debugging a paused project, or a Supabase apply.
+description: Supabase in a Greenlight setup — the `data: supabase` store (Postgres + auth + storage + realtime), schema-per-env, the 7-day pause trap solved by keepalive. Use when wiring a tool's database, debugging a paused project, or a Supabase apply.
 ---
 
 # provider-supabase
 
 `data: supabase` is for tools that need bundled **auth + storage + realtime** together
-(HeistMind). One Supabase **project**, **schema-per-env** (beta/prod share the project —
-NOT project-per-env; branching is paid). The project is **imported** (not recreated):
-name/region are replace-forcing, so the module sets `ignore_changes` to protect the live DB.
+(HeistMind). One Supabase **project**, **schema-per-env** (beta/prod share the project — NOT
+project-per-env; branching is paid). The project is **imported**, not recreated: name/region are
+replace-forcing, so the module sets `ignore_changes` to protect the live DB.
 
 ## Token — `SUPABASE_ACCESS_TOKEN`
 
-Dashboard → Account → Access Tokens (Management API). Push it straight to GitHub Actions with
-`greenlight secrets gather` (or `gh secret set`) — Greenlight keeps no local secret file.
-`greenlight add` verifies it against `/v1/projects` (HTTP 200). The DB password
-(`TF_VAR_supabase_database_password`) is only used if the project is recreated — ignored on
-import, so `import-placeholder` is fine for an existing project.
+Creation + verify live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+Management API PAT, **account-scoped** (it manages every project in the account — keep it tight).
+Single store: GitHub Actions secrets. The DB password (`TF_VAR_supabase_database_password`) is only
+used if the project is *recreated* — ignored on import, so `import-placeholder` is fine for an
+existing project.
 
 ## Terraform module — `infra/modules/supabase`
 
-Single project, import-safe. Outputs `url`, `anon_key`, `service_role_key`, `project_ref` —
-feed these straight into the consumer (e.g. the Vercel env block). To re-apply from fresh
-state, import first: `terraform import module.<name>_supabase.supabase_project.this <ref>`.
+Single project, import-safe. Outputs `url`, `anon_key`, `service_role_key`, `project_ref` — feed
+these straight into the consumer (e.g. the Vercel env block). To re-apply from fresh state, import
+first: `terraform import module.<name>_supabase.supabase_project.this <ref>`.
 
 ## Keepalive — non-negotiable
 
@@ -32,10 +33,14 @@ Supabase **pauses a free project after ~7 days idle** — this is what takes too
 The ping counts any HTTP response (even 401 on `/rest/v1/`) as alive.
 
 ## MCP
-
 `.mcp.json` wires `supabase` (hosted, **read-only**): needs `SUPABASE_ACCESS_TOKEN` +
 `SUPABASE_PROJECT_REF` in the env (Claude Code expands `${VAR}` in the url/header). Run `/mcp`.
 
-## Rule
-The **blog must never use Supabase** for state (it must stay up unattended) — use D1/KV or
-external services. Supabase is per-tool, only when the bundled features are needed together.
+## Gotchas
+- **The blog must never use Supabase** for state (it must stay up unattended) — use D1/KV or
+  external services. Supabase is per-tool, only when the bundled features are needed together.
+- **Migrations gate.** A supabase tool that owns `supabase/migrations` must run `greenlight
+  migrations scan` in the CI that applies them (before `supabase db push`) — `doctor` flags a
+  migrations dir whose workflows don't.
+- **Forgetting keepalive** is the #1 silent-death cause for a supabase tool — `doctor` does not yet
+  assert it, so wire `targets_json` when you add the tool.

package/assets/skills/provider-vercel/SKILL.md

@@ -1,63 +1,66 @@
 ---
 name: provider-vercel
-description: How Vercel works in a Greenlight setup — the default target for the `next` lane, configure-existing-project model (domains + env vars by project_id; deploys ride git integration), team-scoped token, and the Vercel MCP. Use when wiring a next/vercel tool, env vars, domains, or debugging a Vercel deploy.
+description: Vercel in a Greenlight setup — the default target for the `next` lane (configure-existing-project: domains + env vars by project_id; deploys ride git integration). Use when wiring a next/vercel tool, env vars, domains, or debugging a Vercel deploy or verify.
 ---
 
 # provider-vercel
 
-Vercel is the default `target` for the `next` lane. Greenlight does **not** create or deploy
-the project — it **configures an existing** Vercel project (domains + environment variables)
-by `project_id`, and the app's own repo deploys via Vercel's **git integration** (push →
-build). The wrapper owns infra; the tool repo owns deploys.
+Vercel is the default `target` for the `next` lane. Greenlight does **not** create or deploy the
+project — it **configures an existing** Vercel project (domains + environment variables) by
+`project_id`, and the app's own repo deploys via Vercel's **git integration** (push → build). The
+wrapper owns infra; the tool repo owns deploys.
 
 ## Token — `VERCEL_API_TOKEN`
 
-Account → Settings → Tokens. **Scope it to the team** that owns the project. The Terraform
-`vercel` provider also takes `team` (the `team_…` id). Push it straight to GitHub Actions with
-`greenlight secrets gather` (or `gh secret set`) — Greenlight keeps no local secret file.
-`greenlight add` verifies it against `/v2/user` (HTTP 200) before commit.
+Creation + verify live in
+[tokens-reference.md](https://github.com/RTrentJones/greenlight/blob/main/docs/tokens-reference.md).
+**Scope it to the team** that owns the project (the Terraform `vercel` provider also takes the
+`team_…` id). Single store: GitHub Actions secrets.
 
 ## Terraform module — `infra/modules/vercel`
 
 Manages the **existing** project (nothing to import — it configures by id):
 - `domain` → adds `<name>.<domain>` (production) + `beta.<name>.<domain>` (preview/`beta_branch`).
-- `environment` + `environment_values` → env vars per target (`production` / `preview`).
-  Wire Supabase creds straight from the `supabase` module's outputs — no manual copy (that
-  manual copy was the old fragility).
+- `environment` + `environment_values` → env vars per target (`production` / `preview`). Wire
+  Supabase/Neon creds straight from those modules' outputs — no manual copy (that copy was the old
+  fragility).
 
 The DNS CNAME is the **cloudflare** `tool` module, unproxied (`proxied = false`) → `cname.vercel-dns.com`.
 
 ## The verify loop — tool-CI on `deployment_status`
 
-Because Vercel deploys (not the wrapper), the verify gate runs in the **tool repo's own CI**, not a
-wrapper deploy listener. `greenlight adopt … --target vercel` emits, into the tool repo:
+Because Vercel deploys (not the wrapper), the verify gate runs in the **tool repo's own CI**.
+`greenlight adopt … --target vercel` emits, into the tool repo:
 - **`.github/workflows/greenlight-verify.yml`** — triggers on GitHub's **`deployment_status`** event
   (Vercel posts a deployment + `target_url`); on `state == success` it runs
   `npx @rtrentjones/greenlight verify --url <target_url> --spec verify/<name>.config.ts`. The result
-  is a check on the commit — no wrapper round-trip, no dispatch/status PATs (Vercel owns deploy + URL
-  + its own statuses).
-- **`verify/<name>.config.ts`** — a verifyAll array: `api` (deployed URL 200) + `test` (the tool's
-  suite) + `agent-web` (LLM drives the live UI), where agent-web is **config-gated on
-  `ANTHROPIC_API_KEY`** (omitted when unset → the gate stays green on api + test alone).
+  is a check on the commit — no wrapper round-trip, no dispatch/status PATs.
+- **`verify/<name>.config.ts`** — a verifyAll array: `api` + `test` (the tool's suite) + `agent-web`
+  (LLM drives the live UI), where agent-web is **config-gated on `ANTHROPIC_API_KEY`** (omitted when
+  unset → the gate stays green on api + test alone).
 
 `greenlight verify --url <url> --spec <path>` is the **manifest-free** mode that makes this work
 without carrying the wrapper's `greenlight.config.ts` into the tool repo.
 
-**Deployment Protection gotcha:** `deployment_status.target_url` is the `*.vercel.app` *deployment*
-URL, which Vercel **Deployment Protection** gates (→ **401**) even though the public custom domain
-is 200. To verify the real app, create a **Protection Bypass for Automation** secret (Vercel →
-project → Settings → Deployment Protection) and set it as `VERCEL_AUTOMATION_BYPASS_SECRET_<TOOL>` (per-tool — the bypass value is per Vercel project, so a second vercel tool never collides) on the
-tool repo — the api check sends it as `x-vercel-protection-bypass` and asserts 200. Without it the
-generated spec asserts **401** (the deployment is served + protected), so the gate stays green.
-
 ## MCP
-
-`.mcp.json` wires `vercel` (hosted, OAuth, read-only). Run `/mcp` and authenticate in the
-browser. Use it to read deployments, build logs, runtime logs, projects.
+`.mcp.json` wires `vercel` (hosted, OAuth, read-only). Run `/mcp` and authenticate in the browser —
+read deployments, build logs, runtime logs, projects.
 
 ## Gotchas
-- **ENV_CONFLICT** on apply = a var with that key/target already exists on the project. Delete
-  the pre-existing ones (Vercel dashboard or API) then re-apply, or import them.
-- The Greenlight `beta_branch` must match the repo's actual pre-prod branch (HeistMind uses
-  `development`; new tools use `develop`).
+- **`ENV_CONFLICT` on apply** = a var with that key/target already exists on the project. **Terraform
+  owns env vars and does not upsert** — delete the pre-existing ones (dashboard or API) and re-apply,
+  or `terraform import` them first. Adopting an existing project means importing its env vars.
+- **pnpm workspace membership** (a local `next`/`vercel` monorepo tool) — add `tools/<name>` to
+  `pnpm-workspace.yaml`, else Vercel's root install skips its deps (`Cannot find package 'pg'`).
+  `doctor` flags this.
+- **`vercel.json` framework preset** — without `{ "framework": "nextjs" }` Vercel treats the Next
+  build as a static site (`No Output Directory named "public"`). `doctor` flags a missing one.
+- **Deployment Protection (401 on the `*.vercel.app` URL).** `deployment_status.target_url` is the
+  *deployment* URL, which Deployment Protection gates to **401** even when the public custom domain is
+  200. Create a **Protection Bypass for Automation** secret and set it as
+  `VERCEL_AUTOMATION_BYPASS_SECRET_<TOOL>` (per-tool — the value is per Vercel project) on the tool
+  repo; the api check sends it as `x-vercel-protection-bypass` and asserts 200. Without it the spec
+  asserts **401** so the gate still stays green.
+- **`beta_branch` must match the repo's real pre-prod branch** (HeistMind uses `development`; new
+  tools use `develop`).
 - `next` can also target `workers` (V0/V2) — default is vercel.