@donotdev/cli 0.0.11 → 0.0.13

package/templates/root-consumer/.claude/commands/polish.md.example

@@ -1,5 +1,5 @@
 ---
-description: Fix bugs, add styling, customization, i18n (BMAD FINISHER) - AFTER /build
+description: Generate tests, firestore rules, CI/CD, config, fix bugs, i18n (Phase 4) - AFTER /build
 ---
 
 # Polish Command - Production-Ready App
@@ -12,134 +12,118 @@ description: Fix bugs, add styling, customization, i18n (BMAD FINISHER) - AFTER
 
 **If you're in a consumer repo:**
 - ✅ Use `/polish` after `/build` is complete
+- ✅ Use `/polish` to generate tests, firestore rules, CI/CD
 - ✅ Use `/polish` to fix bugs, add styling, add i18n
 - ✅ Use `/polish` to finalize configuration
 
 **WORKFLOW ORDER:**
-1. `/brainstorm` → Extract requirements, generate HLD
-2. `/design` → Create technical plan (LLD)
+1. `/brainstorm` → Extract requirements, generate spec
+2. `/design` → Create technical plan
 3. `/build` → Implement code using framework defaults
-4. `/polish` → Add styling, customization, i18n (THIS COMMAND)
+4. `/polish` → Generate tests, config, CI/CD, fix bugs (THIS COMMAND)
 
 ---
 
 ## Usage
 
 ```
-/polish [bugs, styling requirements, or i18n needs]
+/polish [task]
 ```
 
 **Examples:**
 ```
+/polish Generate all tests and firestore rules
 /polish Fix bug: Projects list is empty
-/polish Add styling to match brand guidelines
 /polish Add French and Spanish translations
-/polish Complete configuration and test everything
+/polish Complete configuration and deploy
 ```
 
 ---
 
 ## Process
 
-### Step 1: Activate FINISHER Agent
-
-**Deploy:** `/agents polisher` (BMAD FINISHER persona)
-
-**Input:** 
-- Working app from `/build`
-- Bug reports (if any)
-- Styling/customization requirements
-- i18n requirements
-
-**Actions:**
-1. **Fix Bugs** (if any):
-   - Understand bug report
-   - Diagnose root cause
-   - Provide minimal fix
-   - Verify fix works
-   - Check for regressions
-
-2. **Add Styling** (if requested):
-   - Identify what needs styling
-   - Break framework defaults where needed
-   - Ensure mobile responsiveness
-   - Verify no regressions
-
-3. **Add i18n** (if required):
-   - Extract hardcoded strings
-   - Create translation files
-   - Replace strings with `useTranslation()` hooks
-   - Add all required languages
-
-4. **Finalize Configuration**:
-   - Update `src/config/app.ts`
-   - Update `src/config/legal.ts`
-   - Fill `.env`
-   - Configure Firestore Rules
-
-5. **Test and Validate**:
-   - Test all features
-   - Verify mobile responsiveness
-   - Check ship readiness
-
-**Output:** Production-ready app
+### Step 1: Activate Polisher Agent
 
----
+**Deploy:** `/agents polisher` (Phase 4 Polisher persona)
 
-## What FINISHER Does
+**READ first:**
+- `guides/wai-way/spec_template.md` — validated spec (your test plan)
+- `entities/index.ts` — all entity definitions
+- `src/pages/` — all page files
+- `guides/dndev/SETUP_TESTING.md` — testing patterns
 
-| Task | Description |
-|------|-------------|
-| **Bug Fixes** | Diagnose and fix bugs with minimal changes |
-| **Styling** | Add custom CSS, break framework defaults where needed |
-| **i18n** | Extract strings, create translation files, replace hardcoded text |
-| **Configuration** | Complete app.ts, legal.ts, .env, Firestore Rules |
-| **Testing** | Verify everything works, check ship readiness |
+### Step 2: Generate Tests
 
----
+Call `get_guide("TESTING")` for patterns.
 
-## Rules
+1. **Entity tests** — one per entity in `tests/entities/[Entity].test.ts`
+2. **Page tests** — one per page in `tests/pages/[Page].test.tsx`
+3. **Access control tests** — `tests/access/access-rules.test.ts`
 
