@donotdev/cli 0.0.6 → 0.0.8

package/templates/root-consumer/guides/wai-way/presets_guide.md.example

@@ -0,0 +1,217 @@
+# Preset Selection Guide
+
+> **One decision. Everything else follows.**
+
+## How Presets Work
+
+**Presets are NOT part of scaffolding.** When you run `dndev create-app`, it creates a base app with either Vite or Next.js.
+
+**Preset is a single config change** in `config/app.ts` after the app is created:
+
+```typescript
+export const appConfig: AppConfig = {
+  preset: 'admin', // Change this one line
+};
+```
+
+The preset controls layout, navigation, and default behaviors - but the files are the same.
+
+---
+
+## Decision Matrix
+
+| If your app is... | Use Preset | Why |
+|-------------------|------------|-----|
+| Marketing site with conversion goals | `landing` | Hero sections, CTAs, no sidebar, public-first |
+| Internal dashboard / back-office tool | `admin` | Sidebar nav, CRUD tables, auth-required by default |
+| Multi-tenant SaaS with teams | `moolti` | Workspace switcher, billing, team management |
+| Documentation / knowledge base | `docs` | Auto-sidebar from pages, search, TOC |
+| Blog / content publishing | `blog` | Article layout, archive, categories |
+| Mobile-first / game / fullscreen | `game` | Minimal chrome, touch-optimized, no sidebar |
+| Custom / minimal / embedded | `plain` | No layout, full control |
+
+---
+
+## Preset Details
+
+### `landing`
+**Best for:** Marketing sites, product pages, portfolios
+
+**Layout:**
+- Header with nav links
+- Full-width content area
+- Footer with legal links
+- NO sidebar
+
+**Default auth:** Public pages, optional protected sections
+
+**Typical pages:**
+- HomePage (hero + features + CTA)
+- AboutPage
+- PricingPage
+- ContactPage
+- LoginPage / SignupPage
+
+---
+
+### `admin`
+**Best for:** Dashboards, CMS, internal tools, CRUD apps
+
+**Layout:**
+- Header with branding + user menu
+- Collapsible sidebar with nav
+- Main content area
+- Optional footer
+
+**Default auth:** Most pages require login
+
+**Typical pages:**
+- DashboardPage (stats, recent items)
+- [Entity]ListPage (table with search/filter)
+- [Entity]Page (create/edit form)
+- SettingsPage
+
+---
+
+### `moolti`
+**Best for:** SaaS with workspaces, team collaboration
+
+**Layout:**
+- Like `admin` but with workspace switcher
+- Team/organization context
+- Billing integration ready
+
+**Default auth:** All pages require login + workspace
+
+**Typical pages:**
+- WorkspaceDashboardPage
+- TeamSettingsPage
+- BillingPage
+- [Entity]ListPage per workspace
+
+---
+
+### `docs`
+**Best for:** Documentation, guides, API reference
+
+**Layout:**
+- Header with search
+- Auto-generated sidebar from `src/pages/docs/**`
+- Wide content area for text
+- Table of contents
+
+**Default auth:** Public (or auth for premium docs)
+
+**Typical structure:**
+```
+src/pages/docs/
+  GettingStartedPage.tsx
+  guides/
+    SetupPage.tsx
+    ConfigurationPage.tsx
+  api/
+    OverviewPage.tsx
+    EndpointsPage.tsx
+```
+
+---
+
+### `blog`
+**Best for:** Articles, news, content marketing
+
+**Layout:**
+- Header with categories
+- Article-focused content area
+- Sidebar for related/recent posts
+- Author profiles
+
+**Default auth:** Public read, admin write
+
+**Typical pages:**
+- BlogHomePage (featured + recent)
+- ArticlePage (single article)
+- CategoryPage (filtered list)
+- AuthorPage (author profile + posts)
+
+---
+
+### `game`
+**Best for:** Mobile apps, games, fullscreen experiences
+
+**Layout:**
+- Minimal/no header
+- Full viewport content
+- Bottom navigation (mobile)
+- Touch-optimized
+
+**Default auth:** Varies
+
+**Typical pages:**
+- GamePage (main experience)
+- LeaderboardPage
+- ProfilePage
+- SettingsPage
+
+---
+
+### `plain`
+**Best for:** Embeds, custom layouts, special cases
+
+**Layout:**
+- No framework layout
+- You control everything
+- Just `<PageContainer>` wrapper
+
+**Default auth:** None (you configure)
+
+**Use when:**
+- Embedding in another app
+- Completely custom design
+- Framework presets don't fit
+
+---
+
+## Quick Decision Flow
+
+```
+START
+  |
+  v
+Is it content/docs focused?
+  YES --> Is it articles/blog? --> YES --> blog
+  |                          --> NO  --> docs
+  NO
+  |
+  v
+Is it a dashboard/tool?
+  YES --> Multi-tenant/teams? --> YES --> moolti
+  |                          --> NO  --> admin
+  NO
+  |
+  v
+Is it marketing/public?
+  YES --> landing
+  NO
+  |
+  v
+Is it mobile-first/fullscreen?
+  YES --> game
+  NO  --> plain
+```
+
+---
+
+## Changing Presets Later
+
+Presets can be changed in `config/app.ts`:
+
+```typescript
+export const appConfig: AppConfig = {
+  preset: 'admin', // Change this
+};
+```
+
+**Low risk:** Switching between similar presets (admin <-> moolti)
+**Higher risk:** Switching layout types (landing <-> admin) - may need page restructuring
+
+**Recommendation:** Get the preset right in Phase 0. Changing later is possible but adds work.

