create-questpie 2.0.2 → 2.0.4

package/skills/questpie/references/workflows.md

@@ -0,0 +1,155 @@
+---
+name: questpie-core/workflows
+description:
+  QUESTPIE durable workflows long-running business processes replay steps sleep waitForEvent invoke compensation cron admin UI workflow service
+  - questpie-core
+---
+
+# Durable Workflows
+
+Use `@questpie/workflows` when business logic spans multiple steps, waits on time or external events, needs retry-safe side effects, or should survive process restarts.
+
+## Install And Register
+
+```bash
+bun add @questpie/workflows
+```
+
+```ts title="modules.ts"
+import { workflowsModule } from "@questpie/workflows/modules/workflows";
+export default [workflowsModule] as const;
+```
+
+`workflowsModule` carries its codegen plugin. Do not also add `workflowsPlugin()` to `questpie.config.ts` unless you are doing a custom module setup that deliberately omits `workflowsModule`.
+
+Runtime options (route access rule — default admin-only — and execution-lease settings) go in plugin-discovered `config/workflows.ts` using the `workflowsConfig()` factory from `@questpie/workflows/server`.
+
+For admin UI pages/widgets, register the client module:
+
+```ts title="questpie/admin/modules.ts"
+import adminClientModule from "@questpie/admin/client-module";
+import { workflowsClientModule } from "@questpie/workflows/client/modules/workflows";
+export default {
+	name: "app-admin" as const,
+	views: { ...adminClientModule.views, ...workflowsClientModule.views },
+	components: {
+		...adminClientModule.components,
+		...workflowsClientModule.components,
+	},
+	fields: { ...adminClientModule.fields, ...workflowsClientModule.fields },
+	pages: { ...adminClientModule.pages, ...workflowsClientModule.pages },
+	widgets: { ...adminClientModule.widgets, ...workflowsClientModule.widgets },
+	blocks: { ...adminClientModule.blocks, ...workflowsClientModule.blocks },
+};
+```
+
+## Define A Workflow
+
+Put workflow definitions in `workflows/*.ts`:
+
+```ts title="workflows/production-order.ts"
+import { workflow } from "@questpie/workflows";
+import { z } from "zod";
+
+export default workflow({
+	name: "production-order",
+	schema: z.object({
+		orderId: z.string(),
+	}),
+	timeout: "7d",
+	handler: async ({ input, step, ctx, log }) => {
+		const order = await step.run("load-order", async () => {
+			return ctx.collections.productionOrders.findOne({
+				where: { id: input.orderId },
+				with: { toy: true },
+			});
+		});
+		if (!order) throw new Error("Production order not found");
+
+		await step.run("reserve-materials", async () => {
+			await ctx.queue.recalculateMaterialPlan.publish({
+				orderId: input.orderId,
+			});
+		});
+
+		await step.waitForEvent("materials-ready", {
+			event: "materials.available",
+			match: { orderId: input.orderId },
+			timeout: "2d",
+		});
+
+		await step.run("notify-scheduled", async () => {
+			await ctx.email.sendTemplate({
+				template: "productionScheduled",
+				input: { orderId: input.orderId },
+				to: order.ownerEmail,
+			});
+		});
+
+		log.info("Production order workflow completed");
+		return { status: "scheduled" };
+	},
+});
+```
+
+Run codegen after adding workflow files:
+
+```bash
+bun questpie generate
+```
+
+## Trigger And Signal
+
+Use injected `workflows` from route, job, hook, or service context:
+
+```ts title="routes/start-production.ts"
+import { route } from "questpie/services";
+import { z } from "zod";
+
+export default route()
+	.post()
+	.schema(z.object({ orderId: z.string() }))
+	.handler(async ({ input, workflows }) => {
+		const result = await workflows.trigger("production-order", {
+			orderId: input.orderId,
+		});
+		return { instanceId: result.instanceId };
+	});
+```
+
+Signal waiting workflows:
+
+```ts
+await workflows.sendEvent(
+	"materials.available",
+	{ receivedAt: new Date().toISOString() },
+	{ orderId },
+);
+```
+
+## Cron Workflows
+
+Use workflow-level `cron` for recurring long-running processes:
+
+```ts
+export default workflow({
+	name: "nightly-material-plan",
+	schema: z.object({}),
+	cron: { schedule: "0 2 * * *", overlap: "skip" },
+	handler: async ({ step, ctx }) => {
+		await step.run("recalculate", async () => {
+			await ctx.queue.recalculateMaterialPlan.publish({});
+		});
+	},
+});
+```
+
+On Node/Bun workers, `app.queue.listen()` runs workflow jobs and maintenance. On Cloudflare Workers, use `cloudflareQueuesAdapter`, export `createCloudflareWorkerHandlers(app)`, and configure a Cron Trigger for workflow maintenance.
+
+## Rules
+
+- Keep external side effects inside `step.run()` so replay does not repeat them.
+- Use stable step names. Renaming a step changes replay identity.
+- Use idempotency keys when calling external APIs.
+- Use `step.waitForEvent()` for durable waits instead of polling loops.
+- Keep workflow definitions in `workflows/`; do not define them inside route/job files.

