create-velox-app 0.6.65 → 0.6.67

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # create-velox-app
 
+## 0.6.67
+
+### Patch Changes
+
+- fix(create): add browser-safe routes.ts for auth template, prevent set -e from hiding CLI errors in smoke tests, add tsx to scaffolded project devDependencies
+
+## 0.6.66
+
+### Patch Changes
+
+- docs(skills): recommend namespace generator for AI agents
+
 ## 0.6.65
 
 ### Patch Changes

package/dist/templates/auth.js

@@ -50,6 +50,9 @@ function generateIndexTs() {
 function generateRouterTs() {
     return compileTemplate('api/router.auth.ts', AUTH_CONFIG);
 }
+function generateRoutesTs() {
+    return compileTemplate('api/routes.auth.ts', AUTH_CONFIG);
+}
 function generateConfigDatabase(config) {
     return compileTemplate('api/config/database.ts', config);
 }
@@ -90,6 +93,7 @@ export function generateAuthTemplate(config) {
         { path: 'apps/api/prisma/schema.prisma', content: generatePrismaSchema(config) },
         // API Source files
         { path: 'apps/api/src/router.ts', content: generateRouterTs() },
+        { path: 'apps/api/src/routes.ts', content: generateRoutesTs() },
         { path: 'apps/api/src/index.ts', content: generateIndexTs() },
         { path: 'apps/api/src/config/app.ts', content: generateConfigApp(config) },
         { path: 'apps/api/src/config/auth.ts', content: generateAuthConfig() },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-velox-app",
-  "version": "0.6.65",
+  "version": "0.6.67",
   "description": "Project scaffolder for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",

package/src/templates/source/api/package.auth.json

@@ -33,6 +33,7 @@
     "hot-hook": "0.4.0",
     "prisma": "7.2.0",
     "tsup": "8.5.1",
+    "tsx": "4.21.0",
     "typescript": "5.9.3"
   },
   "hotHook": {

package/src/templates/source/api/package.default.json

@@ -31,6 +31,7 @@
     "hot-hook": "0.4.0",
     "prisma": "7.2.0",
     "tsup": "8.5.1",
+    "tsx": "4.21.0",
     "typescript": "5.9.3"
   },
   "hotHook": {

package/src/templates/source/api/routes.auth.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser-Safe Route Definitions
+ *
+ * This file exports route metadata that can be safely imported by frontend code.
+ * It does NOT import any server-side modules like procedures or database clients.
+ *
+ * IMPORTANT: Keep this file browser-safe - no Node.js imports or side effects.
+ */
+
+import type { RouteMap } from '@veloxts/router';
+
+/**
+ * Route mappings for the VeloxTS client
+ *
+ * Maps namespace -> procedure -> { method, path, kind }
+ * These must match the actual procedure definitions in ./procedures/
+ */
+export const routes: RouteMap = {
+  health: {
+    getHealth: { method: 'GET', path: '/health', kind: 'query' },
+  },
+  auth: {
+    createAccount: { method: 'POST', path: '/auth/register', kind: 'mutation' },
+    createSession: { method: 'POST', path: '/auth/login', kind: 'mutation' },
+    createRefresh: { method: 'POST', path: '/auth/refresh', kind: 'mutation' },
+    deleteSession: { method: 'DELETE', path: '/auth/session', kind: 'mutation' },
+    getMe: { method: 'GET', path: '/auth/me', kind: 'query' },
+  },
+  users: {
+    listUsers: { method: 'GET', path: '/users', kind: 'query' },
+    getUser: { method: 'GET', path: '/users/:id', kind: 'query' },
+    createUser: { method: 'POST', path: '/users', kind: 'mutation' },
+    updateUser: { method: 'PUT', path: '/users/:id', kind: 'mutation' },
+    patchUser: { method: 'PATCH', path: '/users/:id', kind: 'mutation' },
+    deleteUser: { method: 'DELETE', path: '/users/:id', kind: 'mutation' },
+  },
+};

package/src/templates/source/root/.claude/skills/veloxts/GENERATORS.md

@@ -1,15 +1,44 @@
 # VeloxTS Generators Guide
 
+## AI Agent Recommended Workflow
+
+When creating new entities, the **recommended approach** is:
+
+1. **Design and add the Prisma model** directly to `prisma/schema.prisma`
+2. **Run `velox make namespace EntityName`** to generate procedures
+
+This ensures complete, production-ready code because the AI can design the full schema based on requirements.
+
+```bash
+# Example: Creating a Post entity
+
+# Step 1: AI adds model to prisma/schema.prisma
+model Post {
+  id        String   @id @default(uuid())
+  title     String
+  content   String
+  published Boolean  @default(false)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  @@map("posts")
+}
+
+# Step 2: Generate procedures for the existing model
+velox make namespace Post --example
+```
+
 ## Decision Tree: Which Generator?
 
 ```
 Do you need a new database entity?
-├── YES → Is this a completely new entity?
-│         ├── YES → velox make resource [RECOMMENDED]
-│         │         Creates: Prisma model + Schema + Procedures + Tests
-│         │
-│         └── NO (existing Prisma model) → velox make namespace
-│                   Creates: Schema + Procedures (no Prisma injection)
+├── YES (AI workflow) → 1. Design Prisma model in schema.prisma
+│                       2. velox make namespace EntityName --example
+│                       Creates: Schema + Procedures for existing model
+│
+├── YES (Interactive) → velox make resource EntityName -i
+│                       Prompts for fields, creates everything
 │
 └── NO → What do you need?
          ├── Single API endpoint → velox make procedure
@@ -29,34 +58,26 @@ Do you need a new database entity?
 
 | Generator | Creates | Use When |
 |-----------|---------|----------|
-| `resource` | Prisma + Schema + Procedures + Tests | **New database entity** (recommended default) |
-| `namespace` | Schema + Procedures | Existing model or external API |
+| `namespace` | Schema + Procedures + Tests | **AI agents** or existing Prisma model |
+| `resource -i` | Prisma + Schema + Procedures + Tests | **Human interactive** field definition |
+| `resource` | Scaffolds with TODOs | Quick start (fields needed manually) |
 | `procedure` | Procedures (inline schemas) | Single endpoint, quick prototype |
 | `schema` | Zod schema file | Standalone validation |
 | `model` | Prisma model | Database-only change |
 
-## Resource Generator [RECOMMENDED]
+## Namespace Generator [AI RECOMMENDED]
 
-The full-stack generator for new entities. Like Laravel's `make:model -a`.
+Best choice for AI agents. Works with models you've already defined.
 
 ```bash
-# Basic usage
-velox make resource Post
+# After adding model to schema.prisma:
+velox make namespace Post --example
 
-# Full CRUD with pagination
-velox make resource Post --crud --paginated
+# With tests
+velox make namespace Order --example --with-tests
 
-# Interactive field definition
-velox make resource Product -i
-
-# With soft delete
-velox make resource Comment --soft-delete
-
-# Auto-run migration
-velox make resource Order --auto-migrate
-
-# Preview without writing
-velox make resource Post --dry-run
+# Short form
+velox m ns Product -e -t
 ```
 
 ### What It Creates
@@ -67,40 +88,36 @@ src/
 │   ├── posts.ts              # CRUD procedures
 │   └── __tests__/
 │       └── posts.test.ts     # Unit tests
-├── schemas/
-│   └── post.schema.ts        # Zod validation
-└── models/
-    └── post.prisma           # Injected into schema.prisma
+└── schemas/
+    └── post.ts               # Zod validation
 ```
 
 ### Options
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--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) |
-| `--with-tests` | `-W` | Generate tests (default: true) |
-| `--interactive` | `-i` | Define fields interactively |
-| `--skip-registration` | | Don't auto-register in router |
-| `--auto-migrate` | | Run migration automatically |
-| `--dry-run` | `-d` | Preview changes only |
-| `--force` | `-f` | Overwrite existing files |
+| `--example` | `-e` | Include example CRUD procedures |
+| `--with-tests` | `-t` | Generate test file (default: true) |
+| `--skip-registration` | `-S` | Don't auto-register in router |
 
-## Namespace Generator
+## Resource Generator [HUMAN INTERACTIVE]
 
-For existing Prisma models or external data sources.
+Best for humans defining fields interactively via `-i` flag.
+
+**Important:** Without `-i`, creates scaffolds with TODO placeholders that require manual completion.
 
 ```bash
-# Empty namespace (add procedures manually)
-velox make namespace products
+# RECOMMENDED: Interactive mode (prompts for fields)
+velox make resource Product -i
 
-# With example CRUD
-velox make namespace orders --example
+# Without -i: Creates TODOs (not recommended)
+velox make resource Post
 
-# Short form
-velox m ns inventory -e
+# With all features
+velox make resource Order -i --soft-delete --auto-migrate
+
+# Preview without writing
+velox make resource Post --dry-run
 ```
 
 ### What It Creates
@@ -108,24 +125,29 @@ velox m ns inventory -e
 ```
 src/
 ├── procedures/
-│   └── products.ts           # Procedure namespace
-└── schemas/
-    └── product.ts            # Zod schema
+│   ├── posts.ts              # CRUD procedures
+│   └── __tests__/
+│       └── posts.test.ts     # Unit tests
+├── schemas/
+│   └── post.schema.ts        # Zod validation
+└── models/
+    └── post.prisma           # Injected into schema.prisma
 ```
 
-### When to Use
-
-- You already have a Prisma model defined
-- You're calling an external API (no database)
-- You want separate schema files (not inline)
-- You don't need Prisma model injection
-
 ### Options
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--example` | `-e` | Include example CRUD procedures |
-| `--skip-registration` | `-S` | Don't auto-register in router |
+| `--interactive` | `-i` | **Define fields interactively (recommended)** |
+| `--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) |
+| `--with-tests` | `-W` | Generate tests (default: true) |
+| `--skip-registration` | | Don't auto-register in router |
+| `--auto-migrate` | | Run migration automatically |
+| `--dry-run` | `-d` | Preview changes only |
+| `--force` | `-f` | Overwrite existing files |
 
 ## Procedure Generator
 
