@donotdev/cli 0.0.12 → 0.0.14

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

@@ -47,41 +47,39 @@ export const crud = createCrudFunctions(entities);
 
 ## Custom Functions
 
-**When writing custom functions, use `/server` imports:**
+**Use `createFunction` — handles config, validation, auth, rate limiting, metrics automatically:**
 
 ```typescript
-import { onCall } from 'firebase-functions/v2/https';
-import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
+import * as v from 'valibot';
+import { createFunction } from '@donotdev/functions/firebase';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
-import { handleError } from '@donotdev/core/server';
 
-export const myFunction = onCall(FUNCTION_CONFIG, async (request) => {
+const schema = v.object({ productId: v.string() });
+
+export const getProductDetails = createFunction(schema, 'get_product_details', async (data, { uid }) => {
   const db = getFirebaseAdminFirestore();
-  // Your logic here
-  return { data: 'result' };
+  const doc = await db.collection('products').doc(data.productId).get();
+  return doc.data();
 });
 ```
 
+**That's it.** Rate limiting, metrics, auth, schema validation — all included by default. No config needed.
+
+**Advanced:** Use `createBaseFunction` if you need custom config (memory, timeout, region override).
+
 ---
 
 ## Post-Deployment: Cloud Run IAM
 
-**After deploying, you may see `403 Forbidden` on CORS preflight. Fix:**
+**`dndev deploy` handles this automatically.** It runs `gcloud run services update --no-invoker-iam-check` on all deployed functions after each deploy.
 
-```bash
-# PowerShell
-gcloud run services update create-products --region=europe-west1 --no-invoker-iam-check --project=myproject
-```
+If you deploy manually with `firebase deploy` (not recommended), you'll see `403 Forbidden` on CORS preflight. Fix by using `dndev deploy` instead, or run manually:
 
