@donotdev/cli 0.0.20 → 0.0.21

package/templates/root-consumer/guides/dndev/ENV_SETUP.md.example

@@ -58,9 +58,9 @@ dndev coach
 
 Prints a numbered checklist: which dashboard to visit, what to copy, where to paste it. No automation, no prompts.
 
-### 2. Fill in .env values
+### 2. Fill in credentials
 
-Follow the coach checklist. Paste credentials from your provider dashboards into the appropriate `.env` files.
+Follow the coach checklist. Paste **public** credentials into `apps/<app>/.env`, and **secret** keys into `.dndev.secrets` at project root.
 
 ### 3. Run setup
 
@@ -126,16 +126,19 @@ These are safe to share, shipped in your client JS bundle. We ask for them durin
 | Supabase anon key (public JWT) | `apps/<app>/.env` as `VITE_SUPABASE_ANON_KEY` |
 | Stripe publishable key | `apps/<app>/.env` as `VITE_STRIPE_PUBLISHABLE_KEY` |
 
-### Tier 2: Secret Keys -- We NEVER Ask, We Tell You Where To Put Them
+### Tier 2: Secret Keys -- One File, Project Root
 
-These are server-side only. We never prompt for them, never store them in client code.
+All secret keys go in **`.dndev.secrets`** at project root (gitignored). One file, every secret.
 
-| Key | Where It Goes | How To Get It |
-|-----|--------------|---------------|
-| Stripe secret key | `functions/.env` as `STRIPE_SECRET_KEY` | https://dashboard.stripe.com/apikeys |
-| Stripe webhook secret | `functions/.env` as `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard -> Webhooks |
-| Supabase service_role key | `functions/.env` as `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard -> Settings -> API |
-| OAuth client secrets | `functions/.env` as `*_CLIENT_SECRET` | Provider dashboard |
+| Key | How To Get It |
+|-----|---------------|
+| `VERCEL_TOKEN` | https://vercel.com/account/tokens |
+| `SUPABASE_SECRET_KEY` | Supabase Dashboard → Settings → API |
+| `SUPABASE_ACCESS_TOKEN` | https://supabase.com/dashboard/account/tokens |
+| `STRIPE_SECRET_KEY` | https://dashboard.stripe.com/apikeys |
+| `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard → Webhooks |
+
+Resolution order: `process.env` (CI) → `.dndev.secrets` (local) → legacy paths (with warning).
 
 Then sync to your runtime:
 
@@ -157,25 +160,25 @@ These files are `.gitignored`. Never commit them. For CI/CD, upload the file con
 
 ## Environment Variables
 
-**Each app has its own `.env`.** Vite loads from the app directory only.
+**Public config** lives in each app's `.env`. **Secrets** live in `.dndev.secrets` at project root.
 
 ```
 my-project/
-+-- .env.example              <-- NOT loaded by Vite (reference only)
++-- .dndev.secrets            <-- ALL secrets (gitignored)
++-- .dndev.secrets.example    <-- Template (committed)
 +-- apps/
 |   +-- my-app/
-|       +-- .env              <-- Vite reads THIS (public keys: VITE_*)
-|       +-- .env.local        <-- Overrides .env (gitignored)
+|       +-- .env              <-- Public keys: VITE_*, VERCEL_ORG_ID, VERCEL_PROJECT_ID
 |       +-- .env.staging      <-- Used by dndev staging
 |       +-- .env.production   <-- Production overrides
