@donotdev/cli 0.0.18 → 0.0.20

package/templates/root-consumer/guides/dndev/advanced/VERSION_CONTROL.md.example

@@ -1,174 +1,174 @@
-# Version Control Guide
-
-**How to upgrade DoNotDev framework packages in your project**
-
----
-
-## Quick Start
-
-```bash
-# Check for available updates
-dndev bump --check
-
-# Apply safe updates (minor/patch versions)
-dndev bump
-
-# Preview changes without applying
-dndev bump --dry-run
-```
-
----
-
-## How It Works
-
-### Automatic Updates
-
-**Patch versions (0.0.x):**
-- Handled automatically by `bun install`
-- No action needed - `^` ranges allow automatic patch updates
-- Example: `^0.0.2` → `0.0.3`, `0.0.4`, etc.
-
-**Minor versions (0.x.y):**
-- Handled automatically by `dndev bump`
-- **RISK FREE:** All changes are backward compatible via deprecation
-- No breaking changes in 0.x.y range
-- Example: `^0.0.2` → `^0.1.0` (auto-updated, safe)
-
-### Manual Validation Required
-
-**Major versions (0.*.* → 1.x.y):**
-- `dndev bump` detects major version changes
-- Shows migration guide with breaking changes
-- **You must validate manually** before updating
-- **Only place where breaking changes occur**
-- Example: `^0.1.0` → `^1.0.0` (requires validation)
-
----
-
-## Upgrade Process
-
-### Step 1: Check for Updates
-
-```bash
-dndev bump --check
-```
-
-This shows:
-- Available updates for `@donotdev/*` packages (from npm)
-- Available updates for external peer dependencies (from matrix)
-- Major version changes (with migration guides)
-
-### Step 2: Review Migration Guides
-
-If major version changes are detected:
-- Read the migration guide shown in the output
-- Check for breaking changes that affect your code
-- Review the migration guide file (path shown in output)
-
-### Step 3: Apply Updates
-
-```bash
-# Safe updates (minor/patch) - auto-applied
-dndev bump
-
-# Or preview first
-dndev bump --dry-run
-```
-
-**What gets updated:**
-- `@donotdev/*` packages: Updated to latest compatible version
-- External peer dependencies: Updated to matrix versions
-- All `package.json` files in your project
-
----
-
-## Understanding Version Ranges
-
-### `^` Range (Caret)
-
-**What it means:**
-- Allows updates to latest minor/patch version
-- Same major version required
-- Example: `^0.0.2` allows `0.0.2` through `0.0.9`, but not `0.1.0`
-
-**Why we use it:**
-- Automatic patch updates via `bun install`
-- Safe minor updates via `dndev bump`
-- Prevents accidental major version updates
-
-### Version Format
-
-```json
-{
-  "dependencies": {
-    "@donotdev/core": "^0.0.2",
-    "react": "^19.2.3"
-  }
-}
-```
-
-- `^0.0.2` = allows `0.0.2` to `0.0.x` (patch updates)
-- `^0.1.0` = allows `0.1.0` to `0.x.x` (minor updates)
-- `^1.0.0` = allows `1.0.0` to `1.x.x` (minor updates, not `2.0.0`)
-
----
-
-## Migration Guides
-
-When upgrading major versions, migration guides are provided:
-
-**Location:** Shown in `dndev bump` output
-
-**Contains:**
-- List of breaking changes
-- Step-by-step migration instructions
-- Code examples for updated APIs
-
-**Example:**
-```
-⚠️  Major version update detected: @donotdev/core 0.1.0 → 1.0.0
-
-Migration guide: docs/migration/v0.1-to-v1.0.md
-
-Breaking changes:
-- Removed useAuth() - use useAuthentication() instead
-- Theme API changed - see migration guide
-
-Review the migration guide before updating.
-```
-
----
-
-## Troubleshooting
-
-### "No updates available"
-
-- All packages are up to date
-- Or you're already on latest version
-
-### "Major version change detected"
-
-- Review migration guide
-- Check breaking changes
-- Update code if needed
-- Run `dndev bump` again to apply
-
-### "Package not found on npm"
-
-- Package may not be published yet
-- Check package name spelling
-- Verify you're using correct registry
-
----
-
-## Best Practices
-
-1. **Regular updates:** Run `dndev bump --check` monthly
-2. **Test after updates:** Run your test suite after applying updates
-3. **Review major changes:** Always read migration guides for major versions
-4. **Use `--dry-run`:** Preview changes before applying
-5. **Commit changes:** Commit updated `package.json` files after successful updates
-
----
-
-**Keep your dependencies up to date. Stay secure. Stay compatible.**
+# Version Control Guide
+
+**How to upgrade DoNotDev framework packages in your project**
+
+---
+
+## Quick Start
+
+```bash
+# Check for available updates
+dndev bump --check
+
+# Apply safe updates (minor/patch versions)
+dndev bump
+
+# Preview changes without applying
+dndev bump --dry-run
+```
+
+---
+
+## How It Works
+
+### Automatic Updates
+
+**Patch versions (0.0.x):**
+- Handled automatically by `bun install`
+- No action needed - `^` ranges allow automatic patch updates
+- Example: `^0.0.2` → `0.0.3`, `0.0.4`, etc.
+
+**Minor versions (0.x.y):**
+- Handled automatically by `dndev bump`
+- **RISK FREE:** All changes are backward compatible via deprecation
+- No breaking changes in 0.x.y range
+- Example: `^0.0.2` → `^0.1.0` (auto-updated, safe)
+
+### Manual Validation Required
+
+**Major versions (0.*.* → 1.x.y):**
+- `dndev bump` detects major version changes
+- Shows migration guide with breaking changes
+- **You must validate manually** before updating
+- **Only place where breaking changes occur**
+- Example: `^0.1.0` → `^1.0.0` (requires validation)
+
+---
+
+## Upgrade Process
+
+### Step 1: Check for Updates
+
+```bash
+dndev bump --check
+```
+
+This shows:
+- Available updates for `@donotdev/*` packages (from npm)
+- Available updates for external peer dependencies (from matrix)
+- Major version changes (with migration guides)
+
+### Step 2: Review Migration Guides
+
+If major version changes are detected:
+- Read the migration guide shown in the output
+- Check for breaking changes that affect your code
+- Review the migration guide file (path shown in output)
+
+### Step 3: Apply Updates
+
+```bash
+# Safe updates (minor/patch) - auto-applied
+dndev bump
+
+# Or preview first
+dndev bump --dry-run
+```
+
+**What gets updated:**
+- `@donotdev/*` packages: Updated to latest compatible version
+- External peer dependencies: Updated to matrix versions
+- All `package.json` files in your project
+
+---
+
+## Understanding Version Ranges
+
+### `^` Range (Caret)
+
+**What it means:**
+- Allows updates to latest minor/patch version
+- Same major version required
+- Example: `^0.0.2` allows `0.0.2` through `0.0.9`, but not `0.1.0`
+
+**Why we use it:**
+- Automatic patch updates via `bun install`
+- Safe minor updates via `dndev bump`
+- Prevents accidental major version updates
+
+### Version Format
+
+```json
+{
+  "dependencies": {
+    "@donotdev/core": "^0.0.2",
+    "react": "^19.2.3"
+  }
+}
+```
+
+- `^0.0.2` = allows `0.0.2` to `0.0.x` (patch updates)
+- `^0.1.0` = allows `0.1.0` to `0.x.x` (minor updates)
+- `^1.0.0` = allows `1.0.0` to `1.x.x` (minor updates, not `2.0.0`)
+
+---
+
+## Migration Guides
+
+When upgrading major versions, migration guides are provided:
+
+**Location:** Shown in `dndev bump` output
+
+**Contains:**
+- List of breaking changes
+- Step-by-step migration instructions
+- Code examples for updated APIs
+
+**Example:**
+```
+⚠️  Major version update detected: @donotdev/core 0.1.0 → 1.0.0
+
+Migration guide: docs/migration/v0.1-to-v1.0.md
+
+Breaking changes:
+- Removed useAuth() - use useAuthentication() instead
+- Theme API changed - see migration guide
+
+Review the migration guide before updating.
+```
+
+---
+
+## Troubleshooting
+
+### "No updates available"
+
+- All packages are up to date
+- Or you're already on latest version
+
+### "Major version change detected"
+
+- Review migration guide
+- Check breaking changes
+- Update code if needed
+- Run `dndev bump` again to apply
+
+### "Package not found on npm"
+
+- Package may not be published yet
+- Check package name spelling
+- Verify you're using correct registry
+
+---
+
+## Best Practices
+
+1. **Regular updates:** Run `dndev bump --check` monthly
+2. **Test after updates:** Run your test suite after applying updates
+3. **Review major changes:** Always read migration guides for major versions
+4. **Use `--dry-run`:** Preview changes before applying
+5. **Commit changes:** Commit updated `package.json` files after successful updates
+
+---
+
+**Keep your dependencies up to date. Stay secure. Stay compatible.**

