create-questpie 2.0.3 → 2.1.0

package/skills/questpie/references/production.md

@@ -1,475 +0,0 @@
----
-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-core
----
-
-This skill builds on questpie-core.
-
-## Overview
-
-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)                |
-
-## Authentication
-
-QUESTPIE uses [Better Auth](https://www.better-auth.com/). Configure via `config/auth.ts`:
-
-```ts
-// src/questpie/server/config/auth.ts
-import { authConfig } from "questpie";
-
-export default authConfig({
-	emailAndPassword: {
-		enabled: true,
-		requireEmailVerification: false,
-	},
-	baseURL: process.env.APP_URL || "http://localhost:3000",
-	basePath: "/api/auth",
-	secret: process.env.BETTER_AUTH_SECRET || "change-me",
-});
-```
-
-### Auth Options
-
-| Option                                      | Type      | Description                                         |
-| ------------------------------------------- | --------- | --------------------------------------------------- |
-| `emailAndPassword.enabled`                  | `boolean` | Enable email/password login                         |
-| `emailAndPassword.requireEmailVerification` | `boolean` | Require email verification                          |
-| `baseURL`                                   | `string`  | App public URL                                      |
-| `basePath`                                  | `string`  | Auth API path prefix                                |
-| `secret`                                    | `string`  | Session signing secret (min 32 chars in production) |
-
-### Session in Handlers
-
-Access the current session in functions, hooks, and access rules:
-
-```ts
-handler: async ({ session }) => {
-	if (!session) throw new Error("Not authenticated");
-	const user = session.user;
-	// user.id, user.email, user.name
-};
-```
-
-### Access Control with Session
-
-```ts
-.access({
-  read: true,
-  create: ({ session }) => !!session,
-  update: ({ session }) => (session?.user as any)?.role === "admin",
-  delete: ({ session }) => (session?.user as any)?.role === "admin",
-})
-```
-
-The `adminModule` provides a built-in `user` collection for storing user accounts.
-
-## Database
-
-PostgreSQL with Drizzle ORM. Schema is generated from your collection and global definitions.
-
-```ts
-export default runtimeConfig({
-	db: {
-		url: process.env.DATABASE_URL || "postgres://localhost/myapp",
-	},
-});
-```
-
-Raw access via `db` context, indexes via `.indexes()`. See `references/infrastructure-adapters.md` for field-to-column mapping and full details.
-
-## Migrations
-
-### Development: Push
-
-Sync schema directly without migration files:
-
-```bash
-bunx questpie push
-```
-
-### Production: Migration Files
-
-```bash
-# Generate migration from schema diff
-bunx questpie migrate:generate
-
-# Run pending migrations
-bunx questpie migrate:up
-
-# Rollback last migration
-bunx questpie migrate:down
-
-# Drop everything and re-run (DESTRUCTIVE -- dev only)
-bunx questpie migrate:fresh
-
-# Reset migration tracking
-bunx questpie migrate:reset
-```
-
-Configure migration and seed directories in `questpie.config.ts` under `cli.migrations.directory` and `cli.seeds.directory`. Run seeds with `bunx questpie seed`.
-
-## Storage
-
-QUESTPIE uses [Flydrive](https://flydrive.dev/) for file storage.
-
-### Local (Development Default)
-
-```ts
-export default runtimeConfig({
-	storage: {
-		basePath: "/api",
-	},
-});
-```
-
-### S3 (Production)
-
-```ts
-import { S3Driver } from "flydrive/drivers/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,
-		}),
-	},
-});
-```
-
-### Upload Fields
-
-```ts
-avatar: f.upload({
-  to: "assets",
-  mimeTypes: ["image/*"],
-  maxSize: 5_000_000,
-}),
-```
-
-## Queue
-
-Background job processing with [pg-boss](https://github.com/timgit/pg-boss). Jobs stored in PostgreSQL.
-
-```ts
-import { pgBossAdapter, runtimeConfig } from "questpie";
-
-export default runtimeConfig({
-	queue: {
-		adapter: pgBossAdapter({
-			connectionString: process.env.DATABASE_URL,
-		}),
-	},
-});
-```
-
-### Publishing Jobs
-
-From hooks, functions, or other jobs:
-
-```ts
-handler: async ({ queue }) => {
-	await queue.sendAppointmentConfirmation.publish({
-		appointmentId: "abc",
-		customerId: "def",
-	});
-};
-```
-
-The `queue` object is fully typed -- autocompletion shows all registered jobs and their payload schemas.
-
-## Realtime
-
-SSE-based live updates via `POST /realtime` multiplexed endpoint.
-
-### pgNotify (Single Instance)
-
-```ts
-import { pgNotifyAdapter, runtimeConfig } from "questpie";
-
-export default runtimeConfig({
-	realtime: {
-		adapter: pgNotifyAdapter({
-			connectionString: process.env.DATABASE_URL,
-		}),
-	},
-});
-```
-
-### Redis Streams (Multi-Instance)
-
-Required for horizontal scaling:
-
-```ts
-import { redisStreamsAdapter } from "questpie";
-
-export default runtimeConfig({
-	realtime: {
-		adapter: redisStreamsAdapter({
-			url: process.env.REDIS_URL,
-		}),
-	},
-});
-```
-
-## Email
-
-Transactional email with typed templates. Two adapters: `SmtpAdapter` (production) and `ConsoleAdapter` (development).
-
-```ts
-import { SmtpAdapter, ConsoleAdapter, runtimeConfig } from "questpie";
-
-export default runtimeConfig({
-	email: {
-		adapter:
-			process.env.NODE_ENV === "development"
-				? new ConsoleAdapter({ logHtml: false })
-				: new SmtpAdapter({
-						transport: { host: process.env.SMTP_HOST, port: 587, secure: true },
-					}),
-	},
-});
-```
-
-Templates go in `emails/` directory using the `email()` factory. Send via `email.sendTemplate()` in handlers. See `references/infrastructure-adapters.md` for template examples.
-
-## Search
-
-PostgreSQL full-text search. Mark collections as searchable:
-
-```ts
-.searchable(["title", "body", "tags"])
-```
-
-Client usage:
-
-```ts
-const results = await client.search.search({
-	query: "haircut styles",
-	collections: ["posts", "services"],
-	limit: 20,
-});
-```
-
-## KV Store
-
-### Custom Adapter
-
-```ts
-export default runtimeConfig({
-	kv: {
-		adapter: myKvAdapter,
-		defaultTtl: 3600,
-	},
-});
-```
-
-### In-Memory Default
-
-```ts
-kv: {
-  defaultTtl: 3600,
-}
-```
-
-### Usage
-
-```ts
-handler: async ({ kv }) => {
-	await kv.set("key", "value", { ttl: 3600 });
-	const value = await kv.get("key");
-	await kv.delete("key");
-};
-```
-
-## Logger
-
-Structured logging with [Pino](https://getpino.io):
-
-```ts
-handler: async ({ logger }) => {
-	logger.info("Processing booking");
-	logger.error({ err: error }, "Booking failed");
-	logger.debug({ barberId, serviceId }, "Checking availability");
-};
-```
-
-Log levels: `trace`, `debug`, `info`, `warn`, `error`, `fatal`.
-
-Structured data goes as the first argument:
-
-```ts
-logger.info({ appointmentId: "abc", action: "created" }, "Appointment created");
-```
-
-## OpenAPI
-
-Auto-generate OpenAPI 3.1 spec with `@questpie/openapi`. Install with `bun add @questpie/openapi`, add `openApiModule` to `modules.ts`, configure it in `config/openapi.ts` with `openApiConfig({ info: { title: "My API", version: "1.0.0" } })`, then run `bunx questpie generate`. Serves spec at `/api/openapi.json` and Scalar docs at `/api/docs`. See `references/infrastructure-adapters.md` for full options.
-
-## Deployment
-
-### Docker
-
-```dockerfile
-FROM oven/bun:1 AS base
-WORKDIR /app
-
-FROM base AS build
-COPY package.json bun.lockb ./
-RUN bun install --frozen-lockfile
-COPY . .
-RUN bunx questpie generate
-RUN bun run build
-
-FROM base AS production
-COPY --from=build /app/.output /app/.output
-EXPOSE 3000
-CMD ["bun", "run", ".output/server/index.mjs"]
-```
-
-### Environment Variables
-
-| Variable                            | Required | Description                           |
-| ----------------------------------- | -------- | ------------------------------------- |
-| `DATABASE_URL`                      | Yes      | PostgreSQL connection string          |
-| `APP_URL`                           | Yes      | Public URL of the application         |
-| `APP_SECRET` / `BETTER_AUTH_SECRET` | Yes      | Session signing secret (min 32 chars) |
-| `SMTP_HOST`                         | No       | Email SMTP host                       |
-| `SMTP_PORT`                         | No       | Email SMTP port                       |
-| `REDIS_URL`                         | No       | Redis URL (for KV, realtime)          |
-| `S3_BUCKET`                         | No       | S3 bucket name                        |
-| `S3_REGION`                         | No       | S3 region                             |
-| `S3_ACCESS_KEY`                     | No       | S3 access key                         |
-| `S3_SECRET_KEY`                     | No       | S3 secret key                         |
-
-### Production Checklist
-
-- Set strong `APP_SECRET` (min 32 characters)
-- Use production `DATABASE_URL` with SSL
-- Run `bunx questpie migrate:up` before deploying
-- Configure SMTP for transactional email
-- Set `APP_URL` to your public domain
-- Enable HTTPS
-- Configure S3 or persistent storage for uploads
-- Use `redisStreamsAdapter` if running multiple instances
-- Set up health checks
-
-### Health Check
-
-```ts
-// routes/health.ts
-import { route } from "questpie";
-
-export default route({
-	method: "GET",
-	handler: async ({ db }) => {
-		await db.execute(sql`SELECT 1`);
-		return new Response(JSON.stringify({ status: "ok" }), {
-			headers: { "Content-Type": "application/json" },
-		});
-	},
-});
-```
-
-## Common Mistakes
-
-### CRITICAL: Missing BETTER_AUTH_SECRET in production
-
-Without a strong secret, sessions can be forged. The default `"change-me"` is for development only.
-
-```ts
-// WRONG -- in production
-secret: "change-me";
-
-// CORRECT -- strong random secret from environment
-secret: process.env.BETTER_AUTH_SECRET; // min 32 chars
-```
-
-### HIGH: Not running migrations after schema changes
-
-When you add, remove, or change collection fields, the database schema must be updated. Without migrations, queries fail or return stale data.
-
-```bash
-# After changing any collection fields:
-bunx questpie migrate:generate   # create migration file
-bunx questpie migrate:up         # apply to database
-
-# Or in development:
-bunx questpie push               # direct schema sync (no migration file)
-```
-
-### HIGH: Using local storage in production without persistent volume
-
-The local storage adapter writes to the filesystem. In containerized deployments, files are lost when the container restarts.
-
-```ts
-// WRONG -- files lost on container restart
-storage: { basePath: "/api" }
-
-// CORRECT -- persistent S3 storage
-import { S3Driver } from "flydrive/drivers/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,
-  }),
-}
-```
-
-### MEDIUM: Missing queue adapter for background jobs
-
-Without pg-boss configured, job `.publish()` calls silently do nothing. Jobs defined in `jobs/` will never run.
-
-```ts
-// REQUIRED for jobs to actually execute
-queue: {
-  adapter: pgBossAdapter({
-    connectionString: process.env.DATABASE_URL,
-  }),
-}
-```
-
-## 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.
-
-For the default **same-tab preview**, realtime is NOT involved. Current same-tab preview uses `postMessage` for refresh/focus messages between the editor and the iframe.
-
-| Preview mode        | Transport      | Requires realtime adapter? |
-| ------------------- | -------------- | -------------------------- |
-| Same-tab (default)  | `postMessage`  | No                         |
-| Detached tab        | SSE / realtime | Yes                        |
-| Shared / multi-user | SSE / realtime | Yes                        |
-
-If your app only uses same-tab preview (the default), you do not need to configure a realtime adapter for preview purposes. Configure it when you need detached preview, multi-user collaboration, or other realtime features (live notifications, presence, etc.).
-
-### MEDIUM: Missing APP_URL environment variable
-
-Auth callbacks, email links, and storage URLs all depend on `APP_URL`. Without it, OAuth redirects break and email links point to `localhost`.
-
-```bash
-# WRONG
-# APP_URL not set
-
-# CORRECT
-APP_URL=https://myapp.example.com
-```

package/skills/questpie/references/query-operators.md

@@ -1,125 +0,0 @@
-# Query Operators Reference
-
-Full reference for all `where` clause operators in QUESTPIE CRUD queries.
-
-## Text Fields
-
-Applies to: `text`, `textarea`, `richText`, `email`, `url`, `slug`
-
-| Operator     | Example                           | Description             |
-| ------------ | --------------------------------- | ----------------------- |
-| equality     | `{ title: "Hello" }`              | Exact match (shorthand) |
-| `contains`   | `{ title: { contains: "ell" } }`  | Substring match         |
-| `startsWith` | `{ title: { startsWith: "He" } }` | Prefix match            |
-| `endsWith`   | `{ title: { endsWith: "lo" } }`   | Suffix match            |
-| `in`         | `{ title: { in: ["A", "B"] } }`   | One of values           |
-
-## Number Fields
-
-Applies to: `number`
-
-| Operator | Example                           | Description           |
-| -------- | --------------------------------- | --------------------- |
-| equality | `{ price: 1000 }`                 | Exact match           |
-| `gt`     | `{ price: { gt: 1000 } }`         | Greater than          |
-| `gte`    | `{ price: { gte: 1000 } }`        | Greater than or equal |
-| `lt`     | `{ price: { lt: 5000 } }`         | Less than             |
-| `lte`    | `{ price: { lte: 5000 } }`        | Less than or equal    |
-| `in`     | `{ price: { in: [1000, 2000] } }` | One of values         |
-
-## Boolean Fields
-
-Applies to: `boolean`
-
-| Operator | Example              | Description |
-| -------- | -------------------- | ----------- |
-| equality | `{ isActive: true }` | Exact match |
-
-## Date / DateTime Fields
-
-Applies to: `date`, `dateTime`
-
-| Operator | Example                           | Description  |
-| -------- | --------------------------------- | ------------ |
-| equality | `{ date: "2025-03-01" }`          | Exact match  |
-| `gt`     | `{ date: { gt: "2025-01-01" } }`  | After        |
-| `gte`    | `{ date: { gte: "2025-01-01" } }` | On or after  |
-| `lt`     | `{ date: { lt: "2025-12-31" } }`  | Before       |
-| `lte`    | `{ date: { lte: "2025-12-31" } }` | On or before |
-
-## Select Fields
-
-Applies to: `select`, `multiSelect`
-
-| Operator | Example                                      | Description   |
-| -------- | -------------------------------------------- | ------------- |
-| equality | `{ status: "published" }`                    | Exact match   |
-| `in`     | `{ status: { in: ["draft", "published"] } }` | One of values |
-
-## Relation Fields
-
-Applies to: `relation`
-
-| Operator | Example                 | Description         |
-| -------- | ----------------------- | ------------------- |
-| equality | `{ author: "user-id" }` | Match by related ID |
-
-## Combining Operators
-
-### Multiple Fields (AND)
-
-All top-level fields are combined with AND:
-
-```ts
-where: {
-  status: "published",
-  price: { gte: 1000 },
-  createdAt: { gte: "2025-01-01" },
-}
-// status = "published" AND price >= 1000 AND createdAt >= 2025-01-01
-```
-
-### Multiple Operators on Same Field (AND)
-
-Multiple operators on one field are ANDed together:
-
-```ts
-where: {
-  price: { gte: 1000, lt: 5000 },
-}
-// 1000 <= price < 5000
-```
-
-### Equality Shorthand
-
-Direct values are equivalent to exact match:
-
-```ts
-// These are equivalent:
-where: {
-	status: "published";
-}
-where: {
-	status: {
-		eq: "published";
-	}
-}
-```
-
-## Complete Example
-
-```ts
-const result = await collections.products.find({
-	where: {
-		status: "published",
-		price: { gte: 1000, lte: 50000 },
-		title: { contains: "premium" },
-		category: { in: ["electronics", "software"] },
-		createdAt: { gte: "2025-01-01" },
-	},
-	orderBy: { price: "asc" },
-	limit: 20,
-	offset: 0,
-	with: { category: true },
-});
-```