@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/writeform-section.md

@@ -0,0 +1,300 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/writeform-section. Do not edit. -->
+
+# writeform-section
+
+A projectionDetail `writeForm` section rendered beside an established entityEdit form on the same page, so the shared form chrome (footer, submit affordance) between the two can be verified side by side.
+
+## README
+
+# WriteForm Section
+
+Register a `projectionDetail` screen with a `kind: "writeForm"` section: a
+self-persisting form embedded inside a record detail page, next to the
+established `entityEdit` form for the same fields — so the two form kinds'
+shared chrome (footer, submit button) can be compared side by side.
+
+## What it shows
+
+- `note-edit`, an `entityEdit` screen with one `title`/`category`/`priority`/
+  `body` section
+- `note-detail`, a `projectionDetail` screen whose only section is
+  `kind: "writeForm"` with the identical field set, dispatching its own
+  `note-desk:write:note:comment` handler on submit
+- an e2e layout-parity spec (`e2e/writeform-parity.spec.ts`) proving both
+  submit buttons render the same width, sit right-aligned in their form's
+  footer, and never stretch full-width — the regression this recipe guards
+  against (fw#2681)
+
+## Source
+
+Feature entry point: `src/feature.ts`.
+
+## Tests
+
+```bash
+cd samples/recipes/writeform-section
+bun test
+bun run e2e         # layout-parity spec + regenerates the committed screenshot
+```
+
+## Source files
+
+### src/__tests__/feature.test.ts
+
+```ts
+// WriteForm Section Sample — Unit Test (no DB / HTTP needed).
+// Proves:
+//   - note-desk boots clean (r.translations covers the writeForm
+//     pseudo-entity keys required by fw editable-detail-screens)
+//   - the writeForm section's field list on note-detail is identical to
+//     the entityEdit section's field list on note-edit — the precondition
+//     for the e2e layout-parity comparison between the two forms
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRegistry,
+  createTextField,
+  defineFeature,
+  validateBoot as validateBootRaw,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-framework/testing";
+import { z } from "zod";
+import { noteDeskFeature } from "../feature";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+function fieldName(spec: string | { readonly field: string }): string {
+  return typeof spec === "string" ? spec : spec.field;
+}
+
+const registry = createRegistry([noteDeskFeature]);
+
+describe("writeform-section sample — registration", () => {
+  test("validateBoot accepts the full registered app", () => {
+    expect(() => validateBoot([noteDeskFeature])).not.toThrow();
+  });
+
+  test("note-edit registers as entityEdit with one fields section", () => {
+    const screen = registry.getScreen("note-desk:screen:note-edit");
+    if (screen?.type !== "entityEdit") throw new Error("expected entityEdit");
+    expect(screen.layout.sections).toHaveLength(1);
+    expect(screen.layout.sections[0]?.kind).toBeUndefined();
+  });
+
+  test("note-detail registers as projectionDetail with one writeForm section", () => {
+    const screen = registry.getScreen("note-desk:screen:note-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    expect(screen.layout.sections).toHaveLength(1);
+    expect(screen.layout.sections[0]?.kind).toBe("writeForm");
+  });
+
+  test("the writeForm section and the entityEdit section render the same field list", () => {
+    const editScreen = registry.getScreen("note-desk:screen:note-edit");
+    const detailScreen = registry.getScreen("note-desk:screen:note-detail");
+    if (editScreen?.type !== "entityEdit") throw new Error("expected entityEdit");
+    if (detailScreen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+
+    const editSection = editScreen.layout.sections[0];
+    const detailSection = detailScreen.layout.sections[0];
+    if (
+      editSection === undefined ||
+      editSection.kind === "extension" ||
+      editSection.kind === "relatedList" ||
+      detailSection?.kind !== "writeForm"
+    ) {
+      throw new Error("expected an entityEdit fields section and a writeForm section");
+    }
+
+    const editFields = editSection.fields.map(fieldName);
+    const writeFormFields = detailSection.fields.map(fieldName);
+    expect(writeFormFields).toEqual(editFields);
+  });
+
+  test("the writeForm section's fieldDefs cover every field it renders", () => {
+    const detailScreen = registry.getScreen("note-desk:screen:note-detail");
+    if (detailScreen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    const section = detailScreen.layout.sections[0];
+    if (section?.kind !== "writeForm") throw new Error("expected writeForm section");
+    for (const spec of section.fields) {
+      expect(Object.keys(section.fieldDefs)).toContain(fieldName(spec));
+    }
+  });
+});
+
+describe("writeform-section sample — boot-validator catches author mistakes", () => {
+  test("a writeForm field without its pseudo-entity translation key fails boot", () => {
+    const broken = defineFeature("broken-note-desk", (r) => {
+      r.translations({ keys: { "screen:x.title": { en: "X" } } });
+      r.queryHandler("foo:detail", z.object({ id: z.string() }), async () => ({}), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.writeHandler("save", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "x",
+        type: "projectionDetail",
+        query: "broken-note-desk:query:foo:detail",
+        layout: {
+          sections: [
+            {
+              kind: "writeForm",
+              title: "s",
+              fieldDefs: { name: createTextField({ personal: false, reason: "is_business_data" }) },
+              fields: ["name"],
+              handler: "broken-note-desk:write:save",
+            },
+          ],
+        },
+      });
+    });
+
+    expect(() => validateBootRaw([broken])).toThrow(
+      '[i18n] Feature "broken-note-desk": required translation key missing: "broken-note-desk:entity:__write-form-section__:field:name"',
+    );
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// WriteForm Section Sample
+// Shows: a projectionDetail screen's `kind: "writeForm"` section — a
+// self-persisting form embedded in a record detail page — rendered next to
+// an established `entityEdit` form for the same fields. That side-by-side
+// placement (see e2e/fixtures/client.tsx) is what makes a layout-parity
+// comparison between the two form kinds possible.
+
+import {
+  createEntity,
+  createNumberField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { NOTE_DETAIL_FIELDS } from "./note-fixture";
+
+const NOTE_CATEGORIES = ["question", "bug", "idea"] as const;
+
+const BODY_NOT_PERSONAL = {
+  personal: false,
+  reason: "is_business_data",
+} as const;
+
+// Shared by the entityEdit form and the writeForm section so the parity
+// comparison can't drift through one-sided edits.
+const NOTE_FIELDS = {
+  title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+  body: createTextField(BODY_NOT_PERSONAL),
+  category: createSelectField({ options: NOTE_CATEGORIES, default: "question" }),
+  priority: createNumberField(),
+};
+
+const noteEntity = createEntity({
+  table: "read_sample_writeform_notes",
+  fields: NOTE_FIELDS,
+});
+
+const open = {
+  access: {
+    openToAll: {
+      reason:
+        "demo recipe: any signed-in user manages every note; there is no per-user ownership in this sample",
+    },
+  },
+} as const;
+
+const commentPayloadSchema = z.object({
+  title: z.string().optional(),
+  body: z.string().optional(),
+  category: z.enum(NOTE_CATEGORIES).optional(),
+  priority: z.number().optional(),
+});
+
+export const noteDeskFeature = defineFeature("note-desk", (r) => {
+  r.translations({
+    keys: {
+      "screen:note-edit.title": { en: "Edit note" },
+      "screen:note-detail.title": { en: "Note" },
+      "note-desk:entity:note:field:title": { en: "Title" },
+      "note-desk:entity:note:field:body": { en: "Body" },
+      "note-desk:entity:note:field:category": { en: "Category" },
+      "note-desk:entity:note:field:priority": { en: "Priority" },
+      "note-desk:entity:__write-form-section__:field:title": { en: "Title" },
+      "note-desk:entity:__write-form-section__:field:body": { en: "Body" },
+      "note-desk:entity:__write-form-section__:field:category": { en: "Category" },
+      "note-desk:entity:__write-form-section__:field:priority": { en: "Priority" },
+    },
+  });
+
+  r.crud("note", noteEntity, { write: open, read: open });
+
+  r.screen({
+    id: "note-edit",
+    type: "entityEdit",
+    entity: "note",
+    layout: {
+      sections: [
+        {
+          title: "Note",
+          columns: 2,
+          fields: [{ field: "title", span: 2 }, "category", "priority", { field: "body", span: 2 }],
+        },
+      ],
+    },
+    access: open.access,
+  });
+
+  r.queryHandler(
+    "note:summary",
+    z.object({ id: z.string() }),
+    async (query) => ({ id: query.payload.id, ...NOTE_DETAIL_FIELDS }),
+    open,
+  );
+
+  r.writeHandler(
+    "note:comment",
+    commentPayloadSchema,
+    async () => ({ isSuccess: true as const, data: null }),
+    open,
+  );
+
+  r.screen({
+    id: "note-detail",
+    type: "projectionDetail",
+    query: "note-desk:query:note:summary",
+    layout: {
+      sections: [
+        {
+          // Same field set as note-edit's section — that's what makes the
+          // two forms comparable in the e2e layout-parity spec.
+          kind: "writeForm",
+          title: "Add comment",
+          columns: 2,
+          fieldDefs: NOTE_FIELDS,
+          fields: [{ field: "title", span: 2 }, "category", "priority", { field: "body", span: 2 }],
+          handler: "note-desk:write:note:comment",
+        },
+      ],
+    },
+    access: open.access,
+  });
+});
+```
+
+### src/note-fixture.ts
+
+```ts
+// Server-free on purpose: the e2e mock dispatcher (browser bundle) imports
+// this, so it must not pull in the feature's server-side code.
+export const NOTE_DETAIL_FIELDS = {
+  title: "Sample note",
+  category: "question",
+  priority: 2,
+  body: "...",
+};
+```

package/agents/examples.md

@@ -0,0 +1,74 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/*/package.json. Do not edit. -->
+
+# Examples
+
+| Example | Description | File |
+| --- | --- | --- |
+| `access-control` | Default-deny access rules, openToAll vs. role-based handlers, and auto-indices for foreign keys. | `examples/access-control.md` |
+| `anonymous-access` | Public endpoints (anonymous role) for shop / CMS-style apps. Tenant resolution via header, cookie, or default. | `examples/anonymous-access.md` |
+| `anonymous-access-multitenant` | Subdomain-based tenant resolution for anonymous-access — SaaS shop / CMS pattern with per-tenant public surface. | `examples/anonymous-access-multitenant.md` |
+| `apex-landing` | Apex landing page composed from other features — hero copy from template-resolver, prices and caps from tier-engine — rendered to one static HTML string. | `examples/apex-landing.md` |
+| `apex-surface-auth` | Apex-Surface: öffentliche Account-Flows (Login/Register/PW/Löschen) via createPublicSurface + AuthShell, inkl. anonymem email-verifiziertem Deletion-Flow. | `examples/apex-surface-auth.md` |
+| `api-worker-split` | Split deploy topology: API process (runSingleInstance:false, enqueue-only) + worker process (consumes worker-lane jobs, applies multiStreamProjections, writes results back through the worker dispatcher). | `examples/api-worker-split.md` |
+| `auth-claims` | r.authClaims() — features contribute identity facts into the JWT at login time with auto-prefixed keys. | `examples/auth-claims.md` |
+| `auth-foundation-providers` | Register custom tenantResolver / tenantExistence via auth-foundation extension points (no anonymousAccess callbacks). | `examples/auth-foundation-providers.md` |
+| `auth-mfa` | createAuthMfaFeature — TOTP/2FA enrollment, login challenge, and recovery codes wired into auth-email-password. | `examples/auth-mfa.md` |
+| `basic-entity` | The simplest possible CRUD demo. About six lines of actual code. | `examples/basic-entity.md` |
+| `boot-check` | A feature declares its own mount-invariant via r.bootCheck. | `examples/boot-check.md` |
+| `chat-channels` | Chat channels. Delivery notifications to Slack, minus the browser tab. | `examples/chat-channels.md` |
+| `compliance-profiles-demo` | Two-tenant demo: EU + Swiss compliance profiles deliver different authority contacts, languages, and grace periods through the same App-code. | `examples/compliance-profiles-demo.md` |
+| `cross-feature-events` | Feature appends a typed domain event via ctx.appendEvent; a r.multiStreamProjection reacts asynchronously. | `examples/cross-feature-events.md` |
+| `crypto-shredding-hr` | Crypto-shredding: PII fields encrypted per subject key; forgetting the subject erases the key and every field it protected. | `examples/crypto-shredding-hr.md` |
+| `currencies-global` | Shared money fields across tenants. Commas still matter. | `examples/currencies-global.md` |
+| `currencies-per-tenant` | Tenant-scoped money fields. Commas matter. | `examples/currencies-per-tenant.md` |
+| `custom-fields-basic` | Tenant-defined extra fields on an entity without writing migrations. | `examples/custom-fields-basic.md` |
+| `custom-handlers` | Beyond CRUD — when your domain refuses to fit a table. | `examples/custom-handlers.md` |
+| `delivery-notifications` | Delivery flows plus notifications. Package tracking, minus the tracking. | `examples/delivery-notifications.md` |
+| `designer-demo` | Kumiko sample feature — scaffolded by `bun kumiko create` | `examples/designer-demo.md` |
+| `e2e-generator` | generateE2ESpec + withBootValidatorFixture — Registry → JSON-Specs für externen Playwright-Worker. Zeigt die 4 Test-Kinds, Feldtyp→Interaktion-Mapping und welche Feldtypen heute noch nicht generisch unterstützt sind. | `examples/e2e-generator.md` |
+| `embedded` | Embedded fields on entities. Structured JSON without the JSON part. | `examples/embedded.md` |
+| `embedded-entity-form` | RenderEdit hosted in a Drawer, no screen or route — externally-sourced prefill, controlled mode, and a custom write handler instead of the built-in CRUD create. | `examples/embedded-entity-form.md` |
+| `encrypted-tenant-config` | Per-tenant secrets via config-key encryption — Stripe-API-key pattern. | `examples/encrypted-tenant-config.md` |
+| `error-contract` | Typed errors on the wire. With snake_case reasons, because we care. | `examples/error-contract.md` |
+| `event-sourcing` | Production-pattern ES sample: r.defineEvent (versioned + migrations) + ctx.appendEvent + r.projection + r.multiStreamProjection + ctx.loadAggregate (asOf) + ctx.archiveStream + ctx.queryProjection. | `examples/event-sourcing.md` |
+| `feature-toggles` | Runtime feature-toggle flip — two toggleable features, one registers a cross-feature hook on the other; disabling either has the documented effect without reboot. | `examples/feature-toggles.md` |
+| `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
+| `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
+| `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
+| `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
+| `inbound-mail-triage` | Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint. | `examples/inbound-mail-triage.md` |
+| `lane-routing` | runIn lane-routing: r.job pinned to api/worker deploy-lanes, event-chain via ctx.appendEvent, verified end-to-end through createAllInOneEntrypoint. | `examples/lane-routing.md` |
+| `ledger-banking` | Bank accounts + transfers on the ledger primitive — balances are pure queries, never stored. | `examples/ledger-banking.md` |
+| `ledger-invoicing` | Accrual invoicing on the ledger primitive — revenue at invoice time, VAT as a liability, receivable cleared on payment. | `examples/ledger-invoicing.md` |
+| `legal-pages` | Auto-rendered Impressum + Datenschutzerklärung pages — template-resolver + legal-pages bundled features wired up with anonymousAccess for DACH-compliance. | `examples/legal-pages.md` |
+| `lifecycle-hooks` | preSave, postSave, and the rest. Your logic, our plumbing. | `examples/lifecycle-hooks.md` |
+| `managed-config` | Managed config: one declaration provisions storage + masking + settings-hub, across backings (secrets vs config) and scopes (system vs tenant). | `examples/managed-config.md` |
+| `managed-pages` | Tenant-editable, server-rendered public pages with per-tenant branding + tier-gated sanitized custom CSS — managed-pages wired up with config + anonymousAccess. | `examples/managed-pages.md` |
+| `notes-history-basic` | Append-only note history — who wrote what, when — attached to any entity without changing it. | `examples/notes-history-basic.md` |
+| `ownership` | Entity- and Field-level Row-Ownership: from() helper, Straddle-safe multi-role checks, Field-level Read/Write filtering. | `examples/ownership.md` |
+| `pdf-audit-export` | Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes. | `examples/pdf-audit-export.md` |
+| `pipeline-basics` | M.1 Tier-1 step-vocabulary showcase: every step in one inventory-management feature (aggregate.{create,update,appendEvent}, read.{findOne,findMany}, branch, forEach, compute, return, unsafeProjection{Upsert,Delete}). | `examples/pipeline-basics.md` |
+| `public-share-token` | Generic share-token entity: mint hash-stored token, anonymous read-by-token with IP rate-limit. | `examples/public-share-token.md` |
+| `rate-limiting` | End-to-end rate limiting: L1 global-IP + L2 auth-endpoints + L3 handler opt-in. | `examples/rate-limiting.md` |
+| `realtime-sse` | Server-sent events demo. Goodbye F5. | `examples/realtime-sse.md` |
+| `record-detail-layout` | projectionDetail record header, metrics band, and layout.mode: "tabs" — an order screen with two relatedList tabs and a fields tab. | `examples/record-detail-layout.md` |
+| `reference-data` | Upsert-based seeds. Lookup tables done right. | `examples/reference-data.md` |
+| `relations` | belongsTo, hasMany, manyToMany — the good stuff. | `examples/relations.md` |
+| `screens-nav` | r.screen() + r.nav() — entityList/entityEdit/custom screens, cross-feature nav parents, FieldCondition<TData>, boot-validator behaviour. | `examples/screens-nav.md` |
+| `search` | Tenant-scoped Meilisearch. Because ILIKE is not search. | `examples/search.md` |
+| `secrets-demo` | Tenant-owned secrets with envelope encryption, DEK cache, and KEK rotation. | `examples/secrets-demo.md` |
+| `security-baseline` | securityBaselineFeatures() preset: sessions, crypto-shredding, rate-limiting, audit — plus the NODE_ENV=production boot warning when one is missing. | `examples/security-baseline.md` |
+| `seed-migration` | ES-Operations seed-migrations — file-based diff-and-apply für Aggregate-Updates die idempotent-Seeder nicht erfassen. | `examples/seed-migration.md` |
+| `session-revocation` | createSessionCallbacks + sessionChecker — server-side session revocation via JWT jti. | `examples/session-revocation.md` |
+| `state-machine` | Enforced entity state transitions. No more illegal state changes. | `examples/state-machine.md` |
+| `tags-basic` | Tag and group any entity without changing it — host-agnostic, event-sourced. | `examples/tags-basic.md` |
+| `tenant-isolation` | Multi-tenant separation. Your data stays your data. | `examples/tenant-isolation.md` |
+| `tenant-settings` | Tenant-Settings: per-tenant Currency + Locale defaults, auto-filled into a money field / locale field on create instead of a hard-coded literal. | `examples/tenant-settings.md` |
+| `tier-admin` | Manually grant a tier to a tenant without a billing purchase — the SystemAdmin operator flow and how the resolver cache stays in sync. | `examples/tier-admin.md` |
+| `timezones` | Every time-aware field type on one entity, plus the ctx.tz handler API. | `examples/timezones.md` |
+| `user-data-rights` | DSGVO-compliant in 5 LOC: r.useExtension(EXT_USER_DATA, ...) haengt eine Domain an Forget+Export-Pipeline. Forget-Cron, Export-ZIP, Magic-Link kommen alle aus user-data-rights. | `examples/user-data-rights.md` |
+| `user-profile` | user-profile bundled feature — Self-Service-Kontoseite (Passwort/E-Mail ändern, Konto löschen) als App-Screen verdrahten. | `examples/user-profile.md` |
+| `webhook-step` | Tier-2 r.step.webhook.send showcase: deferred webhook dispatch via step-dispatcher subscription, no outbox table. | `examples/webhook-step.md` |
+| `wizard-form` | EditLayout.mode: "wizard" — a multi-step entity form with a review step that reads live form values through an extension section, and draft: true resuming the in-progress form via the bundled form-draft feature. | `examples/wizard-form.md` |
+| `workflow-engine` | M.4 Tier-3 step-vocabulary showcase: defineWorkflow with wait/waitForEvent/retry steps | `examples/workflow-engine.md` |
+| `writeform-section` | A projectionDetail `writeForm` section rendered beside an established entityEdit form on the same page, so the shared form chrome (footer, submit affordance) between the two can be verified side by side. | `examples/writeform-section.md` |