@donotdev/cli 0.0.3 → 0.0.5

package/templates/root-consumer/guides/SETUP_PAGES.md.example

@@ -0,0 +1,120 @@
+# Setup: Pages & Routing
+
+**Most is pre-configured.** Drop `*Page.tsx` files. Routes auto-discovered, navigation auto-generated, sitemap auto-built.
+
+---
+
+## File Routing Rule
+
+**CRITICAL: Only files ending in `Page.tsx` inside `src/pages` become routes.**
+
+Files must be named `*Page.tsx` (e.g., `HomePage.tsx`, `AboutPage.tsx`, `BlogPostPage.tsx`). Files without the `Page.tsx` suffix are ignored by the routing system.
+
+---
+
+## Standard Use
+
+**Pattern:** `src/pages/**/*Page.tsx` → routes
+
+**Basic page structure:**
+```tsx
+// src/pages/AboutPage.tsx
+import { PageContainer } from '@donotdev/ui';
+
+export const NAMESPACE = 'about';
+
+export const meta: PageMeta = {
+  namespace: NAMESPACE,
+};
+
+export default function AboutPage() {
+  return <PageContainer><h1>About</h1></PageContainer>;
+}
+```
+
+**Cookie-cutter pattern (Landing page):**
+```tsx
+import { PageContainer } from '@donotdev/ui';
+import { HeroSection, Section, Card, CallToAction } from '@donotdev/components';
+
+export default function HomePage() {
+  return (
+    <PageContainer>
+      <HeroSection title="Welcome" subtitle="Build fast" variant="primary" />
+      <Section title="Features" gridCols={3}>
+        <Card title="Fast" />
+        <Card title="Simple" />
+        <Card title="Powerful" />
+      </Section>
+      <CallToAction title="Get Started" primaryAction={<Button>Sign Up</Button>} />
+    </PageContainer>
+  );
+}
+```
+
+**Drop files, get routes. No config needed.**
+
+**Component reference:** See [COMPONENTS_ATOMIC.md](./COMPONENTS_ATOMIC.md) for atomic components, [COMPONENTS_UI.md](./COMPONENTS_UI.md) for layout components.
+
+---
+
+## Advanced: All PageMeta Props
+
+```tsx
+export const meta: PageMeta = {
+  // Translation/SEO namespace
+  namespace: NAMESPACE,
+  
+  // Route configuration
+  route: '/custom-url',                    // Override auto-generated path
+  route: { params: ['slug'] },            // Dynamic: /blog/:slug
+  
+  // Page title (optional - auto-extracted from filename)
+  title: 'Custom Title',
+  
+  // Navigation icon (lucide-react JSX only)
+  icon: <Rocket />,                        // Menu icon (default: Link)
+  
+  // Hide from navigation menu
+  hideFromMenu: false,                     // Default: false (shows in nav)
+  
+  // Authentication
+  auth: true,                              // Simple: auth required
+  auth: { required: true },                // Explicit: auth required
+  auth: { required: true, role: 'admin' }, // Role-based access
+  auth: { required: true, tier: 'pro' },   // Tier-based access
+  auth: { 
+    required: true,
+    validate: (role, tier) => role === 'admin' && tier === 'pro'
+  },                                       // Custom validation
+};
+```
+
+---
+
+## Advanced: Dynamic Routes & Navigation
+
+```tsx
+// Dynamic route
+export const meta: PageMeta = {
+  namespace: 'blog',
+  route: { params: ['slug'] },  // → /blog/:slug
+};
+
+export default function BlogPostPage() {
+  const { slug } = useParams<{ slug: string }>();
+  return <PageContainer><h1>{slug}</h1></PageContainer>;
+}
+
+// Manual navigation
+import { useNavigate, Link } from '@donotdev/ui';
+const navigate = useNavigate();
+navigate('/about');
+<Link path="/about">About</Link>
+```
+
+**Pre-configured:** Navigation menu auto-generated, sitemap auto-built (if `generateSitemap: true`).
+
+---
+
+**Drop files, get routes. Framework handles the rest.**

package/templates/root-consumer/guides/SETUP_THEMES.md.example

