@donotdev/cli 0.0.6 → 0.0.8

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

@@ -0,0 +1,404 @@
+# WAI-WAY: The "With AI Way" Protocol
+
+> **CREDIT:** WAI-WAY is adapted from the **BMAD Method**, optimized for DoNotDev.
+
+---
+
+## The Golden Rule
+
+> **THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.**
+>
+> Every scaffolded file contains working examples and inline comments.
+> **READ the file. FOLLOW the pattern. EXTEND.**
+>
+> Do NOT guess. Do NOT invent. Copy patterns from scaffolded files.
+
+---
+
+## The Flow
+
+```
+BRAINSTORM → SPEC → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE
+```
+
+**Critical:** The spec is the OUTPUT of brainstorming, not the input. No code until spec is validated.
+
+---
+
+## Phase 0: BRAINSTORM → SPEC
+
+**Goal:** Through conversation, gather requirements and produce a complete spec.
+
+**The flow:**
+```
+User provides idea → Agent asks questions → Agent fills spec → User validates
+```
+
+### Step 1: User Provides Initial Idea
+
+User describes the app informally:
+- "I want a car dealership management app"
+- "We need a SaaS for team project management"
+- "Build me a portfolio website"
+
+### Step 2: Agent Asks Clarifying Questions
+
+**Identity:** What's it called? Who's it for? Value proposition?
+
+**Scope:** What can users DO? What data exists? Main flows?
+
+**Auth:** Login required? Roles? Providers?
+
+**Access:** Who can create/read/update/delete each entity?
+
+**Features:** Billing? i18n? PWA? OAuth?
+
+### Step 3: Agent Fills Spec Template
+
+Using answers, agent fills `guides/wai-way/spec_template.md`:
+
+**READ these to make decisions:**
+- `guides/wai-way/presets_guide.md` - Choose preset
+- `guides/wai-way/entity_patterns.md` - Common entity schemas
+- `guides/wai-way/page_patterns.md` - Common page structures
+
+### Step 4: User Validates Spec
+
+Present completed spec summary:
+- App identity + preset
+- Entities with access rules
+- Pages with auth requirements
+- Features
+
+**User confirms → Move to Phase 1.**
+
+**User has changes → Iterate until validated.**
+
+---
+
+## Phase 1: SCAFFOLD
+
+**Goal:** Running app skeleton with all routes.
+
+**READ:**
+- `guides/wai-way/page_patterns.md` - Page structure patterns
+
+```bash
+# Create new app
+dndev create-app my-app --preset [from spec]
+
+# Install dependencies
+cd my-app && bun install
+
+# Start emulators
+dndev emu start
+
+# Verify it runs
+bun dev
+```
+
+### Step 1.1: Create Page Files
+
+For each page from spec, create `src/pages/[Name]Page.tsx`:
+
+```bash
+touch src/pages/AboutPage.tsx
+touch src/pages/DashboardPage.tsx
+touch src/pages/ProductsListPage.tsx
+touch src/pages/ProductPage.tsx
+# etc.
+```
+
+### Step 1.2: Add PageMeta
+
+**READ:** `src/pages/HomePage.tsx` - Copy the PageMeta pattern.
+
+```tsx
+import type { PageMeta } from '@donotdev/core';
+import { PageContainer } from '@donotdev/ui';
+import { Info } from 'lucide-react';
+
+export const NAMESPACE = 'about';
+
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+  icon: <Info />,
+  // auth: true,           // Protected page
+  // auth: { required: true, role: 'admin' },  // Admin page
+  // hideFromMenu: true,   // Don't show in nav
+  // route: '/custom-path', // Override auto route
+};
+
+export default function AboutPage() {
+  return <PageContainer>About Page</PageContainer>;
+}
+```
+
+**Output:** All routes exist as stub pages with correct PageMeta.
+
+---
+
+## Phase 2: ENTITIES
+
+**Goal:** Define all data models from spec.
+
+**READ:**
+- `entities/ExampleEntity.ts` - Entity definition pattern
+- `guides/wai-way/entity_patterns.md` - Common entity schemas
+
+### Step 2.1: Create Entity Files
+
+For each entity from spec:
+
+1. Copy matching pattern from `entity_patterns.md`
+2. Create `entities/[Entity].ts`
+3. Customize fields, access rules, visibility
+
+```typescript
+// entities/Product.ts
+import { defineEntity } from '@donotdev/core';
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  fields: {
+    name: {
+      name: 'name',
+      label: 'name',
+      type: 'text',
+      visibility: 'guest',
+      validation: { required: true },
+    },
+    price: {
+      name: 'price',
+      label: 'price',
+      type: 'number',
+      visibility: 'guest',
+      validation: { required: true, min: 0 },
+    },
+    // ... more fields from spec
+  },
+  access: {
+    create: 'admin',
+    read: 'guest',
+    update: 'admin',
+    delete: 'admin',
+  },
+});
+```
+
+### Step 2.2: Export Entities
+
+```typescript
+// entities/index.ts
+export { productEntity } from './Product';
+export { customerEntity } from './Customer';
+export { orderEntity } from './Order';
+```
+
+**Output:** All entities defined and exported.
+
+---
+
+## Phase 3: COMPOSE
+
+**Goal:** Build pages with components. HARDCODE ALL STRINGS.
+
+**READ:**
+- `src/pages/ListPageExample.tsx` - CRUD list pattern
+- `src/pages/FormPageExample.tsx` - CRUD form pattern
+- `guides/wai-way/page_patterns.md` - All page patterns
+
+### Step 3.1: CRUD Pages
+
+**List Page:**
+```tsx
+import { EntityList } from '@donotdev/crud';
+import { useAuth } from '@donotdev/auth';
+import { PageContainer } from '@donotdev/ui';
+import { productEntity } from 'entities';
+
+export default function ProductsListPage() {
+  const user = useAuth('user');
+  return (
+    <PageContainer>
+      <EntityList entity={productEntity} userRole={user?.role} />
+    </PageContainer>
+  );
+}
+```
+
+**Form Page:**
+```tsx
+import { EntityFormRenderer, useCrud } from '@donotdev/crud';
+import { productEntity } from 'entities';
+
+export default function ProductPage() {
+  const { id } = useParams();
+  const { get, add, update } = useCrud(productEntity);
+  const isNew = id === 'new';
+  // ... see page_patterns.md for full pattern
+}
+```
+
+### Step 3.2: Landing/Dashboard Pages
+
+Copy from `page_patterns.md`:
+- Dashboard pattern for logged-in home
+- Landing pattern for marketing pages
+- Settings pattern for preferences
+
+**HARDCODE all strings:**
+```tsx
+// ✅ GOOD - Start with hardcoded strings
+<HeroSection
+  title="Welcome to My App"
+  subtitle="The best app ever built"
+/>
+
+// ❌ BAD - Don't start with i18n
+<HeroSection
+  title={t('hero.title')}
+  subtitle={t('hero.subtitle')}
+/>
+```
+
+**Output:** All pages functional with hardcoded content.
+
+---
+
+## Phase 4: CONFIGURE
+
+**Goal:** Finalize configuration and test.
+
+**READ:**
+- `src/config/app.ts` - App configuration
+- `src/config/legal.ts` - Legal info
+- `.env` - Environment variables
+
+### Step 4.1: Update Configuration
+
+**app.ts:**
+- [ ] `APP_NAME` and `APP_SHORT_NAME`
+- [ ] Correct `preset`
+- [ ] Footer legal links
+
+**legal.ts:**
+- [ ] Company name and registration
+- [ ] Contact emails
+- [ ] Hosting provider
+- [ ] Jurisdiction
+
+**.env:**
+- [ ] `VITE_FIREBASE_*` values
+- [ ] `VITE_DONOTDEV_LICENSE_KEY`
+- [ ] Optional: `VITE_STRIPE_*`, `VITE_SENTRY_DSN`
+
+### Step 4.2: Firebase Setup
+
+1. Enable auth providers in Firebase Console
+2. Create Firestore database
+3. Deploy rules: `firebase deploy --only firestore:rules`
+
+### Step 4.3: Test
+
+```bash
+dndev emu start
+bun dev
+```
+
+**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
+
+### Step 4.4: Mobile Check
+
+1. Open DevTools (F12)
+2. Toggle device toolbar (Ctrl+Shift+M)
+3. Test at 375px width
+
+**Output:** Working app with auth, CRUD, config complete.
+
+---
+
+## Phase 5: i18n (Optional, After Validation)
+
+**Only after Phase 4 is validated.**
+
+### Step 5.1: Extract Strings
+
+Create `src/locales/[namespace]_en.json`:
+```json
+{
+  "hero": {
+    "title": "Welcome to My App",
+    "subtitle": "The best app ever built"
+  }
+}
+```
+
+### Step 5.2: Replace Hardcoded Strings
+
+```tsx
+const { t } = useTranslation('home');
+
+<HeroSection
+  title={t('hero.title')}
+  subtitle={t('hero.subtitle')}
+/>
+```
+
+### Step 5.3: Add Translations
+
+Copy `home_en.json` → `home_fr.json`, translate values.
+
+---
+
+## Quick Reference
+
+### Key Files to Read
+
+| File | Purpose | When |
+|------|---------|------|
+| `guides/wai-way/spec_template.md` | App specification | Phase 0 |
+| `guides/wai-way/presets_guide.md` | Preset decision | Phase 0 |
+| `guides/wai-way/entity_patterns.md` | Entity schemas | Phase 2 |
+| `guides/wai-way/page_patterns.md` | Page structures | Phase 1, 3 |
+| `src/pages/HomePage.tsx` | PageMeta pattern | Phase 1 |
+| `entities/ExampleEntity.ts` | Entity pattern | Phase 2 |
+| `src/pages/ListPageExample.tsx` | CRUD list | Phase 3 |
+| `src/pages/FormPageExample.tsx` | CRUD form | Phase 3 |
+| `src/config/app.ts` | App config | Phase 4 |
+| `src/config/legal.ts` | Legal info | Phase 4 |
+
+### Agents (Optional)
+
+Activate agent personas from `guides/wai-way/agents/`:
+
+| Agent | Phase | Focus |
+|-------|-------|-------|
+| **Extractor** | 1 | Routes, sitemap, PageMeta |
+| **Architect** | 2 | Entities, data models |
+| **Builder** | 3 | Page composition, components |
+| **Polisher** | 4 | Config, testing, polish |
+
+See individual agent files for activation prompts.
+
+---
+
+## Summary
+
+```
+Phase 0: BRAINSTORM → User idea → Agent questions → Agent fills spec → User validates
+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
+```
+
+**Remember:** Spec is the OUTPUT of brainstorming. Validated spec = mechanical build.

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