-- **Fix bugs only** - Don't add features
-- **Minimal changes** - Change only what's necessary
-- **Verify fixes** - Test before declaring complete
-- **Check regressions** - Ensure other features still work
-- **Ask when unclear** - Don't guess bug causes
+### Step 3: Generate Firestore Rules
 
----
+Create `firestore.rules` from entity access definitions.
 
-## Integration with WAI-WAY
+### Step 4: Generate CI/CD
 
-- Uses **BMAD FINISHER** persona (proven, battle-tested)
-- Follows WAI-WAY Phase 4 (CONFIGURE) + Phase 5 (i18n)
-- Takes working app from `/build` and makes it production-ready
+Create `.github/workflows/ci.yml` — type-check → test → build → deploy.
+
+### Step 5: Configure
+
+- `src/config/app.ts` — APP_NAME, preset, footer
+- `src/config/legal.ts` — company, contacts, jurisdiction
+- `.env` — Firebase config, license key
+
+### Step 6: Run Tests
+
+```bash
+bun test
+```
+
+All tests must pass.
+
+### Step 7: Fix Bugs (if any)
+
+- Understand → Diagnose → Fix (minimal) → Verify → Check regressions
+
+### Step 8: Mobile Check
+
+DevTools → 375px → navigation, forms, text, buttons (44px)
+
+### Step 9: i18n (Optional)
+
+Extract strings to `src/locales/`, replace with `useTranslation()`.
 
 ---
 
-## Requirements
+## What Polisher Does
 
-- Working app from `/build` command
-- Bug reports (if any)
-- Styling requirements (if any)
-- i18n requirements (if any)
+| Task | Description |
+|------|-------------|
+| **Test Generation** | Entity tests, page tests, access tests from spec |
+| **Firestore Rules** | Security rules from entity access definitions |
+| **CI/CD** | GitHub Actions workflow (test → build → deploy) |
+| **Configuration** | app.ts, legal.ts, .env, Firebase setup |
+| **Bug Fixes** | Diagnose and fix bugs with minimal changes |
+| **i18n** | Extract strings, create translation files (optional) |
 
 ---
 
 ## Ship Readiness
 
 App is ready to ship when:
+- ✅ `bun test` passes
+- ✅ `firestore.rules` generated
+- ✅ `.github/workflows/ci.yml` created
 - ✅ No critical bugs
-- ✅ All MVP features work
 - ✅ Auth is secure
-- ✅ Performance acceptable
-- ✅ Mobile works (if in spec)
-- ✅ Styling matches requirements (if specified)
-- ✅ i18n complete (if required)
+- ✅ Mobile works at 375px
 - ✅ Configuration complete
+- ✅ (Optional) i18n added
 
 ---
 
 ## Next Step
 
 Once app is production-ready:
-→ Deploy and ship! 🚀
+→ `dndev deploy`

package/templates/root-consumer/.env.example

@@ -1,19 +1,19 @@
 # =============================================================================
-# DoNotDev Framework License Key
+# ROOT .env — REFERENCE ONLY
 # =============================================================================
-# This root-level .env file should ONLY contain the framework license key.
-# App-specific environment variables (Firebase, emulators, etc.) should be
-# placed in each app's own .env files (apps/*/.env).
+# ⚠️ Vite does NOT read this file. It loads .env from each app's directory.
 #
-# ⚠️ WARNING: If a root .env file exists, Vite/Next.js will load it and
-# it will take priority over app-specific .env files. Only create a root .env
-# if you want to share the same license key across all apps.
+# Put your environment variables in: apps/<your-app>/.env
 #
-# Get your license key from: https://donotdev.com/pricing
-# Removes watermark and enables all features
+# This file exists only as a reference for what variables are available.
+# See apps/<your-app>/.env.example for the full list.
 #
-# For Vite projects:
-VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+# For the license key:
+#   apps/<your-app>/.env → VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
 #
-# For Next.js projects:
-NEXT_PUBLIC_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+# For Firebase config:
+#   apps/<your-app>/.env → VITE_FIREBASE_API_KEY=...
+#
+# For server-side secrets (Stripe, OAuth):
+#   functions/.env → STRIPE_SECRET_KEY=sk_...
+#   Then run: dndev sync-secrets