-**For all CRUD functions:**
-```powershell
-$services = @('create-products', 'get-products', 'list-products', 'update-products', 'delete-products');
-foreach ($service in $services) {
-  gcloud run services update $service --region=europe-west1 --no-invoker-iam-check --project=myproject
-}
+```bash
+gcloud run services update <function-name> --region=<region> --no-invoker-iam-check --project=<project-id>
 ```
 
-**Why?** Cloud Run blocks unauthenticated OPTIONS (CORS preflight) by default. Your function still validates Firebase Auth - this only allows the preflight to pass.
+**Why?** Cloud Run blocks unauthenticated OPTIONS (CORS preflight) by default. Your function still validates Firebase Auth in code — this only allows the preflight to pass.
 
 ---
 

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

@@ -0,0 +1,184 @@
+# Testing Guide
+
+## Setup
+
+```bash
+bun add -D vitest @testing-library/react @testing-library/jest-dom jsdom
+```
+
+### vitest.config.ts
+
+```ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./tests/setup.ts'],
+    globals: true,
+    include: ['tests/**/*.test.ts', 'tests/**/*.test.tsx'],
+  },
+});
+```
+
+### tests/setup.ts
+
+```ts
+import '@testing-library/jest-dom';
+```
+
+### package.json scripts
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}
+```
+
+---
+
+## What To Test
+
+### 1. Entity Tests
+
+For each entity defined in `entities/`, test:
+
+**CRUD operations:**
+```ts
+// tests/entities/Task.test.ts
+import { describe, it, expect } from 'vitest';
+import { TaskEntity } from '../../entities';
+
+describe('TaskEntity', () => {
+  it('has correct fields', () => {
+    const fields = TaskEntity.fields;
+    expect(fields).toHaveProperty('title');
+    expect(fields).toHaveProperty('status');
+    expect(fields.title.required).toBe(true);
+  });
+
+  it('has correct access rules', () => {
+    const access = TaskEntity.access;
+    expect(access.create).toContain('authenticated');
+    expect(access.read).toContain('owner');
+    expect(access.delete).toContain('admin');
+  });
+});
+```
+
+**What to verify per entity:**
+- All required fields defined
+- Field types match spec
+- Access rules match spec (create/read/update/delete per role)
+- State transitions valid (if entity has states)
+- Default values set correctly
+
+### 2. Page Render Tests
+
+For each page in `src/pages/`, test that it mounts:
+
+```tsx
+// tests/pages/DashboardPage.test.tsx
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import DashboardPage from '../../src/pages/DashboardPage';
+
+describe('DashboardPage', () => {
+  it('renders without crashing', () => {
+    render(<DashboardPage />);
+    expect(document.body).toBeTruthy();
+  });
+
+  it('has correct PageMeta', () => {
+    expect(DashboardPage.meta).toBeDefined();
+    expect(DashboardPage.meta.title).toBeTruthy();
+    expect(DashboardPage.meta.auth).toBe(true);
+  });
+});
+```
+
+**What to verify per page:**
+- Page renders without error
+- PageMeta is defined (title, auth requirement, admin flag)
+- Route protection matches spec (public/auth/admin)
+
+### 3. Access Control Tests
+
+Derive from entity permissions in the spec:
+
+```ts
+// tests/access/access-rules.test.ts
+import { describe, it, expect } from 'vitest';
+import { entities } from '../../entities';
+
+describe('Access Control', () => {
+  it('admin entities require admin access', () => {
+    // Entities marked admin-only in spec
+    const adminEntities = ['AuditLog', 'SystemConfig'];
+    for (const name of adminEntities) {
+      const entity = entities[name];
+      expect(entity.access.create).toContain('admin');
+    }
+  });
+
+  it('user-owned entities have owner access', () => {
+    // Entities where users own their own data
+    const userEntities = ['Task', 'Profile'];
+    for (const name of userEntities) {
+      const entity = entities[name];
+      expect(entity.access.update).toContain('owner');
+    }
+  });
+});
+```
+
+### 4. Firestore Rules Tests
+
+If using Firebase, generate rules from entity access definitions:
+
+```
+// firestore.rules — generated from entities
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    // TaskEntity: create=authenticated, read=owner, update=owner, delete=admin
+    match /tasks/{taskId} {
+      allow create: if request.auth != null;
+      allow read, update: if request.auth != null && resource.data.userId == request.auth.uid;
+      allow delete: if request.auth.token.admin == true;
+    }
+  }
+}
+```
+
+---
+
+## Test Generation Checklist
+
+The Polisher agent should generate tests for everything in the spec:
+
+| Source | Test Type | File |
+|--------|-----------|------|
+| Each entity | Field validation + access rules | `tests/entities/[Entity].test.ts` |
+| Each page | Render + PageMeta | `tests/pages/[Page].test.tsx` |
+| Spec permissions | Access control matrix | `tests/access/access-rules.test.ts` |
+| Spec auth | Auth provider config | `tests/auth/auth.test.ts` |
+| Entity access | Firestore rules | `firestore.rules` |
+
+---
+
+## Running Tests
+
+```bash
+bun test              # Run all tests once
+bun test:watch        # Watch mode
+bunx vitest --ui      # Visual UI
+```
+
+Tests should pass before calling `complete_phase({ files: [...test files...] })`.

package/templates/root-consumer/guides/wai-way/WAI_WAY_CLI.md.example

@@ -15,13 +15,98 @@
 
 ---
 