@@ -0,0 +1,107 @@
+# Setup: Themes
+
+**Most is pre-configured.** Override CSS variables in `src/themes.css`. Framework handles theme switching, auto-computed colors.
+
+---
+
+## Standard Use
+
+**File:** `src/themes.css` (scaffolded with all variables)
+
+**Override colors:**
+```css
+:root {
+  /* Brand colors */
+  --primary: #2563eb;
+  --secondary: #9333ea;
+  --accent: #ec4899;
+  
+  /* Base colors */
+  --background: #ffffff;
+  --foreground: #000000;
+}
+```
+
+**Add custom theme:**
+```css
+.ocean {
+  --theme-icon: 'Waves';
+  --theme-label: 'Ocean';
+  --primary: #0ea5e9;
+  --background: #001a33;
+  --foreground: #e0f2fe;
+}
+```
+
+**Framework auto-computes:** Surfaces (card, popover), muted colors, borders, text on brand colors.
+
+---
+
+## Advanced: All CSS Variables
+
+**Brand colors:**
+```css
+--primary, --secondary, --accent
+--primary-foreground, --secondary-foreground, --accent-foreground
+```
+
+**Base colors:**
+```css
+--background, --foreground
+```
+
+**Status colors:**
+```css
+--success, --warning, --destructive
+--success-foreground, --warning-foreground, --destructive-foreground
+```
+
+**Surfaces:**
+```css
+--card, --card-foreground
+--popover, --popover-foreground
+--muted, --muted-foreground
+--border, --input, --ring
+```
+
+**Theme metadata:**
+```css
+--theme-icon: 'Sun';      /* Lucide icon name */
+--theme-label: 'Light';    /* Display name */
+--theme-is-dark: 0;        /* 0 = light, 1 = dark */
+```
+
+---
+
+## Advanced: Styling Overrides
+
+**Utility classes:**
+```tsx
+<Card className="dndev-gap-sm" />  // Gap utilities
+<div className="dndev-flex dndev-gap-md" />  // Layout utilities
+```
+
+**Data attributes:**
+```tsx
+<HeroSection data-text-align="center" title="Centered" />
+<div data-gap="medium" data-radius="md" />
+```
+
+**Inline styles:**
+```tsx
+<Button style={{ minWidth: '200px' }} />
+```
+
+**Global CSS rules:**
+```css
+/* src/themes.css */
+.dndev-button {
+  border-radius: 8px;  /* Override default */
+}
+```
+
+**Framework respects your overrides.** All components use CSS variables, so color changes propagate automatically.
+
+---
+
+**Override variables, get themes. Framework handles the rest.**

package/templates/root-consumer/guides/advanced/COOKIE_REFERENCE.md.example