package/templates/root-consumer/.gemini/settings.json.example

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "donotdev": {
+      "command": "npx",
+      "args": ["-y", "@donotdev/mcp-server@latest"],
+      "trust": true
+    }
+  }
+}

package/templates/root-consumer/.gitignore.example

@@ -63,7 +63,9 @@ Desktop.ini
 
 # Firebase service account keys (sensitive, project-specific)
 service-account-key.json
-**/functions/service-account-key.json
+service-account-key.staging.json
+**/service-account-key.json
+**/service-account-key.staging.json
 
 # Lock files (using Bun)
 package-lock.json

package/templates/root-consumer/AI.md.example

@@ -0,0 +1,139 @@
+# AI Agent Instructions
+
+> **You are building a DoNotDev app.** Read this file completely before doing anything else.
+
+## What To Do Right Now
+
+1. **Check environment setup first.** Ask the user: "Have you completed the setup steps on the homepage? (Run `bun dev` and open the app to see them.) You need Git, Firebase, and .env configured before we start building." If they haven't, coach them through each step on the homepage — Git repo, Firebase project, service account key, environment variables. Don't start coding until Firebase is configured and `dndev emu start` works.
+2. Read `guides/wai-way/WAI_WAY_CLI.md` — the complete workflow
+3. Start with **Phase 0: BRAINSTORM** — ask the user what they want to build
+4. Follow each phase in order. Do not skip phases.
+
+## Environment Variables — Where They Go
+
+**Vite loads `.env` from the app directory only. NOT from the repo root.**
+
+| File | What Goes Here |
+|------|---------------|
+| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key, all `VITE_*` vars |
+| `apps/<app>/.env.local` | Local overrides (gitignored) |
+| `apps/<app>/.env.staging` | Staging Firebase config (used by `dndev staging`) |
+| `functions/.env` | Server-side secrets: `STRIPE_SECRET_KEY`, OAuth client secrets |
+| Root `.env` | **Not read by Vite.** Reference only. |
+
+If the user says their license key or Firebase config "doesn't work", check which `.env` file they put it in. It must be in `apps/<app>/.env`, not the root.
+
+## The 5 Phases
+
+| Phase | Name | What Happens |
+|-------|------|-------------|
+| 0 | **BRAINSTORM** | Ask questions, understand requirements deeply, produce validated spec |
+| 1 | **SCAFFOLD** | Create all routes and page stubs from spec |
+| 2 | **ENTITIES** | Define all data models (fields, access, visibility) |
+| 3 | **COMPOSE** | Build pages with framework components (hardcode strings) |
+| 4 | **CONFIGURE** | Config, test, polish, optional i18n |
+
+Each phase has a blueprint in `guides/wai-way/blueprints/` — read it before starting the phase.
+
+For large projects, you can scope phases to a module (e.g., "user-management", "billing").
+
+## The Workflow Per Phase
+
+```
+start_phase(N)          → get blueprint + context + lessons from previous sessions
+  ↓
+work                    → follow blueprint, use lookup_symbol for every component
+  ↓
+complete_phase(files)   → validate conventions + symbol usage + submit for review
+  ↓
+[user reviews]          → user confirms or requests changes
+  ↓
+approve_phase()         → phase is done, move to next
+```
+
+## How To Use Components Without Hallucinating
+
+**CRITICAL:** Never guess component props. Always look up the actual TypeScript types first.
+
+**With MCP (auto-configured):**
+```
+lookup_symbol({ symbol: "DataTable" })   → returns real TypeScript interface
+lookup_symbol({ symbol: "Card" })        → returns real TypeScript interface
+```
+
+Every `lookup_symbol` call is tracked. When you call `complete_phase`, it checks that every @donotdev component you used was looked up first. Components used without lookup are flagged.
+
+**Without MCP:**
+Read the `.d.ts` file directly:
+```
+node_modules/@donotdev/crud/dist/index.d.ts    → CRUD components
+node_modules/@donotdev/ui/dist/index.d.ts      → UI components
+node_modules/@donotdev/core/dist/index.d.ts    → Core utilities
+```
+
+## Supported IDEs
+
+DoNotDev + WAI-WAY is designed for **MCP-capable AI IDEs**. MCP is what gives the AI agent real TypeScript types instead of hallucinated props.
+
+| IDE | MCP Support | Config File |
+|-----|-------------|-------------|
+| **Cursor** | Full | `.cursor/mcp.json` (auto-configured) |
+| **Claude Code** | Full | `.mcp.json` (auto-configured) |
+| **Windsurf** | Full | `.mcp.json` (auto-configured) |
+| **AntiGravity** | Full | `.mcp.json` (auto-configured) |
+| **Gemini** | Full | `.gemini/settings.json` (auto-configured) |
+
+**Without MCP (ChatGPT, Copilot, etc.):** The workflow still works — read blueprints directly from `guides/wai-way/blueprints/` and look up types manually from `.d.ts` files. You lose symbol tracking and convention enforcement, but the phase structure and entity-driven patterns remain.
+
+## MCP Tools (9 — Pre-Configured)
+
+MCP is configured in `.mcp.json` / `.cursor/mcp.json` / `.gemini/settings.json`. Your IDE connects automatically.
+
+| Tool | What It Does |
+|------|-------------|
+| `start_phase(N)` | Begin a phase — returns blueprint, agent persona, context, and lessons |
+| `complete_phase({ files })` | Validate conventions + symbol usage + submit for review (does NOT auto-advance) |
+| `approve_phase()` | User approved — phase is done, advance to next |
+| `get_phase_status()` | Current phase, symbols tracked, review status |
+| `lookup_symbol("X")` | Get actual TypeScript types — tracked per phase |
+| `get_guide("CRUD")` | Fetch framework setup guides |
+| `get_guideline("styling:colors")` | Fetch architecture guidelines (supports sections) |
+| `search_framework("keyword")` | Search across all guides and type definitions |
+| `record_lesson("text")` | Save to project memory (returned on next start_phase) |
+
+## Convention Enforcement
+
+`complete_phase` checks for:
+- Inline styles (`style={{}}`) — use className
+- fontSize/font-size — use Text levels or Card props
+- textAlign left/right — use start/end for RTL
+- require() — use ESM imports
+- Manual date formatting — use formatDate() from @donotdev/core
+- Import order — React > vendors > @donotdev > relative
+- Unverified components — @donotdev components used without lookup_symbol
+
+## Without MCP — Manual Fallback
+
+Read the blueprints directly:
+
+| Phase | Read This |
+|-------|-----------|
+| 0 | `guides/wai-way/blueprints/0_brainstorm.md` |
+| 1 | `guides/wai-way/blueprints/1_scaffold.md` |
+| 2 | `guides/wai-way/blueprints/2_entities.md` |
+| 3 | `guides/wai-way/blueprints/3_compose.md` |
+| 4 | `guides/wai-way/blueprints/4_configure.md` |
+
+Agent personas: `guides/wai-way/agents/` (extractor, architect, builder, polisher)
+
+## Golden Rule
+
+> **The scaffolded files ARE your documentation.**
+> Read the existing code. Follow the pattern. Extend it. Never invent from scratch.
+
+## Key References
+
+- `guides/wai-way/spec_template.md` — App specification template (Phase 0 output)
+- `guides/wai-way/entity_patterns.md` — Common entity schemas
+- `guides/wai-way/page_patterns.md` — Common page structures
+- `guides/dndev/` — Framework setup guides (CRUD, Auth, Components, etc.)