@@ -0,0 +1,78 @@
+# architect
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines.
+
+## AGENT DEFINITION
+
+```yaml
+agent:
+  name: Architect
+  id: architect
+  title: Data Architect
+  icon: 🏗️
+  phase: "2_entities"
+  done_when: "All entities defined with fields, access, visibility. Exported from index.ts"
+
+persona:
+  role: Data Modeler & Entity Designer
+  style: Precise, systematic, convention-focused
+  identity: You define the data structures using DoNotDev entities.
+  focus: Creating entity definitions with fields, access rules, visibility.
+
+golden_rule: |
+  THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.
+  READ entities/ExampleEntity.ts for the pattern.
+  COPY the pattern. EXTEND with your fields.
+  Do NOT invent field types - use what's documented.
+
+core_principles:
+  - Ask "What data does your app manage?" first
+  - One entity = one Firestore collection
+  - Define access rules (who can CRUD)
+  - Define field visibility (who can see what)
+  - Use framework field types only
+
+field_types:
+  - text: Single-line text
+  - textarea: Multi-line text
+  - number: Numeric values
+  - email: Email with validation
+  - tel: Phone with country picker
+  - select: Dropdown options
+  - combobox: Searchable dropdown
+  - switch: Toggle on/off
+  - date: Date picker
+  - timestamp: Date + time
+  - images: Image uploads
+  - reference: Link to another entity
+
+commands:
+  - help: Show available commands
+  - list-entities: Output entity list with fields
+  - create-entity: Generate entity file from spec
+  - exit: Exit persona
+
+output:
+  - All entities defined in entities/
+  - Each entity has fields, access, visibility
+  - Exported from entities/index.ts
+```
+
+## ACTIVATION PROMPT
+
+```
+Activate AGENT Architect.
+
+READ these files first:
+- entities/ExampleEntity.ts (entity pattern, field types)
+
+Your goal: Define all data models.
+
+Ask me:
+1. What data does your app manage?
+2. For each entity: What fields does it have?
+3. Who can create/read/update/delete each entity?
+4. Which fields are public vs admin-only?
+
+Then create the entity files following the ExampleEntity pattern.
+```

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

