@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/neon/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: neon
+description: "Use when you have picked Neon (serverless Postgres) and need to connect correctly from a serverless or edge runtime, wire database branching into dev, preview and CI, or stop being burned by scale-to-zero cold starts and pooler limits — including choosing HTTP versus WebSocket connections and pooled versus direct endpoints for migrations. NOT generic Postgres schema, index, EXPLAIN, RLS or migration-engine work (that is `postgresdb`)."
+tags: [neon, postgres, serverless, database, branching, edge]
+recommends: [postgresdb, drizzle-orm, prisma-orm, vercel]
+origin: ai-hub
+---
+
+# Neon — serverless Postgres as a platform
+
+Neon is Postgres with three platform features the engine doesn't have: a **serverless driver** that
+talks over HTTP/WebSocket (so you can query from edge runtimes), **built-in connection pooling**, and
+**copy-on-write branching** that makes a fork of production data appear instantly. This skill owns
+that platform layer. The Postgres *engine* underneath — schema, indexes, EXPLAIN, RLS, zero-downtime
+DDL — is identical to any Postgres 16 and belongs to `../postgresdb/SKILL.md`. Don't re-derive engine
+craft here; connect correctly and branch correctly.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Code imports `@neondatabase/serverless`, or `DATABASE_URL` points at `*.neon.tech` / `*.aws.neon.tech`.
+- Connecting from Vercel (Edge/Node), Cloudflare Workers, AWS Lambda, or any serverless/edge function — choosing HTTP `neon()` vs WebSocket `Pool`.
+- Setting up branching: dev branch off production, a branch per PR in CI, `neonctl` usage, the Neon + Vercel preview integration.
+- Neon-specific symptoms: cold start after scale-to-zero, "too many connections" despite being serverless, pooled-vs-direct string confusion, autoscaling CU sizing/cost.
+- Picking the connection string for migrations (direct) vs app queries (pooled).
+
+**When NOT to use — route to the sibling:**
+
+- Schema design, index choice, EXPLAIN/ANALYZE, query tuning, RLS, VACUUM, partitioning, expand-contract migrations → `../postgresdb/SKILL.md`. Neon adds nothing to the engine; defer.
+- Drizzle schema/migrations → `../drizzle-orm/SKILL.md`; Prisma → `prisma-orm`. Neon supplies only the *driver adapter* line.
+- A different managed Postgres/BaaS: Supabase (auth + storage + realtime) → `supabase`; PlanetScale → `planetscale`; Turso/libSQL → `sqlite-turso`.
+- Where to deploy the app talking to Neon → `../vercel/SKILL.md` / `cloudflare` / `railway`.
+- Backup/PITR strategy as a discipline → `backups` (Neon branch-as-restore is mentioned here, not owned).
+
+## Non-negotiables
+
+1. A WebSocket `Pool`/`Client` is **created and closed inside one request handler** — never at module scope in a serverless function. Module scope = a connection that outlives the invocation and leaks.
+2. **App queries use the pooled string** (host contains `-pooler`). **Migrations / DDL / advisory locks / session features use the direct string** (no `-pooler`). Mixing them is the #1 Neon foot-gun.
+3. The HTTP `neon()` driver **always** uses the pooled endpoint — don't hand it a direct string and expect session state.
+4. HTTP `neon()` has **no interactive transactions**. Need `BEGIN ... COMMIT` across round-trips? Use `sql.transaction([...])` (batched, non-interactive) or a WebSocket `Pool`.
+5. On Node.js ≤ 21 you **must** set `neonConfig.webSocketConstructor = ws` before opening a Pool/Client. Node 22+ and edge runtimes have a global `WebSocket`; don't set it there.
+6. Pin the driver: `@neondatabase/serverless` is at **v1.1.0** (npm latest, 2026-04-17). It is a drop-in replacement for `pg`.
+
+## Pick your connection method
+
+Keyed by runtime and what the query needs. Pick the lightest transport that satisfies the need.
+
+| You need | Use | Why |
+| --- | --- | --- |
+| One independent read/write per request (edge, Lambda, React Server Components) | HTTP `neon()` | Single fetch round-trip (~3 round trips vs ~8 for TCP setup); no connection to manage or leak. |
+| Several queries that must be atomic, no logic between them | `sql.transaction([q1, q2])` over HTTP | One round-trip, real transaction, still no socket lifecycle. |
+| Interactive transaction — read a row, branch in app code, then write | WebSocket `Pool` (open+close in handler) | HTTP can't hold `BEGIN` open; WebSocket keeps the session alive within the request. |
+| Full `pg`-API compatibility (cursors, LISTEN/NOTIFY, COPY) | WebSocket `Client`/`Pool` | HTTP is one-shot; node-postgres semantics need the socket. |
+| Migrations / DDL / `pg_advisory_lock` / session GUCs | direct (non-`-pooler`) string with `pg` or WebSocket `Client` | PgBouncer transaction-pooling breaks session-level state. |
+
+If you're behind Drizzle or Prisma, you don't call these directly — you pass the driver to the
+adapter. See the ORM pointers below.
+
+## Connection strings: pooled vs direct
+
+Neon gives every branch two connection strings that differ in **one** thing: the host of the pooled
+one contains `-pooler`.
+
+```text
+pooled:  postgresql://user:pass@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/db?sslmode=require
+direct:  postgresql://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/db?sslmode=require
+```
+
+| Use case | String | Reason |
+| --- | --- | --- |
+| App runtime (queries from your functions) | **pooled** (`-pooler`) | PgBouncer fans many short-lived serverless invocations onto a small pool; up to 10,000 concurrent client connections per project. |
+| HTTP `neon()` driver | **pooled** (it forces it regardless) | The HTTP path is stateless; pooling is the right model. |
+| Migrations, DDL, schema introspection | **direct** | Transaction pooling drops session state; advisory locks and prepared statements need a stable session. |
+| `psql` interactive / debugging | **direct** | You want one real session, not a pooled handle. |
+
+Bad → Good for a typical setup:
+
+```bash
+# Bad: one string everywhere — migrations sporadically fail under PgBouncer.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"
+
+# Good: split them. App uses the pooled one; the migration tool uses DIRECT.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"          # app runtime
+DIRECT_URL="postgresql://....../db?sslmode=require"                    # migrations/DDL
+```
+
+## Serverless driver patterns
+
+All examples assume `@neondatabase/serverless@1.1.0`.
+
+HTTP one-shot — the default for edge/serverless reads and writes:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!); // pooled endpoint, no socket to manage
+export async function getUser(id: string) {
+  const [row] = await sql`select id, email from users where id = ${id}`;
+  return row; // parameterized; ${id} is bound, not interpolated
+}
+```
+
+Batched atomic writes over HTTP — atomicity without a WebSocket and without interactivity:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+await sql.transaction([
+  sql`insert into orders (id, total) values (${id}, ${total})`,
+  sql`update inventory set qty = qty - 1 where sku = ${sku}`,
+]); // one round-trip, both succeed or both roll back
+```
+
+Interactive transaction — WebSocket `Pool`, opened **and closed inside the handler**:
+
+```ts
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws"; // Node ≤21 only; omit on edge / Node 22+
+
+neonConfig.webSocketConstructor = ws; // required on Node ≤21; do NOT set on edge runtimes
+
+export async function transfer(from: string, to: string, cents: number) {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // inside the handler
+  const client = await pool.connect();
+  try {
+    await client.query("begin");
+    const { rows } = await client.query("select balance from accounts where id=$1 for update", [from]);
+    if (rows[0].balance < cents) throw new Error("insufficient");
+    await client.query("update accounts set balance=balance-$1 where id=$2", [cents, from]);
+    await client.query("update accounts set balance=balance+$1 where id=$2", [cents, to]);
+    await client.query("commit");
+  } catch (e) {
+    await client.query("rollback");
+    throw e;
+  } finally {
+    client.release();
+    await pool.end(); // close before the function returns — no leaked connection
+  }
+}
+```
+
+Edge runtime (Vercel Edge, Cloudflare Workers): use HTTP `neon()`; the global `WebSocket` exists, so a
+`Pool` works without `ws`, but prefer HTTP unless you truly need an interactive transaction.
+
+ORM adapters — you wire the driver, the ORM owns the query API:
+
+- Drizzle: pass `neon()`/`Pool` into `drizzle-orm/neon-http` or `neon-serverless` → `../drizzle-orm/SKILL.md`.
+- Prisma: use the `@prisma/adapter-neon` driver adapter → `prisma-orm`.
+
+## Branching for dev / preview / CI
+
+A Neon branch is **copy-on-write**: created instantly with no data copied, it forks production at a
+point in time, gets its own compute endpoint, and scales to zero independently. That makes a branch a
+cheap, isolated, full-data environment — not a backup substitute (test the restore).
+
+| Situation | Do | Why |
+| --- | --- | --- |
+| Per-developer or per-PR isolated data | **branch off production** | Instant, real prod-shaped data, separate endpoint, auto scale-to-zero → near-free idle. |
+| A genuinely separate product/tenant with its own billing & limits | **new project** | Branches share the project's quotas and pooled-connection ceiling. |
+| Throwaway query you can run against staging | **same branch** | Don't manufacture a branch for a one-off SELECT. |
+
+`neonctl` (alias `neon`) drives create/connect/teardown:
+
+```bash
+neonctl branches create --name pr-$PR_NUMBER --parent main
+neonctl connection-string pr-$PR_NUMBER --pooled   # feed to the preview app
+neonctl branches delete pr-$PR_NUMBER              # on PR merge/close
+```
+
+**Vercel preview integration:** with the Neon + Vercel integration, each preview deployment gets its
+own branch forked from production, auto-deleted when the PR merges or closes — zero CI code. If you're
+not on Vercel, replicate it in CI: create branch on PR open → run migrations (direct string) → seed →
+expose the pooled connection string to the app → delete on PR close. Full GitHub Actions workflow,
+`neonctl` reference, and the Neon API endpoints: [branching-ci](references/branching-ci.md).
+
+**Branch-as-restore (PITR):** to recover, branch from an earlier point in time and either read from it
+or promote it. It's a fast undo, not a tested backup discipline — own that in `backups`.
+
+## Autoscaling & scale-to-zero
+
+Each branch's compute endpoint **autoscales** between a min and max CU (vCPU/RAM) on its own, with no
+noisy neighbors across branches. Idle compute **scales to zero** after **5 minutes** of inactivity
+(default), then resumes on the next connection with a millisecond-to-sub-second cold start.
+
+Cost mental model: non-prod branches sit at zero almost always, so a dozen PR branches cost close to
+nothing. The cold start is the price.
+
+Prod endpoint sizing checklist:
+
+- [ ] Set a sane **min/max CU** for the prod branch — not maxed "just in case" (you pay for the max headroom you actually use).
+- [ ] Latency-sensitive prod with sparse traffic? **Disable scale-to-zero** or set **min CU > 0** so there's no cold start in p99.
+- [ ] Treat the cold start as real: warm the connection on deploy, or accept it on non-prod and account for it in latency SLOs.
+- [ ] Keep non-prod branches on scale-to-zero — that's where the near-free economics come from.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `new Pool(...)` at module scope in a serverless function | Connection outlives the invocation; you exhaust the pool → "too many connections". | Create and `await pool.end()` inside the handler, or use HTTP `neon()`. |
+| Pooled (`-pooler`) string for migrations/DDL | PgBouncer transaction-pooling drops session state; advisory locks/prepared statements fail intermittently. | Use the **direct** string for migrations; pooled only for app runtime. |
+| Direct (non-`-pooler`) string as the app `DATABASE_URL` | No pooling → serverless concurrency exhausts raw connections fast. | App runtime always uses the **pooled** string. |
+| Expecting `BEGIN`/interactive txns from HTTP `neon()` | HTTP is one-shot, stateless — there's no open session to hold a transaction. | `sql.transaction([...])` for batched atomicity, or a WebSocket `Pool` for interactive. |
+| Opening a `Pool` without `neonConfig.webSocketConstructor = ws` on Node ≤21 | No global `WebSocket` → the connection silently fails. | Set `webSocketConstructor = ws` on Node ≤21; omit on edge / Node 22+. |
+| Ignoring scale-to-zero in p99 latency | First request after 5 min idle pays the resume cold start; users see a slow request. | Disable scale-to-zero or set min CU > 0 on latency-sensitive prod. |
+| One shared branch for all PRs | PRs clobber each other's data; no isolation. | One branch per PR, deleted on close. |
+| Treating a branch as a backup without testing restore | Branches share project quotas and aren't an exercised recovery path. | Verify branch-as-restore; own real backup strategy in `backups`. |
+| Maxing CU "to be safe" | You pay for headroom you don't use; autoscaling already handles spikes. | Set a realistic min/max; let autoscaling expand. |
+| Doing schema/index design in this skill | Engine craft is identical to any Postgres; duplicating it drifts. | Defer to `../postgresdb/SKILL.md`. |
+
+## Cross-references
+
+- Engine craft (schema, indexes, EXPLAIN, RLS, zero-downtime DDL): `../postgresdb/SKILL.md`.
+- Next.js App Router data layer that calls Neon: `../nextjs/SKILL.md`.
+- ORM query APIs over the Neon driver: `../drizzle-orm/SKILL.md`, `prisma-orm`.
+- Deployment targets: `../vercel/SKILL.md`, `cloudflare`, `railway`. Backups discipline: `backups`.
+- Other managed DBs (route away): `supabase`, `planetscale`, `sqlite-turso`.

