@donotdev/cli 0.0.12 → 0.0.13

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

@@ -0,0 +1,263 @@
+# Setup: Blog
+
+**Convention-based markdown blog.** Drop `slug_lang.md` files in `src/content/blog/`, get a fully functional blog with i18n, reading time, tags, RSS, and sitemap.
+
+---
+
+## Quick Start
+
+### 1. Create the content directory
+
+```
+src/content/blog/
+├── my-first-post_en.md
+├── my-first-post_fr.md
+└── another-post_en.md
+```
+
+### 2. Write a post with frontmatter
+
+```markdown
+---
+title: My First Post
+description: A short summary for listings and SEO
+date: 2025-06-01
+tags: tutorial, getting-started
+image: /blog/my-first-post.png
+---
+
+Your markdown content here. Supports:
+- **Bold**, *italic*, ~~strikethrough~~
+- [Internal links](/faq) and [external links](https://example.com)
+- Images: ![alt text](/blog/my-image.png)
+- Code blocks with syntax highlighting
+```
+
+### 3. Create the data loader
+
+```typescript
+// src/data/blog/index.ts
+import { createBlogLoader } from '@donotdev/templates';
+import type { BlogLoader } from '@donotdev/templates';
+
+const markdownFiles = import.meta.glob('../../content/blog/*.md', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+});
+
+export function getBlogLoader(lang: string = 'en'): BlogLoader {
+  return createBlogLoader(markdownFiles as Record<string, string>, lang);
+}
+```
+
+### 4. Create the listing page
+
+```typescript
+// src/pages/BlogPage.tsx
+import { BookOpen } from 'lucide-react';
+import { HeroSection } from '@donotdev/components';
+import { useTranslation, type PageMeta } from '@donotdev/core';
+import { BlogList } from '@donotdev/templates';
+import { PageContainer } from '@donotdev/ui';
+import { getBlogLoader } from '../data/blog';
+
+export const NAMESPACE = 'blog';
+export const meta: PageMeta = { namespace: NAMESPACE, icon: <BookOpen /> };
+
+export default function BlogPage() {
+  const { t, i18n } = useTranslation([NAMESPACE]);
+  const posts = getBlogLoader(i18n?.language).getAllPosts();
+
+  return (
+    <PageContainer variant="docs">
+      <HeroSection title={t('title')} subtitle={t('subtitle')} />
+      <BlogList posts={posts} />
+    </PageContainer>
+  );
+}
+```
+
+### 5. Create the post page (dynamic route)
+
+```typescript
+// src/pages/BlogPostPage.tsx
+import { BookOpen } from 'lucide-react';
+import { useTranslation, type PageMeta } from '@donotdev/core';
+import { BlogPostView } from '@donotdev/templates';
+import { PageContainer, useRouteParam } from '@donotdev/ui';
+import { getBlogLoader } from '../data/blog';
+
+export const NAMESPACE = 'blog';
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+  icon: <BookOpen />,
+  route: '/blog/:slug',
+  hideFromMenu: true,
+};
+
+export default function BlogPostPage() {
+  const { i18n } = useTranslation([NAMESPACE]);
+  const slug = useRouteParam('slug');
+  const post = slug ? getBlogLoader(i18n?.language).getPostBySlug(slug) : null;
+
+  return (
+    <PageContainer variant="docs">
+      <BlogPostView post={post} />
+    </PageContainer>
+  );
+}
+```
+
+### 6. Add locale files
+
+Blog UI labels (`readMore`, `backToBlog`, `publishedOn`, etc.) are provided by the framework via `blog_*.json` in `@donotdev/core`. Override any key by creating the same file in your app.
+
+Page-specific strings (title, subtitle) go in your app locale:
+
+```json
+// src/pages/locales/blog_en.json
+{
+  "title": "Blog",
+  "subtitle": "Your subtitle here"
+}
+```
+
+---
+
+## File Convention
+
+**Pattern:** `slug_lang.md`
+
+| File | Slug | Language |
+|------|------|----------|
+| `my-post_en.md` | `my-post` | English |
+| `my-post_fr.md` | `my-post` | French |
+| `my-post_de.md` | `my-post` | German |
+| `solo-post_en.md` | `solo-post` | English (no FR = falls back to EN) |
+
+**Rules:**
+- Slug = everything before the last `_xx` suffix
+- Language suffix must be 2-5 characters (ISO codes)
+- English (`_en`) is the fallback language
+- If a post only exists in `_en`, it's shown for all languages
+
+---
+
+## Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Post title |
+| `description` | Yes | Summary for listings and SEO |
+| `date` | Yes | Publication date (YYYY-MM-DD) |
+| `tags` | No | Comma-separated tags |
+| `image` | No | Hero image path — must be in `public/blog/` (see Images section) |
+
+Custom fields are preserved in `meta[key]`.
+
+---
+
+## Images
+
+### Hero Images (frontmatter `image` field)
+
+One image per post. Used in blog listing cards, article page, RSS feed, and OG/social sharing.
+
+**Convention:**
+- **Location:** `public/blog/[slug].png` (matches the post slug)
+- **Size:** 1200×630px minimum (standard OG ratio, sharp on retina)
+- **Format:** PNG or JPG
+- **Reference:** `image: /blog/my-post.png` in frontmatter
+
+```
+public/
+└── blog/
+    ├── my-first-post.png        ← matches my-first-post_en.md
+    ├── another-post.png         ← matches another-post_en.md
+    └── inline-diagram.svg       ← used in markdown body
+```
+
+**Where it shows:**
+| Context | Sizing |
+|---------|--------|
+| Blog listing (featured card) | `width: 100%`, `max-height: 360px`, `object-fit: cover` |
+| Blog listing (grid cards) | `width: 100%`, `max-height: 180px`, `object-fit: cover` |
+| Article page | `width: 100%`, `max-height: 480px`, `object-fit: cover` |
+| RSS feed | `<enclosure>` with full URL |
+
+### Inline Images (in markdown body)
+
+Images referenced in markdown content also go in `public/blog/`:
+
+```markdown
+![Architecture diagram](/blog/inline-diagram.svg)
+```
+
+Rendered with `loading="lazy"` and `decoding="async"`.
+
+**Co-located images (next to .md files) do NOT work** — `?raw` imports treat markdown as text strings, not processed modules.
+
+---
+
+## Tags & Filtering
+
+```typescript
+const blog = getBlogLoader('en');
+const allTags = blog.getAllTags();           // ['react', 'typescript', ...]
+const filtered = blog.getPostsByTag('react'); // Posts tagged 'react'
+```
+
+---
+
+## RSS & Sitemap
+
+**Auto-generated at build time.** The SEO pipeline (Vite `SEOPlugin` / Next.js `SEOHandler`) automatically:
+
+1. Discovers `src/content/blog/*_en.md` files
+2. Appends blog post URLs to `sitemap.xml`
+3. Generates `rss.xml` with all posts
+
+No manual scripts needed. Just drop `.md` files and build.
+
+---
+
+## Scaling (50+ Posts)
+
+Default uses `eager: true` (all posts bundled into JS). For large blogs, switch to lazy loading:
+
+```typescript
+// Lazy: posts loaded on demand, not bundled
+const markdownFiles = import.meta.glob('../../content/blog/*.md', {
+  query: '?raw',
+  import: 'default',
+  eager: false,  // ← Change this
+});
+
+// Now each value is () => Promise<string> instead of string
+// You'll need to await them before passing to createBlogLoader
+```
+
+For most apps (< 50 posts), eager loading is optimal.
+
+---
+
+## Auto-Deploy
+
+Push a new `.md` file → CI builds → `import.meta.glob` picks it up at build time → deployed. No CMS, no API.
+
+---
+
+## API Reference
+
+From `@donotdev/templates`:
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `createBlogLoader` | Function | Create loader from glob results + language |
+| `parseFrontmatter` | Function | Parse `---` frontmatter from raw markdown |
+| `BlogList` | Component | Renders post listing with cards |
+| `BlogPostView` | Component | Renders single post with MarkdownViewer |
+| `BlogPost` | Type | Post with slug, meta, content, readingTime, tags |
+| `BlogMeta` | Type | Frontmatter metadata |
+| `BlogLoader` | Type | Loader interface |

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