package/templates/root-consumer/CLAUDE.md.example

@@ -102,7 +102,7 @@ At end of each plan, list unresolved questions (if any). Extremely concise.
 
 **BEFORE writing ANY @donotdev component:**
 
-1. Call `lookup_component({ component: "ComponentName" })`
+1. Call `lookup_symbol({ symbol: "ComponentName" })`
 2. Read the actual props from the returned TypeScript interface
 3. Use ONLY those props
 
@@ -110,110 +110,19 @@ At end of each plan, list unresolved questions (if any). Extremely concise.
 
 If MCP tools unavailable → STOP and tell user to enable MCP.
 
-**Available MCP tools:**
-- `lookup_component` - get actual props from .d.ts
-- `list_components` - list exports from a package
-- `list_packages` - list all @donotdev packages
+**Key MCP tools:**
+- `lookup_symbol` — get actual TypeScript types from `.d.ts`
+- `get_guide` — fetch framework setup guides (CRUD, Auth, etc.)
+- `get_guideline` — fetch architecture guidelines
+- `search_framework` — search across all guides and symbols
 
-## WAI-WAY Workflow - Four-Phase System (BMAD-Based)
+## WAI-WAY Workflow
 
-**Workflow Order:**
-1. `/brainstorm` → BMAD EXTRACTOR extracts requirements, generates HLD
-2. `/design` → BMAD PRINTER (Architect) creates technical plan (LLD)
-3. `/build` → BMAD FORGER (Builder) implements code using framework defaults
-4. `/polish` → BMAD FINISHER (Polisher) adds styling, customization, i18n
+**Read `AI.md` at the project root for the full workflow.**
 
