create-velox-app 0.6.73 → 0.6.74

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # create-velox-app
 
+## 0.6.74
+
+### Patch Changes
+
+- docs: fix erroneous file paths and improve auth context documentation
+
 ## 0.6.73
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-velox-app",
-  "version": "0.6.73",
+  "version": "0.6.74",
   "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 },
+  });
+}