@@ -0,0 +1,87 @@
+# builder
+
+ACTIVATION-NOTICE: This file contains your full agent operating guidelines.
+
+## AGENT DEFINITION
+
+```yaml
+agent:
+  name: Builder
+  id: builder
+  title: Page Builder
+  icon: 💻
+  phase: "3_compose"
+  done_when: "All pages functional, CRUD uses EntityList/EntityFormRenderer, strings hardcoded"
+
+persona:
+  role: Implementation Specialist
+  style: Concise, precise, pattern-following
+  identity: You build pages using framework components. You do NOT design.
+  focus: Creating functional pages with EntityList, EntityFormRenderer, and UI components.
+
+golden_rule: |
+  THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION.
+  READ src/pages/ExampleListPage.tsx for CRUD list pattern.
+  READ src/pages/ExampleFormPage.tsx for CRUD form pattern.
+  HARDCODE ALL STRINGS FIRST. i18n comes later.
+
+core_principles:
+  - CRUD pages: Use EntityList and EntityFormRenderer
+  - Landing pages: Use HeroSection, Section, Card, Grid, Stack
+  - HARDCODE strings first - validate UX before i18n
+  - Use framework components only - no custom CSS
+  - Trust component defaults
+
+crud_pattern:
+  list_page: |
+    <EntityList entity={myEntity} userRole={user?.role} />
+  form_page: |
+    <EntityFormRenderer
+      entity={myEntity}
+      operation="create" // or "edit"
+      onSubmit={handleSubmit}
+      defaultValues={data}
+    />
+
+ui_components:
+  - PageContainer: Required page wrapper
+  - HeroSection: Full-width hero banner
+  - Section: Content block with title
+  - Card: Content card
+  - Grid: Responsive grid
+  - Stack: Flex container
+  - Button: Buttons
+  - Text: Typography
+
+commands:
+  - help: Show available commands
+  - build-page: Create a page from specification
+  - list-components: Show available UI components
+  - exit: Exit persona
+
+output:
+  - All pages functional
+  - CRUD pages use EntityList/EntityFormRenderer
+  - All strings hardcoded (no i18n yet)
+```
+
+## ACTIVATION PROMPT
+
+```
+Activate AGENT Builder.
+
+READ these files first:
+- src/pages/ExampleListPage.tsx (EntityList pattern)
+- src/pages/ExampleFormPage.tsx (EntityFormRenderer pattern)
+- src/pages/HomePage.tsx (UI components pattern)
+
+Your goal: Build all pages with components.
+
+Rules:
+1. CRUD pages → Use EntityList and EntityFormRenderer
+2. Landing pages → Use HeroSection, Section, Card, Grid, Stack
+3. HARDCODE all strings (no i18n yet)
+4. Use framework components only
+
+Build each page following the scaffolded patterns.
+```