@@ -0,0 +1,252 @@
+# Cookie Reference Guide
+
+**For Framework Consumers: GDPR Compliance**
+
+---
+
+## Overview
+
+This guide maps DoNotDev framework features to the cookies they set, helping you configure your cookie consent banner and privacy policy correctly.
+
+---
+
+## Cookie Categories (GDPR)
+
+- **Necessary** - Essential for service to function (no consent required per GDPR Article 6(1)(f))
+- **Functional** - Enhances experience (requires consent per GDPR Article 6(1)(a))
+- **Analytics** - Usage tracking (requires consent)
+- **Marketing** - Advertising/tracking (requires consent)
+
+---
+
+## Feature Cookie Mapping
+
+### Authentication (`@donotdev/auth`)
+
+**Provider: Firebase Authentication**
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| `__session` | Necessary | Session authentication token | Session |
+| `__Secure-*` | Necessary | Security tokens (HTTPS only) | Varies |
+
+**GDPR Status:** Necessary - Authentication is essential for account-based services.
+
+**Environment Variables:**
+```bash
+VITE_FIREBASE_API_KEY=your-key
+VITE_FIREBASE_PROJECT_ID=your-project
+```
+
+---
+
+### OAuth (`@donotdev/oauth`)
+
+**Providers: Google, GitHub OAuth**
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| OAuth state cookies | Necessary | CSRF protection during OAuth flow | Session |
+| Provider session cookies | Necessary | Maintain OAuth session | Per provider |
+
+**GDPR Status:** Necessary - Part of authentication flow.
+
+**Environment Variables:**
+```bash
+VITE_AUTH_PARTNERS=google,github
+```
+
+**Third-party cookies set by OAuth providers:**
+- **Google:** `SID`, `HSID`, `SSID`, `APISID`, `SAPISID` (necessary for OAuth)
+- **GitHub:** `user_session`, `logged_in` (necessary for OAuth)
+
+---
+
+### Billing (`@donotdev/billing`)
+
+**Provider: Stripe**
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| `__stripe_mid` | Necessary | Fraud prevention | 1 year |
+| `__stripe_sid` | Necessary | Checkout session | 30 minutes |
+
+**GDPR Status:** Necessary - Required for payment processing and fraud prevention.
+
+**Environment Variables:**
+```bash
+VITE_STRIPE_PUBLIC_KEY=pk_live_xxx
+```
+
+**Stripe Privacy:** Stripe sets these cookies when Checkout or Customer Portal is opened. They're classified as necessary for PCI compliance and fraud prevention.
+
+---
+
+### Framework Core Cookies
+
+**Set by `@donotdev/core`**
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| `dndev-cookie-consent` | Necessary | Stores user's cookie preferences | 365 days |
+| `dndev-theme` | Necessary | Remembers dark/light mode preference | 365 days |
+| `dndev-lang` | Necessary | Remembers language preference | 365 days |
+
+**GDPR Status:** Necessary (essential for UX, no tracking, purely local preferences)
+
+---
+
+## Analytics & Marketing (Optional)
+
+These are NOT included in the framework but commonly added by consumers:
+
+### Google Analytics
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| `_ga` | Analytics | Distinguish users | 2 years |
+| `_gid` | Analytics | Distinguish users | 24 hours |
+| `_gat` | Analytics | Throttle requests | 1 minute |
+
+**GDPR Status:** Analytics - Requires explicit consent.
+
+**Setup:** Consumer must add Google Analytics script and obtain consent.
+
+### Facebook Pixel
+
+| Cookie Name | Category | Purpose | Expires |
+|------------|----------|---------|---------|
+| `_fbp` | Marketing | Track conversions | 90 days |
+
+**GDPR Status:** Marketing - Requires explicit consent.
+
+---
+
+## Cookie Banner Configuration
+
+### Minimal Setup (Auth + Billing + Theme/Lang)
+
+If your app only uses auth, billing, theme, and language preferences, all cookies are **necessary**:
+
+```typescript
+// src/config/app.ts
+export const appConfig: AppConfig = {
+  features: {
+    // No config needed - all framework cookies are necessary
+  },
+};
+```
+
+**Result:** No cookie banner shown - all cookies are GDPR-compliant without consent.
+
+### With Analytics/Marketing
+
+If you add Google Analytics or marketing pixels:
+
+```typescript
+// src/config/app.ts
+export const appConfig: AppConfig = {
+  features: {
+    requiredCookies: ['necessary', 'functional', 'analytics'],
+  },
+};
+```
+
+**Result:** Cookie banner shows all categories, users must consent to analytics.
+
+---
+
+## Privacy Policy Template
+
+**Example text for your privacy policy:**
+
+```markdown
+## Cookies We Use
+
+### Essential Cookies (Always Active)
+
+We use essential cookies that are necessary for our service to function:
+
+- **Authentication** (Firebase): Maintains your login session
+- **Payment Processing** (Stripe): Enables secure payments and fraud prevention
+- **Cookie Preferences**: Remembers your cookie consent choices
+
+These cookies are essential and cannot be disabled.
+
+### Functional Cookies (Optional)
+
+With your consent, we use functional cookies to enhance your experience:
+
+- **Theme Preference**: Remembers your dark/light mode choice
+- **Language Preference**: Remembers your selected language
+
+You can disable these in cookie settings.
+
+### Analytics Cookies (Optional) [If applicable]
+
+With your consent, we use Google Analytics to understand how visitors use our site.
+This helps us improve the user experience.
+
+You can disable these in cookie settings.
+```
+
+---
+
+## Testing Cookie Compliance
+
+### Check What Cookies Are Set
+
+```javascript
+// Browser console
+document.cookie
+```
+
+### Verify Consent Before Analytics
+
+```typescript
+import { useConsent } from '@donotdev/core';
+
+function MyAnalytics() {
+  const hasAnalyticsConsent = useConsent('hasCategory')('analytics');
+
+  useEffect(() => {
+    if (hasAnalyticsConsent) {
+      // Initialize Google Analytics
+    }
+  }, [hasAnalyticsConsent]);
+}
+```
+
+---
+
+## GDPR Compliance Checklist
+
+- [ ] List all cookies in privacy policy with categories
+- [ ] Only set analytics/marketing cookies after consent
+- [ ] Provide cookie settings link in footer
+- [ ] Allow users to withdraw consent
+- [ ] Store consent for 12 months maximum
+- [ ] Don't block essential features if functional cookies declined
+
+**Framework handles:** Consent storage, banner UI, category management
+
+**You handle:** Privacy policy text, analytics integration, marketing pixels
+
+---
+
+## Quick Reference
+
+| Feature | Cookies | Category | Consent Required? |
+|---------|---------|----------|-------------------|
+| Auth | `__session`, `__Secure-*` | Necessary | No |
+| OAuth | Provider session cookies | Necessary | No |
+| Billing | `__stripe_mid`, `__stripe_sid` | Necessary | No |
+| Theme | `dndev-theme` | Necessary | No |
+| Language | `dndev-lang` | Necessary | No |
+| Consent | `dndev-cookie-consent` | Necessary | No |
+| Analytics | `_ga`, `_gid` | Analytics | Yes |
+| Marketing | `_fbp`, etc. | Marketing | Yes |
+
+---
+
+**Need help?** Check your browser DevTools → Application → Cookies to see exactly what's being set.