package/skills/shared/neon/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `neon` skill
+
+These cases are routing and trigger checks, not executed code. Run them by reading each prompt and
+confirming the behavior: every `should_trigger` prompt should make an agent load and apply this skill
+(including the non-obvious "too many connections" / cold-start phrasings and the Spanish/Catalan
+ones); every `should_not_trigger` prompt should route to the named sibling (`postgresdb`,
+`drizzle-orm`, `supabase`, `vercel`, `backups`) instead of firing here. The `capability` case is a
+rubric: have an agent answer the Neon-wiring scenario and grade the response against each
+`must_include` item — pooled-vs-direct strings, HTTP vs WebSocket choice, Pool lifecycle inside the
+handler, atomic-operation handling, per-PR branching with teardown, and deferring engine craft to
+postgresdb. No network or database is required.

package/skills/shared/neon/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: neon
+
+should_trigger:
+  - prompt: "Connecting to Neon from a Cloudflare Worker — should I use neon() or Pool?"
+    why: Core driver/transport decision for an edge runtime; the heart of this skill.
+  - prompt: "Set up a database branch per pull request so previews get isolated data."
+    why: Per-PR copy-on-write branching workflow, Neon's signature platform feature.
+  - prompt: "I keep getting 'too many connections' from my Vercel function hitting Neon."
+    why: Non-obvious foot-gun — pooled endpoint and module-scope Pool leak, not an engine issue.
+  - prompt: "The first request after the app's been idle a while is super slow against our Neon DB."
+    why: Non-obvious symptom phrasing for scale-to-zero cold start (5-min idle resume).
+  - prompt: "Conexión serverless a Postgres en Neon: ¿qué connection string uso para las migraciones?"
+    why: Spanish; pooled-vs-direct rule (migrations need the direct, non -pooler string).
+  - prompt: "Vull una branca de base de dades per cada PR amb neonctl i que s'esborri al tancar."
+    why: Catalan; per-PR branching with neonctl and teardown — directly in scope.
+
+should_not_trigger:
+  - prompt: "Design the schema and pick indexes for my orders table in Postgres."
+    route_to: postgresdb
+    why: Engine craft — provider-agnostic schema and indexing, identical on any Postgres 16.
+  - prompt: "Write the Drizzle schema and a migration for my Neon DB."
+    route_to: drizzle-orm
+    why: ORM authoring; Neon only supplies the driver adapter line, not the query/schema API.
+  - prompt: "Set up auth and storage with realtime subscriptions for my app."
+    route_to: supabase
+    why: Different BaaS owning auth/storage/realtime, not the Neon serverless-Postgres layer.
+  - prompt: "Deploy my Next.js app to Vercel with preview deployments."
+    route_to: vercel
+    why: Deployment target and platform config, not the database connection or branching.
+  - prompt: "Plan a backup and point-in-time recovery strategy for production."
+    route_to: backups
+    why: Backup discipline; Neon's branch-as-restore is mentioned but the strategy belongs to backups.
+
+capability:
+  - scenario: >
+      Wire a Next.js app deployed on Vercel to Neon. The agent must choose connection strings,
+      pick the right driver per access pattern, handle a multi-step atomic operation safely from a
+      serverless function, and outline per-PR branch isolation in CI.
+    must_include:
+      - Uses the pooled (-pooler) string for app runtime and the direct (non -pooler) string for migrations.
+      - HTTP neon() for one-shot read paths (edge/serverless, single round-trip).
+      - WebSocket Pool created AND closed inside the request handler, never at module scope.
+      - Uses sql.transaction([...]) or a WebSocket Pool for the multi-step atomic operation, not HTTP single statements expecting interactivity.
+      - Per-PR branch via neonctl or the Neon API with teardown on PR close.
+      - Defers schema and index design to postgresdb rather than redoing engine craft.