@@ -366,7 +366,7 @@ export default function ProductDetailPage() {
   return (
     <PageContainer>
       <Section>
-        <Stack direction="row" gap="medium" align="center">
+        <Stack direction="row" align="center">
           <h1>{data.name}</h1>
           <Button
             variant={isFavorite(id) ? 'primary' : 'outline'}

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

@@ -0,0 +1,168 @@
+# Setup: Firebase
+
+**From zero to deployed in 5 steps.**
+
+---
+
+## Step 1: Run Firebase Setup
+
+```bash
+dndev firebase:setup
+```
+
+This command:
+- Checks Firebase CLI is installed and you're logged in
+- Lists your Firebase projects (or creates a new one)
+- Creates a web app if the project doesn't have one
+- Gets the SDK config and writes it to your app's `.env`
+- Updates `.firebaserc` with the project ID
+- Updates `firebase.json` placeholders
+
+**After running, it will prompt you for 2 manual steps (below).**
+
+---
+
+## Step 2: Download Service Account Key
+
+The CLI gives you a direct link. In short:
+
+1. Firebase Console → Project Settings → Service Accounts
+2. Click "Generate new private key"
+3. Save the file as `service-account-key.json` in your app root
+4. This file is `.gitignored` — never commit it
+
+**Why?** The service account key authenticates `dndev deploy` and Cloud Functions to your Firebase project. Without it, deployment fails.
+
+---
+
+## Step 3: Enable Firebase Services
+
+Go to the Firebase Console and enable:
+
+**Authentication** (required):
+- Get Started → Enable Email/Password
+- Add OAuth providers if needed (Google, GitHub, etc.)
+
+**Cloud Firestore** (required):
+- Create Database → Start in test mode → Select region (e.g., europe-west1)
+- Test mode rules expire after 30 days — Phase 4 generates proper rules
+
+**Storage** (optional — only if your app uploads files):
+- Get Started → Select region
+
+---
+
+## Step 4: Test Locally
+
+```bash
+dndev emu start
+```
+
+Select services: Auth + Firestore + Functions. This starts Firebase emulators so you can develop without touching production.
+
+**Verify:** Open the app (`bun dev`), sign up, create some data. Everything runs locally.
+
+---
+
+## Step 5: Deploy
+
+```bash
+dndev deploy
+```
+
+This handles everything:
+- Builds the app
+- Deploys hosting (your frontend)
+- Deploys Cloud Functions (your backend)
+- Configures Cloud Run IAM automatically (fixes CORS preflight on 2nd gen functions)
+- Deploys Firestore rules (if `firestore.rules` exists)
+
+**After deploy:** Your app is live at `https://<project-id>.web.app`.
+
+---
+
+## Environment Variables
+
+**Vite loads `.env` from the app directory only. NOT from the repo root.**
+
+| File | What Goes Here | Loaded By |
+|------|---------------|-----------|
+| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key | Vite (at dev + build) |
+| `apps/<app>/.env.local` | Local overrides (gitignored) | Vite (overrides .env) |
+| `apps/<app>/.env.production` | Production overrides | Vite (at build --mode production) |
+| `apps/<app>/.env.staging` | Staging config | Vite (via `dndev staging`) |
+| `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | Cloud Functions runtime |
+| Root `.env` | **Not read by Vite.** Reference only. | Nothing |
+
+**`dndev firebase:setup` writes Firebase vars to `apps/<app>/.env` automatically.**
+
+**Custom domains:** Framework uses `APP_URL` hostname as `authDomain` in production (not Firebase's `projectId.firebaseapp.com`). Copy/paste `FIREBASE_AUTH_DOMAIN` from Firebase Console in both `.env.local` and `.env.production` — framework handles the rest.
+
+---
+
+## Staging Environment (Optional)
+
+1. Create a second Firebase project (e.g., `my-app-staging`)
+2. Run `dndev firebase:setup` again and select the staging project
+3. Add to `.firebaserc`: `{ "projects": { "staging": "my-app-staging" } }`
+4. Create `service-account-key.staging.json` (same steps as production)
+5. Deploy: `dndev staging`
+
+---
+
+## Secrets (Stripe, OAuth, etc.)
+
+Server-side secrets go in `functions/.env`, not the app `.env`:
+
+```bash
+# functions/.env
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+GITHUB_CLIENT_SECRET=...
+```
+
+Push to Firebase Secret Manager:
+
+```bash
+dndev sync-secrets
+```
+
+Secrets are auto-loaded by Cloud Functions at runtime. Never put server secrets in `VITE_*` variables — those are exposed to the browser.
+
+---
+
+## Cloud Run IAM (Technical Detail)
+
+Firebase 2nd gen Cloud Functions run on Cloud Run. By default, Cloud Run blocks unauthenticated OPTIONS requests (CORS preflight). This breaks browser calls to your functions.
+
+`dndev deploy` automatically runs `gcloud run services update --no-invoker-iam-check` on all deployed functions. Your functions still validate Firebase Auth in code — this only allows the CORS preflight to pass.
+
+If you deploy manually with `firebase deploy`, you'll need to run this yourself. Use `dndev deploy` instead.
+
+---
+
+## Troubleshooting
+
+**"Service account key not found"**
+→ Download from Firebase Console → Service Accounts → Generate new private key
+→ Save as `service-account-key.json` in your app root
+
+**"Permission denied" / 401 on deploy**
+→ Check service account key is valid JSON with `project_id`, `private_key`, `client_email`
+→ Re-download if corrupted
+
+**"CORS error" on function calls**
+→ Use `dndev deploy` instead of `firebase deploy` (handles IAM automatically)
+→ Or run: `gcloud run services update <function-name> --region=<region> --no-invoker-iam-check --project=<project-id>`
+
+**".env values not loading"**
+→ Check the `.env` file is in your **app directory** (`apps/<app>/.env`), not the repo root
+→ All Vite vars must start with `VITE_`
+
+**"License key not working"**
+→ Must be in `apps/<app>/.env` as `VITE_DONOTDEV_LICENSE_KEY=dndev_...`
+→ Must start with `dndev_` and be at least 20 characters
+
+---
+
+**`dndev firebase:setup` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**

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

@@ -66,22 +66,15 @@ export const myFunction = onCall(FUNCTION_CONFIG, async (request) => {
 
 ## 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...] })`.