create-velox-app 0.6.73 → 0.6.75

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # create-velox-app
 
+## 0.6.75
+
+### Patch Changes
+
+- feat(create): add --pm flag to skip package manager prompt
+
+## 0.6.74
+
+### Patch Changes
+
+- docs: fix erroneous file paths and improve auth context documentation
+
 ## 0.6.73
 
 ### Patch Changes

package/dist/cli.d.ts

@@ -6,11 +6,14 @@
  * Handles command-line arguments and initiates the scaffolding process.
  */
 import type { DatabaseType, TemplateType } from './templates/index.js';
+/** Valid package manager types */
+export type PackageManagerType = 'npm' | 'pnpm' | 'yarn';
 /** @internal Exported for testing */
 export interface ParsedArgs {
     projectName?: string;
     template?: TemplateType;
     database?: DatabaseType;
+    packageManager?: PackageManagerType;
     help: boolean;
     version: boolean;
 }

package/dist/cli.js

@@ -39,6 +39,8 @@ Options:
                          Available: ${getTemplateNames()}
   -d, --database <name>  Database to use (default: "sqlite")
                          Available: ${getDatabaseNames()}
+  --pm <manager>         Package manager to use (npm, pnpm, yarn)
+                         Skips interactive prompt if specified
   -h, --help             Show this help message
   -v, --version          Show version number
 
@@ -60,8 +62,11 @@ Examples:
   npx create-velox-app my-app --auth                 # Auth template (shortcut)
   npx create-velox-app my-app --rsc -d postgresql    # RSC with PostgreSQL
   npx create-velox-app my-app --template=spa         # SPA + API template