package/skills/questpie-admin/AGENTS.md

@@ -20,7 +20,8 @@ For the complete admin reference with all topics expanded: `AGENTS.md`
 - **@base-ui/react** primitives (NOT @radix-ui)
 - **@iconify/react** with Phosphor icon set (`ph:icon-name`)
 - **sonner** for toasts — `toast.error()`, `toast.success()`
-- Brutalist flat design: `--radius: 0px`, no shadows
+- QUESTPIE Neutral Design: flat surfaces, soft neutral geometry,
+  tokenized radius, and restrained floating shadows
 
 ## Setup
 
@@ -33,8 +34,7 @@ bun add @questpie/admin
 ### 2. Runtime Config
 
 ```ts title="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 },
@@ -47,7 +47,8 @@ The admin module contributes the codegen plugin automatically. It discovers `con
 ### 3. Modules
 
 ```ts title="modules.ts"
-import { adminModule, auditModule } from "@questpie/admin/server";
+import { adminModule } from "@questpie/admin/modules/admin";
+import { auditModule } from "@questpie/admin/modules/audit";
 
 export default [adminModule, auditModule] as const;
 ```
@@ -57,6 +58,26 @@ export default [adminModule, auditModule] as const;
 | `adminModule` | User collection, auth pages, admin UI |
 | `auditModule` | Audit log collection, timeline widget |
 