package/templates/root-consumer/guides/dndev/essences_reference.css.example

@@ -1,9 +1,10 @@
 /**
- * Reference: Framework essences (Brutalist, Luxury).
+ * Reference: Framework essences (Brutalist, Luxury, Retro).
  * Copy the blocks you need into your app's src/themes.css.
  * Default essence = SaaS (Inter); these do not apply until you set the class on <html>.
  *
- * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Inter, Roboto are bundled in @donotdev/ui (no external requests).
+ * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Press Start 2P (Retro),
+ * Inter, Roboto are bundled in @donotdev/ui (no external requests).
  */
 
 /** =========================================================================
@@ -172,3 +173,119 @@
   --shadow-md: 0 4px 12px var(--shadow-color);
   --shadow-xl: 0 8px 24px var(--shadow-color);
 }
+
+
+/** =========================================================================
+ *  Retro — 8-bit pixel aesthetic, Press Start 2P, neon on dark, CRT vibes.
+ *  Set <html class="retro"> to apply.
+ *  ========================================================================= */
+.retro {
+  --theme-icon: 'Gamepad2';
+  --theme-label: 'Retro';
+  --theme-is-dark: 1;
+
+  /* 1. Core Colors - Muted neon on zinc */
+  --background: #1c1c22;
+  --foreground: #c8e6c9;
+  --primary: #5eead4;
+  --secondary: #c084fc;
+  --accent: #fbbf24;
+
+  /* 2. Semantic */
+  --success: #6ee7b7;
+  --warning: #fbbf24;
+  --destructive: #f87171;
+
+  /* 3. Surfaces - Zinc CRT glass */
+  --muted: #27272f;
+  --muted-foreground: #8bae8b;
+  --border: #4a6a4a;
+  --input: #1c1c22;
+  --ring: #5eead4;
+  --card: #222228;
+  --card-foreground: #c8e6c9;
+  --popover: #222228;
+  --popover-foreground: #c8e6c9;
+  --surface-1: #1e1e24;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #0f172a;
+  --secondary-foreground: #0f172a;
+  --accent-foreground: #0f172a;
+  --success-foreground: #0f172a;
+  --warning-foreground: #0f172a;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius - Hard pixel corners */
+  --radius-interactive: 0;
+  --radius-surface: 0;
+  --radius-floating: 0;
+
+  /* 6. Typography - Press Start 2P (pixel font, 400 only) */
+  --font-family: 'Press Start 2P', var(--font-mono);
+  --font-headline: 'Press Start 2P', var(--font-mono);
+  --font-weight-normal: 400;
+  --font-weight-medium: 400;
+  --font-weight-semibold: 400;
+  --font-weight-bold: 400;
+
+  /* 7. Font scale - smaller base (pixel font reads large) */
+  --font-size-xs: 0.5rem;
+  --font-size-sm: 0.625rem;
+  --font-size-base: 0.75rem;
+  --font-size-lg: 0.875rem;
+  --font-size-xl: 1rem;
+  --font-size-2xl: 1.25rem;
+  --font-size-3xl: 1.5rem;
+  --line-height: 1.6;
+
+  /* 8. Borders - Chunky pixel borders */
+  --border-width: 3px;
+  --border-huge: 4px;
+
+  /* 9. Shadows — soft neon glow */
+  --shadow-color: #5eead433;
+  --shadow-sm: 0 0 4px #5eead422;
+  --shadow-md: 0 0 8px #5eead433, 0 0 16px #5eead41a;
+  --shadow-xl: 0 0 12px #5eead444, 0 0 24px #5eead42a, 0 0 48px #c084fc1a;
+  --shadow-cta: 0 0 16px #5eead444, 0 0 32px #5eead422;
+
+  /* 10. Per-variant shadows — soft neon matching */
+  --shadow-primary: 0 0 8px #5eead42a;
+  --shadow-primary-xl: 0 0 16px #5eead444, 0 0 32px #5eead422;
+  --shadow-secondary: 0 0 8px #c084fc2a;
+  --shadow-secondary-xl: 0 0 16px #c084fc44, 0 0 32px #c084fc22;
+
+  /* 11. Header padding */
+  --header-shadow-padding: 0;
+}
+
+/* Body - subtle CRT scanlines */
+.retro body {
+  background-color: var(--background);
+  background-image:
+    repeating-linear-gradient(
+      0deg,
+      transparent,
+      transparent 2px,
+      rgba(0, 0, 0, 0.08) 2px,
+      rgba(0, 0, 0, 0.08) 4px
+    );
+}
+
+/* Uppercase headings (pixel fonts look best in caps) */
+.retro {
+  :is(h1, h2, h3, h4, h5, h6),
+  [data-level^='h'] {
+    text-transform: uppercase;
+  }
+}
+
+/* Flat surfaces - no gradient, pixel-sharp */
+.retro .dndev-surface { background: var(--card); }
+.retro .dndev-surface[data-variant='outline'] { border: var(--border-width) solid var(--border); }
+
+.retro .dndev-card[data-variant='outline'] {
+  background: transparent;
+  box-shadow: none;
+}