package/templates/root-consumer/guides/{EMULATOR_SETUP.md.example → advanced/EMULATORS.md.example}

@@ -37,7 +37,7 @@ STRIPE_WEBHOOK_SECRET=whsec_... # Your permanent production webhook secret
 
 ```bash
 # Start emulators for a specific app
-dn emu showcase
+dndev emu showcase
 ```
 
 If you need Stripe webhook forwarding, the emulator command will provide instructions on how to start the Stripe CLI and where to paste the temporary webhook secret.

package/templates/root-consumer/guides/{VERSION_CONTROL.md.example → advanced/VERSION_CONTROL.md.example}

@@ -171,11 +171,4 @@ Review the migration guide before updating.
 
 ---
 
-## Related
-
-- **[Dependency System](../../docs/development/DEPENDENCY_SYSTEM.md)** - How dependency management works
-- **[Architecture Hub](../../docs/architecture/INDEX.md)** - Framework structure
-
----
-
 **Keep your dependencies up to date. Stay secure. Stay compatible.**

package/templates/root-consumer/guides/AUTH_SETUP.md.example

@@ -1,92 +0,0 @@
-# Authentication Setup
-
-**For AI Agents:** Configure auth providers and routes. Framework handles the rest.
-
----
-
-## 1. Environment Variables
-
-```bash
-# .env
-VITE_AUTH_PARTNERS=password,emailLink,google,github,facebook
-```
-
-**Available Firebase Auth providers:** `password`, `emailLink`, `google`, `github`, `facebook`, `twitter`, `microsoft`, `yahoo`, `apple`
-
-**Default:** If not set, only `google` is enabled.
-
----
-
-## 2. App Configuration
-
-```typescript
-// apps/your-app/src/config/app.ts
-import type { AppConfig } from '@donotdev/core';
-
-export const appConfig: AppConfig = {
-  auth: {
-    authRoute: '/login',   // Redirect when auth required (default: '/login')
-    roleRoute: '/404',      // Redirect when role insufficient (default: '/404')
-    tierRoute: '/404',      // Redirect when tier insufficient (default: '/404')
-    loginPath: '/login',   // Optional: Login page path (undefined = show providers in header)
-    profilePath: '/profile', // Optional: Profile page path (default: '/profile')
-  },
-};
-```
-
----
-
-## 3. Firebase Console Setup
-
-**User must enable providers in Firebase Console:**
-- Authentication > Sign-in method
-- Enable Email/Password (for `password` and `emailLink`)
-- Enable OAuth providers (Google, GitHub, etc.) and configure credentials
-
----
-
-## What You Get
-
-**Automatic:**
-- ✅ `AuthHeader` component in layout (null if auth not needed)
-- ✅ OAuth callbacks handled automatically
-- ✅ Protected routes via `PageMeta.auth`
-- ✅ Session management
-
-**Components:**
-- `AuthHeader`, `AuthMenu` from `@donotdev/ui`
-- `LoginTemplate` from `@donotdev/templates`
-- `EmailPasswordForm`, `MultipleAuthProviders` from `@donotdev/auth`
-
-**Hook:**
-```typescript
-import { useAuth } from '@donotdev/auth';
-
-const user = useAuth('user');
-const signIn = useAuth('signInWithEmail');
-const signOut = useAuth('signOut');
-```
-
----
-
-## Protected Route Example
-
-```typescript
-// apps/your-app/src/pages/DashboardPage.tsx
-export const meta = {
-  namespace: 'dashboard',
-  auth: { required: true }, // ← Protected route
-};
-
-export default function DashboardPage() {
-  const user = useAuth('user');
-  return <PageContainer>Welcome, {user?.displayName}!</PageContainer>;
-}
-```
-
----
-
-**Files to modify:**
-- `.env` - Add `VITE_AUTH_PARTNERS`
-- `src/config/app.ts` - Add `auth` config
-- `src/pages/**/*.tsx` - Add `auth` to `PageMeta` for protected routes

