@donotdev/cli 0.0.14 → 0.0.15

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

@@ -335,24 +335,6 @@ import { StartChallengeForm } from '@donotdev/adv-comps';
 />
 ```
 
-### Waterfall
-
-Waterfall component with lazy loading built-in. Features clean cascade layout with diagonal staircase effect, perfect for step-by-step processes or feature showcases.
-
-```tsx
-import { Waterfall } from '@donotdev/adv-comps';
-import type { WaterfallProps } from '@donotdev/adv-comps';
-
-<Waterfall
-  items: ComponentData[]
-  className?: string
-  connectorClassName?: string
-  density?: 'compact' | 'comfortable'
-  ariaLabel?: string
-  direction?: 'horizontal' | 'descending'
-/>
-```
-
 ## Notes
 
 - All components are lazy-loaded by default for optimal performance

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

@@ -83,7 +83,7 @@
 - **usePrefetch** - Prefetch route data.
 - **useLocation** - Get current location.
 - **useParams** - Get route parameters.
-- **useSearchParams** - Get URL search parameters.
+- **useSearchParams** - Get URL search parameters. Returns `URLSearchParams` directly (NOT a tuple). Use `.get('key')` to read values.
 - **useMatch** - Match current route pattern.
 - **useQueryParams** - Get and set query parameters.
 - **useRedirectGuard** - Guard against redirects.

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

@@ -2,16 +2,20 @@
 
 **The complete onboarding flow — from `dndev init` to deployed app.**
 
+If you haven’t run `dndev init` yet, see [AGENT_START_HERE.md](./AGENT_START_HERE.md) § **Getting started (for humans)** (P0 → Install CLI → Run AI.md → Enjoy).
+
 ---
 
 ## The Flow
 
 ```
-bun install                    → install dependencies
-bun dev                        → start app, read the homepage setup guide
-dndev firebase:setup           → configure Firebase project + .env
-dndev emu start                → test locally with emulators
-dndev deploy                   → deploy to production
+bun install                    -> install dependencies
+bun dev                        -> start app, read the homepage setup guide
+dndev firebase:setup           -> configure Firebase project + .env
+  -- or --
+dndev supabase:setup           -> configure Supabase project + .env
+dndev emu start                -> test locally with emulators (Firebase)
+dndev deploy                   -> deploy to production
 ```
 
 ---
@@ -43,29 +47,45 @@ git push -u origin main
 
 ---
 
-## Step 3: Firebase
+## Step 3: Backend Setup
+
+### Firebase
 
 ```bash
 dndev firebase:setup
 ```
 
-Automates: project selection/creation, web app, SDK config → `.env`, `.firebaserc`.
+Automates: project selection/creation, web app, SDK config -> `.env`, `.firebaserc`.
 
 Then 2 manual steps (CLI gives you direct links):
-1. Download service account key → save as `service-account-key.json`
+1. Download service account key -> save as `service-account-key.json`
 2. Enable Auth + Firestore in Firebase Console
 
 See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
 
+### Supabase
+
+```bash
+dndev supabase:setup
+```
+
+Asks for your **public** project URL and anon key (both safe to share -- shipped in client bundle).
+
+Get them from: https://supabase.com/dashboard -> your project -> Settings -> API
+
+See [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) for full details (tables, RLS, `dn generate sql`). See [Secrets Philosophy](#secrets-philosophy) for how we handle secret keys.
+
 ---
 
 ## Step 4: Test Locally
 
 ```bash
-dndev emu start
+dndev emu start          # Firebase emulators
 ```
 
-Select Auth + Firestore + Functions. Develops against local emulators.
+Select services: Auth + Firestore + Functions. This starts Firebase emulators so you can develop without touching production.
+
+For Supabase, development runs against your Supabase project directly (or use `supabase start` for local Supabase if installed).
 
 ---
 
@@ -74,11 +94,11 @@ Select Auth + Firestore + Functions. Develops against local emulators.
 Open the project in **Cursor**, **Claude Code**, **Windsurf**, or **AntiGravity**.
 
 The AI reads `AI.md` and follows the WAI-WAY protocol:
-- Phase 0: Brainstorm → produce a spec
-- Phase 1: Scaffold → create pages
-- Phase 2: Entities → define data models
-- Phase 3: Compose → build pages with components
-- Phase 4: Configure → generate tests, firestore rules, CI/CD
+- Phase 0: Brainstorm -> produce a spec
+- Phase 1: Scaffold -> create pages
+- Phase 2: Entities -> define data models
+- Phase 3: Compose -> build pages with components
+- Phase 4: Configure -> generate tests, firestore rules, CI/CD
 
 Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 
@@ -90,7 +110,51 @@ Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 dndev deploy
 ```
 
-Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
+Deploys hosting + functions + rules. Syncs runtime secrets automatically before deploying functions.
+
+---
+
+## Secrets Philosophy
+
+**DoNotDev follows strict rules about credentials:**
+
+### Tier 1: Public Keys -- We Ask Directly
+
+These are safe to share, shipped in your client JS bundle. We ask for them during setup.
+
+| Key | Where It Goes |
+|-----|--------------|
+| Firebase API key, project ID, auth domain, etc. | `apps/<app>/.env` as `VITE_FIREBASE_*` |
+| Supabase project URL | `apps/<app>/.env` as `VITE_SUPABASE_URL` |
+| 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
+
+These are server-side only. We never prompt for them, never store them in client code.
+
+| 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 |
+
+Then sync to your runtime:
+
+```bash
+dndev sync-secrets                    # -> Firebase Secret Manager or Vercel env
+dndev sync-secrets --target github    # -> GitHub Secrets (for CI/CD)
+```
+
+### Tier 3: Service Account Files -- Download, Place, Gitignore
+
+| File | Where It Goes | How To Get It |
+|------|--------------|---------------|
+| `service-account-key.json` | App root (next to firebase.json) | Firebase Console -> Settings -> Service Accounts |
+| `service-account-key.staging.json` | Same location, for staging | Same, from staging project |
+
+These files are `.gitignored`. Never commit them. For CI/CD, upload the file content as a GitHub Secret and decode it in your workflow.
 
 ---
 
@@ -100,18 +164,21 @@ Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
 
 ```
 my-project/
-├── .env.example              ← NOT loaded by Vite (reference only)
-├── apps/
-│   └── my-app/
-│       ├── .env              ← Vite reads THIS
-│       ├── .env.local        ← Overrides .env (gitignored)
-│       ├── .env.staging      ← Used by dndev staging
-│       └── .env.production   ← Production overrides
-└── functions/
-    └── .env                  ← Server secrets (Stripe, OAuth)
++-- .env.example              <-- NOT loaded by Vite (reference only)
++-- apps/
+|   +-- my-app/
+|       +-- .env              <-- Vite reads THIS (public keys: VITE_*)
+|       +-- .env.local        <-- Overrides .env (gitignored)
+|       +-- .env.staging      <-- Used by dndev staging
+|       +-- .env.production   <-- Production overrides
++-- functions/
+    +-- .env                  <-- Server secrets (Stripe, OAuth, service_role)
 ```
 
-**Rule:** `VITE_*` vars go in `apps/<app>/.env`. Server secrets go in `functions/.env`.
+**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
 
 ---
 
@@ -122,9 +189,11 @@ my-project/
 | `bun dev` | Start dev server |
 | `dndev emu start` | Start Firebase emulators |
 | `dndev firebase:setup` | Configure Firebase project + .env |
-| `dndev deploy` | Deploy to Firebase (hosting + functions + rules) |
+| `dndev supabase:setup` | Configure Supabase project + .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 Firebase Secret Manager |
+| `dndev sync-secrets` | Push functions/.env 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 |
 
@@ -135,8 +204,8 @@ my-project/
 | Feature | Required? | When to Set Up |
 |---------|-----------|---------------|
 | Git + GitHub | Recommended | Before starting development |
-| Firebase (Auth + Firestore) | Yes | Before building any features |
-| Cloud Functions | If using backend | Before deploying functions |
+| Firebase or Supabase | Yes (pick one) | Before building any features |
+| Cloud Functions | If using server logic | Before deploying functions |
 | Stripe | If using billing | When adding payment features |
 | GitHub Actions CI/CD | Optional | Phase 4 generates the workflow |
 | Staging environment | Optional | When you want a test environment |

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

@@ -8,9 +8,11 @@
 
 ## Getting Started
 
