@donotdev/cli 0.0.14 → 0.0.15

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

@@ -0,0 +1,234 @@
+# Setup: SOC2 Readiness
+
+**DoNotDev auto-enforces SOC2 baseline controls.** Zero config needed for the MVP. This guide covers advanced controls and audit verification.
+
+---
+
+## Zero-Config Baseline (Always On)
+
+When you wire `DndevSecurity` into your app, these controls activate automatically:
+
+| Control | Default | SOC2 Criteria |
+|---------|---------|---------------|
+| Structured audit logging (all CRUD + auth) | ✅ Automatic | CC7.1 |
+| Rate limiting (100 writes/min, 500 reads/min) | ✅ Automatic | CC6.6 |
+| Brute-force lockout (5 attempts → 15 min) | ✅ Automatic | CC6.1 |
+| Session timeout (8h idle) | ✅ Automatic | CC6.1 |
+| Field-level RBAC + visibility | ✅ Always on (entity config) | CC6.3 |
+| Supabase RLS / Firestore default-deny | ✅ By convention | CC6.3 |
+
+---
+
+## 1. Wire `DndevSecurity` (Required Once)
+
+```typescript
+// src/security.ts
+import { DndevSecurity } from '@donotdev/security/server';
+
+export const security = new DndevSecurity({
+  // Optional: override defaults
+  // rateLimit: { writesPerMin: 50, readsPerMin: 200 },
+  // lockout: { maxAttempts: 3, lockoutMs: 30 * 60 * 1000 },
+  // sessionTimeoutMs: 4 * 60 * 60 * 1000,
+
+  // Required for PII encryption (see § PII Encryption below)
+  // piiSecret: process.env.PII_SECRET,
+
+  // Optional: send anomaly alerts to your SIEM/Slack
+  // anomalyHandler: async (alert) => { await fetch(process.env.SIEM_WEBHOOK!, { method: 'POST', body: JSON.stringify(alert) }); },
+});
+```
+
+```typescript
+// src/main.ts (or app entry point)
+import { security } from './security';
+import { crudService } from './crud'; // your CrudService instance
+import { auth } from './auth';        // your SupabaseAuth or FirebaseSDK instance
+
+crudService.setSecurity(security);
+auth.setSecurity(security);
+```
+
+---
+
+## 2. PII Encryption (Opt-In — C1 Confidentiality)
+
+Required only for entities storing personal data (email, phone, SSN, health data, etc.).
+
+```typescript
+// entities/user.ts
+export const userEntity = defineEntity({
+  name: 'User',
+  collection: 'users',
+  security: {
+    piiFields: ['email', 'phone', 'dateOfBirth'], // Encrypted at rest with AES-256-GCM
+  },
+  fields: { /* ... */ },
+});
+```
+
+```bash
+# Add to .env (min 32 chars, generate with: openssl rand -hex 32)
+PII_SECRET=your-secret-key-min-32-chars-here
+```
+
+Pass to security:
+```typescript
+export const security = new DndevSecurity({
+  piiSecret: process.env.PII_SECRET,
+});
+```
+
+---
+
+## 3. MFA Enforcement (Opt-In — CC6.1)
+
+Enforce MFA for specific roles on sensitive entities:
+
+```typescript
+export const paymentEntity = defineEntity({
+  name: 'Payment',
+  collection: 'payments',
+  security: {
+    requireMfa: 'admin', // 'admin' | 'manager' | 'user'
+  },
+  fields: { /* ... */ },
+});
+```
+
+Enable MFA in your provider:
+- **Supabase:** Dashboard → Auth → Multi Factor Authentication → Enable TOTP
+- **Firebase:** Firebase Console → Authentication → Multi-factor Auth → Enable
+
+---
+
+## 4. Data Retention (Opt-In — P6 Privacy)
+
+```typescript
+export const auditLogEntity = defineEntity({
+  name: 'AuditLog',
+  collection: 'audit_logs',
+  security: {
+    retention: { days: 365 }, // Auto-flag records for purge after 1 year
+  },
+  fields: { /* ... */ },
+});
+```
+
+Run retention purge (e.g., in a scheduled Cloud Function):
+```typescript
+import { privacyManager } from '@donotdev/security/server';
+// privacyManager.shouldPurge(record.createdAt, retentionDays) → boolean
+```
+
+---
+
+## 5. Right to Erasure (GDPR Art. 17 / P8)
+
+```typescript
+import { DndevSecurity } from '@donotdev/security/server';
+
+// In your account deletion handler:
+await security.privacyManager.eraseUser(userId, async (uid) => {
+  // Your custom erasure logic per collection
+  await db.from('orders').update({ userId: null }).eq('userId', uid);
+  await db.from('profiles').delete().eq('id', uid);
+});
+```
+
+---
+
+## 6. Health Monitoring (Opt-In — A1 Availability)
+
+```typescript
+// src/client/health.ts
+import { HealthMonitor } from '@donotdev/security';
+
+const dbMonitor = new HealthMonitor({ failureThreshold: 3, successThreshold: 2, timeoutMs: 5000 });
+
+// Wrap all downstream DB calls through the circuit breaker
+export const safeQuery = (fn: () => Promise<unknown>) => dbMonitor.protect(fn);
+
+// Expose a health endpoint (Next.js example)
+// app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: dbMonitor.checkLiveness() });
+}
+```
+
+---
+
+## 7. Anomaly Detection (Opt-In — CC7.2)
+
+Triggered automatically when brute-force or bulk-delete thresholds are exceeded. Wire a handler to send alerts:
+
+```typescript
+export const security = new DndevSecurity({
+  anomalyHandler: async (alert) => {
+    // Send to Slack, PagerDuty, Datadog, etc.
+    await fetch(process.env.SLACK_WEBHOOK!, {
+      method: 'POST',
+      body: JSON.stringify({ text: `🚨 SOC2 Anomaly: ${alert.type} — ${alert.details}` }),
+    });
+  },
+});
+```
+
+---
+
+## 8. Audit Log Output
+
+Audit events write to `process.stdout` as NDJSON — pipe to your SIEM:
+
+```json
+{"timestamp":"2025-01-15T10:23:00.000Z","type":"crud.create","userId":"u_123","resource":"products","resourceId":"p_456","ip":"192.168.1.1"}
+{"timestamp":"2025-01-15T10:23:01.000Z","type":"auth.login.failure","userId":"unknown","resource":"auth","ip":"10.0.0.5","details":"brute_force_lockout"}
+```
+
+**Cloud Logging (Firebase / GCP):** Stdout is captured automatically.
+**Datadog:** Set `DD_LOGS_INJECTION=true` and pipe stdout to the Datadog agent.
+**Supabase:** Export `process.stderr` anomaly alerts to Logflare.
+
+---
+
+## SOC2 Readiness Check
+
+Run before any audit:
+
+```bash
+dn soc2                    # Scan current app
+dn soc2 --app my-app       # Scan specific app
+dn soc2 --json             # Machine-readable JSON output (CI/CD)
+dn soc2 --verbose          # Show details for passing checks too
+```
+
+**Exit codes:** `0` = all checks pass, `1` = one or more checks failed (CI-friendly).
+
+**Checks run:**
+
+| Check | Criteria | What It Looks For |
+|-------|----------|--------------------|
+| SecurityContext wired | CC6.1 | `DndevSecurity` in source |
+| PII encryption secret | C1 | `PII_SECRET` in env when `piiFields` defined |
+| Firestore default-deny | CC6.3 | `allow read, write: if false` in `firestore.rules` |
+| Supabase RLS | CC6.3 | `ENABLE ROW LEVEL SECURITY` in SQL migrations |
+| Audit logging | CC7.1 | `.audit()` / `AuditLogger` usage |
+| Rate limiting | CC6.6 | `rateLimit` / `DndevRateLimiter` usage |
+| Retention policies | P6 | `retention.days` in entity config |
+| Health monitoring | A1 | `HealthMonitor` or `/api/health` endpoint |
+| MFA enforcement | CC6.1 | `requireMfa` in sensitive entities |
+
+---
+
+## Coverage After Full Setup
+
+| SOC2 Criteria | Control | Status |
+|---------------|---------|--------|
+| CC6.1 Auth hardening | Lockout + session timeout + MFA | Framework-enforced |
+| CC6.3 Authorization | RBAC + field visibility + RLS/Firestore rules | Framework-enforced |
+| CC6.6 Rate limiting | Per-user sliding window | Framework-enforced |
+| CC7.1 Audit logging | All CRUD + auth events as NDJSON | Framework-enforced |
+| CC7.2 Anomaly detection | Auth failures + bulk ops threshold alerts | Opt-in handler |
+| A1 Availability | Circuit breaker + liveness probes | Opt-in `HealthMonitor` |
+| C1 Confidentiality | AES-256-GCM field encryption | Opt-in `piiFields` |
+| P1–P8 Privacy | Retention policies + right-to-erasure | Opt-in `retention` |

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