package/templates/root-consumer/guides/wai-way/blueprints/1_scaffold.md.example

@@ -37,6 +37,20 @@ Apply the chosen essence (SaaS, Luxury, Brutalist) to your `src/themes.css`.
 
 ---
 
+## Reference: Demo App
+
+**Before creating pages, study the demo app:** `packages/cli/templates/app-demo/src/pages/`
+
+It shows the canonical pattern:
+- Thin page wrappers (~5 lines) that import templates
+- `PageMeta.preset` for per-route layout switching (landing → admin → docs)
+- Component showcase with filterable grid
+- Entity definition with `defineEntity()`
+
+**Copy from the demo app, customize for your spec.**
+
+---
+
 ## Step 3: Review Spec Pages
 
 From your spec, you have a list of pages. Now create them.

package/templates/root-consumer/guides/wai-way/blueprints/2_entities.md.example

@@ -46,6 +46,12 @@ export const productEntity = defineEntity({
 });
 ```
 
+> **Status field:** Auto-added with locked `type`, `visibility`, `editable`. Don't redefine those. To add custom options:
+> ```typescript
+> status: { validation: { options: [{ value: 'shipped', label: 'Shipped' }] } }
+> // Merged result: [draft, available, deleted, shipped]
+> ```
+
 ---
 
 ## Step 3: Export Entities

package/templates/root-consumer/guides/wai-way/blueprints/3_compose.md.example

@@ -20,6 +20,20 @@
 
 ---
 
+## Reference: Demo App
+
+**Before composing pages, study the demo app:** `packages/cli/templates/app-demo/src/pages/`
+
+It shows the canonical pattern:
+- Thin page wrappers (~5 lines) that import templates
+- `PageMeta.preset` for per-route layout switching (landing → admin → docs)
+- CRUD with `ProductCardListTemplate` + `defineEntity()`
+- Component showcase with filterable grid
+
+**Copy from the demo app, customize for your spec.**
+
+---
+
 ## Step 2: Read Page Patterns
 
 **READ:** `guides/wai-way/page_patterns.md` for all patterns:

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

@@ -309,12 +309,9 @@ export const orderEntity = defineEntity({
       visibility: 'owner',
       editable: 'never',
     },
+    // status is auto-added with type/visibility/editable locked.
+    // Only define validation.options — framework auto-adds [draft, available, deleted].
     status: {
-      name: 'status',
-      label: 'status',
-      type: 'select',
-      visibility: 'owner',
-      editable: 'admin',
       validation: {
         options: [
           { value: 'pending', label: 'Pending' },
@@ -341,6 +338,8 @@ export const orderEntity = defineEntity({
 });
 ```
 