+  npx create-velox-app my-app --pm npm               # Non-interactive (npm)
   npx create-velox-app                               # Prompt for all options
 `;
+/** Valid package managers */
+const VALID_PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn']);
 /** Template shorthand flags (--auth, --spa, etc.) */
 const TEMPLATE_FLAGS = new Set([
     '--spa',
@@ -207,6 +212,39 @@ export function parseArgs(args) {
             }
             continue;
         }
+        // Handle --pm=<value>
+        if (arg.startsWith('--pm=')) {
+            const value = arg.split('=')[1];
+            if (!value) {
+                console.error('Error: --pm requires a value. Available: npm, pnpm, yarn');
+                process.exit(1);
+            }
+            if (VALID_PACKAGE_MANAGERS.has(value)) {
+                result.packageManager = value;
+            }
+            else {
+                console.error(`Invalid package manager: ${value}. Available: npm, pnpm, yarn`);
+                process.exit(1);
+            }
+            continue;
+        }
+        // Handle --pm <value>
+        if (arg === '--pm') {
+            const value = args[i + 1];
+            if (!value || value.startsWith('-')) {
+                console.error('Error: --pm requires a value. Available: npm, pnpm, yarn');
+                process.exit(1);
+            }
+            if (VALID_PACKAGE_MANAGERS.has(value)) {
+                result.packageManager = value;
+                i++; // Skip next arg
+            }
+            else {
+                console.error(`Invalid package manager: ${value}. Available: npm, pnpm, yarn`);
+                process.exit(1);
+            }
+            continue;
+        }
         // Non-flag argument
         if (!arg.startsWith('-')) {
             if (!result.projectName) {
@@ -245,7 +283,7 @@ async function main() {
             process.exit(0);
         }
         // Run scaffolder
-        await createVeloxApp(parsed.projectName, parsed.template, parsed.database);
+        await createVeloxApp(parsed.projectName, parsed.template, parsed.database, parsed.packageManager);
     }
     catch (error) {
         // Handle unexpected errors with actionable guidance

package/dist/index.d.ts

@@ -19,7 +19,7 @@ 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>;
+export declare function createVeloxApp(initialProjectName?: string, initialTemplate?: TemplateType, initialDatabase?: DatabaseType, initialPackageManager?: 'npm' | 'pnpm' | 'yarn'): Promise<void>;
 /**
  * Detect which package manager is being used
  * @internal Exported for testing

package/dist/index.js

@@ -59,7 +59,7 @@ export function isPathSafe(baseDir, targetPath) {
 /**
  * Main scaffolding function that creates a new VeloxTS project
  */
-export async function createVeloxApp(initialProjectName, initialTemplate, initialDatabase) {
+export async function createVeloxApp(initialProjectName, initialTemplate, initialDatabase, initialPackageManager) {
     // Print welcome banner
     console.log('');
     p.intro(pc.cyan(pc.bold('create-velox-app')));
@@ -67,7 +67,7 @@ export async function createVeloxApp(initialProjectName, initialTemplate, initia
     let projectCreated = false;
     try {
         // Collect project configuration
-        const config = await promptProjectConfig(initialProjectName, initialTemplate, initialDatabase);
+        const config = await promptProjectConfig(initialProjectName, initialTemplate, initialDatabase, initialPackageManager);
         projectDirectory = config.directory;
         // Show configuration summary
         p.log.info(pc.dim('Configuration:'));
@@ -127,7 +127,7 @@ export async function createVeloxApp(initialProjectName, initialTemplate, initia
 /**
  * Prompt user for project configuration
  */
-async function promptProjectConfig(initialName, initialTemplate, initialDatabase) {
+async function promptProjectConfig(initialName, initialTemplate, initialDatabase, initialPackageManager) {
     // Project name
     const name = initialName
         ? initialName
@@ -199,10 +199,11 @@ async function promptProjectConfig(initialName, initialTemplate, initialDatabase
             throw new Error(`Database "${database}" is not yet available. Please choose SQLite for now.`);
         }
     }
-    // Package manager selection (prompt unless running in CI/non-interactive mode)
-    let packageManager = detectPackageManager();
+    // Package manager selection (prompt unless provided via CLI or running in CI/non-interactive mode)
+    let packageManager = initialPackageManager ?? detectPackageManager();
+    // Only show package manager prompt if not provided via CLI
     // SKIP_INSTALL is set in smoke tests to skip interactive prompts
-    if (process.env.SKIP_INSTALL !== 'true') {
+    if (!initialPackageManager && process.env.SKIP_INSTALL !== 'true') {
         const selectedPackageManager = await p.select({
             message: 'Choose a package manager',
             initialValue: packageManager,

package/package.json

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

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

@@ -99,3 +99,38 @@ export const jwt = jwtManager({
   issuer: 'velox-app',
   audience: 'velox-app-client',
 });
+
+// ============================================================================
+// Full User Helper
+// ============================================================================
+
+/**
+ * Fetch full user from database when ctx.user doesn't have all fields.
+ *
+ * `ctx.user` only contains fields returned by `userLoader` (id, email, name, roles).
+ * Use this helper when you need additional fields like `organizationId`.
+ *
+ * @example
+ * ```typescript
+ * // In a procedure that needs full user data:
+ * .query(async ({ ctx }) => {
+ *   // ctx.user has: id, email, name, roles
+ *   // For additional fields, fetch full user:
+ *   const fullUser = await getFullUser(ctx);
+ *   return { organizationId: fullUser.organizationId };
+ * })
+ * ```
+ *
+ * @param ctx - The procedure context (must have user.id and db)
+ * @returns The full user record from database
+ * @throws If user is not found (should not happen for authenticated requests)
+ */
+export async function getFullUser<
+  TDb extends {
+    user: { findUniqueOrThrow: (args: { where: { id: string } }) => Promise<unknown> };
+  },
+>(ctx: { user: { id: string }; db: TDb }) {
+  return ctx.db.user.findUniqueOrThrow({
+    where: { id: ctx.user.id },
+  });
+}

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

@@ -76,18 +76,24 @@ getUser: procedure().input(z.object({ id: z.string() }))
 
 **Cause**: Procedure not registered in router.
 
-**Fix**:
-1. Check `src/procedures/index.ts` exports your procedure
-2. Check `src/index.ts` includes it in collections array
+**Fix**: Add procedure to `createRouter()` in `src/router.ts`:
 
 ```typescript
-// src/procedures/index.ts
-export * from './users.js';
-export * from './posts.js';  // Add this
+// src/router.ts
+import { createRouter, extractRoutes } from '@veloxts/velox';
+
+import { healthProcedures } from './procedures/health.js';
+import { userProcedures } from './procedures/users.js';
+import { postProcedures } from './procedures/posts.js';  // Add import
+
+export const { collections, router } = createRouter(
+  healthProcedures,
+  userProcedures,
+  postProcedures  // Add here
+);
 
-// src/index.ts
-import { userProcedures, postProcedures } from './procedures/index.js';
-const collections = [userProcedures, postProcedures];  // Add here
+export type AppRouter = typeof router;
+export const routes = extractRoutes(collections);
 ```
 
 ### "Input validation failed"

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

@@ -67,7 +67,19 @@ export const postProcedures = procedures('posts', {
 });
 ```
 
