@donotdev/cli 0.0.12 → 0.0.14

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

@@ -2,294 +2,120 @@
 
 **Built with [DoNotDev Framework](https://donotdev.com)**
 
-## 🚀 Quick Start
+## Setup
+
+**Start the app first — the homepage walks you through everything:**
 
 ```bash
-# Install dependencies
 bun install
-
-# Start development server
-bun run dev
-
-# Build for production
-bun run build
+bun dev
 ```
 
-## 📦 What's Included
+Open the app and follow the setup steps on the homepage (Git, Firebase, Stripe, etc.).
 
-This project is scaffolded with:
+## Environment Variables
 
-- ✅ **DoNotDev Framework** - Modern React framework with auth, billing, i18n
-- ✅ **Vite** - Lightning-fast development
-- ✅ **TypeScript** - Type-safe throughout
-- ✅ **Firebase** - Authentication & database ready
-- ✅ **Stripe** - Billing integration ready (optional)
-- ✅ **i18n** - Multi-language support (8 languages)
-- ✅ **Themes** - Dark mode & custom themes
-
-## 📁 Project Structure
+**Each app has its own `.env` file.** Vite loads from the app directory only.
 
 ```
 {{projectName}}/
-├── src/
-│   ├── pages/              # Auto-discovered routes
-│   │   └── HomePage.tsx    # Your landing page
-│   ├── components/         # Your components
-│   ├── App.tsx             # App entry point
-│   └── main.tsx            # Vite entry
-├── public/
-│   └── assets/
-│       ├── themes/         # Custom theme files
-│       └── locales/        # Translation files
-├── CLAUDE.md               # Guide for AI agents
-└── package.json
-```
-
-## 🔧 Configuration
-
-### License Key
-
-This project uses `@donotdev` packages from npm. To remove the watermark, add your license key:
-
-1. Get your license key from [donotdev.com/pricing](https://donotdev.com/pricing)
-2. Add to `.env` file:
-   ```env
-   VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
-   ```
-   Or for Next.js:
-   ```env
-   NEXT_PUBLIC_DONOTDEV_LICENSE_KEY=dndev_your_key_here
-   ```
-
-### Environment Variables
-
-1. Copy `.env.example` to `.env`:
-   ```bash
-   cp .env.example .env
-   ```
-
-2. Update the values:
-   ```env
-   VITE_FIREBASE_API_KEY=your-api-key
-   VITE_FIREBASE_PROJECT_ID=your-project-id
-   VITE_FIREBASE_AUTH_DOMAIN=your-auth-domain
-   ```
-
-### Features Configuration
-
-Edit `vite.config.ts` to enable/disable features:
-
-```typescript
-export default defineConfig({
-  plugins: [
-    doNotDevPlugin({
-      features: {
-        enabled: ['auth', 'billing', 'oauth'],
-      },
-    }),
-  ],
-});
-```
-
-## 🎨 Customization
-
-### Adding Your Logo
-
-Add your `logo.svg` to `public/`:
-
-- Framework will prompt during build if missing: "Do you want us to provide one from the framework?"
-- Or manually copy from `node_modules/@donotdev/ui/assets/logo.svg`
-- Framework automatically generates favicon, app icons, and PWA assets from your logo
-
-### Add a New Page
-
-Create a file in `src/pages/`:
-
-```tsx
-// src/pages/AboutPage.tsx
-import { PageContainer } from '@donotdev/ui';
-import { Info } from 'lucide-react';
-import type { PageMeta } from '@donotdev/core';
-
-export const meta: PageMeta = {
-  namespace: 'about',
-  icon: <Info />,
-};
-
-export default function AboutPage() {
-  return (
-    <PageContainer variant="standard">
-      <h1>About Us</h1>
-    </PageContainer>
-  );
-}
-```
-
-Route auto-discovered as `/about` ✨
-
-### Add Translations
-
-Create/edit `public/assets/locales/about_en.json`:
-
-```json
-{
-  "title": "About Us",
-  "description": "Learn more about our mission"
-}
-```
-
-### Add Custom Theme
-
-Edit `src/themes.css`:
-
-```css
-.ocean {
-  --theme-icon: 'Waves';
-  --theme-label: 'Ocean';
-  --primary: #0ea5e9;
-  --background: #0a1929;
-}
+├── .env.example              ← NOT loaded by Vite (reference only)
+├── apps/
+│   └── my-app/
+│       ├── .env              ← Vite reads THIS one
+│       ├── .env.local         ← Overrides .env (gitignored)
+│       ├── .env.production    ← Production overrides
+│       └── .env.staging       ← Staging overrides (used by dndev staging)
+└── functions/
+    └── .env                   ← Server-side secrets (Stripe, OAuth, etc.)
 ```
 
-## 🔐 Authentication
-
-Enable Firebase Auth:
-
-1. Set up Firebase project
-2. Enable authentication methods
-3. Update `.env` with Firebase credentials
-4. Use in your pages:
-
-```tsx
-import { useAuth } from '@donotdev/auth';
-
-export default function ProfilePage() {
-  const { user, signOut } = useAuth();
-  return <div>Hello, {user?.displayName}!</div>;
-}
-```
-
-## 💳 Billing (Optional)
-
-Enable Stripe:
-
-1. Create Stripe account
-2. Add Stripe keys to `.env`
-3. Enable in `vite.config.ts`
-4. Use in your pages:
-
-```tsx
-import { useStripeBilling } from '@donotdev/billing';
-
-export default function PricingPage() {
-  const { createCheckoutSession } = useStripeBilling();
-  return <button onClick={() => createCheckoutSession('pro')}>
-    Upgrade to Pro
-  </button>;
-}
-```
-
-## 🚢 Deployment
-
-### Firebase Hosting
+**To set up:** Copy `.env.example` to `.env` in your app directory and fill in the values.
 
 ```bash
-# Install Firebase CLI
-npm install -g firebase-tools
-
-# Login and init
-firebase login
-firebase init hosting
-
-# Deploy
-bun run build
-firebase deploy
+cp apps/my-app/.env.example apps/my-app/.env
 ```
 
-### Vercel
+## CLI Commands
 
 ```bash
-# Install Vercel CLI
-npm install -g vercel
-
-# Deploy
-vercel
+# Development
+bun dev                      # Start dev server
+dndev emu start              # Start Firebase emulators (Auth, Firestore, Functions)
+
+# Deployment
+dndev deploy                 # Deploy to Firebase (hosting + functions + rules)
+dndev staging                # Deploy to staging environment
+dndev sync-secrets           # Push functions/.env secrets to Firebase Secret Manager
+
+# Quality
+bun run type-check           # TypeScript validation
+bun test                     # Run tests
+bun run build                # Build for production
 ```
 
-## 🤖 Working with AI Agents
-
-This project includes `CLAUDE.md` - a guide for AI agents like Claude, ChatGPT, etc.
+## Project Structure
 
-When working with an AI:
-1. The AI will automatically read `CLAUDE.md`
-2. The AI will understand the framework conventions
-3. Ask the AI to create pages, add features, fix bugs, etc.
-
-**Example prompts:**
-- "Create a blog page with post listing"
-- "Add French translations for the home page"
-- "Create a protected dashboard page that requires authentication"
-- "Add a pricing page with Stripe integration"
-
-## 📚 Documentation
-
-- **Framework Docs**: [docs.donotdev.com](https://docs.donotdev.com)
-- **CLAUDE.md**: AI agent guide (in this project)
-- **Component Library**: [donotdev.com/components](https://donotdev.com/components)
-
-## 🆘 Troubleshooting
-
-### Build Errors
-
-```bash
-# Clear cache and reinstall
-rm -rf node_modules bun.lock
-bun install
+```
+{{projectName}}/
+├── apps/
+│   └── my-app/
+│       ├── src/
+│       │   ├── pages/        # Auto-discovered routes (*Page.tsx)
+│       │   ├── config/       # App config (app.ts, legal.ts)
+│       │   └── locales/      # Translations (optional)
+│       ├── .env              # App environment variables
+│       └── vite.config.ts    # Vite config
+├── entities/                 # Entity definitions (shared across apps)
+├── functions/                # Firebase Cloud Functions
+│   └── .env                  # Server-side secrets
+├── guides/                   # WAI-WAY blueprints + framework guides
+├── AI.md                     # AI agent instructions
+├── CLAUDE.md                 # Claude-specific instructions
+├── firebase.json             # Firebase config
+├── firestore.rules           # Firestore security rules (generated by Phase 4)
+└── .firebaserc               # Firebase project aliases
 ```
 
-### Firebase Connection Issues
-
-- Verify `.env` has correct Firebase credentials
-- Check Firebase console for project status
-- Ensure authentication is enabled
-
-### Hot Reload Not Working
-
-- Check Vite config port (default: 5173)
-- Ensure no other process is using the port
+## Building With AI
 
-## 📝 Scripts
+This project is configured for AI-assisted development via WAI-WAY:
 
-```bash
-bun run dev          # Start development server
-bun run build        # Build for production
-bun run preview      # Preview production build
-bun run lint         # Lint code
-bun run type-check   # TypeScript validation
-dndev format         # Format code with Prettier
-```
+1. Open in **Cursor**, **Claude Code**, **Windsurf**, or **AntiGravity**
+2. The AI reads `AI.md` automatically and follows the WAI-WAY protocol
+3. MCP tools are pre-configured — the AI looks up real TypeScript types instead of guessing
 
-### Code Formatting
+**The 5 phases:**
+- Phase 0: Brainstorm — describe your app, produce a validated spec
+- Phase 1: Scaffold — create all pages and routes from spec
+- Phase 2: Entities — define data models with fields, access rules, visibility
+- Phase 3: Compose — build pages with framework components
+- Phase 4: Configure — generate tests, firestore rules, CI/CD
 
-The project includes `.prettierrc.cjs` which extends the framework's Prettier configuration. Run `dndev format` to format all TypeScript files according to the project's Prettier rules.
+Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 
-## 🙏 Built With
+## Key Files
 
-- [DoNotDev Framework](https://donotdev.com) - Application framework
-- [React 19](https://react.dev) - UI library
-- [Vite](https://vitejs.dev) - Build tool
-- [TypeScript](https://www.typescriptlang.org) - Type safety
-- [Firebase](https://firebase.google.com) - Backend services
-- [Stripe](https://stripe.com) - Payment processing
+| File | Purpose |
+|------|---------|
+| `entities/*.ts` | Data model definitions — CRUD, forms, lists auto-generated |
+| `src/pages/*Page.tsx` | Pages — auto-discovered as routes by filename |
+| `src/config/app.ts` | App name, preset, features |
+| `src/config/legal.ts` | Company info, legal compliance |
+| `guides/dndev/` | Framework setup guides (Auth, CRUD, Billing, etc.) |
+| `guides/wai-way/` | WAI-WAY blueprints and agent personas |
 
-## 📄 License
+## License Key
 
-Your project license here (MIT, Apache, proprietary, etc.)
+Add your license key to your **app's** `.env` (not the root):
 
-## 🤝 Contributing
+```env
+# apps/my-app/.env
+VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+```
 
-[Add your contribution guidelines here]
+Get your key from [donotdev.com/pricing](https://donotdev.com/pricing).
 
 ---
 
-**Need help?** Check [DoNotDev Documentation](https://docs.donotdev.com) or open an issue.
+**Need help?** Check the homepage setup guide or read `guides/dndev/` for detailed instructions.

package/templates/root-consumer/entities/Contact.ts.example

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview Contact Entity — Guest-Created, Admin-Managed
+ *
+ * This entity demonstrates the PUBLIC FORM pattern:
+ * - Guests (unauthenticated) can CREATE (contact form submission)
+ * - Only admins can READ, UPDATE, DELETE (CRM inbox)
+ *
+ * COMMON USE CASES:
+ * - Contact forms, inquiry forms, support requests
+ * - Lead capture, newsletter signups
+ * - Any public submission that admins manage
+ *
+ * FIRESTORE PATH: `contacts/{contactId}`
+ */
+
+import { defineEntity } from '@donotdev/core';
+
+export const contactEntity = defineEntity({
+  name: 'Contact',
+  collection: 'contacts',
+  listFields: ['name', 'email', 'subject', 'status'],
+
+  // Guest can create (public form), only admins manage
+  access: {
+    create: 'guest',
+    read: 'admin',
+    update: 'admin',
+    delete: 'admin',
+  },
+
+  fields: {
+    // Public form fields — guests fill these on submission
+    name: {
+      name: 'name',
+      label: 'name',
+      type: 'text',
+      visibility: 'admin',
+      editable: 'admin',
+      validation: { required: true },
+    },
+
+    email: {
+      name: 'email',
+      label: 'email',
+      type: 'email',
+      visibility: 'admin',
+      editable: 'admin',
+      validation: { required: true },
+    },
+
+    phone: {
+      name: 'phone',
+      label: 'phone',
+      type: 'tel',
+      visibility: 'admin',
+      editable: 'admin',
+      validation: { required: false },
+    },
+
+    subject: {
+      name: 'subject',
+      label: 'subject',
+      type: 'select',
+      visibility: 'admin',
+      editable: 'create-only',
+      validation: {
+        required: true,
+        options: [
+          { value: 'general', label: 'subject.general' },
+          { value: 'support', label: 'subject.support' },
+          { value: 'sales', label: 'subject.sales' },
+        ],
+      },
+    },
+
+    message: {
+      name: 'message',
+      label: 'message',
+      type: 'textarea',
+      visibility: 'admin',
+      editable: 'create-only',
+      validation: { required: true },
+    },
+
+    // GDPR consent — required on public forms in EU
+    gdprConsent: {
+      name: 'gdprConsent',
+      label: 'consent',
+      type: 'gdprConsent',
+      visibility: 'guest',
+      editable: 'create-only',
+      validation: { required: true },
+      options: {
+        fieldSpecific: {
+          privacyPolicyPath: '/legal/privacy',
+          termsPath: '/legal/terms',
+        },
+      },
+    },
+
+    // Admin-only fields for managing submissions
+    notes: {
+      name: 'notes',
+      label: 'notes',
+      type: 'textarea',
+      visibility: 'admin',
+      editable: 'admin',
+      validation: { required: false },
+    },
+
+    status: {
+      name: 'status',
+      label: 'status',
+      type: 'select',
+      visibility: 'admin',
+      editable: 'admin',
+      validation: {
+        options: [
+          // Framework adds: draft, available, deleted
+          // Custom statuses:
+          { value: 'responded', label: 'status.responded' },
+        ],
+      },
+    },
+  },
+});

package/templates/root-consumer/entities/index.ts.example

@@ -5,11 +5,14 @@
  *
  * USAGE:
  * ```tsx
- * import { productEntity, customerEntity } from '../entities';
+ * import { contactEntity, productEntity } from '../entities';
  * ```
  */
 
-// Export your entities here:
-// export { productEntity } from './Product';
+// Scaffolded examples — rename or replace with your own entities:
+export { contactEntity } from './Contact';
+export { productEntity } from './ExampleEntity';
+
+// Add your entities:
 // export { customerEntity } from './Customer';
 // export { orderEntity } from './Order';