create-velox-app 0.6.58 → 0.6.60

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # create-velox-app
 
+## 0.6.60
+
+### Patch Changes
+
+- feat(create): add tRPC-specific CLAUDE.md and improve AI-native features
+
+## 0.6.59
+
+### Patch Changes
+
+- refactor(ecosystem): Laravel-style API refinements & added missing unit tests
+
 ## 0.6.58
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # create-velox-app
 
-> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Use with caution in production.
+> **Early Preview (v0.6.x)** - APIs are stabilizing but may still change. Do not use in production yet.
 
 Interactive project scaffolder for VeloxTS Framework - creates production-ready applications with batteries included. Learn more at [@veloxts/velox](https://www.npmjs.com/package/@veloxts/velox).
 

package/dist/cli.d.ts

@@ -5,4 +5,14 @@
  * Executable entry point for the project scaffolder.
  * Handles command-line arguments and initiates the scaffolding process.
  */
-export {};
+import type { DatabaseType, TemplateType } from './templates/index.js';
+/** @internal Exported for testing */
+export interface ParsedArgs {
+    projectName?: string;
+    template?: TemplateType;
+    database?: DatabaseType;
+    help: boolean;
+    version: boolean;
+}
+/** @internal Exported for testing */
+export declare function parseArgs(args: string[]): ParsedArgs;

package/dist/cli.js

@@ -64,7 +64,8 @@ Examples:
   npx create-velox-app my-app -t rsc -d postgresql   # RSC with PostgreSQL
   npx create-velox-app                               # Prompt for name
 `;
-function parseArgs(args) {
+/** @internal Exported for testing */
+export function parseArgs(args) {
     const result = {
         help: false,
         version: false,

package/dist/index.d.ts

@@ -7,7 +7,26 @@
 import type { DatabaseType, TemplateType } from './templates/index.js';
 /** Create-velox-app package version */
 export declare const CREATE_VERSION: string;
+/** Reserved project names that could cause issues
+ * @internal Exported for testing
+ */
+export declare const RESERVED_NAMES: Set<string>;
+/**
+ * Check if a file path is safe (no path traversal attacks)
+ * @internal Exported for testing
+ */
+export declare function isPathSafe(baseDir: string, targetPath: string): boolean;
 /**
  * Main scaffolding function that creates a new VeloxTS project
  */
 export declare function createVeloxApp(initialProjectName?: string, initialTemplate?: TemplateType, initialDatabase?: DatabaseType): Promise<void>;
+/**
+ * Detect which package manager is being used
+ * @internal Exported for testing
+ */
+export declare function detectPackageManager(): 'npm' | 'pnpm' | 'yarn';
+/**
+ * Get the install command for the package manager
+ * @internal Exported for testing
+ */
+export declare function getInstallCommand(packageManager: string): string;

package/dist/index.js

@@ -24,8 +24,10 @@ const packageJson = require('../package.json');
 export const CREATE_VERSION = packageJson.version ?? '0.0.0-unknown';
 /** Timeout for exec commands (5 minutes) */
 const EXEC_TIMEOUT_MS = 5 * 60 * 1000;
-/** Reserved project names that could cause issues */
-const RESERVED_NAMES = new Set([
+/** Reserved project names that could cause issues
+ * @internal Exported for testing
+ */
+export const RESERVED_NAMES = new Set([
     'node_modules',
     'test',
     'tests',
@@ -44,8 +46,9 @@ const RESERVED_NAMES = new Set([
 // ============================================================================
 /**
  * Check if a file path is safe (no path traversal attacks)
+ * @internal Exported for testing
  */
-function isPathSafe(baseDir, targetPath) {
+export function isPathSafe(baseDir, targetPath) {
     const resolved = path.resolve(baseDir, targetPath);
     const normalizedBase = path.normalize(baseDir);
     return resolved.startsWith(normalizedBase);
@@ -222,8 +225,9 @@ async function promptProjectConfig(initialName, initialTemplate, initialDatabase
 }
 /**
  * Detect which package manager is being used
+ * @internal Exported for testing
  */
-function detectPackageManager() {
+export function detectPackageManager() {
     const userAgent = process.env.npm_config_user_agent || '';
     if (userAgent.includes('pnpm'))
         return 'pnpm';
@@ -329,8 +333,9 @@ async function installDependencies(config) {
 }
 /**
  * Get the install command for the package manager
+ * @internal Exported for testing
  */
-function getInstallCommand(packageManager) {
+export function getInstallCommand(packageManager) {
     switch (packageManager) {
         case 'pnpm':
             return 'pnpm install';

package/dist/templates/shared/root.d.ts

@@ -9,6 +9,7 @@ export declare function generatePnpmWorkspaceYaml(): string;
 export declare function generateRootTsConfig(): string;
 export declare function generateRootGitignore(): string;
 export declare function generateRootReadme(config: TemplateConfig): string;
-export declare function generateRootClaudeMd(config: TemplateConfig, isAuthTemplate: boolean): string;
+export type TemplateVariant = 'default' | 'auth' | 'trpc';
+export declare function generateRootClaudeMd(config: TemplateConfig, variant: TemplateVariant | boolean): string;
 export declare function generateRootCursorrules(config: TemplateConfig): string;
-export declare function generateRootFiles(config: TemplateConfig, isAuthTemplate: boolean): TemplateFile[];
+export declare function generateRootFiles(config: TemplateConfig, variant?: TemplateVariant | boolean): TemplateFile[];

package/dist/templates/shared/root.js

@@ -33,8 +33,24 @@ export function generateRootGitignore() {
 export function generateRootReadme(config) {
     return compileTemplate('root/README.md', config);
 }
-export function generateRootClaudeMd(config, isAuthTemplate) {
-    const sourceFile = isAuthTemplate ? 'root/CLAUDE.auth.md' : 'root/CLAUDE.default.md';
+export function generateRootClaudeMd(config, variant) {
+    // Support legacy boolean parameter for backwards compatibility
+    let sourceFile;
+    if (typeof variant === 'boolean') {
+        sourceFile = variant ? 'root/CLAUDE.auth.md' : 'root/CLAUDE.default.md';
+    }
+    else {
+        switch (variant) {
+            case 'auth':
+                sourceFile = 'root/CLAUDE.auth.md';
+                break;
+            case 'trpc':
+                sourceFile = 'root/CLAUDE.trpc.md';
+                break;
+            default:
+                sourceFile = 'root/CLAUDE.default.md';
+        }
+    }
     return compileTemplate(sourceFile, config);
 }
 export function generateRootCursorrules(config) {
@@ -43,14 +59,14 @@ export function generateRootCursorrules(config) {
 // ============================================================================
 // Generate All Root Files
 // ============================================================================
-export function generateRootFiles(config, isAuthTemplate) {
+export function generateRootFiles(config, variant = 'default') {
     return [
         { path: 'package.json', content: generateRootPackageJson(config) },
         { path: 'pnpm-workspace.yaml', content: generatePnpmWorkspaceYaml() },
         { path: 'tsconfig.json', content: generateRootTsConfig() },
         { path: '.gitignore', content: generateRootGitignore() },
         { path: 'README.md', content: generateRootReadme(config) },
-        { path: 'CLAUDE.md', content: generateRootClaudeMd(config, isAuthTemplate) },
+        { path: 'CLAUDE.md', content: generateRootClaudeMd(config, variant) },
         { path: '.cursorrules', content: generateRootCursorrules(config) },
     ];
 }

package/dist/templates/trpc.js

@@ -110,8 +110,8 @@ export function generateTrpcTemplate(config) {
             content: generateDockerCompose(config),
         });
     }
-    // Add root workspace files (use false for isAuthTemplate)
-    const rootFiles = generateRootFiles(config, false);
+    // Add root workspace files (use 'trpc' variant for tRPC-specific CLAUDE.md)
+    const rootFiles = generateRootFiles(config, 'trpc');
     // Add web package files (use false for isAuthTemplate)
     const webBaseFiles = generateWebBaseFiles(config, false);
     const webStyleFiles = generateWebStyleFiles();

package/package.json

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

package/src/templates/source/root/.cursorrules

@@ -5,13 +5,81 @@ This is a VeloxTS full-stack TypeScript application.
 ## Project Type
 
 - **Framework**: VeloxTS (Laravel-inspired TypeScript framework)
+/* @if rsc */
+- **Architecture**: React Server Components with Vinxi
+- **Backend**: Fastify embedded in Vinxi (/api/* routes)
+- **Frontend**: React 19 + RSC + file-based routing
+/* @endif rsc */
+/* @if !rsc */
 - **Backend**: Fastify + VeloxTS procedures (apps/api)
 - **Frontend**: React + Vite + TanStack Router (apps/web)
+/* @endif !rsc */
 - **Database**: Prisma with SQLite
 - **Validation**: Zod schemas
 
 ## Architecture Rules
 
+/* @if rsc */
+### RSC Architecture (Single App)
+
+This project uses React Server Components with a unified structure:
+
+```
+app/
+├── pages/           # File-based routing (RSC pages)
+│   ├── index.tsx    # / (home)
+│   ├── users.tsx    # /users
+│   └── [id].tsx     # Dynamic routes
+├── layouts/         # Layout components
+│   └── root.tsx     # Root layout
+└── actions/         # Server actions
+    └── users.ts     # User actions with validated()
+
+src/
+├── api/             # API layer
+│   ├── handler.ts   # Fastify API handler
+│   ├── procedures/  # Procedure definitions
+│   └── schemas/     # Zod schemas
+└── entry.server.tsx # Server entry
+```
+
+### Server Actions
+
+Use `validated()` for secure server actions:
+
+```typescript
+// app/actions/users.ts
+'use server';
+import { validated, validatedMutation, validatedQuery } from '@veloxts/web/server';
+import { z } from 'zod';
+
+// Public query
+export const searchUsers = validatedQuery(
+  z.object({ query: z.string().optional() }),
+  async (input) => {
+    return db.user.findMany({ where: { name: { contains: input.query } } });
+  }
+);
+
+// Protected mutation
+export const updateUser = validatedMutation(
+  z.object({ id: z.string(), name: z.string() }),
+  async (input, ctx) => {
+    return db.user.update({ where: { id: input.id }, data: input });
+  }
+);
+```
+
+### File-Based Routing
+
+- `app/pages/index.tsx` → `/`
+- `app/pages/users.tsx` → `/users`
+- `app/pages/users/[id].tsx` → `/users/:id` (dynamic)
+- `app/pages/[...slug].tsx` → catch-all route
+- `app/pages/(group)/page.tsx` → route groups (no URL segment)
+/* @endif rsc */
+
+/* @if !rsc */
 ### Backend (apps/api)
 
 Procedures in `src/procedures/` define API endpoints. Naming conventions determine HTTP methods:
@@ -25,7 +93,17 @@ Procedures in `src/procedures/` define API endpoints. Naming conventions determi
 
 Schemas in `src/schemas/` use Zod for validation.
 
-Context available in procedures:
+### Frontend (apps/web)
+
+Routes in `src/routes/` use TanStack Router file-based routing.
+API calls use `@veloxts/client` hooks: `useQuery`, `useMutation`.
+Types flow from backend automatically - no codegen needed.
+/* @endif !rsc */
+
+### Context Object
+
+Available in all procedures via `ctx`:
+
 - `ctx.db` - Prisma client
 - `ctx.request` - Fastify request
 - `ctx.reply` - Fastify reply
@@ -33,12 +111,6 @@ Context available in procedures:
 - `ctx.user` - Authenticated user (if logged in)
 /* @endif auth */
 
-### Frontend (apps/web)
-
-Routes in `src/routes/` use TanStack Router file-based routing.
-API calls use `@veloxts/client` hooks: `useQuery`, `useMutation`.
-Types flow from backend automatically - no codegen needed.
-
 ## Code Style
 
 ### TypeScript Strictness
@@ -135,10 +207,19 @@ __RUN_CMD__ db:studio                # Open Prisma Studio
 
 ## File Naming Conventions
 
-- Procedures: `src/procedures/{entity}.ts` (plural, kebab-case for multi-word)
-- Schemas: `src/schemas/{entity}.ts` (singular, kebab-case)
-- Routes: `src/routes/{path}.tsx`
-- Components: `src/components/{Name}.tsx` (PascalCase)
+/* @if rsc */
+- Pages: `app/pages/{path}.tsx` (kebab-case)
+- Layouts: `app/layouts/{name}.tsx`
+- Actions: `app/actions/{entity}.ts`
+- Procedures: `src/api/procedures/{entity}.ts`
+- Schemas: `src/api/schemas/{entity}.ts`
+/* @endif rsc */
+/* @if !rsc */
+- Procedures: `apps/api/src/procedures/{entity}.ts` (plural, kebab-case)
+- Schemas: `apps/api/src/schemas/{entity}.ts` (singular, kebab-case)
+- Routes: `apps/web/src/routes/{path}.tsx`
+- Components: `apps/web/src/components/{Name}.tsx` (PascalCase)
+/* @endif !rsc */
 
 ## Import Conventions
 
@@ -150,7 +231,12 @@ import { authenticated, hasRole } from '@veloxts/auth';
 /* @endif auth */
 
 // Database client from config
+/* @if rsc */
+import { db } from '@/api/database';
+/* @endif rsc */
+/* @if !rsc */
 import { db } from '../config/database';
+/* @endif !rsc */
 
 // Local schemas
 import { UserSchema, CreateUserSchema } from '../schemas/user';
@@ -176,7 +262,21 @@ throw VeloxError.unauthorized('Login required');
 throw VeloxError.forbidden('Cannot access this resource');
 ```
 
-## JSON Output
+## AI-Powered Development
+
+### MCP Integration
+
+VeloxTS includes an MCP server for AI assistants:
+
+```bash
+# Start MCP server
+npx @veloxts/mcp
+
+# With debug logging
+npx @veloxts/mcp --debug
+```
+
+### JSON Output for AI
 
 All CLI commands support `--json` for AI tooling:
 
@@ -184,4 +284,18 @@ All CLI commands support `--json` for AI tooling:
 velox migrate status --json
 velox make resource Post --json --dry-run
 velox procedures list --json
+velox introspect --json
+```
+
+### Introspection
+
+```bash
+# Full project introspection
+velox introspect all --json
+
+# List all procedures
+velox procedures list --json
+
+# List all routes
+velox routes list
 ```

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

@@ -0,0 +1,328 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code and other AI assistants.
+
+## Project Overview
+
+**__PROJECT_NAME__** is a VeloxTS full-stack application using **tRPC-only** architecture:
+- **Backend**: Fastify + VeloxTS + tRPC (apps/api)
+- **Frontend**: React + Vite + TanStack Router (apps/web)
+- **Database**: Prisma with SQLite
+
+This template uses tRPC exclusively for type-safe internal communication. No REST adapter is included.
+
+## Commands
+
+```bash
+__RUN_CMD__ dev          # Start both API (__API_PORT__) and Web (__WEB_PORT__)
+__RUN_CMD__ build        # Build both apps
+__RUN_CMD__ db:push      # Push database schema
+__RUN_CMD__ db:studio    # Open Prisma Studio
+```
+
+## Architecture
+
+### Workspace Structure
+
+```
+apps/
+├── api/               # Backend (VeloxTS + Fastify + tRPC)
+│   ├── src/
+│   │   ├── procedures/  # tRPC procedures
+│   │   ├── schemas/     # Zod schemas
+│   │   ├── router.ts    # tRPC router setup
+│   │   └── config/      # App configuration
+│   └── prisma/
+│       └── schema.prisma
+│
+└── web/               # Frontend (React + Vite)
+    └── src/
+        ├── routes/      # TanStack Router pages
+        ├── api.ts       # tRPC client
+        └── styles/      # CSS modules
+```
+
+## Why tRPC-Only?
+
+| Feature | tRPC | REST |
+|---------|------|------|
+| Type Safety | Full inference | Manual types |
+| Network | Single `/trpc` endpoint | Multiple endpoints |
+| Best For | Internal frontend | Third-party integrations |
+| Overhead | Minimal | REST adapter layer |
+
+Choose tRPC-only when:
+- Your React frontend is the only API consumer
+- You want maximum type safety with zero overhead
+- You don't need REST for external integrations
+
+### API Development (apps/api)
+
+**Creating a tRPC procedure:**
+
+```typescript
+// apps/api/src/procedures/posts.ts
+import { procedure, procedures, z } from '@veloxts/velox';
+
+export const postProcedures = procedures('posts', {
+  // tRPC query
+  list: procedure()
+    .output(z.array(PostSchema))
+    .query(async ({ ctx }) => {
+      return ctx.db.post.findMany();
+    }),
+
+  // tRPC query with input
+  byId: procedure()
+    .input(z.object({ id: z.string().uuid() }))
+    .output(PostSchema)
+    .query(async ({ input, ctx }) => {
+      return ctx.db.post.findUnique({ where: { id: input.id } });
+    }),
+
+  // tRPC mutation
+  create: procedure()
+    .input(CreatePostSchema)
+    .output(PostSchema)
+    .mutation(async ({ input, ctx }) => {
+      return ctx.db.post.create({ data: input });
+    }),
+});
+```
+
+Then register in `src/router.ts`:
+
+```typescript
+import { createRouter } from '@veloxts/router';
+import { postProcedures } from './procedures/posts';
+
+export const appRouter = createRouter({
+  posts: postProcedures,
+});
+
+export type AppRouter = typeof appRouter;
+```
+
+## Prisma 7 Configuration
+
+This project uses Prisma 7 which has breaking changes:
+- Database URL is configured in `prisma.config.ts`, NOT in `schema.prisma`
+- NEVER add `url` property to the datasource block in `schema.prisma`
+
+### Frontend Development (apps/web)
+
+**Using tRPC client:**
+
+```typescript
+// apps/web/src/routes/posts.tsx
+import { useQuery, useMutation } from '@tanstack/react-query';
+import { api } from '../api';
+
+function PostsPage() {
+  // Full type safety - types flow from backend
+  const { data: posts, isLoading } = useQuery({
+    queryKey: ['posts'],
+    queryFn: () => api.posts.list.query(),
+  });
+
+  const createPost = useMutation({
+    mutationFn: (data) => api.posts.create.mutate(data),
+  });
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <ul>
+      {posts?.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Type Safety
+
+VeloxTS provides end-to-end type safety without code generation:
+
+1. **Define schemas** in `apps/api/src/schemas/`
+2. **Use in procedures** with `.input()` and `.output()`
+3. **Import AppRouter type** in frontend
+4. Types flow automatically through tRPC client
+
+## tRPC Endpoint
+
+All procedures are accessed via single tRPC endpoint:
+
+```
+POST /trpc/{namespace.procedure}
+```
+
+Examples:
+- `POST /trpc/posts.list` - List posts
+- `POST /trpc/posts.byId` - Get post by ID
+- `POST /trpc/health.check` - Health check
+
+## Migrating to REST (if needed later)
+
+If you need REST endpoints for external consumers, add the REST adapter:
+
+```typescript
+// apps/api/src/index.ts
+import { restAdapter } from '@veloxts/router';
+import { appRouter } from './router';
+
+// Add REST routes alongside tRPC
+app.register(restAdapter(appRouter, { prefix: '/api' }));
+```
+
+This auto-generates REST endpoints from procedure names:
+- `posts.list` → `GET /api/posts`
+- `posts.byId` → `GET /api/posts/:id`
+- `posts.create` → `POST /api/posts`
+
+## Database
+
+After schema changes:
+
+```bash
+__RUN_CMD__ db:push      # Apply changes
+__RUN_CMD__ db:generate  # Regenerate client
+```
+
+Access via context: `ctx.db.post.findMany()`
+
+## Code Generation
+
+### Available Generators
+
+| Generator | Alias | Description |
+|-----------|-------|-------------|
+| `procedure` | `p` | tRPC procedure with queries/mutations |
+| `schema` | `s` | Zod validation schema |
+| `model` | `m` | Prisma model definition |
+| `test` | `t` | Unit/integration test file |
+
+### Usage Examples
+
+```bash
+# Generate a procedure
+__RUN_CMD__ velox make procedure Posts
+
+# Generate a schema
+__RUN_CMD__ velox make schema Post
+
+# Preview without writing files
+__RUN_CMD__ velox make --dry-run procedure Posts
+
+# JSON output for scripting
+__RUN_CMD__ velox make procedure Posts --json
+```
+
+## Error Handling
+
+VeloxTS uses structured error codes for AI tooling:
+
+```typescript
+// Error format: VeloxError[E1001]: Message
+import { VeloxError } from '@veloxts/core';
+
+const getPost = procedure()
+  .input(z.object({ id: z.string().uuid() }))
+  .query(async ({ ctx, input }) => {
+    const post = await ctx.db.post.findUnique({ where: { id: input.id } });
+
+    if (!post) {
+      throw VeloxError.notFound('Post', input.id);
+    }
+
+    return post;
+  });
+```
+
+## Development Workflow
+
+### Hot Module Replacement (HMR)
+
+```bash
+# Default: HMR enabled
+__RUN_CMD__ velox dev
+
+# Disable HMR
+__RUN_CMD__ velox dev --no-hmr
+```
+
+### CLI JSON Output
+
+All CLI commands support `--json` for scripting:
+
+```bash
+velox procedures list --json
+velox introspect all --json
+```
+
+## AI-Powered Development with MCP
+
+VeloxTS includes a **Model Context Protocol (MCP) server** that gives AI assistants like Claude direct access to your project structure. This enables intelligent code assistance with full awareness of your procedures, schemas, and types.
+
+### What You Get
+
+- **Resources**: Real-time project introspection (procedures, schemas)
+- **Tools**: Code generation and database migration commands
+- **Prompts**: Best practice templates for tRPC procedures
+
+### Setup for Claude Code (CLI)
+
+The MCP server auto-discovers VeloxTS projects:
+
+```bash
+# Start the MCP server
+npx @veloxts/mcp
+
+# Or with debug logging
+npx @veloxts/mcp --debug
+```
+
+### Setup for Claude Desktop
+
+Add this to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "veloxts": {
+      "command": "npx",
+      "args": ["@veloxts/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after adding the configuration.
+
+### What Claude Can Do With MCP
+
+| Capability | Description |
+|------------|-------------|
+| Generate Code | Create procedures, schemas, models |
+| Run Migrations | Check status, run, rollback, fresh, reset |
+| Access Context | List procedures, schemas, types |
+
+### Example Prompts
+
+1. **"Generate a CRUD procedure set for BlogPost"**
+2. **"Show me all my tRPC procedures and their input/output types"**
+3. **"Add pagination to the posts.list procedure"**
+4. **"Create a schema for Comment with validation"**
+
+### Available MCP Resources
+
+| Resource | Description |
+|----------|-------------|
+| `velox://procedures` | All procedures with types |
+| `velox://schemas` | Zod validation schemas |
+| `velox://errors` | Error catalog with fix suggestions |
+| `velox://project` | Project metadata and file paths |

package/src/templates/source/rsc/app.config.ts

@@ -5,8 +5,8 @@
  * All options have sensible defaults - only specify what you need to change.
  */
 
-import { defineVeloxApp } from '@veloxts/web';
+import { createVeloxApp } from '@veloxts/web';
 
-export default defineVeloxApp({
+export default createVeloxApp({
   port: __API_PORT__,
 });

package/src/templates/source/rsc-auth/app.config.ts

@@ -5,8 +5,8 @@
  * All options have sensible defaults - only specify what you need to change.
  */
 
-import { defineVeloxApp } from '@veloxts/web';
+import { createVeloxApp } from '@veloxts/web';
 
-export default defineVeloxApp({
+export default createVeloxApp({
   port: __API_PORT__,
 });