+> **Merged status options:** `[draft, available, deleted, pending, paid, shipped, delivered, cancelled]`. The three defaults are always first and cannot be removed.
+
 ---
 
 ## Review

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

@@ -152,7 +152,7 @@ import { EntityFormRenderer, useCrud } from '@donotdev/crud';
 import { carEntity } from 'entities/car';
 import { useTranslation } from '@donotdev/core';
 import type { PageMeta } from '@donotdev/core';
-import { useParams } from '@donotdev/ui/routing';
+import { useParams } from '@donotdev/ui';
 
 export const NAMESPACE = 'car';
 
@@ -523,7 +523,7 @@ import { Section, Card, Grid, Stack, Text, Button, Badge } from '@donotdev/compo
 import { useCrud } from '@donotdev/crud';
 import { productEntity } from 'entities/product';
 import type { PageMeta } from '@donotdev/core';
-import { useParams } from '@donotdev/ui/routing';
+import { useParams } from '@donotdev/ui';
 
 export const NAMESPACE = 'product-detail';
 

package/dist/bin/commands/agent-setup.d.ts

@@ -1,6 +0,0 @@
-/**
- * @fileoverview Agent Setup Command Wrapper
- * @description Re-exports agentSetup from tooling for CLI bundling.
- */
-export { agentSetup as main } from '@donotdev/tooling';
-//# sourceMappingURL=agent-setup.d.ts.map