package/skills/shared/neon/references/branching-ci.md

@@ -0,0 +1,86 @@
+# Per-PR Neon branching in CI
+
+Replicate the Neon + Vercel preview integration anywhere: create an isolated, full-data branch when a
+PR opens, migrate and seed it, hand the pooled connection string to the preview app, and delete the
+branch when the PR closes. A branch is copy-on-write (instant, no data copied) and scales to zero, so
+even a dozen open PRs cost almost nothing.
+
+## `neonctl` command reference
+
+`neonctl` (alias `neon`) is the official CLI. Authenticate in CI with `NEON_API_KEY`.
+
+| Command | Purpose |
+| --- | --- |
+| `neonctl branches create --name <n> --parent main` | Fork a new branch from production at the current point in time. |
+| `neonctl connection-string <branch> --pooled` | Print the **pooled** (`-pooler`) string for the app runtime. |
+| `neonctl connection-string <branch>` | Print the **direct** string for migrations/DDL. |
+| `neonctl branches list` | List branches (find a stale one to delete). |
+| `neonctl branches delete <branch>` | Tear the branch down on PR close. |
+
+## GitHub Actions: create on open, delete on close
+
+```yaml
+name: neon-pr-branch
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+env:
+  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}
+
+jobs:
+  create_and_migrate:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm i -g neonctl
+      - name: Create branch
+        run: neonctl branches create --name pr-${{ github.event.number }} --parent main --project-id "$NEON_PROJECT_ID"
+      - name: Resolve strings
+        id: db
+        run: |
+          DIRECT=$(neonctl connection-string pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID")
+          POOLED=$(neonctl connection-string pr-${{ github.event.number }} --pooled --project-id "$NEON_PROJECT_ID")
+          echo "::add-mask::$DIRECT"; echo "::add-mask::$POOLED"
+          echo "direct=$DIRECT" >> "$GITHUB_OUTPUT"
+          echo "pooled=$POOLED" >> "$GITHUB_OUTPUT"
+      - name: Migrate + seed (DIRECT string — DDL needs a real session)
+        env:
+          DATABASE_URL: ${{ steps.db.outputs.direct }}
+        run: |
+          npm ci
+          npm run db:migrate
+          npm run db:seed
+      # Hand steps.db.outputs.pooled to the preview deploy as the app DATABASE_URL.
+
+  delete:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm i -g neonctl
+      - run: neonctl branches delete pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID"
+```
+
+Rules that keep this honest:
+
+- Migrations and seed run against the **direct** string — PgBouncer transaction-pooling breaks DDL and advisory locks.
+- The preview app gets the **pooled** (`-pooler`) string — serverless concurrency needs the pool.
+- The `closed` event covers both merge and abandon, so branches never accumulate.
+
+## Neon API (if you can't use the CLI)
+
+Same flow over REST with a bearer `NEON_API_KEY`:
+
+| Step | Endpoint |
+| --- | --- |
+| Create branch | `POST /api/v2/projects/{project_id}/branches` |
+| Get branch endpoints / connection URI | `GET /api/v2/projects/{project_id}/branches/{branch_id}/endpoints` |
+| Delete branch | `DELETE /api/v2/projects/{project_id}/branches/{branch_id}` |
+
+Pass `endpoints[].pooler_enabled` / request the pooled URI for the app, the plain URI for migrations.
+Engine-level migration mechanics (expand-contract, `CONCURRENTLY`, batched backfill) are not Neon's —
+see `../../postgresdb/SKILL.md`.