+### Auth/User Contract - Critical
+
+`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` with at least `admin` and `user` values. The built-in setup route checks for `role = "admin"`, and the admin `AuthGuard` expects `session.user.role === "admin"`.
+
+Do not create a replacement `collection("user")` from scratch in an app that uses `adminModule`. If the app needs to customize the user admin UI or add fields, merge the starter user collection and extend it:
+
+```ts title="collections/user.ts"
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		// add app-specific user fields here
+		internalNotes: f.textarea(),
+	}));
+```
+
+App-specific authorization tables are fine, but they must not replace or remove the admin user contract unless the app also replaces the built-in admin setup route and auth guard.
+
 ### 4. Admin Config
 
 ```ts title="config/admin.ts"
@@ -129,44 +150,31 @@ export default adminConfig({
 
 The admin uses CSS variables for all theming. Override them in your own CSS file.
 
-### Light Theme (`:root`)
-
-| Variable               | Default   | Purpose                          |
-| ---------------------- | --------- | -------------------------------- |
-| `--background`         | `#FFFFFF` | Page background                  |
-| `--foreground`         | `#0A0A0A` | Primary text                     |
-| `--card`               | `#F8F8F8` | Cards, panels, sidebar           |
-| `--popover`            | `#FFFFFF` | Dropdowns, tooltips, dialogs     |
-| `--muted`              | `#F0F0F0` | Hover states, table headers      |
-| `--muted-foreground`   | `#666666` | Secondary text, placeholders     |
-| `--primary`            | `#B700FF` | Brand accent (CTAs, focus rings) |
-| `--primary-foreground` | `#FFFFFF` | Text on primary backgrounds      |
-| `--destructive`        | `#FF3D57` | Errors, delete actions           |
-| `--success`            | `#00E676` | Positive states                  |
-| `--warning`            | `#FFB300` | Caution states                   |
-| `--info`               | `#40C4FF` | Informational emphasis           |
-| `--border`             | `#E0E0E0` | All structural borders           |
-| `--ring`               | `#B700FF` | Focus ring color                 |
-| `--radius`             | `0px`     | Border radius (0 = brutalist)    |
-
-### Dark Theme (`.dark` class)
-
-Dark mode uses the `.dark` class on the root element. Key overrides:
-
-| Variable       | Dark Value |
-| -------------- | ---------- |
-| `--background` | `#0A0A0A`  |
-| `--foreground` | `#FFFFFF`  |
-| `--card`       | `#111111`  |
-| `--border`     | `#333333`  |
-| `--muted`      | `#1A1A1A`  |
+The full source of truth is `packages/admin/DESIGN.md`. Key defaults:
+
+| Role          | Dark      | Light     |
+| ------------- | --------- | --------- |
+| Background    | `#121212` | `#fafafa` |
+| Foreground    | `#ececec` | `#1c1c1c` |
+| Card          | `#1b1b1b` | `#ffffff` |
+| Surface high  | `#2a2a2a` | `#e8e8e8` |
+| Border        | `#343434` | `#e2e2e2` |
+| Border subtle | `#262626` | `#ebebeb` |
+| Brand primary | `#b700ff` | `#b700ff` |
+
+| Token                    | Default | Use                                         |
+| ------------------------ | ------- | ------------------------------------------- |
+| `--control-radius-inner` | `8px`   | Icon buttons/actions nested inside controls |
+| `--control-radius`       | `12px`  | Inputs, selects, buttons, compact controls  |
+| `--surface-radius`       | `14px`  | Cards, panels, grouped fields, docs blocks  |
+| `--floating-radius`      | `14px`  | Menus, popovers, dialogs, command panels    |
 
 ### Typography
 
 | Variable      | Value                                                               |
 | ------------- | ------------------------------------------------------------------- |
-| `--font-sans` | `"Geist Variable"` — body text, descriptions                        |
-| `--font-mono` | `"JetBrains Mono Variable"` — UI chrome: nav, buttons, tabs, badges |
+| `--font-sans` | `"Geist Variable"` — UI, prose, headings, labels, navigation        |
+| `--font-mono` | `"JetBrains Mono Variable"` — code, file paths, commands, IDs       |
 
 ### Sidebar Variables
 
@@ -184,8 +192,7 @@ Separate tokens for independent sidebar theming: `--sidebar`, `--sidebar-foregro
 When collections have `.localized()` fields, the admin shows a locale switcher:
 
 ```ts title="config/app.ts"