@@ -0,0 +1,124 @@
+# Setup: Supabase
+
+**From zero to a working Supabase backend: env, tables, RLS, and adapter behavior.**
+
+---
+
+## Step 1: Run Supabase Setup
+
+```bash
+dndev supabase:setup
+```
+
+This command:
+- Lets you choose the target app (if you have an `apps/` directory)
+- Asks for your **public** Supabase project URL and anon key
+- Writes `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` to your app's `.env`
+
+**We only ask for public credentials** (safe to ship in your client bundle). We never ask for the service_role key.
+
+Get URL and anon key from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
+
+---
+
+## Step 2: Generate Tables from Entities
+
+The framework can generate PostgreSQL migrations from your entity definitions (same source as the schema used by the app).
+
+```bash
+dn generate sql
+```
+
+**What it does:**
+- Discovers entities (e.g. in `entities/` or your configured `--entity-dir`)
+- For each entity: `CREATE TABLE` with columns mapped from field types (text, number, boolean, timestamptz, uuid, jsonb, etc.)
+- Adds technical columns: `id` (uuid, default `gen_random_uuid()`), `user_id`, `created_at`, `updated_at` (with `DEFAULT now()`), `created_by_id`, `updated_by_id`, `status`
+- Enables **Row Level Security (RLS)** and creates policies so rows are scoped by `auth.uid() = user_id`
+- Adds a trigger so `updated_at` is set automatically on every `UPDATE`
+
+**Options (optional):**
+- `--entity-dir <path>` — where to find entity files (default: from app root)
+- `--output-dir <path>` — where to write migrations (default: `supabase/migrations`)
+- `--no-single-file` — one migration file per entity instead of one combined file
+
+Output is written to `supabase/migrations/` (or your `--output-dir`) as a timestamped `.sql` file. Apply it with the Supabase CLI or Dashboard SQL editor.
+
+---
+
+## Step 3: Apply Migrations
+
+After generating SQL:
+
+**Option A — Supabase CLI (recommended)**
+
+```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.
+
+---
+
+## Step 4: Adapter Behavior (DB-Managed Timestamps)
+
+Tables use **snake_case** column names and **timestamptz** for `created_at` / `updated_at`. The framework expects **camelCase** and **ISO date strings** in the app.
+
+The **Supabase CRUD adapter** handles this automatically:
+
+| Direction | Behavior |
+|-----------|----------|
+| **Read** (get, query, subscribe) | Rows from Supabase are normalized: snake_case → camelCase (e.g. `created_at` → `createdAt`), and timestamp columns are converted to ISO strings. Your UI receives the same shape as with Firebase. |
+| **Write** (add, set, update) | The adapter does **not** send `createdAt` / `updatedAt` (or snake equivalents). The database sets them via `DEFAULT now()` and the `updated_at` trigger. |
+
+So you never set timestamps in app code when using Supabase — the DB owns them.
+
+---
+
+## Environment Variables
+
+**Client (Vite):** in `apps/<app>/.env`
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_SUPABASE_URL` | Project URL (public) |
+| `VITE_SUPABASE_ANON_KEY` | Anon key (public, safe in bundle) |
+
+**Server (e.g. API routes, Edge Functions):** 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.).
+
+See [ENV_SETUP.md](./ENV_SETUP.md) for where to put secrets.
+
+---
+
+## Storage (Optional)
+
+If your app uploads files, create a storage bucket in the Supabase Dashboard (e.g. `uploads`). The default bucket name used by the framework is `uploads`. Configure public or RLS policies in the Dashboard as needed.
+
+---
+
+## Hosting the frontend
+
+Supabase gives you **Auth, Postgres, Storage, and Edge Functions**. It does **not** host your built frontend (Vite/Next SPA). You need a separate host for the `dist/` output.
+
+**We recommend:**
+
+- **Vercel** — Connect your repo, set `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` in the project env, then deploy. Good fit for Next.js or Vite.
+- We scaffold **vercel.json**; run `dndev deploy` and choose Frontend (Vercel) or Frontend + Edge Functions. Set `VITE_SUPABASE_*` in Vercel project env.
+
+**Deploy:** Frontend goes to Vercel (scaffolded vercel.json); Edge Functions to Supabase. It does **not** deploy your Supabase app’s frontend to Vercel/Netlify. For that, use the host’s dashboard or CLI (e.g. `vercel`, `netlify deploy`) after building. See [ENV_SETUP.md](./ENV_SETUP.md) for production env vars on Vercel.
+
+---
+
+## Local Development
+
+- **Against hosted Supabase:** After `supabase:setup`, run `bun dev` — the app talks to your Supabase project.
+- **Local Supabase:** Install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `supabase start` for a local Postgres + Auth + Storage stack. Point `VITE_SUPABASE_URL` and keys to the local instance.
+
+---
+
+## Summary
+
+**`dndev supabase:setup`** → paste URL + anon key → **`dn generate sql`** → apply migrations → **`bun dev`**. The adapter normalizes read (snake→camel, ISO) and leaves timestamps to the DB on write.

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

