create-velox-app 0.4.14 → 0.6.25

package/src/templates/source/root/CLAUDE.default.md

@@ -126,3 +126,188 @@ __RUN_CMD__ db:generate  # Regenerate client
 ```
 
 Access via context: `ctx.db.user.findMany()`
+
+## Code Generation
+
+### Available Generators
+
+| Generator | Alias | Description |
+|-----------|-------|-------------|
+| `procedure` | `p` | API procedure with queries/mutations |
+| `schema` | `s` | Zod validation schema |
+| `model` | `m` | Prisma model definition |
+| `migration` | `mig` | Database migration file |
+| `test` | `t` | Unit/integration test file |
+| `resource` | `r` | Complete CRUD resource (all above) |
+| `seeder` | `seed` | Database seeder |
+| `factory` | `f` | Test data factory |
+
+### Usage Examples
+
+```bash
+# Generate a complete CRUD resource
+__RUN_CMD__ velox make resource Post --crud
+
+# Generate just a procedure
+__RUN_CMD__ velox make procedure Users --crud
+
+# Generate with soft-delete support
+__RUN_CMD__ velox m r Comment --soft-delete
+
+# Preview without writing files
+__RUN_CMD__ velox make --dry-run resource Post
+
+# JSON output for scripting
+__RUN_CMD__ velox make resource Post --json
+```
+
+### Generator Options
+
+**Common Options:**
+- `--dry-run, -d` - Preview changes without writing
+- `--force, -f` - Overwrite existing files
+- `--json` - Output results as JSON
+
+**Resource/Procedure Options:**
+- `--crud, -c` - Generate full CRUD operations
+- `--paginated, -P` - Include pagination for list
+- `--soft-delete, -s` - Add soft delete support
+- `--timestamps, -t` - Include timestamps (default: true)
+
+## Migration Runner
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `velox migrate status` | Show migration status |
+| `velox migrate run` | Run pending migrations |
+| `velox migrate rollback` | Rollback last migration |
+| `velox migrate fresh` | Drop all tables and re-run |
+| `velox migrate reset` | Rollback all then re-run |
+
+### Usage
+
+```bash
+# Check status
+__RUN_CMD__ velox migrate status
+
+# Run pending migrations
+__RUN_CMD__ velox migrate run
+
+# Development mode (creates migration from schema diff)
+__RUN_CMD__ velox migrate run --dev
+
+# Rollback last migration
+__RUN_CMD__ velox migrate rollback
+
+# Fresh database
+__RUN_CMD__ velox migrate fresh
+
+# JSON output
+__RUN_CMD__ velox migrate status --json
+```
+
+## Database Seeding
+
+### Commands
+
+```bash
+# Run all seeders
+__RUN_CMD__ velox db seed
+
+# Run specific seeder
+__RUN_CMD__ velox db seed UserSeeder
+
+# Fresh seed (truncate first)
+__RUN_CMD__ velox db seed --fresh
+
+# Preview
+__RUN_CMD__ velox db seed --dry-run
+```
+
+### Seeder Example
+
+```typescript
+// apps/api/src/database/seeders/UserSeeder.ts
+import type { Seeder } from '@veloxts/cli';
+
+export const UserSeeder: Seeder = {
+  name: 'UserSeeder',
+  dependencies: [],
+
+  async run(db) {
+    await db.user.createMany({
+      data: [
+        { email: 'admin@example.com', name: 'Admin' },
+        { email: 'user@example.com', name: 'User' },
+      ],
+    });
+  },
+};
+```
+
+## Error Handling
+
+VeloxTS uses structured error codes for AI tooling:
+
+```typescript
+// Error format: VeloxError[E1001]: Message
+// E1xxx - Core errors
+// E2xxx - Generator errors
+// E3xxx - Seeding errors
+// E4xxx - Migration errors
+// E5xxx - Dev server errors
+```
+
+### Common Patterns
+
+```typescript
+import { VeloxError } from '@veloxts/core';
+
+const getUser = procedure()
+  .input(z.object({ id: z.string().uuid() }))
+  .query(async ({ ctx, input }) => {
+    const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+
+    if (!user) {
+      throw VeloxError.notFound('User', input.id);
+    }
+
+    return user;
+  });
+```
+
+## Development Workflow
+
+### Hot Module Replacement (HMR)
+
+```bash
+# Default: HMR enabled
+__RUN_CMD__ velox dev
+
+# With verbose timing
+__RUN_CMD__ velox dev --verbose
+
+# Disable HMR
+__RUN_CMD__ velox dev --no-hmr
+```
+
+### CLI JSON Output
+
+All CLI commands support `--json` for scripting:
+
+```bash
+velox migrate status --json
+velox db seed --json --dry-run
+velox procedures list --json
+```
+
+### Recommended Flow
+
+1. Define Zod schemas in `apps/api/src/schemas/`
+2. Generate resource: `velox make resource Post --crud`
+3. Customize generated procedures as needed
+4. Run migrations: `velox migrate run --dev`
+5. Seed data: `velox db seed --fresh`
+6. Test endpoints with Thunder Client or curl

package/src/templates/source/root/package.json

@@ -3,6 +3,9 @@
   "version": "0.0.1",
   "private": true,
   "type": "module",
+  "workspaces": [
+    "apps/*"
+  ],
   "scripts": {
     "dev": "__RUN_CMD__ --parallel -r dev",
     "build": "__RUN_CMD__ -r build",
@@ -11,8 +14,11 @@
     "db:generate": "__RUN_CMD__ -F api db:generate",
     "db:studio": "__RUN_CMD__ -F api db:studio"
   },
+  "dependencies": {
+    "@prisma/client-runtime-utils": "7.2.0"
+  },
   "devDependencies": {
-    "@types/node": "25.0.2",
+    "@types/node": "25.0.3",
     "typescript": "5.9.3"
   }
 }

package/src/templates/source/rsc/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This is a VeloxTS full-stack application using React Server Components.
+
+## Project Structure
+
+```
+__PROJECT_NAME__/
+├── app/                    # Application layer (RSC)
+│   ├── pages/              # File-based routing (RSC pages)
+│   │   ├── index.tsx       # Home page (/)
+│   │   └── users.tsx       # Users page (/users)
+│   ├── layouts/            # Layout components
+│   │   └── root.tsx        # Root layout (wraps all pages)
+│   └── actions/            # Server actions
+│       ├── users.ts        # User-related actions
+│       └── posts.ts        # Post actions (procedure bridge)
+├── src/                    # Source layer
+│   ├── api/                # API layer (Fastify embedded in Vinxi)
+│   │   ├── handler.ts      # API handler for /api/* routes
+│   │   ├── database.ts     # Prisma client
+│   │   ├── procedures/     # API procedure definitions
+│   │   └── schemas/        # Zod validation schemas
+│   ├── entry.client.tsx    # Client hydration entry
+│   └── entry.server.tsx    # Server rendering entry
+├── prisma/
+│   └── schema.prisma       # Database schema
+├── app.config.ts           # Vinxi configuration
+└── package.json
+```
+
+## Key Concepts
+
+### React Server Components (RSC)
+- Pages in `app/pages/` are Server Components by default
+- They run on the server and can directly access the database
+- Use `'use client'` directive for client-side interactivity
+
+### File-Based Routing
+- `app/pages/index.tsx` → `/`
+- `app/pages/users.tsx` → `/users`
+- `app/pages/users/[id].tsx` → `/users/:id` (dynamic route)
+- `app/pages/[...slug].tsx` → catch-all route
+
+### Server Actions
+- Defined in `app/actions/` with `'use server'` directive
+- Type-safe with Zod validation via `createAction()`
+- Can be called directly from client components
+
+### Procedure Bridge Pattern
+Server actions can bridge to API procedures for code reuse:
+```typescript
+// app/actions/posts.ts
+'use server';
+import { action } from '@veloxts/web';
+import { postProcedures } from '@/api/procedures/posts';
+
+export const createPost = action.fromProcedure(
+  postProcedures.procedures.createPost,
+  { parseFormData: true }  // Auto-parse FormData
+);
+```
+
+This pattern:
+- Reuses procedure validation, guards, and business logic
+- Type safety flows from procedure → action → form
+- Works with HTML forms for progressive enhancement
+
+### API Routes
+- All `/api/*` routes are handled by embedded Fastify
+- Procedures defined in `src/api/procedures/`
+- Full VeloxTS type safety and REST conventions
+
+## Commands
+
+```bash
+# Development
+__RUN_CMD__ dev         # Start dev server with HMR
+
+# Database
+__RUN_CMD__ db:generate # Generate Prisma client
+__RUN_CMD__ db:push     # Push schema to database
+__RUN_CMD__ db:migrate  # Run migrations
+__RUN_CMD__ db:studio   # Open Prisma Studio
+
+# Production
+__RUN_CMD__ build       # Build for production
+__RUN_CMD__ start       # Start production server
+```
+
+## Development
+
+1. Run `__RUN_CMD__ db:push` to set up the database
+2. Run `__RUN_CMD__ dev` to start the development server
+3. Open http://localhost:__API_PORT__ in your browser
+
+## API Endpoints
+
+- `GET /api/health` - Health check
+- `GET /api/users` - List all users
+- `GET /api/users/:id` - Get user by ID
+- `POST /api/users` - Create user
+- `PUT /api/users/:id` - Update user
+- `DELETE /api/users/:id` - Delete user

package/src/templates/source/rsc/app/actions/posts.ts

@@ -0,0 +1,93 @@
+'use server';
+
+/**
+ * Post Server Actions - Procedure Bridge Pattern
+ *
+ * Demonstrates the VeloxTS procedure bridge, which allows server actions
+ * to reuse procedure validation, guards, and business logic.
+ *
+ * This pattern bridges the gap between:
+ * - Procedures (API logic with validation and guards)
+ * - Server Actions (form submissions and direct calls)
+ *
+ * Benefits:
+ * - Single source of truth for validation (Zod schemas in procedures)
+ * - Reuse of business logic across REST API and server actions
+ * - Type safety flows from procedure to action
+ *
+ * @example
+ * ```tsx
+ * // In a server component
+ * import { createPost } from '@/actions/posts';
+ *
+ * // Call directly with typed input
+ * const result = await createPost({
+ *   userId: '123',
+ *   title: 'My Post',
+ *   content: 'Content here',
+ * });
+ *
+ * // Or use in a form
+ * <form action={createPost}>
+ *   <input name="title" />
+ *   <button type="submit">Create</button>
+ * </form>
+ * ```
+ */
+
+import { action } from '@veloxts/web';
+
+import { postProcedures } from '@/api/procedures/posts';
+
+// ============================================================================
+// Procedure-Bridged Actions
+// ============================================================================
+
+/**
+ * Creates a new post for a user.
+ *
+ * This action bridges to the createPost procedure, reusing:
+ * - Input validation (CreatePostSchema)
+ * - Output validation (PostSchema)
+ * - Parent resource validation (.parent('users'))
+ * - Any guards or middleware defined on the procedure
+ *
+ * The procedure's REST endpoint is: POST /api/users/:userId/posts
+ */
+export const createPost = action.fromProcedure(postProcedures.procedures.createPost, {
+  parseFormData: true,
+});
+
+/**
+ * Gets a specific post.
+ *
+ * Bridges to getPost procedure which validates:
+ * - userId: UUID format
+ * - id: UUID format (post ID)
+ */
+export const getPost = action.fromProcedure(postProcedures.procedures.getPost);
+
+/**
+ * Updates an existing post.
+ *
+ * Bridges to updatePost procedure which validates:
+ * - userId and id must exist
+ * - Only title and content can be updated
+ */
+export const updatePost = action.fromProcedure(postProcedures.procedures.updatePost, {
+  parseFormData: true,
+});
+
+/**
+ * Deletes a post.
+ *
+ * Bridges to deletePost procedure.
+ */
+export const deletePost = action.fromProcedure(postProcedures.procedures.deletePost);
+
+/**
+ * Lists all posts for a user.
+ *
+ * Bridges to listPosts procedure.
+ */
+export const listPosts = action.fromProcedure(postProcedures.procedures.listPosts);