package/dist/bin/commands/agent-setup.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-setup.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/agent-setup.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/agent-setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"agent-setup.js","sourceRoot":"","sources":["../../../src/bin/commands/agent-setup.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C;;;GAGG;AAEH,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/build.d.ts

@@ -1,11 +0,0 @@
-/**
- * @fileoverview Build Command Wrapper
- * @description Re-exports build from tooling for CLI bundling.
- * Each command wrapper is bundled separately as a fully self-contained script.
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-export { build as main } from '@donotdev/tooling';
-//# sourceMappingURL=build.d.ts.map

package/dist/bin/commands/build.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/build.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/bin/commands/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/bump.d.ts

@@ -1,11 +0,0 @@
-/**
- * @fileoverview Bump Command Wrapper
- * @description Re-exports bump from tooling for CLI bundling.
- * Each command wrapper is bundled separately as a fully self-contained script.
- *
- * @version 0.0.4
- * @since 0.0.2
- * @author AMBROISE PARK Consulting
- */
-export { bump as main } from '@donotdev/tooling';
-//# sourceMappingURL=bump.d.ts.map

package/dist/bin/commands/bump.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bump.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/bump.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/bump.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"bump.js","sourceRoot":"","sources":["../../../src/bin/commands/bump.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/cacheout.d.ts

@@ -1,11 +0,0 @@
-/**
- * @fileoverview Cacheout Command Wrapper
- * @description Re-exports cacheout from tooling for CLI bundling.
- * Each command wrapper is bundled separately as a fully self-contained script.
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-export { cacheout as main } from '@donotdev/tooling';
-//# sourceMappingURL=cacheout.d.ts.map

package/dist/bin/commands/cacheout.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheout.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/cacheout.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/cacheout.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"cacheout.js","sourceRoot":"","sources":["../../../src/bin/commands/cacheout.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/create-app.d.ts

@@ -1,11 +0,0 @@
-/**
- * @fileoverview Create App Command Wrapper
- * @description Re-exports createApp from tooling for CLI bundling.
- * Each command wrapper is bundled separately as a fully self-contained script.
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-export { createApp as main } from '@donotdev/tooling';
-//# sourceMappingURL=create-app.d.ts.map

package/dist/bin/commands/create-app.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-app.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/create-app.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/create-app.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"create-app.js","sourceRoot":"","sources":["../../../src/bin/commands/create-app.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}