create-questpie 2.0.2 → 2.0.4

package/skills/questpie/references/production.md

@@ -1,7 +1,7 @@
 ---
 name: questpie-core/production
 description:
-  QUESTPIE production deployment authentication better-auth OAuth database PostgreSQL Drizzle storage S3 Flydrive queue pg-boss jobs realtime SSE pgNotify Redis migrations email SMTP KV key-value logger Pino OpenAPI Docker environment variables adapters infrastructure
+  QUESTPIE production deployment authentication better-auth OAuth database PostgreSQL Drizzle storage S3 Files SDK queue pg-boss jobs realtime SSE pgNotify Redis migrations email SMTP KV key-value logger Pino OpenAPI Docker environment variables adapters infrastructure
   - questpie-core
 ---
 
@@ -11,15 +11,40 @@ This skill builds on questpie-core.
 
 QUESTPIE uses an adapter-based architecture for all infrastructure. Development defaults work out of the box; production requires explicit adapter configuration in `questpie.config.ts`.
 
-| Service  | Dev Default           | Production Adapter                    |
-| -------- | --------------------- | ------------------------------------- |
-| Database | PostgreSQL (local)    | PostgreSQL (remote, SSL)              |
-| Storage  | Local filesystem      | S3-compatible (`s3` driver)           |
-| Queue    | None (jobs skip)      | pg-boss (`pgBossAdapter`)             |
-| Realtime | pgNotify              | Redis Streams (`redisStreamsAdapter`) |
-| Email    | Console (logs output) | SMTP (`SmtpAdapter`)                  |
-| KV Store | In-memory             | Redis (`"redis"` adapter)             |
-| Logger   | Pino (console)        | Pino (structured JSON)                |
+| Service  | Dev Default           | Production Adapter                              |
+| -------- | --------------------- | ----------------------------------------------- |
+| Database | PostgreSQL (local)    | PostgreSQL (remote, SSL)                        |
+| Storage  | Local filesystem      | Files SDK provider adapter (`s3`, `r2`, etc.)   |
+| Queue    | None (jobs skip)      | pg-boss (`pgBossAdapter`)                       |
+| Realtime | pgNotify              | Redis Streams (`redisStreamsAdapter`)           |
+| Email    | Console (logs output) | SMTP (`SmtpAdapter`)                            |
+| KV Store | In-memory             | Redis (`redisKVAdapter`)                        |
+| Logger   | Pino (console)        | Pino (structured JSON)                          |
+
+## Environment
+
+Declare every env var once in `env.ts` (beside `questpie.config.ts`) — schema-validated at boot, typed everywhere. Never use raw `process.env.X` / `process.env.X!` in app code. Full reference: `references/env.md`.
+
+```ts
+// src/questpie/server/env.ts
+import { env } from "questpie/env";
+import { z } from "zod";
+
+export default env({
+	server: {
+		DATABASE_URL: z.url(),
+		BETTER_AUTH_SECRET: z.string().min(32),
+		S3_BUCKET: z.string().optional(),
+		S3_REGION: z.string().optional(),
+		S3_ACCESS_KEY: z.string().optional(),
+		S3_SECRET_KEY: z.string().optional(),
+		SMTP_HOST: z.string().optional(),
+		REDIS_URL: z.url().optional(),
+	},
+});
+```
+
+All snippets below assume `import env from "./env"` at the top of `questpie.config.ts`.
 
 ## Authentication
 