-**Quality Over Speed:** Each phase must be complete before proceeding. Take as long as needed.
+For each phase (0=BRAINSTORM, 1=SCAFFOLD, 2=ENTITIES, 3=COMPOSE, 4=CONFIGURE):
 
-### Brainstorm Phase
-
-**Use `/brainstorm [app idea]` to extract complete requirements.**
-
-**Workflow:**
-1. `/brainstorm` → BMAD EXTRACTOR asks probing questions
-2. EXTRACTOR uses MCP to discover framework capabilities
-3. EXTRACTOR identifies native vs custom components
-4. Output → Complete HLD document
-
-**Example:**
-```
-/brainstorm I want to build a car dealership management app
-```
-
-**Agent:**
-- `extractor` (BMAD EXTRACTOR) - Extracts requirements through conversation
-
-**See:** `.claude/commands/brainstorm.md` for full workflow details.
-
-### Design Phase
-
-**Use `/design [HLD reference]` to create technical implementation plan.**
-
-**Workflow:**
-1. `/design` → BMAD PRINTER (Architect) reads validated HLD
-2. PRINTER creates technical artifacts (LLD):
-   - Entity schemas
-   - Navigation config
-   - Feature mapping
-   - Custom component specs
-3. Output → Complete LLD document
-
-**Example:**
-```
-/design Create technical plan from HLD.md
-```
-
-**Agent:**
-- `architect` (BMAD PRINTER) - Transforms HLD into technical specifications
-
-**See:** `.claude/commands/design.md` for full workflow details.
-
-### Build Phase
-
-**Use `/build [LLD reference]` to implement working code.**
-
-**Workflow:**
-1. `/build` → BMAD FORGER (Builder) reads LLD
-2. FORGER implements in phases:
-   - Entities → Routes → Auth → Native Pages → Custom Components → Integration
-3. Uses framework defaults ONLY (no styling, no customization)
-4. Hardcodes all strings (no i18n yet)
-5. Output → Working app (functional MVP)
-
-**Example:**
-```
-/build Implement from LLD.md
-```
-
-**Agent:**
-- `builder` (BMAD FORGER) - Implements app from specifications
-
-**See:** `.claude/commands/build.md` for full workflow details.
-
-### Polish Phase
-
-**Use `/polish [requirements]` to make app production-ready.**
-
-**Workflow:**
-1. `/polish` → BMAD FINISHER (Polisher) reads working app
-2. FINISHER:
-   - Fixes bugs (if any)
-   - Adds styling/customization
-   - Adds i18n translations
-   - Finalizes configuration
-   - Tests and validates
-3. Output → Production-ready app
-
-**Example:**
-```
-/polish Add styling and French translations
-```
-
-**Agent:**
-- `polisher` (BMAD FINISHER) - Fixes bugs, adds styling, i18n, config
-
-**See:** `.claude/commands/polish.md` for full workflow details.
-
-**Requirements:**
-- MCP server configured (`.mcp.json` or `.cursor/mcp.json`)
-- `@donotdev/mcp-server` available (via `bunx` or installed)
+1. `mcp:start_phase(N)` — returns blueprint, context, and lessons
+2. Work — follow blueprint, call `lookup_symbol` before using any component
+3. `mcp:complete_phase({ files })` — validates conventions + symbol usage, submits for review
+4. `mcp:approve_phase()` — user approves, phase is done