-import { appConfig } from "questpie";
-
+import { appConfig } from "questpie/app";
 export default appConfig({
 	locale: {
 		locales: [
@@ -213,9 +220,9 @@ The admin renders drag-and-drop upload, image preview, file info, and remove but
 
 ## Live Preview
 
-Live Preview uses a split-screen iframe. The current implementation refreshes the iframe after save/autosave and uses `postMessage` for field/block focus sync.
+Live Preview is one system: the existing collection `FormView`, Preview button, `LivePreviewMode`, and frontend iframe. Preserve the normal form lifecycle. Do not introduce a separate visual-edit form API, a second default form view, or a parallel preview surface.
 
-Preview V2 patch-based docs are design notes until `useQuestpiePreview`, `PreviewRoot`, and `PreviewBlock` are exported.
+The admin form is authoritative. The iframe mirrors form state through `postMessage`, supports field/block focus, and may request inline scalar edits. Persistence still goes through existing save, autosave, Cmd+S, history, workflow, locks, and actions.
 
 ### Server Config
 
@@ -239,35 +246,57 @@ export const pages = collection("pages")
 	});
 ```
 
-Current preview refreshes the iframe after save/autosave and supports field focus through `postMessage`.
+Preview opens the existing split-screen editor. Patches and refresh/resync messages update the iframe mirror; save/autosave still writes through the form.
+
+### Prepare a Frontend Page
 
-### Frontend Integration
+Use exported APIs only: `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and `BlockRenderer`.
 
-Use `useCollectionPreview` with `PreviewProvider` and `PreviewField`:
+Checklist:
+
+1. Configure `.preview({ url })` on the collection.
+2. Load the same record shape the page normally renders.
+3. For workflow-published pages, public reads use `stage: "published"`; if the public client/HTTP API is exposed, anonymous read access also checks `input?.stage === "published"`. Authorized preview/draft reads can load the working record.
+4. Call `useCollectionPreview({ initialData, onRefresh })` in the page renderer.
+5. Wrap the visual output in `PreviewProvider`.
+6. Render from `preview.data`, not the original loader object.
+7. Wrap editable scalar text with `PreviewField field="..." editable="text" | "textarea"`.
+8. Render block content with `BlockRenderer`; pass `selectedBlockId` and `onBlockClick`.
+9. Keep add/remove/reorder/nesting block operations in the existing block editor.
 
 ```tsx
 import {
+	BlockRenderer,
 	PreviewField,
 	PreviewProvider,
 	useCollectionPreview,
 } from "@questpie/admin/client";
+import admin from "@/questpie/admin/.generated/client";
 
-function PagePreview({ initialData }) {
+function PagePreview({ 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">
-				{preview.data.title}
-			</PreviewField>
+		<PreviewProvider preview={preview}>
+			<main className={preview.isPreviewMode ? "questpie-preview" : undefined}>
+				<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
+					}
+				/>
+			</main>
 		</PreviewProvider>
 	);
 }
@@ -275,11 +304,15 @@ function PagePreview({ initialData }) {
 
 ### Key Principles
 
-- Current preview = save/autosave refresh plus field/block focus sync
-- `useCollectionPreview` sends `PREVIEW_READY`, `FIELD_CLICKED`, and `BLOCK_CLICKED`
+- Keep `FormView`, the Preview button, and `LivePreviewMode`
+- Never add a separate visual-edit form API, a second default form view, or parallel preview API names
+- Preserve save/autosave/Cmd+S/history/workflow/locks/actions
+- `useCollectionPreview` handles preview mode, mirrored data, refresh/resync, and focus state
 - `PreviewProvider` supplies preview context to `PreviewField`
-- Each message carries `sessionId`, `seq`, `timestamp`, `protocolVersion`
-- Preview wrappers must prevent accidental navigation in the iframe
+- `PreviewField` annotates scalar fields and can opt into inline editing with `editable`
+- `BlockRenderer` preserves block IDs and block scopes for block annotations
+- Use `BlockScopeProvider` only for custom/manual block rendering outside `BlockRenderer`
+- Validate all iframe messages before updating form state
 
 ## History & Versions
 
@@ -560,7 +593,7 @@ Section-level visibility:
 {
   type: "section",
   label: { en: "SEO" },
-  hidden: ({ data }) => !data.isPublished,
+  hidden: ({ data }) => !data.showSeo,
   fields: [f.metaTitle, f.metaDescription],
 }
 ```
@@ -803,7 +836,7 @@ export const logs = collection("logs")
 
 ## Form Views and Live Preview
 
-Form views connect to the Live Preview V2 system when the collection has `.preview()` configured. The form editor becomes the source of `postMessage` patches — every field change emits a patch through the bus, giving the preview iframe instant updates.
+Form views connect to the existing Live Preview system when the collection has `.preview()` configured. Keep `v.collectionForm()` as the form surface; do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names. The form editor remains the source of patches, refreshes, commits, and resyncs.
 
 ### Enabling Preview on a Collection
 
@@ -827,9 +860,25 @@ export const pages = collection("pages")
 ### How It Works
 
 1. The form view detects `.preview()` config and opens a split-screen layout
-2. Save/autosave sends a `PREVIEW_REFRESH` message to the preview iframe
-3. The preview page handles refreshes through `useCollectionPreview({ initialData, onRefresh })`
-4. `PreviewProvider` and `PreviewField` wire field focus and click-to-focus messages
+2. The preview iframe mirrors form state with snapshot, patch, refresh, commit, and resync messages
+3. Save/autosave/Cmd+S/history/workflow/locks/actions stay in the form lifecycle
+4. The preview page uses `useCollectionPreview({ initialData, onRefresh })`
+5. `PreviewProvider`, `PreviewField`, and `BlockRenderer` wire field and block annotations
+
+### Frontend Preparation Checklist
+
+Use this checklist before expecting visual editing to work:
+
+1. The collection has `.preview({ url })`.
+2. The page loader returns the complete rendered record shape.
+3. Public workflow reads use `stage: "published"`; if public client/HTTP access is enabled, anonymous read access also requires `input?.stage === "published"`. Preview/draft-mode reads load the working record for authorized editors.
+4. The page renderer calls `useCollectionPreview({ initialData, onRefresh })`.
+5. The rendered page is wrapped in `PreviewProvider preview={preview}`.
+6. UI reads from `preview.data`, not directly from loader data.
+7. Scalar text uses `PreviewField field="..." editable="text" | "textarea"` when inline editing is expected.
+8. Blocks render through `BlockRenderer` with `selectedBlockId` and `onBlockClick`.
+9. `BlockScopeProvider` is only needed for custom/manual block rendering outside `BlockRenderer`.
+10. Add/remove/reorder/nesting block operations stay in the existing block editor.
 
 ---
 
@@ -1111,11 +1160,35 @@ function PageRenderer({ page }) {
 
 ## Blocks in Live Preview
 
-When a collection has `.preview()` configured, blocks can participate in preview focus by combining `BlockScopeProvider` with `PreviewField`.
+When a collection has `.preview()` configured, blocks participate in the existing Live Preview system through `BlockRenderer` and `PreviewField`. The form remains authoritative; block annotations only mirror values, focus fields, select blocks, or request inline scalar edits.
+
+### Preferred: BlockRenderer
+
+Use `BlockRenderer` for normal frontend page rendering. It preserves `data-block-id`, routes block selection, and scopes nested `PreviewField` paths automatically.
+
+```tsx
+<BlockRenderer
+	content={preview.data.content}
+	data={preview.data.content?._data}
+	renderers={admin.blocks}
+	selectedBlockId={preview.selectedBlockId}
+	onBlockClick={preview.isPreviewMode ? preview.handleBlockClick : undefined}
+/>
+```
+
+Inside custom block renderers, annotate scalar values with `PreviewField`:
+
+```tsx
+<PreviewField field="title" editable="text" as="h2">
+	{values.title}
+</PreviewField>
+```
+
+This resolves to `content._values.{blockId}.title` when rendered inside `BlockRenderer`.
 
-### BlockScopeProvider Wrapper
+### Manual BlockScopeProvider Wrapper
 
-Use `BlockScopeProvider` in your frontend to scope field paths inside a block:
+Use `BlockScopeProvider` only when you manually render blocks outside `BlockRenderer`:
 
 ```tsx
 import { BlockScopeProvider } from "@questpie/admin/client";
@@ -1134,7 +1207,7 @@ function PageRenderer({ blocks, previewData }) {
 
 `PreviewField` components inside the provider resolve paths like `content._values.{blockId}.title`.
 
-Blocks with declarative prefetch (`{ with: { image: true } }`) resolve relations during reconcile — the preview shows the image URL immediately after the server round-trip completes, not just the asset ID.
+Inline block edits target `_values`, for example `content._values.<blockId>.title`. Tree edits such as add, remove, reorder, and nesting stay in the existing block editor and should trigger refresh or resync when patching is not safe.
 
 ---
 
@@ -1437,6 +1510,6 @@ toast.error("Failed to save");
 
 6. **MEDIUM: Using `@phosphor-icons/react` or `lucide-react`** — use `@iconify/react` with `ph:` prefix for all icons.
 
-7. **LOW: Not using shadcn components** — prefer `<Button>`, `<Card>`, `<Input>` from the shadcn component library instead of raw HTML elements. The admin has a consistent brutalist design system.
+7. **LOW: Not using shadcn components** — prefer `<Button>`, `<Card>`, `<Input>` from the shadcn component library instead of raw HTML elements. The admin follows QUESTPIE Neutral Design.
 
 ---