create-questpie 2.0.2 → 2.0.4

package/skills/questpie/references/auth.md

@@ -8,8 +8,7 @@ Auth is configured via `config/auth.ts` using the `authConfig()` factory:
 
 ```ts
 // src/questpie/server/config/auth.ts
-import { authConfig } from "questpie";
-
+import { authConfig } from "questpie/app";
 export default authConfig({
 	emailAndPassword: {
 		enabled: true,
@@ -38,7 +37,7 @@ Codegen discovers this file automatically. No manual registration needed.
 ### In Routes
 
 ```ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -95,16 +94,132 @@ export default route()
 
 ## User Collection
 
-The `adminModule` provides a built-in `user` collection. It stores:
+The `adminModule` includes the starter auth model and provides the canonical Better Auth `user` collection. It stores:
 
 - `id` -- unique identifier
 - `email` -- email address
 - `name` -- display name
 - `image` -- avatar URL
 - `emailVerified` -- verification status
+- `role` -- admin access role (`admin` or `user`)
+- `avatar`, `banned`, `banReason`, `banExpires` -- admin-managed profile and access fields
 
 This collection is automatically created when you add the admin module to your config.
 
+Critical: the built-in admin setup route and admin `AuthGuard` depend on `user.role`. Setup checks whether any user has `role = "admin"`, and the admin UI expects `session.user.role === "admin"`. Do not replace `collection("user")` from scratch in an app that uses `adminModule`; merge `starterModule.collections.user` and extend it if custom user fields or admin layout are needed.
+
+```ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		internalNotes: f.textarea(),
+	}));
+```
+
+`.fields()` is cumulative -- it adds to the merged starter fields and overrides them by key, never wipes them, so this recipe keeps the full starter user model.
+
+### Anonymous Users (Better Auth plugin)
+
+Better Auth plugins that extend the user model follow the same recipe. For the anonymous plugin, register it in `auth.ts` (merged after the built-in plugins) and extend the starter user with the `isAnonymous` field the plugin expects:
+
+```ts
+// auth.ts
+import { anonymous } from "better-auth/plugins";
+import type { AuthConfig } from "questpie/app";
+
+export default {
+	plugins: [anonymous()],
+} satisfies AuthConfig;
+```
+
+```ts
+// collections/user.ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		isAnonymous: f.boolean().default(false),
+	}));
+```
+
+Run `questpie generate` and apply migrations to add the column. Anonymous sign-in (`authClient.signIn.anonymous()` on the client) creates throwaway users that Better Auth can later link to real accounts.
+
+## Reaching the App from Better Auth Callbacks
+
+The `/auth/*` catch-all is a plain **raw route**, and raw routes execute their handler inside `runWithContext()` (the request's AsyncLocalStorage scope). That means every Better Auth callback — `onLinkAccount`, `databaseHooks`, `sendMagicLink`, plugin hooks — already runs inside the request scope, and `getContext<App>()` returns the live app, session, db, and locale.
+
+**Never build a module-level app singleton or a hand-rolled context bridge for auth callbacks.** The `App` import stays type-only, so there is no circular import:
+
+```ts
+// config/auth.ts
+import { anonymous } from "better-auth/plugins";
+import { getContext } from "questpie";
+import { authConfig } from "questpie/app";
+import type { App } from "#questpie"; // type-only — no runtime cycle
+
+export default authConfig({
+	plugins: [
+		anonymous({
+			// Fires when an anonymous user signs in with a real account —
+			// re-point the guest's rows onto the new user before the plugin
+			// deletes the anonymous user.
+			onLinkAccount: async ({ anonymousUser, newUser }) => {
+				const { app } = getContext<App>();
+				// Bare { accessMode: "system" } elevates ONLY the mode —
+				// session, db, and locale inherit from the request scope (ALS).
+				await app.collections.memberships.updateMany(
+					{
+						where: { user: anonymousUser.user.id },
+						data: { user: newUser.user.id },
+					},
+					{ accessMode: "system" },
+				);
+			},
+		}),
+	],
+});
+```
+
+### Partial Context Overrides
+
+CRUD context normalization merges what you pass with the ambient request scope — priority: explicit param → ALS scope → defaults (`accessMode: "system"`, `locale: "en"`). Passing only `{ accessMode: "system" }` elevates the mode while the request's session/db/locale ride along. The inverse also holds: `{ accessMode: "user" }` inside system-scoped code re-enables access rules against the inherited session without re-threading it:
+
+```ts
+// Inside any handler — session comes from the request ALS scope
+await app.collections.posts.find({}, { accessMode: "user" }); // rules enforced for the current user
+await app.collections.posts.find({}, { accessMode: "system" }); // rules bypassed, same session/locale
+```
+
+## Client-Side Auth (authClient)
+
+For session state and sign-in/out on the frontend, create a typed Better Auth client. In admin-equipped apps use the typed wrapper (session includes your merged user fields):
+
+```ts
+// src/lib/auth-client.ts
+import { createAdminAuthClient } from "@questpie/admin/client";
+import type { AppConfig } from "#questpie";
+import { env } from "#questpie/env.client.vite"; // generated from env.client.ts
+
+export const authClient = createAdminAuthClient<AppConfig>({
+	baseURL: typeof window !== "undefined" ? window.location.origin : env.APP_URL,
+	basePath: "/api/auth",
+});
+```
+
+```tsx
+const { data: session, isPending } = authClient.useSession();
+await authClient.signIn.email({ email, password });
+await authClient.signIn.anonymous(); // with the anonymous plugin
+await authClient.signOut();
+```
+
+Apps without `@questpie/admin` use Better Auth's own `createAuthClient` from `better-auth/react` pointed at `${APP_URL}/api/auth` — same call surface, without the app-inferred session typing.
+
 ## Environment Variables
 
 | Variable             | Required   | Description                                               |

package/skills/questpie/references/business-logic.md

@@ -1,6 +1,7 @@
 ---
 name: questpie-core-business-logic
-description: QUESTPIE routes jobs services emails route job service email background queue scheduling Zod input validation server-side logic reusable services email templates
+description:
+  QUESTPIE routes jobs services emails route job service email background queue scheduling Zod input validation server-side logic reusable services email templates
   - questpie-core
 ---
 
@@ -16,7 +17,7 @@ JSON routes are typed server-side endpoints. Define an input schema with Zod, wr
 
 ```ts
 // routes/get-active-barbers.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -37,7 +38,7 @@ JSON routes validate input with Zod automatically:
 
 ```ts
 // routes/create-booking.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -77,15 +78,18 @@ export default route()
 
 Route handlers receive the full `AppContext`:
 
-| Property      | Description                            |
-| ------------- | -------------------------------------- |
-| `input`       | Validated data matching the Zod schema |
-| `collections` | Typed collection API                   |
-| `queue`       | Publish background jobs                |
-| `email`       | Send emails                            |
-| `db`          | Raw database access                    |
-| `session`     | Current auth session                   |
-| `services`    | Custom services from `services/`       |
+| Property      | Description                                                |
+| ------------- | ---------------------------------------------------------- |
+| `input`       | Validated data matching the Zod schema                     |
+| `collections` | Typed collection API                                       |
+| `queue`       | Publish background jobs                                    |
+| `email`       | Send emails                                                |
+| `db`          | Raw database access                                        |
+| `session`     | Current auth session                                       |
+| `services`    | Custom services from `services/`                           |
+| _extensions_  | `appConfig({ context })` result, flat (e.g. `workspaceId`) |
+
+Derived request context (from `appConfig({ context })`) reaches route access rules and handlers alike — destructure the keys directly. Inside any nested code, `getContext<App>()` exposes the same keys (see `references/multi-tenancy.md`).
 
 ### Calling Routes
 
@@ -125,7 +129,7 @@ Jobs are background tasks that run outside the request lifecycle. Ideal for send
 
 ```ts
 // jobs/send-appointment-confirmation.ts
-import { job } from "questpie";
+import { job } from "questpie/services";
 import z from "zod";
 
 export default job({
@@ -182,6 +186,31 @@ Publish from hooks, routes, or other jobs via the typed `queue` context:
 
 The `queue` object provides full autocompletion for all jobs and their payloads.
 
+### Recurring Jobs (Cron)
+
+Jobs accept a job-level cron expression in `options.cron`. Schedules are registered automatically when the queue worker starts (`app.queue.listen()` calls `registerSchedules()`):
+
+```ts
+// jobs/cleanup-expired.ts
+import { job } from "questpie/services";
+import z from "zod";
+
+export default job({
+	name: "cleanupExpired",
+	schema: z.object({}),
+	options: { cron: "0 3 * * *" }, // every day at 03:00
+	handler: async ({ collections }) => {
+		await collections.sessions.deleteMany({
+			where: { expiresAt: { lt: new Date() } },
+		});
+	},
+});
+```
+
+Programmatic scheduling from any handler: `queue.cleanupExpired.schedule({}, "0 3 * * *")` and `queue.cleanupExpired.unschedule()`.
+
+Use job-level cron for simple recurring tasks (cleanup, digests, syncs). Reach for **workflow-level cron** (`references/workflows.md`) only when the recurring process needs steps, durable waits, or replay — a workflow is the heavier primitive.
+
 ### Job Handler Context
 
 | Property      | Description                            |
@@ -198,7 +227,8 @@ Configure the queue adapter in your runtime config:
 
 ```ts
 // questpie.config.ts
-import { pgBossAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgBossAdapter } from "questpie/adapters/pg-boss";
 
 export default runtimeConfig({
 	queue: {
@@ -209,26 +239,28 @@ export default runtimeConfig({
 });
 ```
 
-## Routes
+## Raw Routes
 
-Routes give raw HTTP request/response handling for webhooks, OAuth callbacks, health checks, file downloads, and streaming.
+Raw routes (`route().raw()`) give raw HTTP request/response handling for webhooks, OAuth callbacks, health checks, file downloads, and streaming. The handler receives the standard `Request` and must return a `Response`.
 
-### Defining a Route
+### Defining a Raw Route
 
 ```ts
 // routes/health.ts
-import { route } from "questpie";
+import { sql } from "questpie/drizzle";
+import { route } from "questpie/services";
 
-export default route({
-	method: "GET",
-	handler: async ({ db }) => {
+export default route()
+	.get()
+	.raw()
+	.access(true)
+	.handler(async ({ db }) => {
 		const healthy = await db
 			.execute(sql`SELECT 1`)
 			.then(() => true)
 			.catch(() => false);
 		return Response.json({ status: healthy ? "ok" : "degraded" });
-	},
-});
+	});
 ```
 
 Place files in `routes/`. The file path maps to a flat URL under your `basePath` (`/api` by default):
@@ -243,27 +275,29 @@ routes/
 
 ### Route Methods
 
+Chain HTTP method calls on the builder (multiple methods = multiple calls):
+
 ```ts
-route({ method: "POST", handler: ... })           // Single method
-route({ method: ["GET", "POST"], handler: ... })   // Multiple methods
-route({ handler: ... })                            // All methods (default)
+route().post().raw().handler(...)          // POST only
+route().get().post().raw().handler(...)    // GET + POST
 ```
 
-Supported: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
+Supported: `.get()`, `.post()`, `.put()`, `.delete()`, `.patch()`. The built-in `/auth/*` catch-all is itself a raw route (`route().get().post().raw()` delegating to Better Auth) — raw handlers run inside `runWithContext`, so the full request context is live in any code they call.
 
 ### Route Handler Context
 
-| Property      | Type                     | Description              |
-| ------------- | ------------------------ | ------------------------ |
-| `request`     | `Request`                | Standard Web API Request |
-| `params`      | `Record<string, string>` | URL path parameters      |
-| `locale`      | `string`                 | Current locale           |
-| `db`          | `Database`               | Database instance        |
-| `session`     | `Session \| null`        | Current auth session     |
-| `collections` | `CollectionsAPI`         | Typed collection API     |
-| `queue`       | `QueueClient`            | Queue client             |
-| `email`       | `MailerService`          | Email service            |
-| `services`    |                          | User-defined services    |
+| Property      | Type                     | Description                                  |
+| ------------- | ------------------------ | -------------------------------------------- |
+| `request`     | `Request`                | Standard Web API Request                     |
+| `params`      | `Record<string, string>` | URL path parameters                          |
+| `locale`      | `string`                 | Current locale                               |
+| `db`          | `Database`               | Database instance                            |
+| `session`     | `Session \| null`        | Current auth session                         |
+| `collections` | `CollectionsAPI`         | Typed collection API                         |
+| `queue`       | `QueueClient`            | Queue client                                 |
+| `email`       | `MailerService`          | Email service                                |
+| `services`    |                          | User-defined services                        |
+| _extensions_  |                          | `appConfig({ context })` result, flat        |
 
 Route handlers must return a `Response` object.
 
@@ -279,27 +313,66 @@ Route handlers must return a `Response` object.
 
 **Rule of thumb**: Use JSON routes for typed input/output with automatic validation. Use raw routes for HTTP-level control (custom headers, binary data, streams, signature verification).
 
-### Webhook Example
+### Webhook Example (Signature Verification)
+
+Webhooks need the raw body for signature verification — exactly what `.raw()` is for:
 
 ```ts
 // routes/webhooks/stripe.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 
-export default route({
-	method: "POST",
-	handler: async ({ request, db }) => {
+export default route()
+	.post()
+	.raw()
+	.access(true) // signature IS the auth — verify it yourself below
+	.handler(async ({ request, collections, queue }) => {
 		const body = await request.text();
 		const signature = request.headers.get("stripe-signature");
-		const event = verifyStripeWebhook(body, signature);
+		const event = verifyStripeWebhook(body, signature); // throws on bad signature
+		if (!event) return new Response("Invalid signature", { status: 401 });
 
-		await db.insert(webhookEvents).values({
+		await collections.webhook_events.create({
 			type: event.type,
 			payload: body,
 		});
+		await queue.processStripeEvent.publish({ eventId: event.id });
 
 		return new Response("OK", { status: 200 });
-	},
-});
+	});
+```
+
+### Streamed Response Example
+
+Raw routes can return any `Response`, including streams — CSV exports, server-sent progress, large file proxies:
+
+```ts
+// routes/export.ts
+import { route } from "questpie/services";
+
+export default route()
+	.get()
+	.raw()
+	.access(({ session }) => !!session)
+	.handler(async ({ collections }) => {
+		const { docs } = await collections.orders.find({ limit: 10_000 });
+
+		const stream = new ReadableStream({
+			start(controller) {
+				controller.enqueue("id,total,createdAt\n");
+				for (const order of docs) {
+					controller.enqueue(`${order.id},${order.total},${order.createdAt.toISOString()}\n`);
+				}
+				controller.close();
+			},
+		});
+
+		return new Response(stream, {
+			headers: {
+				"Content-Type": "text/csv; charset=utf-8",
+				"Content-Disposition": 'attachment; filename="orders.csv"',
+			},
+		});
+	});
 ```
 
 ## Services
@@ -310,8 +383,7 @@ Services are reusable units of logic injected into `AppContext` under the `servi
 
 ```ts
 // services/blog.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 const WORDS_PER_MINUTE = 200;
 
 function stripHtml(html: string): string {
@@ -372,7 +444,7 @@ Services are available via `services` destructuring in any handler:
 
 ```ts
 // services/stripe.ts
-import { service } from "questpie";
+import { service } from "questpie/services";
 import Stripe from "stripe";
 
 export default service({
@@ -385,8 +457,7 @@ export default service({
 
 ```ts
 // services/tenant-db.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export default service({
 	lifecycle: "request",
 	deps: ["db", "session"] as const,
@@ -403,8 +474,7 @@ Services can depend on other services and infrastructure via `deps`. Use `as con
 
 ```ts
 // services/analytics.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export default service({
 	deps: ["db", "logger"] as const,
 	create: ({ db, logger }) => {
@@ -449,7 +519,7 @@ Email templates are defined in `emails/` and discovered by codegen. Each templat
 
 ```ts
 // emails/appointment-confirmation.ts
-import { email } from "questpie";
+import { email } from "questpie/services";
 import { z } from "zod";
 
 export default email({
@@ -500,7 +570,7 @@ Email handlers receive the full `AppContext` for fetching data:
 
 ```ts
 // emails/weekly-digest.ts
-import { email } from "questpie";
+import { email } from "questpie/services";
 import { z } from "zod";
 
 export default email({