@donotdev/cli 0.0.6 → 0.0.8

package/templates/root-consumer/guides/wai-way/blueprints/1_scaffold.md.example

@@ -0,0 +1,77 @@
+# BLUEPRINT: 1_SCAFFOLD + SITEMAP
+
+**Goal:** Running app with all routes defined.
+
+**Done when:** All routes listed, all *Page.tsx files created with correct PageMeta.
+
+**Prerequisite:** Phase 0 (spec) must be complete.
+
+---
+
+## Step 1: Create App
+
+```bash
+dndev create-app my-app --preset [from spec]
+cd my-app && bun install
+dndev emu start
+bun dev
+```
+
+Preset comes from your completed spec (Phase 0).
+
+---
+
+## Step 2: Review Spec Pages
+
+From your spec, you have a list of pages. Now create them.
+
+**READ:** `guides/wai-way/page_patterns.md` for page structure patterns.
+
+---
+
+## Step 3: Create Page Files
+
+For each page in spec:
+
+```bash
+touch src/pages/AboutPage.tsx
+touch src/pages/DashboardPage.tsx
+touch src/pages/ProductsListPage.tsx
+touch src/pages/ProductPage.tsx
+```
+
+---
+
+## Step 4: Add PageMeta
+
+**READ:** `src/pages/HomePage.tsx` for 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 />,
+  // From spec:
+  // auth: true,                              // Protected
+  // auth: { required: true, role: 'admin' }, // Admin
+  // hideFromMenu: true,                      // Form pages
+};
+
+export default function AboutPage() {
+  return <PageContainer>About Page</PageContainer>;
+}
+```
+
+---
+
+## Output
+
+- [ ] App runs with `bun dev`
+- [ ] All route files created (from spec)
+- [ ] PageMeta set with correct auth levels (from spec)
+- [ ] Navigation auto-generated

package/templates/root-consumer/guides/wai-way/blueprints/2_entities.md.example

@@ -0,0 +1,104 @@
+# BLUEPRINT: 2_ENTITIES
+
+**Goal:** Define all data models from spec.
+
+**Done when:** All entities defined with fields, access rules, visibility. Exported from index.ts.
+
+**Prerequisite:** Phase 0 (spec) and Phase 1 (scaffold) complete.
+
+---
+
+## Step 1: Review Spec Entities
+
+From your spec, you have a list of entities with fields and access rules.
+
+**READ:** `guides/wai-way/entity_patterns.md` for common schemas:
+- UserProfile, Post, Product, Order, Review, Comment
+- Category, Settings, Workspace, Invitation, Media, ActivityLog
+
+---
+
+## Step 2: Create Entity Files
+
+For each entity in spec:
+
+1. Find matching pattern in `entity_patterns.md`
+2. Copy pattern → `entities/[Entity].ts`
+3. Customize fields from spec
+4. Set access rules from spec
+
+**READ:** `entities/ExampleEntity.ts` for the base pattern.
+
+```typescript
+// entities/Product.ts
+import { defineEntity } from '@donotdev/core';
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  fields: {
+    // Fields from spec...
+  },
+  access: {
+    // Access rules from spec...
+  },
+});
+```
+
+---
+
+## Step 3: Export Entities
+
+```typescript
+// entities/index.ts
+export { productEntity } from './Product';
+export { customerEntity } from './Customer';
+export { orderEntity } from './Order';
+```
+
+---
+
+## Field Type Quick Reference
+
+| Type | Use for |
+|------|---------|
+| `text` | Single-line text |
+| `textarea` | Multi-line text |
+| `richtext` | Rich text editor |
+| `number` | Numbers |
+| `email` | Email addresses |
+| `tel` | Phone numbers |
+| `url` | URLs |
+| `select` | Dropdown with options |
+| `combobox` | Searchable dropdown |
+| `multiselect` | Multiple selection |
+| `switch` | On/off toggle |
+| `date` | Date picker |
+| `timestamp` | Date + time |
+| `image` | Single image |
+| `images` | Multiple images |
+| `file` | Single file |
+| `files` | Multiple files |
+| `address` | Address autocomplete |
+
+---
+
+## Access Levels
+
+| Level | Who |
+|-------|-----|
+| `guest` | Anyone |
+| `user` | Authenticated |
+| `owner` | Creator only |
+| `admin` | Admins |
+| `super` | Super admins |
+| `never` | No one |
+
+---
+
+## Output
+
+- [ ] All entities from spec defined in `entities/`
+- [ ] Fields match spec
+- [ ] Access rules match spec
+- [ ] Exported from `entities/index.ts`

package/templates/root-consumer/guides/wai-way/blueprints/3_compose.md.example

@@ -0,0 +1,124 @@
+# BLUEPRINT: 3_COMPOSE
+
+**Goal:** Build pages with components. HARDCODE ALL STRINGS.
+
+**Done when:** All pages functional with content. CRUD pages use EntityList/EntityFormRenderer. All strings hardcoded.
+
+**Prerequisite:** Phase 0-2 complete. Spec validated, entities defined.
+
+---
+
+## Step 1: Read Page Patterns
+
+**READ:** `guides/wai-way/page_patterns.md` for all patterns:
+- Dashboard, List Page, Form Page
+- Landing/Home, Pricing, Settings
+- Profile, Detail Page, Analytics
+
+---
+
+## Step 2: CRUD Pages
+
+For each entity in spec:
+
+### List Page
+
+**READ:** `src/pages/ListPageExample.tsx`
+
+```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
+
+**READ:** `src/pages/FormPageExample.tsx`
+
+```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: Dashboard Page
+
+Copy Dashboard pattern from `page_patterns.md`:
+- Quick actions (cards with onClick)
+- KPI cards in grid
+- Alert/attention sections
+
+---
+
+## Step 4: Landing Pages
+
+Copy Landing pattern from `page_patterns.md`:
+- HeroSection with CTAs
+- Feature grid with Cards
+- Final CTA section
+
+---
+
+## Component Quick Reference
+
+| Component | Use for |
+|-----------|---------|
+| `PageContainer` | Page wrapper (required) |
+| `HeroSection` | Full-width hero banner |
+| `Section` | Content block with title |
+| `Card` | Content card |
+| `Grid` | Responsive grid ([1,2,3,3] = mobile 1, tablet 2, desktop 3) |
+| `Stack` | Flex container |
+| `Button` | Buttons |
+| `Text` | Typography |
+| `Badge` | Status badges |
+| `Alert` | Notifications |
+| `Loader` | Loading spinner |
+
+---
+
+## CRITICAL: HARDCODE FIRST
+
+```tsx
+// ✅ GOOD - Start with hardcoded strings
+<HeroSection
+  title="Welcome to My App"
+  subtitle="The best app ever"
+/>
+
+// ❌ BAD - Don't start with i18n
+<HeroSection
+  title={t('hero.title')}
+  subtitle={t('hero.subtitle')}
+/>
+```
+
+Validate UX in one language. Add i18n in Phase 5.
+
+---
+
+## Output
+
+- [ ] All CRUD pages use EntityList/EntityFormRenderer
+- [ ] Dashboard uses pattern from page_patterns.md
+- [ ] Landing pages use framework components
+- [ ] All strings are HARDCODED (not i18n)
+- [ ] App is fully functional

package/templates/root-consumer/guides/wai-way/blueprints/4_configure.md.example

@@ -0,0 +1,165 @@
+# BLUEPRINT: 4_CONFIGURE + POLISH
+
+**Goal:** Finalize configuration, test, and optionally add i18n.
+
+**Done when:** Config complete, tests pass, mobile responsive.
+
+**Prerequisite:** Phase 0-3 complete. App is functional.
+
+---
+
+## Step 1: Update Configuration
+
+### app.ts
+
+**READ:** `src/config/app.ts`
+
+- [ ] `APP_NAME` - Your app name (from spec)
+- [ ] `APP_SHORT_NAME` - Abbreviation
+- [ ] `preset` - From spec (landing/admin/moolti/docs/blog/game/plain)
+- [ ] Footer legal links
+
+### legal.ts
+
+**READ:** `src/config/legal.ts`
+
+- [ ] Company name and registration
+- [ ] Contact emails
+- [ ] Hosting provider info
+- [ ] Jurisdiction
+
+### .env
+
+Required:
+- [ ] `VITE_FIREBASE_*` - Firebase config
+- [ ] `VITE_DONOTDEV_LICENSE_KEY` - License key
+
+Optional (from spec features):
+- [ ] `VITE_STRIPE_*` - If billing enabled
+- [ ] `VITE_SENTRY_DSN` - If error tracking
+
+---
+
+## Step 2: Firebase Setup
+
+1. Go to [Firebase Console](https://console.firebase.google.com)
+2. Enable auth providers (from spec):
+   - [ ] Email/Password
+   - [ ] Google
+   - [ ] GitHub
+   - [ ] etc.
+3. Create Firestore Database
+4. Deploy rules: `firebase deploy --only firestore:rules`
+
+---
+
+## Step 3: Test with Emulators
+
+```bash
+dndev emu start
+bun dev
+```
+
+### Auth Tests
+- [ ] Can create user account
+- [ ] Can login/logout
+- [ ] Public pages work without auth
+- [ ] Protected pages redirect to login
+- [ ] Admin pages require admin role
+
+### CRUD Tests
+- [ ] Can create entities
+- [ ] Can read/list entities
+- [ ] Can update entities
+- [ ] Can delete entities
+- [ ] Data persists
+
+### Access Control Tests
+- [ ] Guest can only see guest-visible fields
+- [ ] User can only edit own data (if owner access)
+- [ ] Admin can edit all data
+
+---
+
+## Step 4: Theme Customization
+
+**READ:** `src/themes.css`
+
+Key variables:
+- `--primary` - Brand color
+- `--accent` - Accent color
+- `--background` - Page background
+- `--foreground` - Text color
+- `--radius` - Border radius
+
+---
+
+## Step 5: Mobile Check
+
+1. Open DevTools (F12)
+2. Toggle device toolbar (Ctrl+Shift+M)
+3. Test at 375px width
+
+Check:
+- [ ] Navigation works (mobile menu)
+- [ ] Forms are usable
+- [ ] Text is readable
+- [ ] Buttons are tappable (44px min)
+- [ ] No horizontal scroll
+
+---
+
+## Step 6: i18n (Optional)
+
+**Only after Steps 1-5 are validated!**
+
+### Extract Strings
+
+Create `src/locales/[namespace]_en.json`:
+```json
+{
+  "hero": {
+    "title": "Your App Name",
+    "subtitle": "Your tagline"
+  }
+}
+```
+
+### Replace Hardcoded Strings
+
+```tsx
+const { t } = useTranslation('home');
+
+<HeroSection
+  title={t('hero.title')}
+  subtitle={t('hero.subtitle')}
+/>
+```
+
+### Add Languages
+
+Copy `home_en.json` → `home_fr.json`, translate values.
+
+---
+
+## Final Checklist
+
+- [ ] app.ts configured
+- [ ] legal.ts configured
+- [ ] .env configured
+- [ ] Firebase connected
+- [ ] Auth working
+- [ ] CRUD working
+- [ ] Access control working
+- [ ] Mobile responsive
+- [ ] (Optional) i18n added
+
+---
+
+## Output
+
+Production-ready app with:
+- Complete configuration
+- Working auth & CRUD
+- Mobile responsive
+- (Optional) Multi-language support

package/templates/root-consumer/guides/wai-way/context_map.json.example

@@ -0,0 +1,95 @@
+{
+  "description": "WAI-WAY context map - maps phases to required files. READ the scaffolded files, they contain inline documentation.",
+  "golden_rule": "THE SCAFFOLDED FILES ARE YOUR DOCUMENTATION. Read the file. Follow the pattern. Extend.",
+  "phases": {
+    "0_brainstorm_spec": {
+      "agent": "extractor",
+      "goal": "Gather requirements through conversation and produce validated spec",
+      "flow": "User idea → Agent questions → Agent fills spec → User validates",
+      "done_when": "spec_template.md filled and validated by user",
+      "read_files": [
+        "guides/wai-way/spec_template.md",
+        "guides/wai-way/presets_guide.md",
+        "guides/wai-way/entity_patterns.md",
+        "guides/wai-way/page_patterns.md"
+      ],
+      "output": "Validated spec with preset, entities, pages, auth/billing requirements"
+    },
+    "1_scaffold_sitemap": {
+      "agent": "extractor",
+      "goal": "Running app with all routes defined",
+      "done_when": "All routes listed, all *Page.tsx files created with correct PageMeta",
+      "read_files": [
+        "src/pages/HomePage.tsx",
+        "src/config/app.ts",
+        "guides/wai-way/page_patterns.md"
+      ],
+      "output": "All *Page.tsx files created with correct PageMeta"
+    },
+    "2_entities": {
+      "agent": "architect",
+      "goal": "Define all data models",
+      "done_when": "All entities defined with fields, access, visibility. Exported from index.ts",
+      "read_files": [
+        "entities/ExampleEntity.ts",
+        "entities/index.ts",
+        "guides/wai-way/entity_patterns.md"
+      ],
+      "output": "All entities defined in entities/"
+    },
+    "3_compose": {
+      "agent": "builder",
+      "goal": "Build pages with components (hardcoded strings)",
+      "done_when": "All pages functional, CRUD uses EntityList/EntityFormRenderer, strings hardcoded",
+      "read_files": [
+        "src/pages/ListPageExample.tsx",
+        "src/pages/FormPageExample.tsx",
+        "src/pages/HomePage.tsx",
+        "guides/wai-way/page_patterns.md"
+      ],
+      "output": "All pages functional with hardcoded content"
+    },
+    "4_configure_polish": {
+      "agent": "polisher",
+      "goal": "Finalize config, test, optional i18n",
+      "done_when": "Config complete, tests pass, mobile responsive",
+      "read_files": [
+        "src/config/app.ts",
+        "src/config/legal.ts",
+        "src/themes.css",
+        ".env"
+      ],
+      "output": "Working app with auth, CRUD, and config complete"
+    }
+  },
+  "key_files": {
+    "spec": {
+      "guides/wai-way/spec_template.md": "App specification template - fill before coding",
+      "guides/wai-way/presets_guide.md": "Preset decision matrix - landing/admin/moolti/docs/blog/game/plain",
+      "guides/wai-way/entity_patterns.md": "Common entity schemas - UserProfile, Post, Product, Order, etc.",
+      "guides/wai-way/page_patterns.md": "Common page structures - Dashboard, List, Form, Landing, Settings, etc."
+    },
+    "config": {
+      "src/config/app.ts": "App name, preset, features, auth routes",
+      "src/config/legal.ts": "Company info, legal compliance",
+      ".env": "Firebase config, API keys"
+    },
+    "pages": {
+      "src/pages/HomePage.tsx": "PageMeta pattern, basic page structure",
+      "src/pages/ListPageExample.tsx": "EntityList CRUD pattern",
+      "src/pages/FormPageExample.tsx": "EntityFormRenderer pattern"
+    },
+    "entities": {
+      "entities/ExampleEntity.ts": "defineEntity pattern, field types, access rules",
+      "entities/index.ts": "Entity exports"
+    },
+    "styling": {
+      "src/themes.css": "CSS variables, light/dark themes",
+      "src/globals.css": "Font overrides"
+    }
+  },
+  "workflow": {
+    "summary": "BRAINSTORM → SPEC → SCAFFOLD → ENTITIES → COMPOSE → CONFIGURE",
+    "critical_rule": "Spec is OUTPUT of brainstorming. User validates before coding. Validated spec = mechanical build."
+  }
+}