@@ -1,12 +1,16 @@
 # Setup: Themes
 
-**Most is pre-configured.** Override CSS variables in `src/themes.css`. Framework handles theme switching, auto-computed colors.
+**Single source of truth:** `src/themes.css`. Import it from `globals.css`; do not set font/color overrides in globals. Framework handles theme switching.
+
+**Default essence = SaaS** (Inter, neutral). Optional essences (Brutalist, Luxury) are in the scaffold; they do **not** apply until you set the class on `<html>` (e.g. `class="brutalist"`) or use the theme switcher.
+
+**Reference:** Copy Brutalist/Luxury blocks from `guides/dndev/essences_reference.css` into your `src/themes.css` if you need them. Default-essence fonts (Inter, Space Grotesk, Playfair, Roboto) are bundled via `@donotdev/ui`; no Google Fonts, no `public/fonts/` required.
 
 ---
 
 ## Standard Use
 
-**File:** `src/themes.css` (scaffolded with all variables)
+**File:** `src/themes.css` (scaffolded with light, dark, and optional Brutalist/Luxury)
 
 **Override colors:**
 ```css

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

@@ -0,0 +1,176 @@
+# Setup: Vercel
+
+**From zero to deployed: Vercel hosting + API routes with Firebase data layer.**
+
+---
+
+## Architecture
+
+Vercel is your **hosting and API platform** — it serves your frontend and runs serverless API routes.
+Firebase is your **data layer** — Firestore (CRUD), Firebase Auth (users), Firebase Storage (files).
+
+The framework generates API routes as Vercel Serverless Functions that talk to Firebase on the backend.
+
+---
+
+## Step 1: Create Firebase Project (Data Layer)
+
+Even though you deploy to Vercel, you still need Firebase for data.
+
+1. Go to [Firebase Console](https://console.firebase.google.com) → Create a project
+2. Enable **Authentication** → Email/Password (+ OAuth providers if needed)
+3. Enable **Cloud Firestore** → Create Database → select region
+4. Enable **Storage** if your app uploads files
+
+Get the Firebase web config from: **Project Settings → General → Your apps → Web app → SDK config**.
+
+---
+
+## Step 2: Run Setup
+
+```bash
+dndev firebase:setup
+```
+
+This writes Firebase SDK config to your app's `.env`. The `overlay-vercel` providers.ts initializes the Firebase client SDK.
+
+---
+
+## Step 3: Configure Vercel
+
+1. Create a [Vercel](https://vercel.com) account and link your Git repo
+2. Import the project in Vercel Dashboard
+3. Set the **Root Directory** to `apps/<your-app>` (or leave blank if monorepo auto-detected)
+4. Set **Framework Preset** to Vite (or Next.js if using Next)
+
+**Environment Variables** (in Vercel Dashboard → Settings → Environment Variables):
+
+Copy your Firebase vars from `.env`:
+- `VITE_FIREBASE_API_KEY`
+- `VITE_FIREBASE_PROJECT_ID`
+- `VITE_FIREBASE_AUTH_DOMAIN`
+- `VITE_FIREBASE_STORAGE_BUCKET`
+- `VITE_FIREBASE_MESSAGING_SENDER_ID`
+- `VITE_FIREBASE_APP_ID`
+
+For Next.js apps, use `NEXT_PUBLIC_` prefix instead of `VITE_`.
+
+**Server secrets** (for API routes):
+- `STRIPE_SECRET_KEY`
+- `STRIPE_WEBHOOK_SECRET`
+- Any OAuth client secrets
+
+---
+
+## Step 4: API Routes (Functions)
+
+Your backend functions are in `functions/` and deploy as Vercel Serverless Functions.
+
+```
+functions/
+├── src/
+│   ├── auth/        # Auth endpoints (signup, login, etc.)
+│   ├── billing/     # Stripe endpoints (checkout, webhook, etc.)
+│   ├── crud/        # CRUD endpoints (create, read, update, delete)
+│   └── oauth/       # OAuth callback handlers
+├── vercel.json      # Route configuration
+├── tsconfig.json
+└── package.json
+```
+
+Functions use the Firebase Admin SDK on the server side to access Firestore, verify auth tokens, etc.
+
+---
+
+## Step 5: Deploy
+
+**Option A — Git push (recommended)**
+
+Push to your connected branch. Vercel auto-deploys.
+
+```bash
+git push origin main
+```
+
+**Option B — Vercel CLI**
+
+```bash
+npx vercel --prod
+```
+
+---
+
+## Environment Variables
+
+| File | What Goes Here | Loaded By |
+|------|---------------|-----------|
+| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key | Vite/Next.js (dev + build) |
+| `apps/<app>/.env.local` | Local overrides (gitignored) | Vite/Next.js (overrides .env) |
+| `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
+| `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | API routes runtime |
+| Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
+
+**Client vars** (browser-safe): `VITE_*` or `NEXT_PUBLIC_*` prefix.
+**Server vars** (secrets): No prefix needed in Vercel Dashboard — only accessible in API routes.
+
+---
+
+## Local Development
+
+```bash
+bun dev
+```
+
+The app runs locally, talking to your Firebase project. API routes can be tested with:
+
+```bash
+vercel dev
+```
+
+Or use Firebase emulators for fully local development:
+
+```bash
+dndev emu start
+```
+
+---
+
+## Secrets
+
+Server-side secrets go in `functions/.env` locally and in Vercel Dashboard for production.
+
+**We NEVER ask for secret keys.** You place them yourself:
+
+```bash
+# functions/.env
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Then add the same values in Vercel Dashboard → Settings → Environment Variables.
+
+See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+
+---
+
+## Troubleshooting
+
+**"Firebase config not loading"**
+→ Check `.env` is in your **app directory** (`apps/<app>/.env`), not repo root
+→ Vite vars must start with `VITE_`, Next.js vars with `NEXT_PUBLIC_`
+
+**"401 / Permission denied on API routes"**
+→ Check Firebase service account key is configured in Vercel env vars
+→ Verify `GOOGLE_APPLICATION_CREDENTIALS` or inline credentials in API routes
+
+**"CORS error"**
+→ Vercel handles CORS for same-origin requests automatically
+→ For cross-origin: add CORS headers in your API route handler
+
+**"Build fails on Vercel"**
+→ Check Root Directory is set to your app directory
+→ Ensure `package.json` has correct `build` script
+
+---
+
+**`dndev firebase:setup` → configure Vercel project → set env vars → `git push`. Vercel deploys automatically.**

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

@@ -226,18 +226,14 @@ navigate('/products', {
 
 ### 5. Query Parameters
 
-**✅ Use framework useSearchParams:**
+**✅ Use framework useSearchParams (read-only, returns URLSearchParams directly):**
 ```tsx
 import { useSearchParams } from '@donotdev/ui/routing';
 
 function ProductList() {
-  const [searchParams, setSearchParams] = useSearchParams();
+  const searchParams = useSearchParams();
   const page = searchParams.get('page') || '1';
-  
-  const handlePageChange = (newPage: string) => {
-    setSearchParams({ page: newPage });
-  };
-  
+
   return <div>Page: {page}</div>;
 }
 ```
@@ -478,8 +474,8 @@ navigate('/products', { replace: true });
 // Route params
 const id = useRouteParam('id');
 
-// Query params
-const [searchParams, setSearchParams] = useSearchParams();
+// Query params (read-only, returns URLSearchParams directly)
+const searchParams = useSearchParams();
 const page = searchParams.get('page');
 
 // Navigation menu