-+-- functions/
-    +-- .env                  <-- Server secrets (Stripe, OAuth, service_role)
+|       +-- service-account-key.json  <-- Firebase SA (gitignored)
 ```
 
 **Rules:**
-- `VITE_*` / `NEXT_PUBLIC_*` vars -> `apps/<app>/.env` (public, shipped to browser)
-- Server secrets -> `functions/.env` (never exposed to client)
-- Service account files -> app root, gitignored
+- `VITE_*` / `NEXT_PUBLIC_*` vars → `apps/<app>/.env` (public, shipped to browser)
+- `VERCEL_ORG_ID` / `VERCEL_PROJECT_ID` → `apps/<app>/.env` (public, per-app)
+- All secret keys → `.dndev.secrets` at project root (one file, gitignored)
+- Service account files → app root, gitignored
 
 ---
 
@@ -190,7 +193,7 @@ my-project/
 | `dndev doctor` | Check project health (providers, .env) |
 | `dndev deploy` | **Firebase:** hosting + functions + rules. **Supabase:** deploys frontend to [Vercel](https://vercel.com) (via scaffolded vercel.json) and Edge Functions to Supabase. Set `VITE_SUPABASE_*` in Vercel project env. |
 | `dndev staging` | Deploy to staging environment |
-| `dndev sync-secrets` | Push functions/.env to runtime (Firebase/Vercel) |
+| `dndev sync-secrets` | Push .dndev.secrets to runtime (Firebase/Vercel) |
 | `dndev sync-secrets --target github` | Push secrets to GitHub Secrets (CI/CD) |
 | `bun test` | Run tests (after Phase 4) |
 | `bun run type-check` | TypeScript validation |

package/templates/root-consumer/guides/dndev/INDEX.md.example

@@ -14,6 +14,7 @@
 - [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev coach` → `dndev setup`)
 - [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev coach` → `dndev setup`)
 - [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
+- [SETUP_CICD.md](./SETUP_CICD.md) - CI/CD setup (`dndev setup-cicd` → GitHub Actions)
 
 ---
 

package/templates/root-consumer/guides/dndev/SETUP_BILLING.md.example

@@ -8,16 +8,12 @@
 
 **Environment:**
 ```bash
-# .env (frontend)
+# apps/<app>/.env (frontend, public)
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
 
-# functions/.env.local (local)
+# .dndev.secrets (project root, gitignored)
 STRIPE_SECRET_KEY=sk_test_xxx
-STRIPE_WEBHOOK_SECRET=whsec_xxx  # From 'stripe listen'
-
-# functions/.env (production)
-STRIPE_SECRET_KEY=sk_live_xxx
-STRIPE_WEBHOOK_SECRET=whsec_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx  # From 'stripe listen' or Stripe Dashboard → Webhooks
 ```
 
 **Stripe Dashboard:** Create products, copy Price IDs (`price_...`)

package/templates/root-consumer/guides/dndev/SETUP_CICD.md.example

@@ -0,0 +1,115 @@
+# Setup: CI/CD
+
+**One command to set up GitHub Actions: secrets, workflows, staging.**
+
+---
+
+## Prerequisites
+
+1. **GitHub CLI** installed and authenticated:
+   ```bash
+   gh auth login
+   ```
+2. **Git remote** pointing to your GitHub repository
+3. **`.dndev.secrets`** at project root with private tokens:
+   ```env
+   GH_PAT=ghp_your_personal_access_token
+   VERCEL_TOKEN=your_vercel_token        # if using Vercel
+   SUPABASE_ACCESS_TOKEN=your_token      # if using Supabase
+   ```
+4. **Service account key** (Firebase projects):
+   - `service-account-key.json` in your app directory
+   - `service-account-key.staging.json` for staging (optional)
+
+---
+
+## Quick Start
+
+```bash
+dndev setup-cicd
+```
+
+The command will:
+1. Detect your app and providers (Firebase, Vercel, Supabase)
+2. Show a plan of secrets to upload and workflows to generate
+3. Upload all secrets to GitHub
+4. Write `.github/workflows/ci.yml`, `deploy.yml`, and optionally `deploy-staging.yml`
+
+---
+
+## Options
+
+```bash
+dndev setup-cicd --app web       # Target specific app
+dndev setup-cicd --dry-run       # Preview without uploading or writing
+```
+
+---
+
+## What Gets Created
+
+### Secrets (uploaded to GitHub)
+
+| Secret | Source | When |
+|--------|--------|------|
+| `GH_PAT` | `.dndev.secrets` | Always (private dndev checkout) |
+| `FIREBASE_SERVICE_ACCOUNT` | `service-account-key.json` (base64) | Firebase projects |
+| `FIREBASE_SERVICE_ACCOUNT_STAGING` | `service-account-key.staging.json` (base64) | If staging detected |
+| `VERCEL_TOKEN` | `.dndev.secrets` | Vercel projects |
+| `VERCEL_ORG_ID` | `.env` | Vercel projects |
+| `VERCEL_PROJECT_ID` | `.env` | Vercel projects |
+| `SUPABASE_ACCESS_TOKEN` | `.dndev.secrets` | Supabase projects |
+| `SUPABASE_PROJECT_REF` | Extracted from `VITE_SUPABASE_URL` | Supabase projects |
+| `VITE_*` / `NEXT_PUBLIC_*` | `.env` | Public build vars |
+
+### Workflows
+
+| File | Trigger | What it does |
+|------|---------|-------------|
+| `ci.yml` | Push + PR to main | Checkout, install, typecheck, test |
+| `deploy.yml` | Push to main | Build + deploy to detected providers |
+| `deploy-staging.yml` | Push to staging/develop | Same as deploy, using staging credentials |
+
+---
+
+## Staging Support
+
+Staging is auto-detected if:
+- `.firebaserc` contains a `staging` project alias
+- `service-account-key.staging.json` exists
+
+To enable staging manually:
+
+1. Add staging alias to `.firebaserc`:
+   ```json
+   {
+     "projects": {
+       "default": "my-app-prod",
+       "staging": "my-app-staging"
+     }
+   }
+   ```
+2. Download the staging service account key as `service-account-key.staging.json`
+3. Re-run `dndev setup-cicd`
+
+---
+
+## Troubleshooting
+
+**"Could not detect GitHub repository"**
+→ Ensure `git remote -v` shows a GitHub URL.
+
+**Missing secrets warning**
+→ Add the missing values to `.dndev.secrets` or `.env` and re-run.
+
+**"gh: not found"**
+→ Install GitHub CLI: https://cli.github.com/
+
+---
+
+## See Also
+
+- [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) — Firebase setup
+- [SETUP_VERCEL.md](./SETUP_VERCEL.md) — Vercel setup
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) — Supabase setup
+- [ENV_SETUP.md](./ENV_SETUP.md) — Environment variables

package/templates/root-consumer/guides/dndev/SETUP_CRUD.md.example

@@ -164,6 +164,47 @@ See `lookup_symbol("registerScopeProvider")`.
 
 ---
 
+## 7. Data Fetching & Pagination
+
+### Default: Auto Mode (zero config)
+
+```tsx
+<EntityList entity={productEntity} />
+```
+
+That's it. The framework handles pagination automatically:
+
+1. **First fetch** — loads up to 1000 items client-side (instant search, sort, filter in the browser)
+2. **If total > 1000** — auto-switches to server pagination (fetches one page at a time via cursor)
+
+You never need to configure pagination mode. It just works.
+
+### Forcing a Mode (rare)
+
+| Mode | Behavior | When to force |
+|------|----------|---------------|
+| `pagination='auto'` (default) | Client-side up to 1000, auto-switches to server if more | Never — this is the default |
+| `pagination='client'` | Always client-side, fetches all | You know the dataset is small and want instant filters |
+| `pagination='server'` | Always server-side, cursor pagination | You know the dataset is huge and want minimal fetch |
+
+```tsx
+// Force server pagination with custom page size
+<EntityList entity={productEntity} pagination="server" pageSize={50} />
+```
+
+### What Changes When Auto-Switches to Server
+
+| Feature | Client mode (< 1000) | Server mode (> 1000) |
+|---------|----------------------|----------------------|
+| Search | Instant (in-memory) | Re-fetches per query |
+| Sort | Instant | Re-fetches |
+| Filters | Instant | Re-fetches |
+| Page navigation | Instant | Fetches next page |
+
+Server mode fetches only `pageSize` items per request — not the whole collection.
+
+---
+
 ## What's Available
 
 ### Components (`@donotdev/ui`)

package/templates/root-consumer/guides/dndev/SETUP_SUPABASE.md.example

@@ -12,9 +12,12 @@ dndev coach
 
 This prints a numbered checklist of what to configure. For Supabase, you'll need:
 - **Project URL** and **public key** → paste into your app's `.env`
-- **service_role key** → paste into `supabase/functions/.env`
+- **service_role key** → paste into `.dndev.secrets` at project root
+- **Access token** → paste into `.dndev.secrets` (needed for DB migrations via Management API)
 
-Get these from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
+Where to get them:
+- URL + public key + service_role key: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**
+- Access token: [supabase.com/dashboard/account/tokens](https://supabase.com/dashboard/account/tokens) (account-level, not project-level)
 
 Then run setup to validate and automate:
 
@@ -22,7 +25,7 @@ Then run setup to validate and automate:
 dndev setup
 ```
 
-Setup validates your .env values are present, links the Supabase CLI, generates SQL migrations, and runs an inline health check.
+Setup validates your credentials, generates SQL migrations from entities, and pushes them via the Supabase Management API (HTTPS — no CLI needed).
 
 ---
 
@@ -49,19 +52,11 @@ Output is written to `supabase/migrations/` as a timestamped `.sql` file.
 
 ## Step 3: Apply Migrations
 
-After generating SQL:
+`dndev setup` pushes migrations automatically via the Supabase Management API. No CLI needed.
 
-**Option A — Supabase CLI (recommended)**
+If you prefer to apply manually:
 
-```bash
-supabase db push
-```
-
-(or `supabase migration up` if you manage migrations locally)
-
-**Option B — Dashboard**
-
-Copy the contents of the generated migration file into the SQL Editor in the Supabase Dashboard and run it.
+**Dashboard SQL Editor** — Copy the generated `.sql` file contents from `supabase/migrations/` into the SQL Editor in the Supabase Dashboard and run it.
 
 ---
 
@@ -162,7 +157,7 @@ You never set timestamps in app code — the DB owns them.
 | `VITE_SUPABASE_URL` | Project URL (public) |
 | `VITE_SUPABASE_PUBLIC_KEY` | Public key (safe in bundle) |
 
-**Server (Edge Functions, API routes):** use the same URL and `SUPABASE_SERVICE_ROLE_KEY` for admin operations. Never expose the service_role key to the client. Put it in `functions/.env` or your host's env (Vercel, etc.).
+**Server (Edge Functions, API routes):** use the same URL and `SUPABASE_SECRET_KEY` for admin operations. Never expose the service_role key to the client. Put it in `.dndev.secrets` at project root (or your host's env for production).
 
 See [ENV_SETUP.md](./ENV_SETUP.md) for the full secrets policy.
 
@@ -205,16 +200,16 @@ Or install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `sup
 ## Troubleshooting
 
 **"Table not found" / "relation does not exist"**
-→ Run `dndev setup` (generates SQL) then apply migrations with `supabase db push`
+→ Run `dndev setup` — it generates SQL and pushes via Management API. Or copy the SQL from `supabase/migrations/` into the Dashboard SQL Editor.
 
 **"Permission denied" / RLS errors**
 → Check RLS policies in Supabase Dashboard → Database → Policies
 → Generated migrations include default policies — verify they were applied
 
 **"Service role key" errors in functions**
-→ Put `SUPABASE_SERVICE_ROLE_KEY` in `functions/.env` (never in `VITE_*` vars)
+→ Put `SUPABASE_SECRET_KEY` in `.dndev.secrets` at project root (never in `VITE_*` vars)
 → Get it from Supabase Dashboard → Settings → API
 
 ---
 
-**`dndev coach` → fill .env → `dndev setup` → apply migrations → `dndev dev`. The adapter normalizes everything automatically.**
+**`dndev coach` → fill `.env` + `.dndev.secrets` → `dndev setup` → `dndev dev`. The adapter normalizes everything automatically.**

package/templates/root-consumer/guides/dndev/SETUP_VERCEL.md.example

@@ -29,24 +29,28 @@ The framework scaffolds `vercel.json` with CSP headers, rewrites, and caching ru
 
 ---
 
-## Step 2: Add Credentials to `.env.local`
+## Step 2: Add Credentials
 
-Add these 3 values to `apps/<your-app>/.env.local`:
+**Secret (shared across apps):** add to `.dndev.secrets` at project root:
 
 ```env
-# Vercel Deployment Credentials (gitignored — never commit these)
 VERCEL_TOKEN=your_vercel_token
+```
+
+**Per-app (public):** add to `apps/<your-app>/.env`:
+
+```env
 VERCEL_ORG_ID=your_team_id
 VERCEL_PROJECT_ID=your_project_id
 ```
 
 **Where to find them:**
 
-| Variable | Where |
-|----------|-------|
-| `VERCEL_TOKEN` | [vercel.com/account/tokens](https://vercel.com/account/tokens) — scope to your team |
-| `VERCEL_ORG_ID` | Vercel Dashboard → Settings → General → **Team ID** |
-| `VERCEL_PROJECT_ID` | Vercel Dashboard → Your Project → Settings → General → **Project ID** |
+| Variable | Where | File |
+|----------|-------|------|
+| `VERCEL_TOKEN` | [vercel.com/account/tokens](https://vercel.com/account/tokens) — scope to your team | `.dndev.secrets` |
+| `VERCEL_ORG_ID` | Vercel Dashboard → Settings → General → **Team ID** | `apps/<app>/.env` |
+| `VERCEL_PROJECT_ID` | Vercel Dashboard → Your Project → Settings → General → **Project ID** | `apps/<app>/.env` |
 
 That's it. No `vercel login`, no `vercel link`, no interactive prompts.
 
@@ -156,8 +160,8 @@ Available: auth (claims, status, delete account), billing (checkout, cancel, por
 
 | File | What Goes Here | Loaded By |
 |------|---------------|-----------|
-| `apps/<app>/.env` | Public keys (backend config, license key, Stripe publishable) | Vite/Next.js (dev + build) |
-| `apps/<app>/.env.local` | Secrets: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` (gitignored) | `dndev deploy` |
+| `.dndev.secrets` | `VERCEL_TOKEN` (gitignored) | `dndev deploy` |
+| `apps/<app>/.env` | Public keys + `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` | Vite/Next.js + `dndev deploy` |
 | `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
 | Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
 
@@ -193,7 +197,8 @@ dndev emu start
 ## Troubleshooting
 
 **"Missing Vercel credentials"**
-→ Check `apps/<app>/.env.local` has all 3 vars: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`
+→ Check `VERCEL_TOKEN` is in `.dndev.secrets` at project root
+→ Check `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` are in `apps/<app>/.env`
 → Run `dndev setup` to validate
 
 **"Build fails on Vercel"**
@@ -211,4 +216,4 @@ dndev emu start
 
 ---
 
-**3 values in `.env.local` → `dndev deploy` → done.**
+**Token in `.dndev.secrets` + IDs in `.env` → `dndev deploy` → done.**