create-questpie 2.0.3 → 2.0.4

package/skills/questpie/references/data-modeling.md

@@ -62,6 +62,24 @@ export default collection("posts")
 | `.options({...})`                               | Timestamps, versioning, soft delete     |
 | `.search({...})`                                | Search indexing                         |
 | `.searchable(string[])`                         | Searchable fields                       |
+| `.merge(other)`                                 | Extend a same-name builder (see below)  |
+
+### Extending Collections — `.merge()`
+
+To extend a collection a module already provides, merge its builder — never redefine the collection from scratch (same-key registration replaces the module's collection wholesale):
+
+```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/options/extension keys combine by key (merged-in side wins), hooks concatenate, and `.fields()` after `.merge()` is cumulative — it never wipes merged fields. The result stays fully typed.
 
 ### Collection Options
 
@@ -242,8 +260,7 @@ Every field accepts:
 ### Virtual (Computed) Fields
 
 ```ts
-import { sql } from "questpie";
-
+import { sql } from "questpie/builders";
 displayTitle: f.text().virtual(sql<string>`(
     SELECT COALESCE(name, 'Unknown') || ' - ' ||
     TO_CHAR("scheduledAt", 'YYYY-MM-DD HH24:MI')
@@ -260,7 +277,7 @@ All relations are defined via `f.relation()` inside `.fields()`.
 ### Belongs-To (Single)
 
 ```ts
-author: f.relation("users").required(),
+author: f.relation("user").required(),
 barber: f.relation("barbers").required().onDelete("cascade"),
 ```
 
@@ -319,8 +336,7 @@ const appointments = await collections.appointments.find({
 ### Locale Configuration
 
 ```ts title="config/app.ts"
-import { appConfig } from "questpie";
-
+import { appConfig } from "questpie/app";
 export default appConfig({
 	locale: {
 		locales: [
@@ -450,7 +466,7 @@ collection("posts").relations({ author: belongsTo("users") });
 
 // CORRECT -- use f.relation() inside .fields()
 collection("posts").fields(({ f }) => ({
-	author: f.relation("users"),
+	author: f.relation("user"),
 }));
 ```
 

package/skills/questpie/references/extend.md

@@ -15,7 +15,7 @@ A plugin tells codegen what to discover and what types to generate. Plugins cont
 ### Plugin Structure
 
 ```ts
-import type { CodegenPlugin } from "questpie";
+import type { CodegenPlugin } from "questpie/codegen";
 
 export function myPlugin(): CodegenPlugin {
 	return {
@@ -76,7 +76,7 @@ export function myPlugin(): CodegenPlugin {
 ### Register in Config
 
 ```ts title="questpie.config.ts"
-import { runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
 import { myPlugin } from "my-plugin-package";
 
 export default runtimeConfig({
@@ -167,7 +167,9 @@ The admin module contributes a codegen plugin to both `"server"` and `"admin-cli
 A module is a reusable package that contributes entities to any QUESTPIE project.
 
 ```ts
-import { module, collection, job } from "questpie";
+import { module } from "questpie/app";
+import { collection } from "questpie/builders";
+import { job } from "questpie/services";
 import { z } from "zod";
 
 const notificationsCollection = collection("notifications")
@@ -235,10 +237,35 @@ export const notificationsModule = module({
 | `seeds`       | `Seed[]`      | Seed data                |
 | `messages`    | `Record`      | i18n translations        |
 
+### How Module Contributions Merge
+
+When several modules (and the app) contribute the same key, `createApp()` merges them deterministically — later modules win per entry:
+
+| Key | Strategy |
+| --- | --- |
+| `collections`, `globals`, `jobs`, `routes`, `fields`, `services` | record spread-merge — same key: later wins |
+| `messages` | deep-merge by locale — same message key: later wins |
+| `migrations`, `seeds` | array concatenation |
+| `config.*` (app, auth, admin, plugin config keys) | per-key strategies; `auth`/`admin` deep-merge; unknown keys: incoming replaces existing |
+| anything else | auto-detect: object+object → spread, array+array → concat, otherwise incoming wins |
+
+The merge helpers behind these strategies are exported from `questpie/app` for module authors combining config fragments of their own:
+
+```ts
+import { lastWins, mergeConcat, mergeDeepConcat, mergeRecord, type MergeFn } from "questpie/app";
+
+mergeRecord(a, b); // { ...a, ...b }
+mergeConcat(a, b); // [...a, ...b]
+mergeDeepConcat(a, b); // spread objects, concat array-valued props
+lastWins(a, b); // b
+```
+
+Use them (instead of hand-rolled spreads) when a module exposes its own "combine these contributions" surface — the semantics then match what the framework does for built-in keys.
+
 ### Using a Module
 
 ```ts title="modules.ts"
-import { adminModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
 import { notificationsModule } from "my-notifications-package";
 
 export default [adminModule, notificationsModule] as const;
@@ -281,7 +308,7 @@ A custom field defines:
 The `Field` class is an immutable builder:
 
 ```ts
-import { Field } from "questpie";
+import { Field } from "questpie/builders";
 
 // Each method returns a new Field with updated type state
 f.text(255).required().label({ en: "Name" }).admin({ placeholder: "..." });
@@ -312,7 +339,7 @@ QUESTPIE ships with adapters for Hono, Elysia, and Next.js. For other frameworks
 ### Generic Fetch Handler
 
 ```ts
-import { createFetchHandler } from "questpie";
+import { createFetchHandler } from "questpie/http";
 import { app } from "#questpie";
 
 const handler = createFetchHandler(app, { basePath: "/api" });
@@ -360,7 +387,7 @@ export const { GET, POST, PATCH, DELETE } = questpieNextRouteHandlers(app, {
 
 ```ts title="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" });

package/skills/questpie/references/field-types.md

@@ -14,6 +14,9 @@ Complete configuration patterns for built-in QUESTPIE field types. Fields use fl
 | `.inputOptional()`   | Optional in API input but required in DB    |
 | `.admin(config)`     | Admin UI rendering hints                    |
 | `.virtual(sql)`      | SQL expression for computed read-only field |
+| `.zod(fn)`           | Extend/replace Zod schema (output narrows value type) |
+| `.drizzle(fn)`       | Raw Drizzle column builder — constraints/SQL defaults land in DDL; `$type` narrows value type |
+| `.$type<T>()`        | Explicitly set TS value type (type-level; mainly json) |
 
 ## `f.text(options?)`
 
@@ -206,7 +209,7 @@ Reference to another collection.
 Belongs-to (single):
 
 ```ts
-author: f.relation("users").required(),
+author: f.relation("user").required(),
 category: f.relation("categories").onDelete("set null"),
 ```
 
@@ -355,13 +358,22 @@ pageContent: f.blocks(),
 
 ## `f.json(options?)`
 
-Raw JSON data. No schema validation.
+Raw JSON data. No schema validation by default; value types as loose `JsonValue`.
 
 ```ts
 metadata: f.json(),
 rawConfig: f.json().label("Configuration"),
 ```
 
+Type it explicitly with `.$type<T>()` (type only) or `.zod()` (type + runtime validation) — the type flows into CRUD select/insert types:
+
+```ts
+type Layout = { rows: { id: string; span: number }[] };
+
+layout: f.json().$type<Layout>(),
+settings: f.json().zod(() => z.object({ theme: z.enum(["light", "dark"]) })),
+```
+
 ## Admin Meta Options
 
 The `meta.admin` object controls field rendering in the admin panel:

package/skills/questpie/references/infrastructure-adapters.md

@@ -7,8 +7,7 @@ All adapter configurations for QUESTPIE production infrastructure.
 PostgreSQL with Drizzle ORM. Configured in `questpie.config.ts`:
 
 ```ts
-import { runtimeConfig } from "questpie";
-
+import { runtimeConfig } from "questpie/app";
 export default runtimeConfig({
 	db: {
 		url: process.env.DATABASE_URL || "postgres://localhost/myapp",
@@ -58,7 +57,7 @@ collection("posts")
 
 ## Storage
 
-File storage via [Flydrive](https://flydrive.dev/).
+File storage via [Files SDK](https://files-sdk.dev/).
 
 ### Local (Development)
 
@@ -74,19 +73,42 @@ export default runtimeConfig({
 
 ### S3-Compatible (Production)
 
-Works with AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2:
+Works with AWS S3, MinIO, DigitalOcean Spaces, and other S3-compatible
+providers that do not have a dedicated Files SDK adapter:
 
 ```ts
-import { S3Driver } from "flydrive/drivers/s3";
+import { s3 } from "files-sdk/s3";
 
 export default runtimeConfig({
 	storage: {
 		basePath: "/api",
-		driver: new S3Driver({
+		adapter: s3({
 			bucket: process.env.S3_BUCKET,
 			region: process.env.S3_REGION,
-			accessKeyId: process.env.S3_ACCESS_KEY,
-			secretAccessKey: process.env.S3_SECRET_KEY,
+			credentials: {
+				accessKeyId: process.env.S3_ACCESS_KEY!,
+				secretAccessKey: process.env.S3_SECRET_KEY!,
+			},
+		}),
+	},
+});
+```
+
+### Cloudflare R2 (Production)
+
+Use Files SDK's dedicated R2 adapter:
+
+```ts
+import { r2 } from "files-sdk/r2";
+
+export default runtimeConfig({
+	storage: {
+		basePath: "/api",
+		adapter: r2({
+			bucket: process.env.R2_BUCKET!,
+			accountId: process.env.R2_ACCOUNT_ID!,
+			accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+			secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
 		}),
 	},
 });
@@ -114,14 +136,41 @@ const assets = await client.collections.assets.uploadMany(files, {
 });
 ```
 
+Failed uploads reject with `UploadError` (from `questpie/client`) carrying the HTTP status and server message.
+
+### Signed URLs (Private Files)
+
+Upload rows carry a `url` populated automatically on read: `visibility: "public"` files get a plain collection-scoped URL (`{basePath}/{collection}/files/{key}`); `"private"` files get an HMAC-signed token appended (`?token=...`), signed with `app.config.secret` and expiring after `storage.signedUrlExpiration` (default `3600` seconds):
+
+```ts
+export default runtimeConfig({
+	storage: {
+		basePath: "/api",
+		signedUrlExpiration: 900, // 15 minutes
+	},
+});
+```
+
+Serving stays collection-scoped — the file route verifies the token **and** the collection's `serve` access rule. To mint URLs manually (custom emails, server-rendered pages):
+
+```ts
+import { buildStorageFileUrl, generateSignedUrlToken } from "questpie/storage";
+
+const token = await generateSignedUrlToken(asset.key, app.config.secret!, 900, "assets");
+const url = buildStorageFileUrl(app.config.app.url, "/api", "assets", asset.key, token);
+```
+
+(`verifySignedUrlToken` is the verification half the serve route runs — you rarely call it yourself.)
+
 ## Queue
 
-Background jobs via [pg-boss](https://github.com/timgit/pg-boss). Jobs stored in PostgreSQL -- no external queue service needed.
+Background jobs via [pg-boss](https://github.com/timgit/pg-boss), BullMQ, or a custom queue adapter.
 
 ### Configuration
 
 ```ts
-import { pgBossAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgBossAdapter } from "questpie/adapters/pg-boss";
 
 export default runtimeConfig({
 	queue: {
@@ -132,6 +181,24 @@ export default runtimeConfig({
 });
 ```
 
+### BullMQ
+
+```ts
+import { runtimeConfig } from "questpie/app";
+import { bullMQAdapter } from "questpie/adapters/bullmq";
+
+export default runtimeConfig({
+	queue: {
+		adapter: bullMQAdapter({
+			connection: { url: process.env.REDIS_URL! },
+			queuePrefix: "my-app",
+		}),
+	},
+});
+```
+
+The built-in BullMQ adapter targets open-source BullMQ and does not expose per-group FIFO behavior. Use a native grouped queue adapter if the workload needs one active job per group with cross-group parallelism.
+
 ### Publishing Jobs
 
 The `queue` context object is fully typed:
@@ -154,7 +221,8 @@ SSE-based live updates.
 Uses PostgreSQL `LISTEN/NOTIFY`. Best for single-server deployments:
 
 ```ts
-import { pgNotifyAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
 
 export default runtimeConfig({
 	realtime: {
@@ -170,7 +238,8 @@ export default runtimeConfig({
 Required for horizontal scaling across multiple server instances:
 
 ```ts
-import { redisStreamsAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { redisStreamsAdapter } from "questpie/adapters/redis-streams";
 
 export default runtimeConfig({
 	realtime: {
@@ -188,6 +257,48 @@ export default runtimeConfig({
 | `pgNotifyAdapter`     | Single server, development, simple deployments        |
 | `redisStreamsAdapter` | Multiple servers, horizontal scaling, high throughput |
 
+## Search
+
+Full-text search via PostgreSQL (no extra service). The adapter goes directly on the `search` key:
+
+```ts
+import { runtimeConfig } from "questpie/app";
+import { createPostgresSearchAdapter } from "questpie/adapters/postgres-search";
+
+export default runtimeConfig({
+	search: createPostgresSearchAdapter(), // pg_trgm + tsvector FTS
+});
+```
+
+### Semantic Search (pgvector + Embeddings)
+
+`createPgVectorSearchAdapter` wraps the Postgres adapter and adds an `embedding` vector column + cosine-distance search. It needs the `pgvector` extension (`CREATE EXTENSION "vector";` — the adapter ships its own migrations) and an embedding provider:
+
+```ts
+import { runtimeConfig } from "questpie/app";
+import {
+	createOpenAIEmbeddingProvider,
+	createPgVectorSearchAdapter,
+} from "questpie/adapters/pgvector-search";
+
+export default runtimeConfig({
+	search: createPgVectorSearchAdapter({
+		embeddingProvider: createOpenAIEmbeddingProvider({
+			apiKey: process.env.OPENAI_API_KEY!,
+			model: "text-embedding-3-small",
+		}),
+		// Hybrid scoring weights (defaults shown)
+		lexicalWeight: 0.4,
+		semanticWeight: 0.6,
+		indexType: "ivfflat", // or "hnsw"
+	}),
+});
+```
+
+Search modes: `lexical` (FTS + trigram), `semantic` (pure vector similarity), `hybrid` (weighted combination). Embeddings are generated on `index()`; if generation fails, the row still indexes for lexical search.
+
+For non-OpenAI providers, `createCustomEmbeddingProvider({ name, model, dimensions, generate })` wraps any embedding function.
+
 ## Email
 
 Transactional email with typed templates.
@@ -195,7 +306,8 @@ Transactional email with typed templates.
 ### SMTP (Production)
 
 ```ts
-import { SmtpAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { SmtpAdapter } from "questpie/adapters/smtp";
 
 export default runtimeConfig({
 	email: {
@@ -215,7 +327,8 @@ export default runtimeConfig({
 Logs emails to console instead of sending:
 
 ```ts
-import { ConsoleAdapter, runtimeConfig } from "questpie";
+import { runtimeConfig } from "questpie/app";
+import { ConsoleAdapter } from "questpie/adapters/console";
 
 export default runtimeConfig({
 	email: {
@@ -224,6 +337,46 @@ export default runtimeConfig({
 });
 ```
 
+### Resend (HTTP API)
+
+For [Resend](https://resend.com) and Resend-compatible providers — no SMTP credentials needed:
+
+```ts
+import { runtimeConfig } from "questpie/app";
+import { resendAdapter } from "questpie/adapters/resend";
+
+export default runtimeConfig({
+	email: {
+		adapter: resendAdapter({
+			apiKey: process.env.RESEND_API_KEY!,
+			// baseUrl: "https://api.resend.com",  // override for compatible providers
+		}),
+	},
+});
+```
+
+### Plunk (HTTP API)
+
+For [Plunk](https://www.useplunk.com) transactional email (also self-hosted):
+
+```ts
+import { runtimeConfig } from "questpie/app";
+import { plunkAdapter } from "questpie/adapters/plunk";
+
+export default runtimeConfig({
+	email: {
+		adapter: plunkAdapter({
+			apiKey: process.env.PLUNK_API_KEY!, // secret key — public keys only track events
+			// baseUrl: "https://next-api.useplunk.com",  // override for self-hosted
+		}),
+	},
+});
+```
+
+### Custom Mail Adapter
+
+For any other provider, extend the `MailAdapter` base class from `questpie/mailer` (implement `send(options)`) and pass an instance as `email.adapter`.
+
 ### Environment-Based Switching
 
 ```ts
@@ -247,7 +400,7 @@ Templates go in the `emails/` directory:
 
 ```ts
 // emails/welcome.ts
-import { email } from "questpie";
+import { email } from "questpie/services";
 import z from "zod";
 
 export default email({
@@ -279,6 +432,26 @@ handler: async ({ email }) => {
 
 Key-value storage for caching, rate limiting, ephemeral data.
 
+### Redis
+
+```ts
+import { createClient } from "redis";
+import { redisKVAdapter } from "questpie/adapters/redis-kv";
+
+async function getRedis() {
+	const redis = createClient({ url: process.env.REDIS_URL! });
+	await redis.connect();
+	return redis;
+}
+
+export default runtimeConfig({
+	kv: {
+		adapter: redisKVAdapter({ client: getRedis, keyPrefix: "my-app:" }),
+		defaultTtl: 3600,
+	},
+});
+```
+
 ### Custom Adapter
 
 ```ts
@@ -305,7 +478,7 @@ export default runtimeConfig({
 ```ts
 handler: async ({ kv }) => {
 	// Set with TTL (seconds)
-	await kv.set("session:abc", JSON.stringify(data), { ttl: 3600 });
+	await kv.set("session:abc", JSON.stringify(data), 3600);
 
 	// Get
 	const value = await kv.get("session:abc");
@@ -367,16 +540,18 @@ bun add @questpie/openapi
 
 ```ts
 // src/questpie/server/modules.ts
-import { adminModule } from "@questpie/admin/server";
-import { openApiModule } from "@questpie/openapi";
+import { adminModule } from "@questpie/admin/modules/admin";
+import { openApiModule } from "@questpie/openapi/modules/openapi";
 
 export default [adminModule, openApiModule] as const;
 ```
 
+`openApiModule` carries its codegen plugin — do not also add `openApiPlugin()` to `questpie.config.ts` unless you deliberately omit the module.
+
 Configure it in `config/openapi.ts`:
 
 ```ts
-import { openApiConfig } from "@questpie/openapi";
+import { openApiConfig } from "@questpie/openapi/server";
 
 export default openApiConfig({
 	info: { title: "My API", version: "1.0.0" },
@@ -437,7 +612,7 @@ Instead of the module, create route files directly:
 
 ```ts
 // routes/openapi.json.ts
-import { openApiRoute } from "@questpie/openapi";
+import { openApiRoute } from "@questpie/openapi/server";
 
 export default openApiRoute({
 	info: { title: "My API", version: "1.0.0" },
@@ -446,7 +621,7 @@ export default openApiRoute({
 
 ```ts
 // routes/docs.ts
-import { docsRoute } from "@questpie/openapi";
+import { docsRoute } from "@questpie/openapi/server";
 
 export default docsRoute({
 	scalar: { theme: "purple" },
@@ -456,7 +631,7 @@ export default docsRoute({
 ### Programmatic Access
 
 ```ts
-import { generateOpenApiSpec } from "@questpie/openapi";
+import { generateOpenApiSpec } from "@questpie/openapi/server";
 
 const spec = generateOpenApiSpec(app, {
 	info: { title: "My API", version: "1.0.0" },
@@ -478,13 +653,11 @@ const spec = generateOpenApiSpec(app, {
 ## Complete Production Config Example
 
 ```ts
-import {
-	runtimeConfig,
-	pgBossAdapter,
-	pgNotifyAdapter,
-	SmtpAdapter,
-} from "questpie";
-import { S3Driver } from "flydrive/drivers/s3";
+import { runtimeConfig } from "questpie/app";
+import { pgBossAdapter } from "questpie/adapters/pg-boss";
+import { pgNotifyAdapter } from "questpie/adapters/pg-notify";
+import { SmtpAdapter } from "questpie/adapters/smtp";
+import { s3 } from "files-sdk/s3";
 
 export default runtimeConfig({
 	db: {
@@ -492,11 +665,13 @@ export default runtimeConfig({
 	},
 	storage: {
 		basePath: "/api",
-		driver: new S3Driver({
+		adapter: s3({
 			bucket: process.env.S3_BUCKET!,
 			region: process.env.S3_REGION!,
-			accessKeyId: process.env.S3_ACCESS_KEY!,
-			secretAccessKey: process.env.S3_SECRET_KEY!,
+			credentials: {
+				accessKeyId: process.env.S3_ACCESS_KEY!,
+				secretAccessKey: process.env.S3_SECRET_KEY!,
+			},
 		}),
 	},
 	queue: {