@@ -27,16 +52,18 @@ QUESTPIE uses [Better Auth](https://www.better-auth.com/). Configure via `config
 
 ```ts
 // src/questpie/server/config/auth.ts
-import { authConfig } from "questpie";
+import { authConfig } from "questpie/app";
+
+import env from "../env";
 
 export default authConfig({
 	emailAndPassword: {
 		enabled: true,
 		requireEmailVerification: false,
 	},
-	baseURL: process.env.APP_URL || "http://localhost:3000",
+	baseURL: env.APP_URL ?? "http://localhost:3000",
 	basePath: "/api/auth",
-	secret: process.env.BETTER_AUTH_SECRET || "change-me",
+	secret: env.BETTER_AUTH_SECRET,
 });
 ```
 
@@ -73,7 +100,28 @@ handler: async ({ session }) => {
 })
 ```
 
-The `adminModule` provides a built-in `user` collection for storing user accounts.
+The `adminModule` provides the canonical Better Auth `user` collection for storing user accounts. That contract includes `user.role` (`admin` or `user`), which built-in admin setup and login guards depend on. Do not replace `collection("user")` from scratch in apps that use `adminModule`; merge `starterModule.collections.user` and extend it instead.
+
+### Locking Down the REST Surface
+
+Deny-all is actually deny-all — there are no implicit framework grants above
+`defaultAccess`:
+
+```ts title="config/app.ts"
+export default appConfig({
+	access: { read: false, create: false, update: false, delete: false },
+});
+```
+
+With this config, anonymous and authenticated callers get nothing unless a
+collection opts in via `.access()`: no row listing (including
+public-visibility upload collections like `assets`), and no schema/meta
+introspection (gated by the same access system — visible iff at least one
+operation is allowed, overridable with the `introspect` access kind). Public
+upload files still serve by key (`GET /:collection/files/:key`) because
+`visibility: "public"` declares the BYTES public — override with the `serve`
+access kind. Do not wrap schema/meta routes in custom auth middleware; use
+`introspect` rules instead.
 
 ## Database
 
@@ -82,7 +130,7 @@ PostgreSQL with Drizzle ORM. Schema is generated from your collection and global
 ```ts
 export default runtimeConfig({
 	db: {
-		url: process.env.DATABASE_URL || "postgres://localhost/myapp",
+		url: env.DATABASE_URL,
 	},
 });
 ```
@@ -122,7 +170,7 @@ Configure migration and seed directories in `questpie.config.ts` under `cli.migr
 
 ## Storage
 