package/skills/shared/neon/scripts/verify.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# verify.sh — static Neon foot-gun scan. Read-only, no network, no DB.
+# Usage: verify.sh [TARGET_DIR]   (defaults to current directory)
+# Exit 0 when clean or no Neon usage found; non-zero only on a hard FAIL.
+set -uo pipefail
+
+TARGET="${1:-.}"
+fails=0
+
+say()  { printf '%s\n' "$*"; }
+pass() { say "PASS: $*"; }
+warn() { say "WARN: $*"; }
+fail() { say "FAIL: $*"; fails=$((fails+1)); }
+
+# Files that actually reference Neon — keeps the scan scoped and avoids false hits.
+# Portable across bash 3.2 (macOS) and 4+: newline-separated, then filter by grep.
+neon_files=()
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  if grep -qE '@neondatabase/serverless|neon\.tech' "$f" 2>/dev/null; then
+    neon_files+=("$f")
+  fi
+done < <(
+  find "$TARGET" \
+    -type d \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.env' -o -name '.env*' \) -print 2>/dev/null
+)
+
+if [ "${#neon_files[@]}" -eq 0 ]; then
+  say "no Neon usage found — nothing to check"
+  exit 0
+fi
+
+# (a) WebSocket Pool/Client created at module/top scope (heuristic: `new Pool(`/`new Client(`
+#     on a line with no leading indentation, i.e. not inside a function/handler block).
+for f in "${neon_files[@]}"; do
+  if grep -nE '^(export +)?(const|let|var) +[A-Za-z0-9_]+ *= *new +(Pool|Client) *\(' "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      fail "module-scope WebSocket Pool/Client in $f -> $line (move inside the request handler; it leaks connections)"
+    done < <(grep -nE '^(export +)?(const|let|var) +[A-Za-z0-9_]+ *= *new +(Pool|Client) *\(' "$f")
+  fi
+done
+
+# (b) pooled string in a migration config, or a non-pooler Neon host used as the app DATABASE_URL.
+for f in "${neon_files[@]}"; do
+  base="$(basename "$f")"
+  case "$base" in
+    *migrat*|drizzle.config.*|knexfile.*|*.env.migrat*)
+      if grep -nE '-pooler\.[^ "'\'']*neon\.tech' "$f" >/dev/null 2>&1; then
+        warn "pooled (-pooler) host in migration config $f (migrations/DDL need the DIRECT string)"
+      fi
+      ;;
+  esac
+  # App DATABASE_URL pointing at a non-pooler Neon host.
+  if grep -nE 'DATABASE_URL *= *.*[^-]neon\.tech' "$f" 2>/dev/null | grep -vqE '\-pooler\.' ; then
+    if grep -nE 'DATABASE_URL *= *.*[a-z0-9-]+\.[a-z0-9-]*\.?neon\.tech' "$f" 2>/dev/null | grep -vqE '\-pooler' ; then
+      warn "DATABASE_URL uses a non -pooler Neon host in $f (app runtime should use the POOLED string)"
+    fi
+  fi
+done
+
+# (c) `ws` imported but neonConfig.webSocketConstructor never assigned (Node <=21 will fail silently).
+for f in "${neon_files[@]}"; do
+  if grep -qE "(import +ws +from +['\"]ws['\"]|require\(['\"]ws['\"]\))" "$f" 2>/dev/null; then
+    if ! grep -qE 'neonConfig\.webSocketConstructor *=' "$f" 2>/dev/null; then
+      warn "ws imported without neonConfig.webSocketConstructor in $f (required on Node <=21)"
+    fi
+  fi
+done
+
+if [ "$fails" -gt 0 ]; then
+  say "---"
+  say "$fails hard failure(s)."
+  exit 1
+fi
+say "---"
+say "no hard failures."
+exit 0