@@ -238,25 +260,45 @@ velox make task SendDailyDigest --cron="0 9 * * *"
 
 ## Common Workflows
 
-### New Feature: Blog Posts
+### New Feature: Blog Posts (AI Agent)
 
 ```bash
-# 1. Generate complete resource
-velox make resource Post --crud --paginated -i
-
-# 2. (Optional) Add related resources
-velox make resource Comment --crud
-velox make resource Tag --crud
-
-# 3. Run migration
+# 1. Design Prisma model directly in schema.prisma
+model Post {
+  id        String   @id @default(uuid())
+  title     String
+  slug      String   @unique
+  content   String
+  excerpt   String?
+  published Boolean  @default(false)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id])
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  @@map("posts")
+}
+
+# 2. Generate procedures for the model
+velox make namespace Post --example
+
+# 3. Push database changes
 pnpm db:push
 
-# 4. Seed sample data
+# 4. (Optional) Seed sample data
 velox make seeder PostSeeder
-pnpm velox db seed
 ```
 
-### Adding to Existing Model
+### New Feature: Blog Posts (Human Interactive)
+
+```bash
+# 1. Interactive field definition
+velox make resource Post -i --auto-migrate
+
+# 2. Follow prompts to define fields
+# 3. Migration runs automatically
+```
+
+### Adding Procedures for Existing Model
 
 ```bash
 # Model already exists in Prisma

package/src/templates/source/web/main.tsx

@@ -9,7 +9,7 @@ import './styles/global.css';
 // Import router type (type-only import is erased at compile time)
 import type { AppRouter } from '../../api/src/router.js';
 /* @if auth */
-// Import routes from browser-safe routes file
+// Import routes from browser-safe routes file (no server-side code)
 import { routes } from '../../api/src/routes.js';
 
 /* @endif auth */