-QUESTPIE uses [Flydrive](https://flydrive.dev/) for file storage.
+QUESTPIE uses [Files SDK](https://files-sdk.dev/) for file storage.
 
 ### Local (Development Default)
 
@@ -137,16 +185,36 @@ export default runtimeConfig({
 ### S3 (Production)
 
 ```ts
-import { S3Driver } from "flydrive/drivers/s3";
+import { s3 } from "files-sdk/s3";
 
 export default runtimeConfig({
 	storage: {
 		basePath: "/api",
-		driver: new S3Driver({
-			bucket: process.env.S3_BUCKET,
-			region: process.env.S3_REGION,
-			accessKeyId: process.env.S3_ACCESS_KEY,
-			secretAccessKey: process.env.S3_SECRET_KEY,
+		adapter: s3({
+			bucket: env.S3_BUCKET,
+			region: env.S3_REGION,
+			credentials: {
+				accessKeyId: env.S3_ACCESS_KEY,
+				secretAccessKey: env.S3_SECRET_KEY,
+			},
+		}),
+	},
+});
+```
+
+### Cloudflare R2 (Production)
+
+```ts
+import { r2 } from "files-sdk/r2";
+
+export default runtimeConfig({
+	storage: {
+		basePath: "/api",
+		adapter: r2({
+			bucket: env.R2_BUCKET,
+			accountId: env.R2_ACCOUNT_ID,
+			accessKeyId: env.R2_ACCESS_KEY_ID,
+			secretAccessKey: env.R2_SECRET_ACCESS_KEY,
 		}),
 	},
 });
@@ -167,17 +235,22 @@ avatar: f.upload({
 Background job processing with [pg-boss](https://github.com/timgit/pg-boss). Jobs stored in PostgreSQL.
 
 ```ts
-import { pgBossAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgBossAdapter } from "questpie/adapters/pg-boss";
 
 export default runtimeConfig({
 	queue: {
 		adapter: pgBossAdapter({
-			connectionString: process.env.DATABASE_URL,
+			connectionString: env.DATABASE_URL,
 		}),
 	},
 });
 ```
 
+> **Warning:** pg-boss uses `LISTEN/NOTIFY` internally. Do not point `connectionString` at a PgBouncer in transaction pool mode — jobs will queue but never wake the worker, so they fire only on the polling fallback (slow, sometimes never). See "PgBouncer Compatibility" for the full adapter matrix and routing options. Use a direct PG connection or `cloudflareQueuesAdapter`.
+
+On Cloudflare Workers, queue processing is push-based. Configure `cloudflareQueuesAdapter` from `questpie/adapters/cloudflare` and export the Worker through `createCloudflareWorkerHandlers`; do not run `app.queue.listen()` in a Worker.
+
 ### Publishing Jobs
 
 From hooks, functions, or other jobs:
@@ -197,15 +270,18 @@ The `queue` object is fully typed -- autocompletion shows all registered jobs an
 
 SSE-based live updates via `POST /realtime` multiplexed endpoint.
 
+> **Warning:** `pgNotifyAdapter` requires a direct PG connection (or PgBouncer in `session` mode). Behind PgBouncer transaction pooling, `LISTEN` is silently dropped and clients fall back to polling — events never fan out. See "PgBouncer Compatibility" below.
+
 ### pgNotify (Single Instance)
 
 ```ts
-import { pgNotifyAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
 
 export default runtimeConfig({
 	realtime: {
 		adapter: pgNotifyAdapter({
-			connectionString: process.env.DATABASE_URL,
+			connectionString: env.DATABASE_URL,
 		}),
 	},
 });
@@ -216,31 +292,80 @@ export default runtimeConfig({
 Required for horizontal scaling:
 
 ```ts
-import { redisStreamsAdapter } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { redisStreamsAdapter } from "questpie/adapters/redis-streams";
 
 export default runtimeConfig({
 	realtime: {
 		adapter: redisStreamsAdapter({
-			url: process.env.REDIS_URL,
+			url: env.REDIS_URL,
 		}),
 	},
 });
 ```
 
+> **Warning:** `pgNotifyAdapter` and `pgBossAdapter` both rely on PostgreSQL `LISTEN/NOTIFY`. They will silently fail behind PgBouncer in transaction pool mode. See "PgBouncer Compatibility" below.
+
+### SSE Keepalive & Timeouts
+
+The `POST /realtime` SSE stream sends a `ping` every **8s** by default (`realtime.keepAliveIntervalMs`). Every layer between browser and server must tolerate at least that idle window, or subscriptions die and reconnect in a loop:
+
+| Layer                      | Setting                            | Recommendation                                                            |
+| -------------------------- | ---------------------------------- | ------------------------------------------------------------------------- |
+| Bun (`Bun.serve`)          | `idleTimeout` (default 10s)        | Default ping survives it; set `idleTimeout: 30` for headroom              |
+| nginx                      | `proxy_read_timeout` (default 60s) | Keep >= 60s; disable SSE response buffering (`proxy_buffering off`)       |
+| Load balancers (ALB, etc.) | idle timeout (often 60s)           | Keep above `keepAliveIntervalMs`                                          |
+| Serverless platforms       | response buffering / max duration  | SSE needs streaming responses; buffered platforms break realtime entirely |
+
+```ts
+// Bun server entry — the app owns Bun.serve options, not the framework
+export default {
+	port: 3000,
+	idleTimeout: 30, // seconds
+	fetch: server.fetch,
+};
+```
+
+## PgBouncer Compatibility
+
+PgBouncer in `transaction` pool mode reassigns sessions per-transaction, so persistent listeners are impossible. Once `LISTEN` returns, the connection is handed to a different client and notifications are dropped. This breaks any feature that depends on session-bound state.
+
+Bun SQL (`new SQL({ url })`) already pools connections internally. In single-instance and small-replica deployments, PgBouncer adds nothing on top of it. PgBouncer only earns its keep when you have 20+ replicas, run on serverless with cold-start churn, or share infra with non-Bun consumers.
+
+### Adapter Compatibility Matrix
+
+| Adapter                          | Direct PG | PgBouncer (transaction)           | PgBouncer (session)         |
+| -------------------------------- | --------- | --------------------------------- | --------------------------- |
+| `pgNotifyAdapter` (realtime)     | works     | broken — listens silently dropped | works (pooling neutralized) |
+| `pgBossAdapter` (queue)          | works     | broken — LISTEN/NOTIFY required   | works (pooling neutralized) |
+| Drizzle queries via Bun SQL      | works     | works                             | works                       |
+| `redisStreamsAdapter` (realtime) | n/a       | n/a                               | n/a                         |
+
+Prepared statements also break under transaction pooling. If you must use it, ensure your driver disables prepared statements end-to-end.
+
+### DB Connection Routing
+
+- **Default and recommended:** direct connection to the PG primary. Bun SQL pools internally; you do not need PgBouncer.
+- **If you must use PgBouncer:** put it in `session` pool mode for any process that runs `pgBossAdapter` or `pgNotifyAdapter`. Session mode pins one server connection per client, which neutralizes pooling but keeps `LISTEN/NOTIFY` working.
+- **Split topology:** route web traffic through PgBouncer (transaction mode) and run workers (pgBoss, pgNotify) on a direct connection. This works, but realtime fired from web handlers still routes through the same `QUESTPIE_DB`, so realtime in web fails. In practice, going direct everywhere is simpler.
+- **TODO / current limitation:** the framework reads a single `QUESTPIE_DB` env var. There is no built-in split between a pooled URL and a direct URL for LISTEN consumers. Track this if you need a mixed topology.
+
 ## Email
 
 Transactional email with typed templates. Two adapters: `SmtpAdapter` (production) and `ConsoleAdapter` (development).
 
 ```ts
-import { SmtpAdapter, ConsoleAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { ConsoleAdapter } from "questpie/adapters/console";
+import { SmtpAdapter } from "questpie/adapters/smtp";
 
 export default runtimeConfig({
 	email: {
 		adapter:
-			process.env.NODE_ENV === "development"
+			env.NODE_ENV === "development"
 				? new ConsoleAdapter({ logHtml: false })
 				: new SmtpAdapter({
-						transport: { host: process.env.SMTP_HOST, port: 587, secure: true },
+						transport: { host: env.SMTP_HOST, port: 587, secure: true },
 					}),
 	},
 });
@@ -268,12 +393,21 @@ const results = await client.search.search({
 
 ## KV Store
 
-### Custom Adapter
+### Redis
 
 ```ts
+import { createClient } from "redis";
+import { redisKVAdapter } from "questpie/adapters/redis-kv";
+
+async function getRedis() {
+	const redis = createClient({ url: env.REDIS_URL });
+	await redis.connect();
+	return redis;
+}
+
 export default runtimeConfig({
 	kv: {
-		adapter: myKvAdapter,
+		adapter: redisKVAdapter({ client: getRedis, keyPrefix: "my-app:" }),
 		defaultTtl: 3600,
 	},
 });
@@ -291,7 +425,7 @@ kv: {
 
 ```ts
 handler: async ({ kv }) => {
-	await kv.set("key", "value", { ttl: 3600 });
+	await kv.set("key", "value", 3600);
 	const value = await kv.get("key");
 	await kv.delete("key");
 };
@@ -373,17 +507,17 @@ CMD ["bun", "run", ".output/server/index.mjs"]
 
 ```ts
 // routes/health.ts
-import { route } from "questpie";
-
-export default route({
-	method: "GET",
-	handler: async ({ db }) => {
+import { sql } from "questpie/drizzle";
+import { route } from "questpie/services";
+
+export default route()
+	.get()
+	.raw()
+	.access(true)
+	.handler(async ({ db }) => {
 		await db.execute(sql`SELECT 1`);
-		return new Response(JSON.stringify({ status: "ok" }), {
-			headers: { "Content-Type": "application/json" },
-		});
-	},
-});
+		return Response.json({ status: "ok" });
+	});
 ```
 
 ## Common Mistakes
@@ -396,8 +530,8 @@ Without a strong secret, sessions can be forged. The default `"change-me"` is fo
 // WRONG -- in production
 secret: "change-me";
 
-// CORRECT -- strong random secret from environment
-secret: process.env.BETTER_AUTH_SECRET; // min 32 chars
+// CORRECT -- declared in env.ts as z.string().min(32), validated at boot
+secret: env.BETTER_AUTH_SECRET;
 ```
 
 ### HIGH: Not running migrations after schema changes
@@ -422,15 +556,17 @@ The local storage adapter writes to the filesystem. In containerized deployments
 storage: { basePath: "/api" }
 
 // CORRECT -- persistent S3 storage
-import { S3Driver } from "flydrive/drivers/s3";
+import { s3 } from "files-sdk/s3";
 
 storage: {
   basePath: "/api",
-  driver: new S3Driver({
-    bucket: process.env.S3_BUCKET,
-    region: process.env.S3_REGION,
-    accessKeyId: process.env.S3_ACCESS_KEY,
-    secretAccessKey: process.env.S3_SECRET_KEY,
+  adapter: s3({
+    bucket: env.S3_BUCKET,
+    region: env.S3_REGION,
+    credentials: {
+      accessKeyId: env.S3_ACCESS_KEY,
+      secretAccessKey: env.S3_SECRET_KEY,
+    },
   }),
 }
 ```
@@ -443,11 +579,40 @@ Without pg-boss configured, job `.publish()` calls silently do nothing. Jobs def
 // REQUIRED for jobs to actually execute
 queue: {
   adapter: pgBossAdapter({
-    connectionString: process.env.DATABASE_URL,
+    connectionString: env.DATABASE_URL,
   }),
 }
 ```
 
+### HIGH: PgBouncer transaction pool with pgNotify/pgBoss
+
+Pointing `QUESTPIE_DB` at a PgBouncer in transaction pool mode silently breaks `pgNotifyAdapter` and `pgBossAdapter`. Both rely on PostgreSQL `LISTEN/NOTIFY`, which requires a persistent session. PgBouncer transaction pooling reassigns the session per-transaction, so the listener is dropped right after `LISTEN` returns.
+
+Symptoms:
+
+- Realtime: SSE clients connect but never receive events; UI silently falls back to polling, or never refreshes
+- Queue: jobs sit in the table; workers process them only on the polling tick (delayed by seconds to minutes), or never wake at all
+
+Fix:
+
+```ts
+// WRONG -- QUESTPIE_DB points at PgBouncer (transaction mode)
+realtime: {
+	adapter: pgNotifyAdapter({ connectionString: env.QUESTPIE_DB });
+}
+queue: {
+	adapter: pgBossAdapter({ connectionString: env.QUESTPIE_DB });
+}
+
+// CORRECT -- direct PG connection (Bun SQL pools internally)
+// Or switch to redisStreamsAdapter for realtime in multi-instance deployments
+realtime: {
+	adapter: redisStreamsAdapter({ url: env.REDIS_URL });
+}
+```
+
+If your infra mandates PgBouncer, use `session` pool mode for processes that run pgBoss or pgNotify. See "PgBouncer Compatibility" for the full matrix.
+
 ## Realtime and Live Preview
 
 The realtime adapter (`pgNotifyAdapter` or `redisStreamsAdapter`) is relevant for **detached or shared preview sessions** — when the preview runs in a separate browser tab, or multiple collaborators view the same preview.

package/skills/questpie/references/quickstart.md

@@ -101,8 +101,7 @@ Only hyphens are camelized in factory args; underscores are preserved (`global("
 
 ```ts
 // src/questpie/server/questpie.config.ts
-import { runtimeConfig } from "questpie";
-
+import { runtimeConfig } from "questpie/app";
 export default runtimeConfig({
 	app: {
 		url: process.env.APP_URL || "http://localhost:3000",
@@ -162,7 +161,7 @@ Core: `text`, `number`, `boolean`, `date`, `datetime`, `time`, `select`, `relati
 
 ```ts
 // src/questpie/server/routes/get-overdue-tasks.ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -239,7 +238,7 @@ bunx questpie migrate:fresh
 ```ts
 // src/routes/api/$.ts
 import { createAPIFileRoute } from "@tanstack/react-start/api";
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });
@@ -285,7 +284,7 @@ bun add @questpie/admin
 
 ```ts
 // src/questpie/server/modules.ts
-import { adminModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
 
 export default [adminModule] as const;
 ```
@@ -443,8 +442,7 @@ export { default } from "./src/questpie/server/questpie.config";
 
 ```ts
 // src/questpie/server/questpie.config.ts
-import { runtimeConfig } from "questpie";
-
+import { runtimeConfig } from "questpie/app";
 export default runtimeConfig({
 	app: { url: process.env.APP_URL || "http://localhost:3000" },
 	db: { url: process.env.DATABASE_URL! },
@@ -469,7 +467,7 @@ export default collection("posts").fields(({ f }) => ({
 ```ts
 // src/routes/api/$.ts
 import { createAPIFileRoute } from "@tanstack/react-start/api";
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });
@@ -494,7 +492,7 @@ bun dev
 
 ## 12. Live Preview (Optional)
 
-Add split-screen live preview to any collection with `.preview()`. The current same-tab flow refreshes the preview iframe after save/autosave and supports field focus over `postMessage`.
+Add split-screen live preview to any collection with `.preview()`. Live Preview uses the existing admin `FormView`, Preview button, `LivePreviewMode`, and iframe. Do not introduce a second default form view or parallel preview API names.
 
 ### Add Preview to a Collection
 
@@ -518,32 +516,47 @@ export default collection("pages")
 
 ### Add Preview Support to the Frontend Page
 
+Frontend checklist:
+
+1. Call `useCollectionPreview({ initialData, onRefresh })`.
+2. Wrap the rendered output in `PreviewProvider`.
+3. Render from `preview.data`, not directly from loader data.
+4. Wrap editable scalar text in `PreviewField`.
+5. Render blocks with `BlockRenderer` when the page uses `f.blocks()`.
+
 ```tsx
 import {
+	BlockRenderer,
 	PreviewField,
 	PreviewProvider,
 	useCollectionPreview,
 } from "@questpie/admin/client";
+import admin from "@/questpie/admin/.generated/client";
 
-function PageView({ initialData }) {
+function PageView({ page }) {
 	const router = useRouter();
 	const preview = useCollectionPreview({
-		initialData,
+		initialData: page,
 		onRefresh: () => router.invalidate(),
 	});
 
 	return (
-		<PreviewProvider
-			isPreviewMode={preview.isPreviewMode}
-			focusedField={preview.focusedField}
-			onFieldClick={preview.handleFieldClick}
-		>
-			<PreviewField field="title" as="h1">
+		<PreviewProvider preview={preview}>
+			<PreviewField field="title" editable="text" as="h1">
 				{preview.data.title}
 			</PreviewField>
+			<BlockRenderer
+				content={preview.data.content}
+				data={preview.data.content?._data}
+				renderers={admin.blocks}
+				selectedBlockId={preview.selectedBlockId}
+				onBlockClick={
+					preview.isPreviewMode ? preview.handleBlockClick : undefined
+				}
+			/>
 		</PreviewProvider>
 	);
 }
 ```
 
-The `"hybrid"` strategy is recommended as the default — it applies field patches instantly via `postMessage` while reconciling derived data (slugs, relations) through the server.
+The form remains authoritative. Save, autosave, Cmd+S, history, workflow, locks, and actions stay in the existing form lifecycle.