+## The Intelligence Engine (MCP Server)
+
+Your project is pre-configured with a **Knowledge Engine** (MCP Server) in `.mcp.json`.
+
+1. **Phase Tracking:** `start_phase(N)` returns the blueprint, agent persona, and files to read for each phase.
+2. **Type Intelligence:** `lookup_symbol("ComponentName")` returns actual TypeScript types — never guess props.
+3. **Knowledge Retrieval:** `get_guide("CRUD")`, `get_guideline("styling")`, `search_framework("keyword")`.
+4. **Implementation Tracking:** `init_implementation()` creates a persistent checklist. `update_progress()` ticks items. `get_progress()` reads status. Survives across sessions.
+5. **Captain's Log:** Session history auto-recorded on `approve_phase()`. `get_project_history()` for metrics and post-mortem.
+6. **Lessons:** `record_lesson("gotcha", { tags: ["stripe", "billing"] })` saves tagged gotchas to `.dndev/LESSONS.md`. Filtered by phase + module on next `start_phase`.
+
+The IDE (Cursor, Claude Code, etc.) handles file write approval natively. No MCP-level gating.
+
+---
+
+## Implementation Tracking (Multi-Session Progress)
+
+For projects that span multiple AI sessions, `.dndev/implementation.md` tracks what's done and what's pending.
+
+### Setup (after Phase 0)
+
+```
+# Auto-generate from spec
+init_implementation({ from_spec: true })
+
+# Or manual sections
+init_implementation({ sections: [
+  { title: "Auth Module", items: ["Login page", "Registration", "Password reset"] },
+  { title: "Dashboard", items: ["Stats cards", "Activity feed", "Charts"] }
+] })
+```
+
+### During Work
+
+```
+# Tick items as you complete them
+update_progress({ item: "Login page", done: true })
+update_progress({ item: "Stats cards", done: true, note: "Used Card component with level h3" })
+
+# Check progress
+get_progress()                              # full overview
+get_progress({ section: "Auth Module" })    # filtered to section
+```
+
+### Cross-Session Continuity
+
+When you start a new session:
+1. `start_phase(N)` automatically includes implementation progress
+2. The agent sees what's done and picks up where it left off
+3. No repeated work, no drift
+
+---
+
+## Captain's Log (Project History)
+
+Every `approve_phase()` auto-records a session entry to `.dndev/captain-log.json`. No manual action needed.
+
+### What's Recorded Automatically
+
+- Date + timestamps (started/completed)
+- Phase number and name
+- Module (if scoped)
+- Files touched + symbols used
+- Outcome summary (from `complete_phase({ summary: "..." })`)
+
+### Viewing History
+
+```
+get_project_history()
+```
+
+Returns computed metrics + timeline:
+- Total sessions, phases completed
+- Files and symbols totals
+- Per-session timeline with outcomes
+
+### Post-Mortem
+
+The raw JSON at `.dndev/captain-log.json` enables:
+- Phase velocity analysis (how many sessions per phase)
+- Issue tracking across the project lifecycle
+- Team-level comparison across projects
+
+---
+
 ## The Flow
 
 ```
-BRAINSTORM → SPEC → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
+BRAINSTORM (→ spec) → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
 ```
 
-**Critical:** The spec is the OUTPUT of brainstorming, not the input. No code until spec is validated.
+**Critical:** The spec is the OUTPUT of Phase 0 (BRAINSTORM), not a separate phase. No code until spec is validated.
 
 ---
 
@@ -267,94 +352,75 @@ Copy from `page_patterns.md`:
 
 ---
 
-## Phase 4: CONFIGURE
+## Phase 4: CONFIGURE + TEST
 
-**Goal:** Finalize configuration and test.
+**Goal:** Generate tests, firestore rules, CI/CD, and finalize config.
 
 **READ:**
+- `guides/wai-way/spec_template.md` - The validated spec (your test plan)
+- `entities/index.ts` - All entity definitions
 - `src/config/app.ts` - App configuration
-- `src/config/legal.ts` - Legal info
-- `.env` - Environment variables
+- `guides/dndev/SETUP_TESTING.md` - Testing patterns
 
-### Step 4.1: Update Configuration
+### Step 4.1: Generate Tests
 
-**app.ts:**
-- [ ] `APP_NAME` and `APP_SHORT_NAME`
-- [ ] Correct `preset`
-- [ ] Footer legal links
+Call `get_guide("TESTING")` for patterns.
 
-**legal.ts:**
-- [ ] Company name and registration
-- [ ] Contact emails
-- [ ] Hosting provider
-- [ ] Jurisdiction
+**Entity tests** — one per entity in `tests/entities/[Entity].test.ts`:
+- [ ] Required fields defined
+- [ ] Field types match spec
+- [ ] Access rules match spec (create/read/update/delete per role)
 
-**.env:**
-- [ ] `VITE_FIREBASE_*` values
-- [ ] `VITE_DONOTDEV_LICENSE_KEY`
-- [ ] Optional: `VITE_STRIPE_*`, `VITE_SENTRY_DSN`
+**Page tests** — one per page in `tests/pages/[Page].test.tsx`:
+- [ ] Renders without error
+- [ ] PageMeta defined (title, auth, admin)
+- [ ] Route protection matches spec
 
-### Step 4.2: Firebase Setup
+**Access control tests** in `tests/access/access-rules.test.ts`:
+- [ ] Admin entities require admin access
+- [ ] User-owned entities have owner access
+- [ ] No unauthenticated writes
 
-1. Enable auth providers in Firebase Console
-2. Create Firestore database
-3. Deploy rules: `firebase deploy --only firestore:rules`
+### Step 4.2: Generate Firestore Rules
 
-### Step 4.3: Test
+Create `firestore.rules` from entity access definitions:
+- `owner` → `resource.data.userId == request.auth.uid`
+- `admin` → `request.auth.token.admin == true`
+- `authenticated` → `request.auth != null`
 
-```bash
-dndev emu start
-bun dev
-```
+### Step 4.3: Generate CI/CD
 