-- [ENV_SETUP.md](./ENV_SETUP.md) - **START HERE** — Full onboarding flow (install → firebase → deploy)
+- **Human flow:** P0 (Bun/Node + AI IDE) → Install CLI & `dndev init` → Run **AI.md** → Enjoy. See [AGENT_START_HERE.md](./AGENT_START_HERE.md) § Getting started (for humans).
+- [ENV_SETUP.md](./ENV_SETUP.md) — After `dndev init`: env, Firebase/Supabase, deploy
 - [GOTCHAS.md](./GOTCHAS.md) - **Common mistakes & pitfalls** (phase-tagged, read before coding)
 - [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev firebase:setup`)
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev supabase:setup`, `dn generate sql`)
 - [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
 
 ---

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

@@ -20,6 +20,34 @@
 
 ---
 
+## 0. Provider configuration (required)
+
+CRUD operations use the **CRUD provider** registered at app startup. You must call `configureProviders()` before any component uses `useCrud`.
+
+- **Where:** In a dedicated module, e.g. `src/config/providers.ts`.
+- **When:** Import that module from your root component (e.g. `App.tsx`) so it runs before any CRUD usage.
+
+```typescript
+// App.tsx
+import './config/providers';  // Before any useCrud
+// ...
+```
+
+```typescript
+// config/providers.ts
+import { configureProviders } from '@donotdev/core';
+import { FirestoreAdapter } from '@donotdev/firebase';  // or SupabaseCrudAdapter from '@donotdev/supabase'
+
+configureProviders({
+  crud: new FirestoreAdapter(),
+  // auth, storage optional
+});
+```
+
+If you skip this step, `useCrud` will throw at runtime: "Provider \"crud\" not available. Call configureProviders() at app startup."
+
+---
+
 ## 1. Define Entity
 
 ```typescript
@@ -80,7 +108,7 @@ For multi-tenant apps where data belongs to a company/tenant/workspace:
 ### Step 1: Register Scope Provider (once at app startup)
 
 ```typescript
-// src/main.tsx or src/App.tsx
+// src/App.tsx
 import { registerScopeProvider } from '@donotdev/core';
 import { useCurrentCompanyStore } from './stores/currentCompanyStore';
 
@@ -665,9 +693,15 @@ transmission: {
 
 ## 7. Custom Fields & Schemas
 
-### Custom Field Types with UI Components
+A custom field type (when the requirement is not a built-in type) needs up to four things: **(1)** entity field with your custom `type` and `validation.schema`, **(2)** form component(s) so the field is editable, **(3)** optional **display** formatter so list/card/detail views render the value correctly, **(4)** optional **filter** so the field appears in EntityFilters with the right filter UI. All four are wired through a single `registerFieldType({ ... })` call.
+
+> **Custom type strings work out of the box.** Just use any string as the `type` — no declaration file or module augmentation needed. The framework accepts any string while still autocompleting built-in types.
+>
+> `CustomFieldOptionsMap` augmentation (see below) is only needed if you want type-checked `options.fieldSpecific` for your custom type.
 
-For custom field types that need custom UI components:
+### Form (required for editable fields)
+
+You must register a **controlled component** so the field appears in forms. Optionally register an **uncontrolled component** (e.g. for submit/reset-style fields).
 
 ```typescript
 import { registerFieldType, useController } from '@donotdev/crud';
@@ -687,7 +721,6 @@ function RepairOperationsField({
     control: control,
   });
 
-  // Use field.value and field.onChange for form state
   const value = (field.value as any) || [];
 
   return (
@@ -701,13 +734,13 @@ function RepairOperationsField({
   );
 }
 
-// Register UI component
+// Minimal registration (form only)
 registerFieldType({
   type: 'repairOperations',
   controlledComponent: RepairOperationsField,
 });
 
-// Then define schema in entity
+// Entity with schema
 export const carEntity = defineEntity({
   name: 'Car',
   collection: 'cars',
@@ -715,11 +748,10 @@ export const carEntity = defineEntity({
     repairs: {
       name: 'repairs',
       label: 'repairs',
-      type: 'repairOperations' as any,
+      type: 'repairOperations',
       visibility: 'admin',
       validation: {
         required: false,
-        // Custom Valibot schema - single source of truth
         schema: v.nullish(v.array(v.object({
           operation: v.string(),
           cost: v.number(),
@@ -730,10 +762,109 @@ export const carEntity = defineEntity({
 });
 ```
 
-**Important:**
-- Custom controlled components receive `control` prop, NOT `field` prop
-- You MUST use `useController` hook to get `field` and `fieldState`
-- Define schema in `validation.schema` - it's the single source of truth
+**Important:** Custom controlled components receive `control` prop, NOT `field` prop. You MUST use `useController` to get `field` and `fieldState`. Define schema in `validation.schema` — it's the single source of truth.
+
+### Display (list/card/detail)
+
+Without a **displayFormatter**, list/card/detail views show the raw value (or a fallback). To control how the value is rendered in read-only views, pass `displayFormatter` in the same `registerFieldType` call. Signature: `(value, fieldConfig, t, options?) => string | ReactNode`. Use `options?.compact` for list/card vs detail.
+
+```typescript
+// Example: format a custom object for display
+displayFormatter: (value, fieldConfig, t, options) => {
+  if (value == null) return '';
+  const arr = Array.isArray(value) ? value : [];
+  if (options?.compact) return `${arr.length} item(s)`;
+  return arr.map((item: any) => `${item.operation}: ${item.cost}`).join(', ') || '—';
+}
+```
+
+### Filter (EntityFilters)
+
+For the field to appear in the list/card **filters** section (EntityFilters), set **filterable: true** and **filterType** in `registerFieldType`. The filter type determines the filter UI:
+
+| filterType     | Use for |
+|----------------|--------|
+| `'text'`       | Free text search |
+| `'range'`      | Numbers, dates (min/max) |
+| `'select'`     | Single choice (e.g. enum) |
+| `'multiselect'`| Multiple choices |
+| `'address'`    | Address-based filter |
+| `'none'`       | Not filterable (omit or set filterable: false) |
+
+```typescript
+registerFieldType({
+  type: 'repairOperations',
+  controlledComponent: RepairOperationsField,
+  displayFormatter: (value, fieldConfig, t, options) => { /* ... */ },
+  filterable: true,
+  filterType: 'text',  // or 'range', 'select', 'multiselect', 'address', 'none'
+});
+```
+
+### Full example: form + display + filter
+
+One registration with form, displayFormatter, and filter:
+
+```typescript
+import { registerFieldType, useController } from '@donotdev/crud';
+import type { ControlledFieldProps } from '@donotdev/crud';
+import { defineEntity } from '@donotdev/core';
+import * as v from 'valibot';
+
+function StatusTierField({ fieldConfig, control, errors, t }: ControlledFieldProps) {
+  const { field, fieldState } = useController({ name: fieldConfig.name, control });
+  return (
+    <div>
+      <label>{t(fieldConfig.label)}</label>
+      <select value={field.value ?? ''} onChange={(e) => field.onChange(e.target.value)}>
+        <option value="">—</option>
+        <option value="basic">Basic</option>
+        <option value="premium">Premium</option>
+      </select>
+      {fieldState?.error && <span className="error">{fieldState.error.message}</span>}
+    </div>
+  );
+}
+
+registerFieldType({
+  type: 'statusTier',
+  controlledComponent: StatusTierField,
+  displayFormatter: (value) => (value ? String(value) : '—'),
+  filterable: true,
+  filterType: 'select',
+});
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  fields: {
+    statusTier: {
+      name: 'statusTier',
+      label: 'statusTier',
+      type: 'statusTier',
+      visibility: 'guest',
+      validation: { schema: v.optional(v.picklist(['basic', 'premium'])) },
+    },
+  },
+});
+```
+
+### Typing custom field options
+
+To get type-checked `options.fieldSpecific` for custom types (e.g. `extractDistrictCode: boolean`), augment the framework's `CustomFieldOptionsMap` in your app:
+
+```typescript
+// e.g. in src/types/crud.d.ts or next to your entity
+import '@donotdev/core';
+declare module '@donotdev/core' {
+  interface CustomFieldOptionsMap {
+    'repairOperations': { maxItems?: number };
+    'isousou-address': { extractDistrictCode?: boolean };
+  }
+}
+```
+
+Then in entity fields you can use `type: 'repairOperations'` and `options: { fieldSpecific: { maxItems: 10 } }` without type errors or `as any`.
 
 ### Custom Schemas (No Custom UI)
 

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

@@ -112,23 +112,29 @@ This handles everything:
 
 ## Secrets (Stripe, OAuth, etc.)
 
-Server-side secrets go in `functions/.env`, not the app `.env`:
+Server-side secrets go in `functions/.env`, not the app `.env`.
+
+**We NEVER ask for secret keys.** You place them yourself:
 
 ```bash
 # functions/.env
 STRIPE_SECRET_KEY=sk_live_...
 STRIPE_WEBHOOK_SECRET=whsec_...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...   # if using Supabase
 GITHUB_CLIENT_SECRET=...
 ```
 
-Push to Firebase Secret Manager:
+Then sync to your runtime and CI/CD:
 
 ```bash
-dndev sync-secrets
+dndev sync-secrets                    # Firebase Secret Manager / Vercel env
+dndev sync-secrets --target github    # GitHub Secrets (for CI/CD workflows)
 ```
 
 Secrets are auto-loaded by Cloud Functions at runtime. Never put server secrets in `VITE_*` variables — those are exposed to the browser.
 
+See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+
 ---
 
 ## Cloud Run IAM (Technical Detail)