package/skills/shared/nestjs/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: nestjs
+description: "Use when building or structuring a NestJS backend — feature modules, providers and DI wiring, provider scopes and request-lifecycle order, where to bind guards/pipes/interceptors/filters, and testing with Test.createTestingModule. NOT a bare Express/Fastify service with no DI (that is `nodejs`), NOT framework-agnostic REST design (that is `api-design`)."
+tags: [nestjs, nodejs, backend, dependency-injection, guards, pipes, testing, typescript]
+recommends: [nodejs, typescript, api-design, prisma-orm, testing-web]
+origin: ai-hub
+---
+
+# NestJS
+
+Build server-side Node apps the way NestJS intends: feature modules, providers wired through the DI container, controllers, and a cross-cutting layer bound at a deliberate scope. This skill is about Nest-specific mechanics — how DI scopes resolve, what order the request lifecycle runs in, where to bind guards/pipes/interceptors/filters, and how to test it with `Test.createTestingModule`.
+
+## Not this — route instead
+
+- Bare Express/Fastify/`http` service, no `@Module`/`@Injectable` → `../nodejs/SKILL.md`. Nest starts the moment the DI container appears.
+- REST resource modeling, versioning, status codes, idempotency (framework-agnostic) → `../api-design/SKILL.md`. Nest is where you *implement* those decisions.
+- Designing the schema / writing queries / migrations → `../prisma-orm/SKILL.md`. *Injecting* a repo or `DataSource` provider stays here; designing the table does not.
+- Generic JS/TS test infra (Jest config, coverage thresholds, monorepo) → `../testing-web/SKILL.md`. The Nest harness (`TestingModule`, `overrideProvider`, Supertest bootstrap) stays here.
+
+## Mental model
+
+Everything is a **provider** in a directed DI graph. **Modules** draw the boundaries of that graph — a provider is only reachable where it is provided or imported. **Cross-cutting concerns** (guards, interceptors, pipes, filters) are decorators bound at a scope you choose: global, controller, or route. Get those three right and the rest is plumbing.
+
+The request lifecycle runs in a fixed order. Memorize it — most "my guard can't see the validated body" bugs are an ordering misunderstanding:
+
+```text
+req → middleware → guards → interceptors(pre) → pipes → handler → interceptors(post) → exception filters → res
+```
+
+So pipes run *after* guards (a guard cannot read a transformed DTO), and filters catch everything thrown downstream. Source: NestJS request-lifecycle docs.
+
+## Module design
+
+One feature module per bounded context. Rules, each with its why:
+
+- **`exports` is the module's public API.** A provider not exported is private to that module — that is the encapsulation, lean on it.
+- **`imports` brings in another module's exports; it does not re-declare providers.** Re-declaring a provider in two modules gives you two singletons and silent state bugs.
+- **Keep `AppModule` thin.** It wires feature modules and global config, nothing else. A god `AppModule` that declares every controller becomes an untestable circular-dependency magnet.
+- **Use a dynamic module (`forRoot` / `forRootAsync`) for configurable infrastructure** (DB, cache, mailer) so consumers pass options instead of editing the module.
+
+```typescript
+// Bad — everything dumped in AppModule, no boundaries
+@Module({ controllers: [OrdersController, UsersController, BillingController],
+          providers: [OrdersService, UsersService, BillingService, PrismaService] })
+export class AppModule {}
+
+// Good — a feature module owns its slice and exports only its public surface
+@Module({
+  imports: [PrismaModule],
+  controllers: [OrdersController],
+  providers: [OrdersService],
+  exports: [OrdersService], // other modules consume the service, not the repo
+})
+export class OrdersModule {}
+```
+
+## Providers & DI
+
+Pick the custom-provider form by intent:
+
+| Form | Use it when | Resolved by |
+|------|-------------|-------------|
+| `useClass` | Default — swap implementation by class (e.g. real vs fake mailer) | Nest instantiates |
+| `useValue` | A ready object/constant: config, a mock in tests | Used as-is |
+| `useFactory` | Value needs computing or other providers (`inject: [...]`) | Your factory fn |
+| `useExisting` | Alias an existing token to a new token | Reuses instance |
+
+A non-class token needs explicit injection — Nest has no type to reflect on:
+
+```typescript
+const STRIPE = 'STRIPE_CLIENT';
+
+@Module({
+  providers: [{
+    provide: STRIPE,
+    useFactory: (cfg: ConfigService) => new Stripe(cfg.get('STRIPE_KEY')),
+    inject: [ConfigService],
+  }],
+  exports: [STRIPE],
+})
+export class PaymentsModule {}
+
+@Injectable()
+export class CheckoutService {
+  constructor(@Inject(STRIPE) private readonly stripe: Stripe) {}
+}
+```
+
+`forwardRef(() => X)` is a last resort, not a fix — it works around a circular dependency that usually signals two modules that should share a third. Reach for the refactor first; if you must, `forwardRef` goes on *both* sides. See the anti-patterns table.
+
+## Provider scopes
+
+| Scope | Lifetime | Use when |
+|-------|----------|----------|
+| `DEFAULT` | Singleton (one per app) | Almost always — stateless services |
+| `REQUEST` | New instance per request | You genuinely need per-request state (`@Inject(REQUEST)` for the live request) |
+| `TRANSIENT` | New instance per consumer | Each injector gets its own copy |
+
+REQUEST scope **bubbles up**: any provider that injects a request-scoped provider becomes request-scoped too, and so does the controller — with a real per-request instantiation cost. Default to singleton; reach for REQUEST only when you must.
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class RequestContext {
+  constructor(@Inject(REQUEST) private readonly req: Request) {}
+  get userId() { return this.req.user?.id; }
+}
+```
+
+The classic gotcha: a request-scoped provider injected into a **guard** reads as undefined or stale because guards run early and the scope propagation is not what you assumed. If a guard needs request data, pull it from `ExecutionContext` (`context.switchToHttp().getRequest()`), not from an injected request-scoped service.
+
+## Cross-cutting layer
+
+Pick the primitive by what it is *for*:
+
+| Primitive | Job | Signature |
+|-----------|-----|-----------|
+| Guard | Authorize — allow/deny the request | returns `boolean` / `Promise<boolean>` |
+| Interceptor | Wrap the handler before **and** after (logging, transform, timeout, cache) | RxJS, `handle().pipe(...)` |
+| Pipe | Validate and/or transform an input argument | returns transformed value or throws |
+| Exception filter | Catch a thrown error and shape the response | `catch(exception, host)` |
+
+Then pick the binding scope:
+
+| Binding | Reach | Can inject deps? |
+|---------|-------|------------------|
+| `APP_GUARD` / `APP_PIPE` / `APP_INTERCEPTOR` / `APP_FILTER` token in a module's `providers` | Global | **Yes** — resolved by the DI container |
+| `@UseGuards(X)` / `@UsePipes(X)` on controller or route | Local | Yes if you pass the class |
+| `app.useGlobalGuards(new X())` in `main.ts` | Global | **No** — you instantiated it yourself |
+
+The gotcha that bites everyone: `app.useGlobalPipes(new ValidationPipe())` works, but a guard or pipe that needs to inject a `ConfigService` **cannot** be registered with `new` — Nest never resolved it. Use the `APP_*` token instead so the container builds it:
+
+```typescript
+// Good — global AND DI-capable
+@Module({
+  providers: [{ provide: APP_GUARD, useClass: AuthGuard }],
+})
+export class AppModule {}
+```
+
+Deeper material — `ExecutionContext`, custom param decorators, `Reflector` + `SetMetadata` for role/`@Public()` guards, transform/timeout interceptors, filter shape, multiple-binding order — is in `references/cross-cutting.md`.
+
+## Validation
+
+DTO + `ValidationPipe` + `class-validator`/`class-transformer`. The production-safe config:
+
+```typescript
+// main.ts
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,            // strip properties with no decorator
+  forbidNonWhitelisted: true, // 400 on unknown properties instead of silently dropping
+  transform: true,            // coerce payloads to DTO class instances (and primitives)
+}));
+```
+
+```typescript
+export class CreateOrderDto {
+  @IsString() @IsNotEmpty()
+  sku: string;
+
+  @IsInt() @Min(1)
+  quantity: number;
+}
+```
+
+If the pipe needs to inject something, bind it globally via `APP_PIPE` instead of `new` (same DI rule as above).
+
+## Testing
+
+`Test.createTestingModule({...}).compile()` returns a `TestingModule` you pull providers from. Decision line: **unit-test a provider with its collaborators mocked; e2e-test the wired app over HTTP.**
+
+Unit — mock the collaborators:
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  providers: [OrdersService],
+})
+  .overrideProvider(OrderRepository)
+  .useValue({ findById: vi.fn().mockResolvedValue(order) })
+  .compile();
+
+const service = moduleRef.get(OrdersService);
+```
+
+e2e — boot the real app and hit it with Supertest. **Replicate the global config from `main.ts`** (pipes, filters, guards) or the test passes while prod 400s:
+
+```typescript
+const app = moduleRef.createNestApplication();
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true })); // mirror main.ts
+await app.init();
+await request(app.getHttpServer()).post('/orders').send(body).expect(201);
+```
+
+`overrideGuard(AuthGuard).useValue({ canActivate: () => true })` lets an e2e test bypass auth. Full recipes — mocking a repo, request-scoped via `resolve()`, ConfigModule in tests, Vitest vs Jest — in `references/testing-recipes.md`.
+
+## Bootstrap & tooling
+
+- Scaffold with the CLI, not by hand: `nest g resource orders`, `nest g module orders`, `nest g service orders`. It wires the module registration for you.
+- **NestJS 11** is current (Jan 2025), requires **Node.js 20+**, and ships **Express v5** as the default HTTP adapter (Fastify remains an option).
+- Use the **SWC builder** for dev — roughly 20x faster builds and faster cold start than `tsc`. Keep `tsc` for type-checking in CI.
+- ESM is first-class in v11 (top-level await aligned with modern Node).
+- The official harness is moving toward **Vitest** (SWC-powered) alongside Jest; Jest is still fully supported and is what `nest new` historically scaffolds.
+
+## Anti-patterns
+
+| Anti-pattern | Why it hurts | Do instead |
+|--------------|--------------|------------|
+| God `AppModule` declaring every controller/provider | No boundaries; breeds circular deps; untestable | One feature module per bounded context, `exports` = public API |
+| `new OrdersService(repo)` inside a controller/service | Bypasses DI; same class becomes two unmocked instances | Constructor-inject; let the container build it |
+| Business logic in the controller | Controllers should map HTTP ↔ service calls only | Push logic into a provider; controller stays thin |
+| `Scope.REQUEST` by default | Bubbles up the chain, per-request cost, surprise undefined in guards | Default singleton; REQUEST only with a real reason |
+| `useGlobalPipes(new X())` for a pipe that needs deps | `new` is not DI-resolved; injected deps are undefined | Bind via `APP_PIPE` / `APP_GUARD` token in `providers` |
+| e2e test that skips `main.ts` globals | Green test, red prod — validation/filters not applied | Replicate global pipes/filters/guards in the e2e bootstrap |
+| `forwardRef` sprinkled to silence "circular dependency" | Hides the real coupling; fragile bootstrap order | Refactor to a shared module; `forwardRef` only as last resort, on both sides |
+
+## Verify
+
+Run `scripts/verify.sh [dir]` to statically catch DI bypasses without a Nest install. It hard-fails only on `new XxxService(...)` outside test files; everything else is a warning. Exits 0 on a clean or empty target.