-**Test checklist:**
-- [ ] Can create/login user
-- [ ] Public pages work without auth
-- [ ] Protected pages redirect to login
-- [ ] Admin pages require admin role
-- [ ] CRUD operations work
-- [ ] Data persists
+Create `.github/workflows/ci.yml`:
+- Quality job: `bun install` → `bun run type-check` → `bun test`
+- Deploy job: `bun run build` → Firebase deploy (on main push)
 
-### Step 4.4: Mobile Check
+### Step 4.4: Update Configuration
 
-1. Open DevTools (F12)
-2. Toggle device toolbar (Ctrl+Shift+M)
-3. Test at 375px width
+**app.ts:** APP_NAME, APP_SHORT_NAME, preset, footer links
+**legal.ts:** Company, contacts, hosting, jurisdiction
+**.env:** VITE_FIREBASE_*, VITE_DONOTDEV_LICENSE_KEY, optional Stripe/Sentry
 
-**Output:** Working app with auth, CRUD, config complete.
+### Step 4.5: Run Tests
 
----
-
-## Phase 5: i18n (Optional, After Validation)
+```bash
+bun test
+```
 
-**Only after Phase 4 is validated.**
+All tests must pass before completing.
 
-### Step 5.1: Extract Strings
+### Step 4.6: Mobile Check
 
-Create `src/locales/[namespace]_en.json`:
-```json
-{
-  "hero": {
-    "title": "Welcome to My App",
-    "subtitle": "The best app ever built"
-  }
-}
-```
+DevTools → 375px width → navigation, forms, text, buttons (44px), no horizontal scroll.
 
-### Step 5.2: Replace Hardcoded Strings
+**Output:** Test files, firestore.rules, CI/CD pipeline, configured app.
 
-```tsx
-const { t } = useTranslation('home');
+---
 
-<HeroSection
-  title={t('hero.title')}
-  subtitle={t('hero.subtitle')}
-/>
-```
+### Step 4.7: i18n (Optional)
 
-### Step 5.3: Add Translations
+**Only after Steps 4.1-4.6 pass.**
 
-Copy `home_en.json` → `home_fr.json`, translate values.
+Extract hardcoded strings to `src/locales/[namespace]_en.json`, replace with `useTranslation()`.
 
 ---
 
@@ -381,10 +447,10 @@ Activate agent personas from `guides/wai-way/agents/`:
 
 | Agent | Phase | Focus |
 |-------|-------|-------|
-| **Extractor** | 1 | Routes, sitemap, PageMeta |
+| **Extractor** | 0-1 | Requirements gathering, routes, sitemap, PageMeta |
 | **Architect** | 2 | Entities, data models |
 | **Builder** | 3 | Page composition, components |
-| **Polisher** | 4 | Config, testing, polish |
+| **Polisher** | 4 | Config, testing, polish, i18n |
 
 See individual agent files for activation prompts.
 
@@ -397,8 +463,7 @@ Phase 0: BRAINSTORM → User idea → Agent questions → Agent fills spec → U
 Phase 1: SCAFFOLD   → Create all *Page.tsx with PageMeta (from spec)
 Phase 2: ENTITIES   → Define all entities with fields/access (from spec)
 Phase 3: COMPOSE    → Build pages with components (HARDCODE strings)
