create-questpie 2.0.2 → 2.0.4

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: {

package/skills/questpie/references/mcp.md

@@ -0,0 +1,147 @@
+# MCP Integration
+
+Use `@questpie/mcp` when a QUESTPIE app should expose collections, globals, annotated JSON routes, schemas, or custom tools to Model Context Protocol clients.
+
+## Static Module Pattern
+
+MCP is codegen-aware. Keep `modules.ts` static and put options in `config/mcp.ts`.
+
+```ts title="modules.ts"
+import mcpModule from "@questpie/mcp";
+
+export default [mcpModule] as const;
+```
+
+```ts title="config/mcp.ts"
+import { mcpConfig } from "@questpie/mcp";
+
+export default mcpConfig({
+	crud: {
+		defaults: {
+			collections: { read: true, write: false, delete: false },
+			globals: { read: true, write: false },
+		},
+		collections: {
+			posts: { read: true, write: true },
+			users: false,
+		},
+		globals: {
+			siteSettings: { read: true, write: true },
+		},
+	},
+	routes: {
+		exposeAnnotated: true,
+	},
+});
+```
+
+Do not use `mcpModule(options)`. Runtime options belong in the plugin-discovered config file.
+
+`mcpModule` carries its codegen plugin. Do not also add `mcpPlugin()` to `questpie.config.ts` unless you are doing a custom setup that deliberately omits `mcpModule` — double registration duplicates the plugin.
+
+## CRUD Policy
+
+Generated collection tools:
+
+- `collections.{name}.list`
+- `collections.{name}.count`
+- `collections.{name}.get`
+- `collections.{name}.create`
+- `collections.{name}.update`
+- `collections.{name}.delete`
+
+Generated global tools:
+
+- `globals.{name}.get`
+- `globals.{name}.update`
+
+Policy order:
+
+1. Transport defaults.
+2. CRUD defaults.
+3. Per-entity override.
+4. QUESTPIE access rules execute last and can still deny.
+
+HTTP is user mode and read-oriented by default. HTTP cannot be made system mode with config or options. Stdio defaults to trusted system mode unless explicitly lowered to user mode.
+
+Use `fields.include` / `fields.exclude` for top-level filtering. It applies to create/update input, CRUD outputs, list docs, global results, and schema resources. Nested relation projection is out of scope for v1.
+
+## Route Tools
+
+Only simple JSON routes are auto-converted:
+
+- Route has `.schema(...)`.
+- Route is not `.raw()`.
+- Route has `meta.mcp.expose === true`.
+- `routes.exposeAnnotated` is not `false`.
+
+```ts
+route()
+	.post()
+	.schema(inputSchema)
+	.outputSchema(outputSchema)
+	.meta({
+		title: "Generate report",
+		mcp: {
+			expose: true,
+			name: "reports.generate",
+			annotations: { readOnlyHint: true },
+		},
+	})
+	.handler(async ({ input }) => ({ ok: true }));
+```
+
+Routes without path params use the route input schema directly. Routes with params use `{ params, input }`. Route policy keys use the route key, not the overridden tool name.
+
+## Resources
+
+Built-in resources:
+
+- `questpie://schema/collections`
+- `questpie://schema/collections/{name}`
+- `questpie://schema/globals`
+- `questpie://schema/globals/{name}`
+- `questpie://schema/routes`
+- `questpie://schema/routes/{key}`
+
+Resources honor MCP policy and QUESTPIE access visibility. Route resources include input/output JSON Schema when the route has Zod schemas.
+
+## Custom Tools
+
+Custom tools live in `mcp-tools/` and are discovered by codegen.
+
+```ts
+import { mcpTool } from "@questpie/mcp";
+import { z } from "zod";
+
+export default mcpTool("generate-report", {
+	description: "Generate a report.",
+	inputSchema: z.object({ period: z.string() }),
+	access: ({ session }) => !!session,
+}).handler(async ({ input, ctx }) => ({
+	structuredContent: await ctx.services.reports.generate(input),
+}));
+```
+
+Custom tool access is checked during `tools/list` and again during `tools/call`.
+
+## Programmatic Servers
+
+Use `createMcpServer(app, { transport: "http", request })` for programmatic HTTP setup. If no `ctx` is passed, the request is preserved through `app.createContext()`.
+
+Use `startStdioServer(app)` for trusted stdio integrations:
+
+```ts
+import { app } from "#questpie";
+import { startStdioServer } from "@questpie/mcp/stdio";
+
+await startStdioServer(app);
+```
+
+## Gotchas
+
+- Add `mcpModule` to static `modules.ts`, then run codegen.
+- HTTP system mode is intentionally impossible until a future trusted-token design exists.
+- Field filtering is top-level only.
+- Raw routes and unannotated routes are not tools.
+- Custom tool results should use `structuredContent` for machine-readable output.

package/skills/questpie/references/multi-tenancy.md

@@ -278,8 +278,7 @@ For advanced cases, create a request-scoped service that provides a tenant-aware
 
 ```ts
 // services/scoped-db.ts
-import { service } from "questpie";
-
+import { service } from "questpie/services";
 export default service({
 	lifecycle: "request",
 	deps: ["db", "session"] as const,