package/templates/root-consumer/guides/BILLING_SETUP.md.example

@@ -1,120 +0,0 @@
-# Billing Setup
-
-**For AI Agents:** Create Stripe config files. Framework handles checkout, webhooks, subscriptions.
-
----
-
-## 1. Environment Variables
-
-**Local Emulators (.env.local):**
-```bash
-# apps/your-app/functions/.env.local
-STRIPE_SECRET_KEY=sk_test_xxx
-STRIPE_WEBHOOK_SECRET=whsec_xxx        # Get from 'stripe listen'
-```
-
-**Production (.env):**
-```bash
-# apps/your-app/functions/.env
-STRIPE_SECRET_KEY=sk_live_xxx
-STRIPE_WEBHOOK_SECRET=whsec_xxx        # Permanent production secret
-```
-
-**Frontend (.env):**
-```bash
-# apps/your-app/.env
-VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
-```
-
----
-
-## 2. Stripe Dashboard
-
-**User must:**
-1. Create products in Stripe Dashboard
-2. Copy Price IDs (starts with `price_...`)
-
----
-
-## 3. Frontend Config
-
-```typescript
-// apps/your-app/src/config/stripeFrontConfig.ts
-import type { StripeFrontConfig } from '@donotdev/core';
-
-export const stripeFrontConfig: StripeFrontConfig = {
-  pro_plan: {
-    name: 'Pro Plan',
-    price: 29,
-    currency: 'USD',
-    description: 'Perfect for growing teams',
-    features: ['Unlimited projects', 'Priority support'],
-    priceId: 'price_1234567890', // ← Stripe Price ID
-    allowPromotionCodes: true,
-  },
-};
-```
-
----
-
-## 4. Backend Config
-
-```typescript
-// apps/your-app/functions/src/config/stripeBackConfig.ts
-import type { StripeBackConfig } from '@donotdev/core';
-
-export const stripeBackConfig: StripeBackConfig = {
-  pro_plan: {
-    type: 'StripeSubscription', // or 'StripePayment'
-    name: 'Pro Plan',
-    price: 2900, // In cents
-    currency: 'USD',
-    priceId: process.env.STRIPE_PRICE_PRO_PLAN!,
-    tier: 'pro',
-    duration: 'month',
-
-    // Optional hooks
-    onPurchaseSuccess: async (userId, metadata) => {
-      // Grant features, send email, etc.
-    },
-    onSubscriptionCancelled: async (userId) => {
-      // Revoke features, etc.
-    },
-  },
-};
-```
-
----
-
-## 5. Wire Up Functions
-
-```typescript
-// apps/your-app/functions/src/index.ts
-import { createCheckoutSession } from '@donotdev/functions/firebase';
-import { stripeBackConfig } from './config/stripeBackConfig';
-
-export const createCheckout = createCheckoutSession(stripeBackConfig);
-```
-
----
-
-## What You Get
-
-**Components:**
-- `SubscriptionTemplate`, `PaymentTemplate` from `@donotdev/templates`
-- `ProductCard`, `SubscriptionManager` from `@donotdev/billing`
-
-**Hook:**
-```typescript
-import { useStripeBilling } from '@donotdev/billing';
-
-const checkout = useStripeBilling('checkout');
-await checkout({ priceId: 'price_123', mode: 'subscription' });
-```
-
----
-
-**Files to create:**
-- `src/config/stripeFrontConfig.ts` - Frontend config
-- `functions/src/config/stripeBackConfig.ts` - Backend config
-- `functions/src/index.ts` - Wire up functions