-Then register in `src/procedures/index.ts` and add to collections in `src/index.ts`.
+Then register in `src/router.ts` by importing and adding to `createRouter()`:
+
+```typescript
+// src/router.ts
+import { postProcedures } from './procedures/posts.js';
+
+export const { collections, router } = createRouter(
+  healthProcedures,
+  authProcedures,
+  userProcedures,
+  postProcedures  // Add here
+);
+```
 
 ## Prisma 7 Configuration
 
@@ -229,19 +241,41 @@ createdAt: z.coerce.date()
 updatedAt: z.coerce.date()
 ```
 
-### Extending User Context
+### Authentication Context (`ctx.user`)
 
-The `ctx.user` object is populated by `userLoader` in `src/config/auth.ts`.
+**Important:** `ctx.user` is NOT the raw database user - it only contains fields explicitly returned by `userLoader` in `src/config/auth.ts`.
 
-To add fields to `ctx.user` (e.g., `organizationId`):
+#### How ctx.user Gets Populated
 
-1. Update `userLoader`:
+1. JWT token is validated from cookie/header
+2. User ID is extracted from token payload
+3. `userLoader(userId)` is called to fetch user data
+4. Only the fields returned by `userLoader` are available on `ctx.user`
+
+#### Default Fields
+
+The default `userLoader` returns:
+```typescript
+{
+  id: string;
+  email: string;
+  name: string;
+  roles: string[];
+}
+```
+
+#### Adding Fields to ctx.user
+
+To add a field like `organizationId`:
+
+1. Update `userLoader` in `src/config/auth.ts`:
 ```typescript
 async function userLoader(userId: string) {
   const user = await db.user.findUnique({ where: { id: userId } });
   return {
     id: user.id,
     email: user.email,
+    name: user.name,
     roles: parseUserRoles(user.roles),
     organizationId: user.organizationId, // Add new fields here
   };
@@ -250,15 +284,36 @@ async function userLoader(userId: string) {
 
 2. Update related schemas (`UserSchema`, `UpdateUserInput`, etc.).
 
+#### Common Mistake
+
+```typescript
+// ❌ WRONG - organizationId is undefined (not in userLoader)
+const orgId = ctx.user.organizationId;
+
+// ✅ CORRECT - After adding to userLoader in src/config/auth.ts
+const orgId = ctx.user.organizationId;
+
+// ✅ ALTERNATIVE - Use getFullUser helper when you need extra fields
+import { getFullUser } from '@/utils/auth';
+const fullUser = await getFullUser(ctx);
+const orgId = fullUser.organizationId;
+```
+
 ### Role Configuration
 
-Roles are stored as a JSON string array in the database (e.g., `["ADMIN"]`).
+Roles are stored as a JSON string array in the database (e.g., `["user"]`, `["admin"]`).
+
+The `parseUserRoles()` function from `@veloxts/auth` safely parses the JSON string:
+```typescript
+// Imported and used in src/config/auth.ts
+import { parseUserRoles } from '@veloxts/auth';
+roles: parseUserRoles(user.roles),  // Converts '["user"]' to ['user']
+```
 
-When changing roles, update ALL locations:
-- `prisma/schema.prisma` - Role enum
-- `src/config/auth.ts` - `ALLOWED_ROLES` and `parseUserRoles`
-- `src/utils/auth.ts` - `ALLOWED_ROLES` (if duplicated)
-- `src/schemas/auth.ts` - Role validation schemas
+When adding new roles, update:
+- `prisma/schema.prisma` - Default value in the roles field
+- `src/schemas/auth.ts` - Role validation schemas (if using enum validation)
+- Any guards that check for specific roles (e.g., `hasRole('admin')`)
 
 ### MCP Project Path
 

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

@@ -66,7 +66,18 @@ export const postProcedures = procedures('posts', {
 });
 ```
 
-Then register in `src/procedures/index.ts` and add to collections in `src/index.ts`.
+Then register in `src/router.ts` by importing and adding to `createRouter()`:
+
+```typescript
+// src/router.ts
+import { postProcedures } from './procedures/posts.js';
+
+export const { collections, router } = createRouter(
+  healthProcedures,
+  userProcedures,
+  postProcedures  // Add here
+);
+```
 
 ## Prisma 7 Configuration
 

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

@@ -122,6 +122,44 @@ await logout();  // Clears cookies server-side
 - At least one number
 - Not a common password
 
+### Authentication Context (`ctx.user`)
+
+**Important:** `ctx.user` is NOT the raw database user - it only contains fields explicitly returned by `userLoader` in `src/api/handler.ts`.
+
+#### How ctx.user Gets Populated
+
+1. JWT token is validated from cookie/header
+2. User ID is extracted from token payload
+3. `userLoader(userId)` is called to fetch user data
+4. Only the fields returned by `userLoader` are available on `ctx.user`
+
+#### Default Fields
+
+The default `userLoader` returns:
+```typescript
+{
+  id: string;
+  email: string;
+  name: string;
+  roles: string[];
+}
+```
+
+#### Common Mistake
+
+```typescript
+// ❌ WRONG - organizationId is undefined (not in userLoader)
+const orgId = ctx.user.organizationId;
+
+// ✅ CORRECT - After adding to userLoader in src/api/handler.ts
+const orgId = ctx.user.organizationId;
+
+// ✅ ALTERNATIVE - Use getFullUser helper when you need extra fields
+import { getFullUser } from '@/api/utils/auth';
+const fullUser = await getFullUser(ctx);
+const orgId = fullUser.organizationId;
+```
+
 ## Server Actions with validated()
 
 Use the `validated()` helper for secure server actions:
@@ -302,33 +340,41 @@ updatedAt: z.coerce.date()
 
 ### Extending User Context
 
-The `ctx.user` object is populated by `userLoader` in `src/api/utils/auth.ts`.
+The `ctx.user` object is populated by `userLoader` in `src/api/handler.ts` (inline in `createAuthConfig()`).
 
 To add fields to `ctx.user` (e.g., `organizationId`):
 
-1. Update `userLoader`:
+1. Update `userLoader` in `src/api/handler.ts`:
 ```typescript
-async function userLoader(userId: string) {
+userLoader: async (userId: string) => {
   const user = await db.user.findUnique({ where: { id: userId } });
   return {
     id: user.id,
     email: user.email,
+    name: user.name,
     roles: parseUserRoles(user.roles),
     organizationId: user.organizationId, // Add new fields here
   };
-}
+},
 ```
 
 2. Update related schemas (`UserSchema`, `UpdateUserInput`, etc.).
 
 ### Role Configuration
 
-Roles are stored as a JSON string array in the database (e.g., `["ADMIN"]`).
+Roles are stored as a JSON string array in the database (e.g., `["user"]`, `["admin"]`).
+
+The `parseUserRoles()` function from `@veloxts/auth` safely parses the JSON string:
+```typescript
+// Imported and used in src/api/handler.ts
+import { parseUserRoles } from '@veloxts/auth';
+roles: parseUserRoles(user.roles),  // Converts '["user"]' to ['user']
+```
 
-When changing roles, update ALL locations:
-- `prisma/schema.prisma` - Role enum
-- `src/api/utils/auth.ts` - `ALLOWED_ROLES` and `parseUserRoles`
-- `src/api/schemas/auth.ts` - Role validation schemas
+When adding new roles, update:
+- `prisma/schema.prisma` - Default value in the roles field
+- `src/api/schemas/auth.ts` - Role validation schemas (if using enum validation)
+- Any guards or server actions that check for specific roles
 
 ### MCP Project Path
 

package/src/templates/source/rsc-auth/src/api/utils/auth.ts

@@ -99,3 +99,38 @@ export const jwt = jwtManager({
   issuer: 'velox-app',
   audience: 'velox-app-client',
 });
+
+// ============================================================================
+// Full User Helper
+// ============================================================================
+
+/**
+ * Fetch full user from database when ctx.user doesn't have all fields.
+ *
+ * `ctx.user` only contains fields returned by `userLoader` (id, email, name, roles).
+ * Use this helper when you need additional fields like `organizationId`.
+ *
+ * @example
+ * ```typescript
+ * // In a procedure that needs full user data:
+ * .query(async ({ ctx }) => {
+ *   // ctx.user has: id, email, name, roles
+ *   // For additional fields, fetch full user:
+ *   const fullUser = await getFullUser(ctx);
+ *   return { organizationId: fullUser.organizationId };
+ * })
+ * ```
+ *
+ * @param ctx - The procedure context (must have user.id and db)
+ * @returns The full user record from database
+ * @throws If user is not found (should not happen for authenticated requests)
+ */
+export async function getFullUser<
+  TDb extends {
+    user: { findUniqueOrThrow: (args: { where: { id: string } }) => Promise<unknown> };
+  },
+>(ctx: { user: { id: string }; db: TDb }) {
+  return ctx.db.user.findUniqueOrThrow({
+    where: { id: ctx.user.id },
+  });
+}