package/src/templates/source/rsc/app/actions/users.ts

@@ -0,0 +1,83 @@
+'use server';
+
+/**
+ * User Server Actions
+ *
+ * Type-safe server actions for user operations using the VeloxTS action() helper.
+ * These can be called directly from client components with full type inference.
+ *
+ * @example
+ * ```tsx
+ * // In a client component
+ * const result = await createUser({ name: 'John', email: 'john@example.com' });
+ *
+ * if (result.success) {
+ *   console.log('Created user:', result.data);
+ * } else {
+ *   console.log('Error:', result.error.message);
+ * }
+ * ```
+ */
+
+import { action } from '@veloxts/web';
+import { z } from 'zod';
+
+import { db } from '@/api/database';
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+/**
+ * Schema for creating a new user
+ */
+const CreateUserSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name is too long'),
+  email: z.string().email('Invalid email address'),
+});
+
+/**
+ * Schema for deleting a user
+ */
+const DeleteUserSchema = z.object({
+  id: z.string().min(1, 'User ID is required'),
+});
+
+// ============================================================================
+// Actions
+// ============================================================================
+
+/**
+ * Creates a new user.
+ *
+ * Input is automatically validated against CreateUserSchema.
+ * Returns a discriminated union for type-safe error handling.
+ */
+export const createUser = action(CreateUserSchema, async (input) => {
+  // Input is fully typed as { name: string; email: string }
+  // Validation has already been performed by the action() helper
+
+  const user = await db.user.create({
+    data: {
+      name: input.name.trim(),
+      email: input.email.toLowerCase().trim(),
+    },
+  });
+
+  return user;
+});
+
+/**
+ * Deletes a user by ID.
+ *
+ * Input is automatically validated to ensure a valid ID is provided.
+ */
+export const deleteUser = action(DeleteUserSchema, async (input) => {
+  // Input is fully typed as { id: string }
+
+  await db.user.delete({
+    where: { id: input.id },
+  });
+
+  return { deleted: true };
+});

