@donotdev/cli 0.0.3

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

@@ -0,0 +1,177 @@
+# Firebase Functions Setup
+
+This guide covers Firebase Cloud Functions setup, deployment, and the critical `functions.yaml` file.
+
+## Overview
+
+Firebase Functions provide serverless backend capabilities for your DoNotDev application. Functions are scaffolded into your app's `functions/` directory and deployed to Firebase Cloud Functions.
+
+## Structure
+
+```
+functions/
+├── src/
+│   ├── auth/                    # Authentication functions
+│   ├── oauth/                   # OAuth functions
+│   ├── billing/                 # Billing functions
+│   └── index.ts                # Main functions entry point
+├── package.json                # Dependencies and scripts
+├── tsconfig.json              # TypeScript configuration
+├── functions.yaml             # Firebase function manifest (auto-generated)
+├── .env.example               # Environment variables template
+├── service-account-key.json   # Firebase service account key
+└── README.md                  # Functions documentation
+```
+
+## Critical: functions.yaml
+
+**`functions.yaml` must be manually created and maintained.** This file serves as a manifest that tells Firebase which functions to deploy and their configuration.
+
+### Important Notes
+
+1. **Manually Maintained**: You must create and maintain this file yourself
+2. **Must Include All Functions**: Every function exported from `src/index.ts` must be listed in `functions.yaml`
+3. **Deployment Dependency**: If a function is missing from `functions.yaml`, it won't be deployed
+4. **Cleared Before Build**: The deployment script clears `functions.yaml` before building, so you must recreate it with all your functions
+
+### How It Works
+
+1. **Export in `src/index.ts`**: All functions must be exported from `src/index.ts`
+   ```typescript
+   export * from './billing/createCustomerPortal.js';
+   ```
+
+2. **Create Entry in `functions.yaml`**: For each exported function, add an entry:
+   ```yaml
+   endpoints:
+     createCustomerPortal:
+       region:
+         - europe-west1
+       platform: gcfv2
+       httpsTrigger: {}
+       entryPoint: createCustomerPortal
+       labels: {}
+   ```
+
+3. **Deployment Process**: During `dndev deploy`:
+   - Functions are built to `lib/`
+   - Firebase CLI deploys functions listed in `functions.yaml`
+   - `functions.yaml` is preserved and not modified by the deployment script
+
+### Troubleshooting Missing Functions
+
+If a function isn't being deployed:
+
+1. **Check Export**: Ensure the function is exported in `src/index.ts`
+2. **Check Build**: Verify the function exists in `lib/index.js` after build
+3. **Check functions.yaml**: Verify the function is listed in `functions.yaml` with correct `entryPoint` name matching the export name
+
+### Example functions.yaml
+
+```yaml
+endpoints:
+  functionName1:
+    region:
+      - europe-west1
+    platform: gcfv2
+    httpsTrigger: {}
+    entryPoint: functionName1
+    labels: {}
+  functionName2:
+    region:
+      - europe-west1
+    platform: gcfv2
+    httpsTrigger: {}
+    entryPoint: functionName2
+    labels: {}
+specVersion: v1alpha1
+requiredAPIs: []
+```
+
+## Environment Variables
+
+Functions use a different `.env` system than Vite/Next.js:
+
+- **Local Development**: `.env.local` file (Loaded automatically by `dn emu`)
+- **Production Secrets**: `.env` file (Used by `dn sync-secrets` to update Cloud Functions)
+
+**Note:** Functions don't follow Vite/Next.js `.env.local` priority rules. We enforce a strict separation: `.env` is ONLY for production, `.env.local` is ONLY for emulators.
+
+See [EMULATOR_SETUP.md](./EMULATOR_SETUP.md) for more details.
+
+### Required Environment Variables (.env.local for development)
+
+```bash
+# Stripe Configuration
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## Deployment
+
+Use the unified deployment command from workspace root:
+
+```bash
+# Deploy everything (interactive)
+dndev deploy
+
+# Deploy specific app
+dndev deploy <app-name>
+```
+
+The deployment process:
+1. Clears `lib/` folder for fresh build
+2. Builds functions to `lib/`
+3. Deploys all functions listed in `functions.yaml` (manually maintained, not modified by deployment)
+
+## Development
+
+```bash
+# Start Firebase emulators
+bun run serve
+
+# Start with debugging
+bun run dev
+```
+
+## Adding New Functions
+
+1. **Create Function File**: Add your function in `src/` (e.g., `src/billing/myNewFunction.ts`)
+2. **Export in index.ts**: Add export to `src/index.ts`:
+   ```typescript
+   export * from './billing/myNewFunction.js';
+   ```
+3. **Add to functions.yaml**: Add entry to `functions.yaml`:
+   ```yaml
+   myNewFunction:
+     region:
+       - europe-west1
+     platform: gcfv2
+     httpsTrigger: {}
+     entryPoint: myNewFunction
+     labels: {}
+   ```
+4. **Deploy**: Run `dndev deploy` - the function will be deployed if listed in `functions.yaml`
+
+## Security
+
+- All functions require authentication
+- Webhook signature verification
+- Secure token management
+- Firebase custom claims for user status
+
+## Framework Integration
+
+Functions use the framework's `@donotdev/functions` package:
+
+```typescript
+// apps/your-app/functions/src/billing/createCheckoutSession.ts
+import { createCheckoutSession as generic } from '@donotdev/functions/firebase';
+import { stripeBackConfig } from '../config/stripeBackConfig';
+
+// Your app's function = framework + your config
+export const createCheckoutSession = generic(stripeBackConfig);
+```
+
+See [Functions Package Architecture](../../../docs/architecture/packages/FUNCTIONS_PACKAGE.md) for detailed explanation.
+

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

@@ -0,0 +1,451 @@
+# 🚀 Getting Started with DoNotDev Framework
+
+This guide will help you create your first DoNotDev application from scratch.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Bun** >= 1.3.0 ([install](https://bun.sh/))
+- **Node.js** >= 20.19.0 or >= 22.12.0 (LTS)
+- **Git** (for version control)
+- A GitHub account (for framework access)
+
+## Step 1: Install the CLI
+
+```bash
+# Using npx (temporary)
+npx @donotdev/cli create-project
+
+# Or install globally with Bun
+bun add -g @donotdev/cli
+
+# Or use bunx (recommended)
+bunx @donotdev/cli create-project
+```
+
+## Choosing Your Features
+
+Before creating your project, decide what features you need:
+
+### Do You Need Billing?
+
+```
+┌─────────────────────────────────────────┐
+│ Do you need billing/subscriptions?      │
+└─────────┬───────────────────────────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+   No          Yes
+    │           │
+    ▼           ▼
+┌────────┐  ┌─────────┐
+│  Auth  │  │  Auth   │
+│  Only  │  │    +    │
+│        │  │ Billing │
+└────────┘  └─────────┘
+    │           │
+    ├───────────┼──────────────────────┐
+    │           │                      │
+    ▼           ▼                      ▼
+Internal    Subscription           One-Time
+Tools       (Recurring)            Payment
+Free Apps   SaaS Apps              Lifetime
+MVPs        Monthly/Yearly         License
+```
+
+**Auth-Only Apps:**
+
+- ✅ 49% smaller bundle
+- ✅ No Stripe overhead
+- ✅ Simpler setup
+- ✅ Easy to add billing later
+- **Use cases:** Internal tools, free apps, MVPs, prototypes
+- **Guide:** [Auth-Only Apps](docs/guides/AUTH_ONLY_APPS.md)
+
+**Billing-Enabled Apps:**
+
+- ✅ Full Stripe integration
+- ✅ 80-90% less code than manual
+- ✅ Webhook handling included
+- ✅ Subscription management
+- **Use cases:** SaaS products, paid tools, membership sites
+- **Guide:** [Billing Quickstart](docs/guides/BILLING_QUICKSTART.md)
+
+## Step 2: Create Your Project
+
+```bash
+# Run the scaffolding command
+bunx @donotdev/cli create-project
+
+# You'll be prompted for:
+# - Project name: my-awesome-app
+# - Include Firebase Functions: Yes/No
+# - App name(s): web, admin (comma-separated)
+# - Template for each app: Vite (SPA)
+```
+
+**Example interaction:**
+
+```
+🚀 DoNotDev Project Creator
+
+? Project name: my-awesome-app
+? Include Firebase Functions? Yes
+? Configuration mode? Guided (recommended)
+? App name(s): web
+? What are you building? A web application with user accounts
+? Need backend/API? Yes, Firebase
+? User authentication? Yes, email/password
+? Payment/subscriptions? No
+```
+
+## Step 3: Navigate and Install
+
+```bash
+cd my-awesome-app
+bun install
+```
+
+## Step 4: Configure Environment
+
+Create `.env` file in your project root:
+
+```bash
+# Firebase Configuration (if using Firebase)
+VITE_FIREBASE_API_KEY=your-api-key
+VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
+VITE_FIREBASE_PROJECT_ID=your-project-id
+VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
+VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
+VITE_FIREBASE_APP_ID=1:123456789:web:abcdef
+
+# Stripe Configuration (if using billing)
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# App Configuration
+VITE_APP_NAME="My Awesome App"
+VITE_APP_URL=http://localhost:5173
+```
+
+## Step 5: Start Development
+
+```bash
+# Start all apps
+bun run dev
+
+# Or start a specific app
+bun run dev:web
+```
+
+Your app should now be running at `http://localhost:5173`!
+
+**Note:** During the first build, if `logo.svg` is missing, the framework will prompt: "We didn't find a logo.svg. Do you want us to provide one from the framework?" You can say yes, or add your own logo to `public/logo.svg`.
+
+## Project Structure Explained
+
+```
+my-awesome-app/
+├── apps/
+│   └── web/                         # Your application
+│       ├── src/
+│       │   ├── pages/               # Routes (auto-discovered)
+│       │   │   ├── HomePage.tsx     # → /home
+│       │   │   ├── AboutPage.tsx    # → /about
+│       │   │   └── blog/
+│       │   │       └── BlogPostPage.tsx  # → /blog/:slug
+│       │   ├── components/          # Your components
+│       │   ├── locales/             # Translation files
+│       │   │   ├── home_en.json
+│       │   │   ├── home_fr.json
+│       │   │   └── ...
+│       │   ├── themes.css           # Custom themes
+│       │   ├── App.tsx              # App entry
+│       │   └── main.tsx             # Vite entry
+│       ├── public/                  # Static assets
+│       ├── functions/               # Backend functions (if enabled, per-app)
+│       │   ├── src/
+│       │   │   ├── firebase/       # Firebase Cloud Functions
+│       │   │   │   └── auth/
+│       │   │   │       └── onCreate.ts
+│       │   │   └── shared/         # Shared business logic
+│       │   └── package.json
+│       ├── package.json
+│       └── vite.config.ts           # Vite configuration
+├── entities/                        # Your data models (Valibot schemas, workspace package)
+│   ├── package.json                 # Workspace package (includes valibot from matrix)
+│   ├── index.ts
+│   ├── user.ts
+│   └── post.ts
+├── .env                            # Environment variables (don't commit!)
+├── .env.example                    # Example env vars (commit this)
+├── firebase.json                   # Firebase config (if using Firebase)
+├── turbo.json                      # Turborepo configuration
+└── package.json                    # Monorepo root
+```
+
+## Step 6: Create Your First Page
+
+```tsx
+// apps/web/src/pages/DashboardPage.tsx
+import { PageContainer } from '@donotdev/templates';
+import { useAuth } from '@donotdev/auth';
+
+export function DashboardPage() {
+  const { user } = useAuth();
+
+  return (
+    <PageContainer>
+      <h1>Welcome, {user?.displayName}!</h1>
+      <p>This is your dashboard.</p>
+    </PageContainer>
+  );
+}
+
+// Auto-discovered route: /dashboard
+// No configuration needed!
+```
+
+## Step 7: Add Translations
+
+```json
+// apps/web/src/locales/dashboard_en.json
+{
+  "title": "Dashboard",
+  "welcome": "Welcome, {{name}}!",
+  "description": "This is your dashboard."
+}
+```
+
+```tsx
+// Use in your component
+import { useTranslation } from '@donotdev/core';
+
+export function DashboardPage() {
+  const { t } = useTranslation();
+  const { user } = useAuth();
+
+  return (
+    <PageContainer>
+      <h1>{t('dashboard.welcome', { name: user?.displayName })}</h1>
+      <p>{t('dashboard.description')}</p>
+    </PageContainer>
+  );
+}
+```
+
+## Step 8: Customize Your Theme
+
+```css
+/* apps/web/src/themes.css */
+
+/* Extend the default light theme */
+.light {
+  --primary: #3b82f6; /* Your brand color */
+  --secondary: #10b981;
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+}
+
+/* Extend the default dark theme */
+.dark {
+  --primary: #60a5fa;
+  --secondary: #34d399;
+  --background: #0a0a0a;
+  --foreground: #fafafa;
+}
+
+/* Add a custom theme */
+.ocean {
+  --theme-icon: 'Waves'; /* Lucide icon name */
+  --theme-label: 'Ocean'; /* Display name */
+  --primary: #0ea5e9;
+  --secondary: #06b6d4;
+  --background: #001a33;
+  --foreground: #e0f2fe;
+}
+```
+
+Users can now switch between light, dark, and ocean themes!
+
+## Step 9: Add Dynamic Routes
+
+```tsx
+// apps/web/src/pages/blog/BlogPostPage.tsx
+import type { PageMeta } from '@donotdev/types';
+import { useParams } from 'react-router-dom';
+
+// Define route parameters
+export const meta: PageMeta = {
+  route: { params: ['slug'] }, // Creates /blog/:slug
+};
+
+export function BlogPostPage() {
+  const { slug } = useParams<{ slug: string }>();
+
+  return (
+    <article>
+      <h1>Blog Post: {slug}</h1>
+      {/* Fetch and display post content */}
+    </article>
+  );
+}
+```
+
+## Step 10: Deploy
+
+### Firebase
+
+```bash
+# Login to Firebase
+firebase login
+
+# Initialize (if not already done)
+firebase init
+
+# Deploy
+dndev deploy
+```
+
+### Vercel
+
+```bash
+# Login to Vercel
+vercel login
+
+# Link project
+vercel link
+
+# Deploy
+vercel --prod
+```
+
+## Common Tasks
+
+### Add Authentication
+
+```tsx
+import { useAuth, LoginPage } from '@donotdev/auth';
+
+export function ProtectedPage() {
+  const user = useAuth('user');
+  const isLoading = useAuth('loading');
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!user) return <LoginPage />;
+
+  return <div>Protected content for {user.email}</div>;
+}
+```
+
+### Add Billing
+
+```tsx
+import { useStripeBilling } from '@donotdev/billing';
+
+export function UpgradePage() {
+  const subscription = useStripeBilling('subscription');
+  const checkout = useStripeBilling('checkout');
+
+  return (
+    <div>
+      <h2>Current Plan: {subscription?.planId || 'Free'}</h2>
+      <button
+        onClick={() => checkout({ priceId: 'pro', mode: 'subscription' })}
+      >
+        Upgrade to Pro
+      </button>
+    </div>
+  );
+}
+```
+
+### Add a New Language
+
+1. Create translation files in `apps/web/src/locales/`:
+
+   ```
+   home_es.json      (Spanish)
+   about_es.json
+   dashboard_es.json
+   ```
+
+2. The framework automatically detects and enables the language!
+
+### Create CRUD Operations
+
+```tsx
+import { DataTable, CreateForm, EditForm } from '@donotdev/ui';
+import { userSchema } from 'entities/user';
+
+export function UsersPage() {
+  return (
+    <DataTable
+      entity="users"
+      schema={userSchema}
+      columns={['name', 'email', 'role']}
+      actions={['create', 'edit', 'delete']}
+    />
+  );
+}
+```
+
+## Next Steps
+
+- **Read the full documentation**: [docs.donotdev.com](https://docs.donotdev.com)
+- **Join the community**: [Discord](https://discord.gg/your-invite)
+- **Explore the demo app**: `apps/demo` in the framework repository
+- **Check CLAUDE.md**: For architecture deep-dive and framework internals
+
+## Troubleshooting
+
+### "Module not found: @donotdev/..."
+
+Make sure you ran `bun install` in the project root. The framework uses workspaces.
+
+```bash
+cd /path/to/your/project
+bun install
+```
+
+### Firebase deployment fails
+
+1. Check you're logged in: `firebase login`
+2. Verify project ID in `.firebaserc`
+3. Ensure functions are built: `bun run build`
+
+### Vite dev server not starting
+
+1. Check port 5173 isn't already in use
+2. Clear cache: `rm -rf node_modules/.vite`
+3. Reinstall: `bun install`
+
+### Type errors in IDE
+
+1. Restart TypeScript server in your IDE
+2. Check `tsconfig.json` is properly configured
+3. Run `bun run type-check` to see actual errors
+
+## Tips & Tricks
+
+1. **Use the demo app as reference** - It showcases all features
+2. **Follow the dependency hierarchy** - Don't import up the chain
+3. **Let the framework handle routing** - Just create pages, routes are auto-discovered
+4. **Use TypeScript** - Full type safety throughout
+5. **Customize via override** - Don't modify framework files directly
+
+## Need Help?
+
+- **Discord**: Real-time help from the community
+- **GitHub Issues**: Report bugs or request features
+- **Email**: mooti.web.app@gmail.com for licensing questions
+- **Documentation**: Comprehensive guides at docs.donotdev.com
+
+---
+
+**Happy coding! 🚀**
+
+Built something cool? Share it in the Discord community!