-Phase 4: CONFIGURE  → Config, Firebase, test, mobile
-Phase 5: i18n       → (Optional) Extract strings, translate
+Phase 4: CONFIGURE  → Config, Firebase, test, mobile, optional i18n
 ```
 
 **Remember:** Spec is the OUTPUT of brainstorming. Validated spec = mechanical build.

package/templates/root-consumer/guides/wai-way/agents/polisher.md.example

@@ -10,27 +10,58 @@ agent:
   id: polisher
   title: QA & Config Specialist
   icon: 🧪
-  phase: "4_configure_polish"
-  done_when: "Config complete, tests pass, mobile responsive"
+  phase: "4_configure_test"
+  done_when: "Tests pass, config complete, firestore rules generated"
 
 persona:
-  role: Quality Gatekeeper & Configuration Expert
-  style: Detail-oriented, systematic, thorough
-  identity: You ensure the app is configured correctly and production-ready.
-  focus: Configuration, testing, mobile check, optional i18n.
+  role: Quality Gatekeeper & Test Generator
+  style: Systematic, thorough, test-driven
+  identity: You generate tests from the spec, configure the app, and verify everything works.
+  focus: Test generation, configuration, firestore rules, mobile check.
 
 golden_rule: |
-  THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.
-  READ src/config/app.ts for config options.
-  READ src/config/legal.ts for legal checklist.
-  READ src/themes.css for theme variables.
+  THE SPEC IS YOUR TEST PLAN.
+  READ the spec (Phase 0 output) for entities, permissions, journeys.
+  READ each entity file for access rules and fields.
+  GENERATE tests that verify the spec is implemented correctly.
 
 core_principles:
-  - Configuration first: app.ts, legal.ts, .env
-  - Test with emulators: dndev emu start
+  - Tests first: generate entity tests, page tests, access tests
+  - Firestore rules from entities: access definitions → security rules
+  - Configuration: app.ts, legal.ts, .env
   - Mobile check: 375px width
   - i18n is OPTIONAL and comes LAST
 
+test_generation:
+  entity_tests:
+    per_entity:
+      - Required fields are defined
+      - Field types match spec
+      - Access rules match spec (create/read/update/delete per role)
+      - State transitions valid (if applicable)
+    output: "tests/entities/[EntityName].test.ts"
+  page_tests:
+    per_page:
+      - Renders without error
+      - PageMeta defined (title, auth, admin)
+      - Route protection matches spec
+    output: "tests/pages/[PageName].test.tsx"
+  access_tests:
+    - Admin entities require admin access
+    - User-owned entities have owner access
+    - Public entities allow guest read
+    - No unauthenticated writes
+    output: "tests/access/access-rules.test.ts"
+
+firestore_rules:
+  source: "Entity access definitions"
+  mapping:
+    owner: "resource.data.userId == request.auth.uid"
+    admin: "request.auth.token.admin == true"
+    authenticated: "request.auth != null"
+    guest: "true"
+  output: "firestore.rules"
+
 config_checklist:
   app_ts:
     - APP_NAME and APP_SHORT_NAME set
@@ -45,32 +76,19 @@ config_checklist:
     - VITE_FIREBASE_* values set
     - VITE_DONOTDEV_LICENSE_KEY set
 
-test_checklist:
-  - Can create/login user
-  - Public pages work without auth
-  - Protected pages redirect to login
-  - Admin pages require admin role
-  - CRUD operations work
-  - Data persists
-
-mobile_check:
-  - Open DevTools (F12)
-  - Toggle device toolbar (Ctrl+Shift+M)
-  - Test at 375px width
-  - Navigation works
-  - Forms are usable
-  - Text is readable
-
 commands:
   - help: Show available commands
+  - generate-tests: Generate all test files from spec + entities
+  - generate-rules: Generate firestore.rules from entities
   - audit-config: Check configuration files
   - audit-mobile: Check mobile responsiveness
   - add-i18n: Extract strings to locales (optional)
   - exit: Exit persona
 
 output:
+  - Test files generated and passing
+  - Firestore rules generated
   - Configuration complete
-  - All tests pass
   - Mobile responsive
   - (Optional) i18n added
 ```
@@ -81,20 +99,24 @@ output:
 Activate AGENT Polisher.
 
 READ these files first:
+- guides/wai-way/spec_template.md (the validated spec — your test plan)
+- entities/index.ts (all entity definitions)
+- src/pages/ (all page files)
 - src/config/app.ts (app configuration)
-- src/config/legal.ts (legal info checklist)
-- src/themes.css (theme customization)
-- .env (environment variables)
-
-Your goal: Finalize configuration and test the app.
-
-Checklist:
-1. Update app.ts (name, preset, footer)
-2. Update legal.ts (company, contacts)
-3. Fill .env (Firebase config)
-4. Test with emulators
-5. Mobile check at 375px
-6. (Optional) Add i18n
-
-Verify each item before marking complete.
+- guides/dndev/SETUP_TESTING.md (testing patterns)
+
+Your goal: Generate tests, firestore rules, and finalize config.
+
+Steps:
+1. Create vitest.config.ts + tests/setup.ts
+2. Generate entity tests (one per entity from entities/)
+3. Generate page tests (one per page from src/pages/)
+4. Generate access control tests (from spec permissions)
+5. Generate firestore.rules (from entity access definitions)
+6. Update app.ts, legal.ts, .env
+7. Run bun test — all must pass
+8. Mobile check at 375px
+9. (Optional) Add i18n
+
+Call get_guide("TESTING") for testing patterns.
 ```