create-questpie 2.0.4 → 2.1.0

package/skills/questpie/references/mcp.md

@@ -1,147 +0,0 @@
-# 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

@@ -1,363 +0,0 @@
----
-name: questpie-core-multi-tenancy
-description: QUESTPIE multi-tenant scope context resolver header-based tenant isolation ScopeProvider ScopePicker request-scoped services data filtering access control workspace organization property
-  - questpie-core
-  - questpie-core-rules
-  - questpie-core-business-logic
----
-
-# QUESTPIE Multi-Tenancy
-
-QUESTPIE supports multi-tenant applications through a **scope-based** architecture. A "scope" can represent anything: organizations, workspaces, properties, cities, brands — any entity that partitions data.
-
-The pattern is simple: **HTTP header carries a scope ID, server extracts it into typed context, access rules filter data**.
-
-## Architecture Overview
-
-```text
-Client                          Server
-──────                          ──────
-ScopeProvider                   context.ts (file convention)
-  ↓ stores scopeId                ↓ extracts header → typed context
-ScopePicker (UI)                appConfig({ context }) (types)
-  ↓ user selects scope            ↓ available in every handler
-useScopedFetch()                access rules / hooks
-  ↓ injects HTTP header           ↓ filter data by scope
-fetch("x-selected-city: id")   AsyncLocalStorage → getContext()
-```
-
-## Step 1: Define the Scope Collection
-
-Create a collection that represents your tenant entity:
-
-```ts
-// collections/workspaces.ts
-import { collection } from "#questpie/factories";
-
-export default collection("workspaces").fields(({ f }) => ({
-	name: f.text().label("Name").required(),
-	slug: f.text().label("Slug").inputOptional(),
-	owner: f.relation("user").label("Owner"),
-}));
-```
-
-Other collections reference the scope via a relation:
-
-```ts
-// collections/projects.ts
-import { collection } from "#questpie/factories";
-
-export default collection("projects").fields(({ f }) => ({
-	title: f.text().label("Title").required(),
-	workspace: f.relation("workspaces").label("Workspace").required(),
-}));
-```
-
-## Step 2: Create the Context Resolver
-
-The `context.ts` file convention is a singleton that extracts custom properties from each incoming request. Codegen discovers it automatically.
-
-```ts
-// src/questpie/server/context.ts
-import { context } from "#questpie";
-
-export default context(async ({ request, session, db }) => {
-	const workspaceId = request.headers.get("x-selected-workspace");
-
-	// Optional: validate that the user has access to this workspace
-	// if (workspaceId && session?.user) {
-	//   const membership = await db.query.workspaceMembers.findFirst({
-	//     where: and(
-	//       eq(workspaceMembers.workspaceId, workspaceId),
-	//       eq(workspaceMembers.userId, session.user.id),
-	//     ),
-	//   });
-	//   if (!membership) throw new Error("No access to this workspace");
-	// }
-
-	return {
-		workspaceId: workspaceId || null,
-	};
-});
-```
-
-### Context Resolver Parameters
-
-| Parameter | Type                        | Description                                     |
-| --------- | --------------------------- | ----------------------------------------------- |
-| `request` | `Request`                   | The incoming HTTP request (Web API)             |
-| `session` | `{ user, session } \| null` | Resolved auth session (null if unauthenticated) |
-| `db`      | `Database`                  | Database client for validation queries          |
-
-The object you return is merged into the request context and becomes available in **every** handler, hook, and access rule.
-
-## Step 3: Filter Data with Access Rules
-
-Use the typed context in access rules and hooks to enforce data isolation:
-
-```ts
-// collections/projects.ts
-import { collection } from "#questpie/factories";
-
-export default collection("projects")
-	.fields(({ f }) => ({
-		title: f.text().label("Title").required(),
-		workspace: f.relation("workspaces").label("Workspace").required(),
-	}))
-	.access({
-		// Only allow reads when a workspace is selected
-		read: ({ ctx }) => {
-			if (!ctx.workspaceId) return false;
-			return { workspace: ctx.workspaceId };
-		},
-		create: ({ ctx }) => !!ctx.workspaceId,
-		update: ({ ctx }) => {
-			if (!ctx.workspaceId) return false;
-			return { workspace: ctx.workspaceId };
-		},
-		delete: ({ ctx }) => {
-			if (!ctx.workspaceId) return false;
-			return { workspace: ctx.workspaceId };
-		},
-	})
-	.hooks({
-		// Auto-assign workspace on create
-		beforeChange: async ({ data, operation, ctx }) => {
-			if (operation === "create" && ctx.workspaceId) {
-				data.workspace = ctx.workspaceId;
-			}
-			return data;
-		},
-	});
-```
-
-### Access Rule Return Values
-
-| Return                         | Meaning                                  |
-| ------------------------------ | ---------------------------------------- |
-| `true`                         | Allow all records                        |
-| `false`                        | Deny all records                         |
-| `{ field: value }` | Where-clause filter (row-level security) |
-
-## Step 5: Set Up the Admin UI
-
-### ScopeProvider
-
-Wrap your admin with `ScopeProvider` to enable scope selection. It manages the selected scope ID and persists it to localStorage.
-
-```tsx
-// routes/admin/$.tsx
-import {
-	AdminLayout,
-	AdminRouter,
-	ScopePicker,
-	ScopeProvider,
-} from "@questpie/admin/client";
-
-function AdminPage() {
-	return (
-		<ScopeProvider
-			headerName="x-selected-workspace"
-			storageKey="admin-selected-workspace"
-		>
-			<AdminContent />
-		</ScopeProvider>
-	);
-}
-```
-
-#### ScopeProvider Props
-
-| Prop           | Type             | Required | Description                       |
-| -------------- | ---------------- | -------- | --------------------------------- |
-| `headerName`   | `string`         | Yes      | HTTP header name for the scope ID |
-| `storageKey`   | `string`         | No       | localStorage key for persistence  |
-| `defaultScope` | `string \| null` | No       | Default scope if none stored      |
-
-### ScopePicker
-
-A dropdown for selecting the current scope. Place it in the sidebar:
-
-```tsx
-function AdminContent() {
-	return (
-		<AdminLayout
-			admin={admin}
-			basePath="/admin"
-			slots={{
-				afterBrand: (
-					<div className="px-3 py-2 border-b">
-						<ScopePicker
-							collection="workspaces"
-							labelField="name"
-							placeholder="Select workspace..."
-							allowClear
-							clearText="All Workspaces"
-							compact
-						/>
-					</div>
-				),
-			}}
-		>
-			<AdminRouter basePath="/admin" />
-		</AdminLayout>
-	);
-}
-```
-
-#### ScopePicker Props
-
-| Prop          | Type                           | Default       | Description                                |
-| ------------- | ------------------------------ | ------------- | ------------------------------------------ |
-| `collection`  | `string`                       | —             | Collection to fetch options from           |
-| `labelField`  | `string`                       | `"name"`      | Field to display as label                  |
-| `valueField`  | `string`                       | `"id"`        | Field to use as value                      |
-| `options`     | `ScopeOption[]`                | —             | Static options (alternative to collection) |
-| `loadOptions` | `() => Promise<ScopeOption[]>` | —             | Async options loader                       |
-| `placeholder` | `string`                       | `"Select..."` | Placeholder text                           |
-| `allowClear`  | `boolean`                      | `false`       | Show "All" option to clear scope           |
-| `clearText`   | `string`                       | `"All"`       | Label for the clear option                 |
-| `compact`     | `boolean`                      | `false`       | Render smaller (no label)                  |
-
-### Three Data Sources
-
-```tsx
-// 1. From a collection
-<ScopePicker collection="workspaces" labelField="name" />
-
-// 2. Static options
-<ScopePicker options={[
-  { value: "ws_1", label: "Workspace 1" },
-  { value: "ws_2", label: "Workspace 2" },
-]} />
-
-// 3. Async loader
-<ScopePicker loadOptions={async () => {
-  const res = await fetch("/api/my-workspaces");
-  return res.json();
-}} />
-```
-
-### useScopedFetch
-
-When you need to create the API client, use `useScopedFetch()` to automatically inject the scope header into all requests:
-
-```tsx
-import { useScopedFetch } from "@questpie/admin/client";
-
-function AdminContent() {
-	const scopedFetch = useScopedFetch();
-
-	const client = useMemo(
-		() => createClient<typeof app>({ baseURL: "/api", fetch: scopedFetch }),
-		[scopedFetch],
-	);
-
-	return <AdminProvider client={client} />;
-}
-```
-
-### createScopedFetch (Non-React)
-
-For use outside React components:
-
-```ts
-import { createScopedFetch } from "@questpie/admin/client";
-
-let currentScopeId: string | null = null;
-
-const scopedFetch = createScopedFetch(
-	"x-selected-workspace",
-	() => currentScopeId,
-);
-```
-
-## Request-Scoped Services
-
-For advanced cases, create a request-scoped service that provides a tenant-aware database connection:
-
-```ts
-// services/scoped-db.ts
-import { service } from "questpie/services";
-export default service({
-	lifecycle: "request",
-	deps: ["db", "session"] as const,
-	create: ({ db, session }) => {
-		return createScopedDb(db, session?.user?.tenantId);
-	},
-	dispose: (scopedDb) => scopedDb.release(),
-});
-```
-
-## Full Request Flow
-
-```text
-1. User selects "Acme Corp" in ScopePicker
-2. ScopeProvider stores scopeId = "ws_123" in state + localStorage
-3. useScopedFetch() creates fetch that adds header: x-selected-workspace: ws_123
-4. Client makes API call → POST /api/collections/projects/find
-5. Server: createAdapterContext() receives Request
-6. Server: context.ts resolver extracts workspaceId = "ws_123" from header
-7. Server: RequestContext created with { workspaceId: "ws_123", session, locale, ... }
-8. Server: runWithContext() stores in AsyncLocalStorage
-9. Server: Access rules evaluate → return { workspace: "ws_123" }
-10. Server: Query filtered to workspace = "ws_123"
-11. Response: Only Acme Corp's projects returned
-```
-
-## Common Mistakes
-
-### HIGH: Forgetting module augmentation
-
-Without a `context` function in `appConfig()`, your custom context properties won't be available in handlers. Make sure to define `context` in your `config/app.ts`.
-
-### HIGH: Not filtering in access rules
-
-The context resolver only **extracts** the scope. You must still enforce isolation in `.access()` rules or `.hooks()`. Without access rules, all data is returned regardless of scope.
-
-### MEDIUM: Hardcoding header names
-
-Use the same header name in `ScopeProvider.headerName` and `context.ts`. A mismatch means the server never sees the scope ID.
-
-```ts
-// These MUST match:
-// Client:
-<ScopeProvider headerName="x-selected-workspace" />
-
-// Server (context.ts):
-request.headers.get("x-selected-workspace")
-```
-
-### MEDIUM: Not validating scope access
-
-In production, validate that the authenticated user actually belongs to the selected scope. Otherwise any user can access any scope by sending the header manually.
-
-```ts
-export default context(async ({ request, session, db }) => {
-	const workspaceId = request.headers.get("x-selected-workspace");
-
-	if (workspaceId && session?.user) {
-		const isMember = await db.query.workspaceMembers.findFirst({
-			where: and(
-				eq(workspaceMembers.workspaceId, workspaceId),
-				eq(workspaceMembers.userId, session.user.id),
-			),
-		});
-		if (!isMember) {
-			throw new Error("Unauthorized access to workspace");
-		}
-	}
-
-	return { workspaceId: workspaceId || null };
-});
-```
-
-## Reference Example
-
-See the **city-portal** example for a complete working implementation:
-
-```text
-examples/city-portal/
-  src/questpie/server/context.ts       # Context resolver (x-selected-city header)
-  src/routes/admin/$.tsx               # Admin with ScopeProvider + ScopePicker
-```