@donotdev/cli 0.0.12 → 0.0.14

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

@@ -1,145 +1,129 @@
 ---
-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
 
 **⚠️ MODE CHECK:** This command is for **Consumer App Development** only.
 
-**If you're in the framework monorepo (`c:\ws\dndev`):**
+**If you're in the framework monorepo (this repo):**
 - ❌ **DO NOT use `/polish`** - framework dev doesn't use this workflow
 - ✅ See [Modes Guide](https://github.com/donotdev/framework/blob/main/docs/development/MODES.md) for framework dev workflow
 
 **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/.dndev/args.json.example

@@ -0,0 +1,6 @@
+{
+  "platform": "firebase",
+  "strictness": "enforced",
+  "features": ["crud", "auth", "i18n", "billing", "oauth", "functions"],
+  "region": "europe-west1"
+}

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": "bunx",
+      "args": ["@donotdev/mcp-server"],
+      "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,150 @@
+# AI Agent Instructions
+
+> **You are building a DoNotDev app.** Read this file completely before doing anything else.
+
+## What To Do Right Now
+
+1. **Verify MCP is working.** Try calling `list_features()`. If it works, you're good. If not:
+   - **Cursor:** Settings → Tools & MCP → toggle "donotdev" ON. MCP only works in Composer mode (`Cmd/Ctrl+I`).
+   - **Claude Code / Windsurf:** Auto-connects from `.mcp.json`. If broken, check `bun` is in PATH.
+2. **Check environment setup.** Ask the user: "Have you run `bun install`? Run `dndev dev` and open the app — the homepage has setup steps for Git, Firebase, and .env."
+3. Call `start_phase(0)` — begin **Phase 0: BRAINSTORM**
+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
+
+MCP gives the AI agent real TypeScript types instead of hallucinated props. Config files are auto-created by `dndev init`.
+
+| IDE | Config | Setup |
+|-----|--------|-------|
+| **Claude Code** | `.mcp.json` | Auto-connects. Nothing to do. |
+| **Windsurf** | `.mcp.json` | Auto-connects. Nothing to do. |
+| **Cursor** | `.cursor/mcp.json` | Settings → Tools & MCP → toggle "donotdev" ON. **MCP only works in Composer mode** (`Cmd/Ctrl+I`). |
+| **Gemini CLI** | `.gemini/settings.json` | Auto-connects. Nothing to do. |
+
+**If MCP tools aren't available**, guide the user:
+1. Check `bun` is in PATH (`which bun`)
+2. **Cursor:** Must be in Composer mode (`Cmd/Ctrl+I`) and server toggled ON
+3. Check MCP logs: `Cmd/Ctrl+Shift+U` → Output → "MCP Logs"
+
+**Without MCP (ChatGPT, Copilot, etc.):** Read blueprints from `guides/wai-way/blueprints/` and types from `node_modules/@donotdev/*/dist/*.d.ts`. You lose symbol tracking and convention enforcement.
+
+## MCP Tools (13 — Pre-Configured)
+
+MCP config files are auto-created in `.mcp.json` / `.cursor/mcp.json` / `.gemini/settings.json`. **You must enable the server in your IDE settings** (see "Supported IDEs" above). Once enabled, 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 |
+| `list_features()` | List all framework packages with summaries |
+| `record_lesson("text")` | Save to project memory (returned on next start_phase) |
+| `init_implementation({ from_spec: true })` | Create `.dndev/implementation.md` to track progress |
+| `update_progress({ item: "...", done: true })` | Tick/untick items in implementation checklist |
+| `get_progress()` | Read implementation progress stats |
+| `get_project_history()` | Get captain's log with full session history |
+
+## 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

@@ -17,7 +17,7 @@
 - **Creating with framework** (Mode 3): Build new app features
 - **Tweaking framework app** (Mode 4): Modify existing app features
 
-**CLI:** `dndev` (public CLI, installed globally)
+**CLI:** `dndev` (public CLI, installed globally via `npm install -g @donotdev/cli`)
 
 **Workflow:**
 1. `/design [requirement]` → Architect designs solution
@@ -29,7 +29,7 @@
 **⚠️ IMPORTANT:**
 - Use ONLY published `@donotdev/*` packages
 - Cannot modify framework internals
-- If framework needs changes, work in monorepo (`c:\ws\dndev`)
+- If framework needs changes, work in the framework monorepo (this repo)
 
 ---
 
@@ -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,25 @@ 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)
+## Project Args & Gotchas
 
-**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
+- **`.dndev/args.json`** — Per-project config (platform, strictness, features, region). All features ON by default. Phase 0 narrows down. Edit `strictness` to control validation: `enforced` (default) | `warnings` | `permissive`.
+- **`guides/dndev/GOTCHAS.md`** — Common mistakes, phase-tagged. Read directly or loaded by MCP `start_phase()`.
+- **Without MCP:** Both files are plain JSON/markdown — any agent reads them directly. MCP automates filtering + enforcement but is not required.
 
-**Quality Over Speed:** Each phase must be complete before proceeding. Take as long as needed.
+## WAI-WAY Workflow
 
-### Brainstorm Phase
+**Read `AI.md` at the project root for the full workflow.**
 
-**Use `/brainstorm [app idea]` to extract complete requirements.**
+For each phase (0=BRAINSTORM, 1=SCAFFOLD, 2=ENTITIES, 3=COMPOSE, 4=CONFIGURE):
 
-**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, lessons, project args, and phase-relevant gotchas
+2. Work — follow blueprint, call `lookup_symbol` before using any component
+3. `mcp:complete_phase({ files })` — validates conventions + symbol usage (respects `strictness`), submits for review
+4. `mcp:approve_phase()` — user approves, phase is done