package/src/templates/source/rsc/app/layouts/dashboard.tsx

@@ -0,0 +1,127 @@
+/**
+ * Dashboard Layout
+ *
+ * A nested layout for pages in the (dashboard) route group.
+ * Adds a sidebar navigation for dashboard-related pages.
+ * This is NOT a full HTML document - it wraps within RootLayout.
+ */
+
+import type { ReactNode } from 'react';
+
+interface DashboardLayoutProps {
+  children: ReactNode;
+  params?: Record<string, string>;
+}
+
+export default function DashboardLayout({ children }: DashboardLayoutProps) {
+  return (
+    <div className="dashboard-layout">
+      <style>{`
+        .dashboard-layout {
+          display: flex;
+          gap: 2rem;
+          min-height: 60vh;
+        }
+
+        .dashboard-sidebar {
+          width: 200px;
+          flex-shrink: 0;
+          background: white;
+          border-radius: 8px;
+          padding: 1rem;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+          height: fit-content;
+        }
+
+        .dashboard-sidebar h3 {
+          font-size: 0.75rem;
+          text-transform: uppercase;
+          color: #888;
+          margin-bottom: 0.5rem;
+          padding: 0 0.5rem;
+        }
+
+        .sidebar-nav {
+          list-style: none;
+        }
+
+        .sidebar-nav a {
+          display: block;
+          padding: 0.5rem;
+          color: #1a1a2e;
+          text-decoration: none;
+          border-radius: 4px;
+          transition: background 0.2s;
+        }
+
+        .sidebar-nav a:hover {
+          background: #f0f0f0;
+        }
+
+        .sidebar-nav a.active {
+          background: #6366f1;
+          color: white;
+        }
+
+        .dashboard-content {
+          flex: 1;
+          background: white;
+          border-radius: 8px;
+          padding: 1.5rem;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+
+        .dashboard-badge {
+          display: inline-block;
+          background: #6366f1;
+          color: white;
+          font-size: 0.625rem;
+          text-transform: uppercase;
+          padding: 0.25rem 0.5rem;
+          border-radius: 4px;
+          margin-bottom: 1rem;
+        }
+      `}</style>
+
+      <aside className="dashboard-sidebar">
+        <h3>Dashboard</h3>
+        <nav>
+          <ul className="sidebar-nav">
+            <li>
+              <a href="/profile">Profile</a>
+            </li>
+            <li>
+              <a href="/settings">Settings</a>
+            </li>
+            <li>
+              <a href="/settings?tab=notifications">Notifications</a>
+            </li>
+            <li>
+              <a href="/settings?tab=security">Security</a>
+            </li>
+          </ul>
+        </nav>
+
+        <h3 style={{ marginTop: '1rem' }}>Navigation</h3>
+        <nav>
+          <ul className="sidebar-nav">
+            <li>
+              <a href="/">Home</a>
+            </li>
+            <li>
+              <a href="/users">Users</a>
+            </li>
+            <li>
+              <a href="/docs/getting-started">Docs</a>
+            </li>
+          </ul>
+        </nav>
+      </aside>
+
+      <div className="dashboard-content">
+        <span className="dashboard-badge">Dashboard</span>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/templates/source/rsc/app/layouts/marketing.tsx

@@ -0,0 +1,25 @@
+/**
+ * Marketing Layout
+ *
+ * This layout wraps pages in the (marketing) route group.
+ * It's automatically applied to all pages in app/pages/(marketing)/*.
+ */
+
+import type { ReactNode } from 'react';
+
+interface MarketingLayoutProps {
+  children: ReactNode;
+  params?: Record<string, string>;
+}
+
+export default function MarketingLayout({ children }: MarketingLayoutProps) {
+  return (
+    <div className="marketing-layout">
+      <div className="marketing-banner">
+        <span className="badge">Marketing</span>
+        <span>This page uses the marketing layout</span>
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/templates/source/rsc/app/layouts/minimal.tsx

@@ -0,0 +1,30 @@
+/**
+ * Minimal Layout
+ *
+ * A stripped-down layout for pages that need minimal chrome,
+ * such as print-friendly pages, embedded widgets, or auth pages.
+ */
+
+import type { ReactNode } from 'react';
+
+interface MinimalLayoutProps {
+  children: ReactNode;
+  params?: Record<string, string>;
+}
+
+export default function MinimalLayout({ children }: MinimalLayoutProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>VeloxTS</title>
+        <link rel="stylesheet" href="/_build/styles.css" />
+      </head>
+      <body className="minimal-layout">
+        {children}
+        <script src="/_build/entry.client.js" type="module" />
+      </body>
+    </html>
+  );
+}