package/templates/root-consumer/guides/wai-way/spec_template.md.example

@@ -0,0 +1,312 @@
+# App Specification
+
+> **This is the contract.** Complete spec = deterministic build. Incomplete spec = wasted work.
+> **Do NOT start coding until this document is complete and validated.**
+
+---
+
+## 1. Identity
+
+| Field | Value |
+|-------|-------|
+| **App Name** | |
+| **One-Line Description** | |
+| **Primary User** | _(Who uses this daily?)_ |
+| **Secondary Users** | _(Who else interacts?)_ |
+| **Core Value** | _(What problem does it solve?)_ |
+
+---
+
+## 2. User Journeys
+
+> **Most important section.** These drive everything else.
+
+### Journey 1: [Name - e.g., "New User Onboarding"]
+
+**Actor:** [User type]
+**Goal:** [What they're trying to accomplish]
+**Trigger:** [What starts this journey]
+
+**Steps:**
+1.
+2.
+3.
+4.
+5.
+
+**Success:** [What indicates completion]
+**Failure:** [What could go wrong, how to handle]
+
+---
+
+### Journey 2: [Name - e.g., "Daily Core Task"]
+
+**Actor:** [User type]
+**Goal:** [What they're trying to accomplish]
+**Trigger:** [What starts this journey]
+
+**Steps:**
+1.
+2.
+3.
+4.
+5.
+
+**Success:** [What indicates completion]
+**Failure:** [What could go wrong, how to handle]
+
+---
+
+### Journey 3: [Name - e.g., "Admin Management"]
+
+**Actor:** [User type]
+**Goal:** [What they're trying to accomplish]
+
+**Steps:**
+1.
+2.
+3.
+
+---
+
+_(Add more journeys as needed)_
+
+---
+
+## 3. Preset Selection
+
+**Selected:** `_______________`
+
+| Preset | When to Use |
+|--------|-------------|
+| `landing` | Marketing site, public pages, conversion focus |
+| `admin` | Dashboard with sidebar, CRUD-heavy, internal tools |
+| `moolti` | Multi-tenant SaaS, teams/workspaces, billing |
+| `docs` | Documentation, auto-sidebar from pages |
+| `blog` | Content-focused, articles, archive |
+| `game` | Mobile-first, fullscreen, minimal chrome |
+| `plain` | Custom everything, no framework layout |
+
+---
+
+## 4. Auth & Roles
+
+| Question | Answer |
+|----------|--------|
+| **Auth required?** | Yes / No |
+| **Providers** | [ ] Email [ ] Google [ ] GitHub [ ] Apple |
+| **Self-registration?** | Yes / No / Invite-only |
+
+### Roles
+
+| Role | Description | Can Do |
+|------|-------------|--------|
+| `guest` | Not logged in | |
+| `user` | Logged in | |
+| `admin` | Administrator | |
+| | | |
+
+---
+
+## 5. Billing (if applicable)
+
+| Question | Answer |
+|----------|--------|
+| **Billing enabled?** | Yes / No |
+| **Model** | Subscription / One-time / Usage-based |
+| **Provider** | Stripe / Other |
+
+### Plans
+
+| Plan | Price | Features |
+|------|-------|----------|
+| | | |
+| | | |
+
+---
+
+## 6. Entities
+
+> One entity = one collection. Define ALL data.
+
+### Entity: [Name]
+
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| id | string | yes | auto-generated |
+| | | | |
+| | | | |
+| createdAt | timestamp | yes | auto |
+| updatedAt | timestamp | yes | auto |
+
+**States:** `[state1]` → `[state2]` → `[state3]`
+
+**State Transitions:**
+- `state1` → `state2`: [What triggers this]
+- `state2` → `state3`: [What triggers this]
+- `state2` → `cancelled`: [What triggers this]
+
+**Relationships:**
+- Belongs to: [Entity] (via `fieldName`)
+- Has many: [Entity]
+
+**Permissions:**
+| Action | Who | Conditions |
+|--------|-----|------------|
+| Create | | |
+| Read | | |
+| Update | | |
+| Delete | | |
+
+---
+
+### Entity: [Name]
+
+| Field | Type | Required | Validation |
+|-------|------|----------|------------|
+| | | | |
+
+**States:** (if applicable)
+
+**Relationships:**
+
+**Permissions:**
+| Action | Who | Conditions |
+|--------|-----|------------|
+| Create | | |
+| Read | | |
+| Update | | |
+| Delete | | |
+
+---
+
+_(Copy entity template for each entity)_
+
+---
+
+## 7. Business Rules
+
+> Explicit rules that govern behavior. If it's not here, it doesn't exist.
+
+### [Entity/Feature] Rules
+
+1. **[Rule name]:** [Description]
+   - Example: "Order total = sum(items) + shipping - discount"
+
+2. **[Rule name]:** [Description]
+
+3. **[Rule name]:** [Description]
+
+### Validation Rules
+
+| Entity | Field | Rule |
+|--------|-------|------|
+| | | |
+| | | |
+
+### Automatic Calculations
+
+| When | Calculate | Formula/Logic |
+|------|-----------|---------------|
+| | | |
+
+### Notifications/Triggers
+
+| Event | Action | Recipients |
+|-------|--------|------------|
+| | | |
+| | | |
+
+---
+
+## 8. Pages
+
+> Derived from user journeys. Every page exists because a journey needs it.
+
+### Public Pages
+
+| Route | Page | Purpose | From Journey |
+|-------|------|---------|--------------|
+| `/` | HomePage | | |
+| | | | |
+
+### Protected Pages (login required)
+
+| Route | Page | Purpose | From Journey |
+|-------|------|---------|--------------|
+| `/dashboard` | DashboardPage | | |
+| | | | |
+
+### Admin Pages
+
+| Route | Page | Purpose | From Journey |
+|-------|------|---------|--------------|
+| `/admin` | AdminDashboard | | |
+| | | | |
+
+---
+
+## 9. Features
+
+| Feature | Needed | Details |
+|---------|--------|---------|
+| **i18n** | Yes/No | Languages: |
+| **PWA** | Yes/No | |
+| **Real-time** | Yes/No | Which entities: |
+| **File uploads** | Yes/No | Which entities: |
+| **Email notifications** | Yes/No | Triggers: |
+| **Search** | Yes/No | Which entities: |
+| **Export (CSV/PDF)** | Yes/No | Which entities: |
+
+---
+
+## 10. Edge Cases & Error Handling
+
+> What happens when things go wrong?
+
+| Scenario | Handling |
+|----------|----------|
+| User submits invalid data | |
+| Network connection lost | |
+| Concurrent edit conflict | |
+| External service down | |
+| User tries unauthorized action | |
+| | |
+
+---
+
+## 11. Open Questions
+
+> Anything unresolved? List here. **No coding until resolved.**
+
+- [ ]
+- [ ]
+- [ ]
+
+---
+
+## Validation Checklist
+
+Before starting Phase 1, ALL must be checked:
+
+### Completeness
+- [ ] Every user journey has numbered steps
+- [ ] Every entity has fields, states, permissions defined
+- [ ] Every business rule is explicit (not implied)
+- [ ] Every page is linked to a journey
+- [ ] No "TBD", "TODO", or empty fields
+
+### Clarity
+- [ ] Can explain app to someone unfamiliar in 2 minutes
+- [ ] Can trace any page back to a user journey
+- [ ] Can answer "who can do X to Y?" for any entity/action
+- [ ] Can answer "what happens when Z fails?" for common scenarios
+
+### User Validation
+- [ ] User has reviewed this spec
+- [ ] User has confirmed it's complete
+- [ ] User has no outstanding questions
+
+---
+
+**All boxes checked? Proceed to Phase 1: SCAFFOLD.**

package/templates/functions-firebase/functions-firebase/src/crud/createEntity.ts.example

@@ -1,19 +0,0 @@
-/**
- * @fileoverview {{APP_NAME}} Create Entity Wrapper
- * @description Wrapper for framework's createEntity with {{APP_NAME}}-specific configuration
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-
-import { createEntity as frameworkCreateEntity } from '@donotdev/functions/firebase';
-
-/**
- * {{APP_NAME}} entity creation
- * Wraps the framework function with {{APP_NAME}}-specific configuration
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-export const createEntity = frameworkCreateEntity;

package/templates/functions-firebase/functions-firebase/src/crud/deleteEntity.ts.example

@@ -1,14 +0,0 @@
-// functions/src/crud/deleteEntity.ts
-
-/**
- * @fileoverview {{APP_NAME}} Delete Entity Wrapper
- * @description Wrapper for framework's deleteEntity with {{APP_NAME}}-specific configuration
- */
-
-import { deleteEntity as frameworkDeleteEntity } from '@donotdev/functions/firebase';
-
-/**
- * {{APP_NAME}} entity deletion
- * Wraps the framework function with {{APP_NAME}}-specific configuration
- */
-export const deleteEntity = frameworkDeleteEntity;

package/templates/functions-firebase/functions-firebase/src/crud/getEntity.ts.example

@@ -1,14 +0,0 @@
-// functions/src/crud/getEntity.ts
-
-/**
- * @fileoverview {{APP_NAME}} Get Entity Wrapper
- * @description Wrapper for framework's getEntity with {{APP_NAME}}-specific configuration
- */
-
-import { getEntity as frameworkGetEntity } from '@donotdev/functions/firebase';
-
-/**
- * {{APP_NAME}} entity retrieval
- * Wraps the framework function with {{APP_NAME}}-specific configuration
- */
-export const getEntity = frameworkGetEntity;

package/templates/functions-firebase/functions-firebase/src/crud/index.ts.example

@@ -1,12 +0,0 @@
-// functions/src/crud/index.ts
-
-/**
- * @fileoverview {{APP_NAME}} CRUD Functions
- * @description Exports all CRUD-related functions for the {{APP_NAME}} app
- */
-
-export { createEntity } from './createEntity';
-export { updateEntity } from './updateEntity';
-export { deleteEntity } from './deleteEntity';
-export { getEntity } from './getEntity';
-export { listEntities } from './listEntities';

package/templates/functions-firebase/functions-firebase/src/crud/listEntities.ts.example

@@ -1,14 +0,0 @@
-// functions/src/crud/listEntities.ts
-
-/**
- * @fileoverview {{APP_NAME}} List Entities Wrapper
- * @description Wrapper for framework's listEntities with {{APP_NAME}}-specific configuration
- */
-
-import { listEntities as frameworkListEntities } from '@donotdev/functions/firebase';
-
-/**
- * {{APP_NAME}} entities listing
- * Wraps the framework function with {{APP_NAME}}-specific configuration
- */
-export const listEntities = frameworkListEntities;

package/templates/functions-firebase/functions-firebase/src/crud/updateEntity.ts.example

@@ -1,14 +0,0 @@
-// functions/src/crud/updateEntity.ts
-
-/**
- * @fileoverview {{APP_NAME}} Update Entity Wrapper
- * @description Wrapper for framework's updateEntity with {{APP_NAME}}-specific configuration
- */
-
-import { updateEntity as frameworkUpdateEntity } from '@donotdev/functions/firebase';
-
-/**
- * {{APP_NAME}} entity update
- * Wraps the framework function with {{APP_NAME}}-specific configuration
- */
-export const updateEntity = frameworkUpdateEntity;

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

@@ -1,70 +0,0 @@
-# CRUD Package Reference
-
-**Check JSDoc in your IDE** - Hover over any component import to see props, types, and examples.
-
-**Import from:** `@donotdev/crud` (CRUD operations and forms)
-
----
-
-## Core Hook
-
-- **useCrud** - React hook for CRUD operations (create, read, update, delete, query) with automatic validation and backend abstraction.
-
----
-
-## Service
-
-- **getCrudService** - Get CrudService singleton instance for direct service access.
-
----
-
-## Form Components
-
-- **EntityFormRenderer** - Renders complete entity forms with automatic field mapping.
-- **FormFieldRenderer** - Renders individual form fields based on schema.
-- **FormLayout** - Form layout component with spacing and structure.
-- **CrudButton** - Button component integrated with CRUD operations.
-
----
-
-## Form Field Components
-
-- **TextFieldComponent** - Text input field component.
-- **NumberFieldComponent** - Number input field component.
-- **TextAreaComponent** - Textarea input field component.
-- **PasswordFieldComponent** - Password input field component.
-- **DateFieldComponent** - Date picker field component.
-- **CheckboxFieldComponent** - Checkbox field component.
-- **RadioFieldComponent** - Radio button field component.
-- **DropdownComponent** - Single-select dropdown field component.
-- **MultiDropdownComponent** - Multi-select dropdown field component.
-- **FileFieldComponent** - File upload field component.
-- **ImageFieldComponent** - Image upload field component.
-- **AvatarFieldComponent** - Avatar upload field component.
-- **BadgeFieldComponent** - Badge display/input field component.
-- **PhoneNumberComponent** - Phone number input field component.
-- **GeoPointFieldComponent** - Geographic point input field component.
-- **MapFieldComponent** - Map picker field component.
-- **TimestampFieldComponent** - Timestamp input field component.
-- **ReferenceFieldComponent** - Reference/link field component.
-- **MultiInputTextFieldComponent** - Multiple text inputs field component.
-- **ButtonFieldComponent** - Button field component.
-- **HiddenFieldComponent** - Hidden field component.
-
----
-
-## Controlled Fields
-
-- **ControlledFields** - Controlled form field components with validation.
-
----
-
-## Utilities
-
-- **loadDeterministicRange** - Load deterministic range from collections.
-- **upsertDeterministic** - Upsert with deterministic ID.
-- **appendToCollection** - Append item to collection.
-
----
-
-**All props documented in JSDoc** - Hover in IDE for complete reference.