@cosmicdrift/kumiko-samples 0.366.0 → 0.368.0

package/samples/recipes/event-sourcing/src/feature.ts

@@ -5,8 +5,8 @@
 //
 //   - r.defineEvent with { version, migrations } — evolving event shapes +
 //     upcast older payloads on read (declarative + sync/async transforms)
-//   - ctx.appendEvent — write domain events onto the aggregate stream
-//   - ctx.appendEvent with headers — Marten free key/value metadata
+//   - emitEvent — write domain events onto the aggregate stream, payload typed by the EventDef
+//   - emitEvent with headers — Marten free key/value metadata
 //   - r.projection — single-stream read model (inline in the write TX)
 //   - r.multiStreamProjection — cross-aggregate async read model
 //   - ctx.loadAggregate with { asOf } — point-in-time aggregate state
@@ -19,26 +19,25 @@
 //   - getAllProjectionProgress — projection lag for ops dashboards
 
 import {
-  createEntity,
-  createTextField,
-  defineFeature,
-  defineProjectionQueryHandler,
-  typedPayload,
-} from "@app/define";
-import {
+  buildEntityTable,
+  createEventStoreExecutor,
   fetchOne,
   incrementCounter,
   insertOne,
-  updateMany,
-} from "@cosmicdrift/kumiko-framework/bun-db";
-import {
-  buildEntityTable,
-  createEventStoreExecutor,
   integer,
   table,
   text,
+  updateMany,
   uuid,
 } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  defineProjectionQueryHandler,
+  emitEvent,
+  typedPayload,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 // --- Reducer: shared by live + snapshot-aware query handlers ---
@@ -286,10 +285,9 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
       const headers: Record<string, string> = {};
       if (event.payload.geoRegion) headers["geoRegion"] = event.payload.geoRegion;
       if (event.payload.abTestBucket) headers["abTestBucket"] = event.payload.abTestBucket;
-      await ctx.appendEvent({
+      await emitEvent(ctx, approved, {
         aggregateId: event.payload.id,
         aggregateType: "showcase-invoice",
-        type: approved.name,
         payload: { amountCents: event.payload.amountCents, approvedBy: event.payload.approvedBy },
         ...(Object.keys(headers).length > 0 ? { headers } : {}),
       });
@@ -306,10 +304,9 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
         approverId: event.payload.approverId,
       });
       const approverDisplayName: string = row?.displayName ?? `unknown:${event.payload.approverId}`;
-      await ctx.appendEvent({
+      await emitEvent(ctx, acknowledged, {
         aggregateId: event.payload.id,
         aggregateType: "showcase-invoice",
-        type: acknowledged.name,
         payload: { approverId: event.payload.approverId, approverDisplayName },
       });
       return { isSuccess: true as const, data: { id: event.payload.id } };
@@ -321,10 +318,9 @@ export const invoiceFeature = defineFeature("showcase", (r) => {
     name: "invoice:pay",
     schema: z.object({ id: z.uuid(), amountCents: z.number().int() }),
     handler: async (event, ctx) => {
-      await ctx.appendEvent({
+      await emitEvent(ctx, paid, {
         aggregateId: event.payload.id,
         aggregateType: "showcase-invoice",
-        type: paid.name,
         payload: { amountCents: event.payload.amountCents },
       });
       return { isSuccess: true as const, data: { id: event.payload.id } };

package/samples/recipes/event-sourcing/tsconfig.json

@@ -11,16 +11,12 @@
       "@cosmicdrift/kumiko-dev-server": [
         "../../../packages/dev-server/src/index.ts"
       ],
-      "@cosmicdrift/kumiko-dev-server/*": [
-        "../../../packages/dev-server/src/*"
-      ],
-      "@app/define": ["./.kumiko/define.ts"],
-      "@app/*": ["./.kumiko/*"]
+      "@cosmicdrift/kumiko-dev-server/*": ["../../../packages/dev-server/src/*"]
     },
     "noEmit": true,
     "rootDir": "../../..",
     "lib": ["ESNext", "DOM", "DOM.Iterable"],
     "types": ["bun-types"]
   },
-  "include": ["./src", "./.kumiko"]
+  "include": ["./src"]
 }

package/samples/recipes/feature-toggles/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/field-access/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/files-post-processing/package.json

@@ -7,6 +7,7 @@
     "@cosmicdrift/kumiko-framework": "workspace:*"
   },
   "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*",
     "sharp": "^0.35.5"
   }
 }

package/samples/recipes/golden-path/README.md

@@ -0,0 +1,30 @@
+# Golden path
+
+The smallest complete Kumiko feature: one entity, one write handler that emits
+an event, one projection, one screen, and an integration test that writes
+through HTTP and reads the result back. Every other recipe is a variation on
+this shape. The walkthrough is in [`docs/golden-path.md`](../../../docs/golden-path.md).
+
+## What it shows
+
+- **Entity** — `ticketEntity` declares `title` and `isClosed`. `r.crud` registers
+  `ticket:create`, `ticket:list` and `ticket:detail` for it; update and delete
+  are switched off with `verbs`.
+- **Write handler** — `ticket:close` checks that the ticket exists and emits the
+  `ticket-closed` event. It never touches the table.
+- **Event** — `r.defineEvent` declares `ticket-closed` with a Zod payload;
+  `emitEvent` appends it to the ticket's stream in the handler's transaction.
+- **Projection** — `ticket-status` folds `ticket-closed` into the ticket row
+  (`isClosed: true`), in the same transaction as the write.
+- **Screen** — `ticket-list` is a declarative `entityList`; the renderer builds
+  the UI from it.
+- **Test** — `setupTestStack` boots the real server and database;
+  `stack.http.writeOk` and `queryOk` go over HTTP. Each test runs in its own
+  tenant.
+
+## Files
+
+```
+src/feature.ts                          entity, event, handler, projection, screen
+src/__tests__/feature.integration.test.ts   write → read back, access, not found
+```

package/samples/recipes/golden-path/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-golden-path",
+  "description": "The smallest complete feature: entity, write handler, event, projection, screen and an integration test.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
+  }
+}

package/samples/recipes/golden-path/src/feature.ts

@@ -0,0 +1,70 @@
+import {
+  createBooleanField,
+  createEntity,
+  createEntityExecutor,
+  createTextField,
+  defineFeature,
+  emitEvent,
+  setFields,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { failNotFound } from "@cosmicdrift/kumiko-framework/errors";
+import { z } from "zod";
+
+export const ticketEntity = createEntity({
+  table: "read_golden_path_tickets",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    isClosed: createBooleanField({ default: false }),
+  },
+});
+
+export const helpdeskFeature = defineFeature("helpdesk", (r) => {
+  const { table: ticketTable, executor: ticketExecutor } = createEntityExecutor(
+    "ticket",
+    ticketEntity,
+  );
+
+  r.crud("ticket", ticketEntity, {
+    write: { access: { roles: ["Admin", "User"] } },
+    read: { access: { roles: ["Admin", "User"] } },
+    verbs: { update: false, delete: false },
+  });
+
+  const ticketClosed = r.defineEvent("ticket-closed", z.object({ resolution: z.string().min(1) }), {
+    piiFields: "none",
+  });
+
+  r.writeHandler({
+    name: "ticket:close",
+    schema: z.object({ id: z.uuid(), resolution: z.string().min(1) }),
+    access: { roles: ["Admin"] },
+    handler: async (event, ctx) => {
+      const ticket = await ticketExecutor.detail({ id: event.payload.id }, event.user, ctx.db);
+      if (!ticket) {
+        return failNotFound("ticket", event.payload.id);
+      }
+      await emitEvent(ctx, ticketClosed, {
+        aggregateId: event.payload.id,
+        aggregateType: "ticket",
+        payload: { resolution: event.payload.resolution },
+      });
+      return { isSuccess: true as const, data: { id: event.payload.id } };
+    },
+  });
+
+  r.projection({
+    name: "ticket-status",
+    source: "ticket",
+    table: ticketTable,
+    apply: {
+      [ticketClosed.name]: setFields(ticketTable, { isClosed: true }),
+    },
+  });
+
+  r.screen({
+    id: "ticket-list",
+    type: "entityList",
+    entity: "ticket",
+    columns: ["title", "isClosed"],
+  });
+});

package/samples/recipes/idempotency/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/inbound-mail-triage/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/lane-routing/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/ledger-banking/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/ledger-invoicing/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/legal-pages/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/lifecycle-hooks/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/managed-config/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/managed-pages/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/notes-history-basic/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/ownership/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/pdf-audit-export/package.json

@@ -7,6 +7,7 @@
     "@cosmicdrift/kumiko-framework": "workspace:*"
   },
   "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*",
     "unpdf": "^1.8.1"
   }
 }

package/samples/recipes/pipeline-basics/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/public-share-token/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/public-share-token/src/feature.ts

@@ -6,7 +6,7 @@
 // A full consumer adds domain snapshots, layouts and tier gates on top.
 
 import { generateToken } from "@cosmicdrift/kumiko-framework/api";
-import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createEntityExecutor,

package/samples/recipes/rate-limiting/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/realtime-sse/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/record-detail-layout/package.json

@@ -14,6 +14,7 @@
   },
   "devDependencies": {
     "@cosmicdrift/kumiko-server-runtime": "workspace:*",
+    "@cosmicdrift/kumiko-testing": "workspace:*",
     "@playwright/test": "^1.62.1",
     "@tailwindcss/cli": "^4.3.0",
     "@types/react": "^19.2.14",

package/samples/recipes/reference-data/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/relations/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/screens-nav/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/search/package.json

@@ -4,5 +4,8 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/secrets-demo/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/security-baseline/src/feature.ts

@@ -3,7 +3,7 @@
 // rate-limiting, audit) and how it silences the NODE_ENV=production boot
 // warning that fires when one of those four is missing.
 
-import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
 import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
@@ -14,6 +14,6 @@ export const APP_FEATURES: FeatureDefinition[] = [
   createConfigFeature(),
   createUserFeature(),
   createTenantFeature(),
-  authFoundationFeature,
+  createAuthFoundationFeature(),
   ...securityBaselineFeatures(),
 ];

package/samples/recipes/session-revocation/README.md

@@ -15,7 +15,7 @@ The production wiring shape: an app builds `createSessionCallbacks()` against a
 ## What to copy into your app
 
 ```ts illustration
-const db = createDbConnection(config.databaseUrl);
+const db = createDbConnection({ url: config.databaseUrl });
 const callbacks = createSessionCallbacks({ db });
 
 const server = buildServer({

package/samples/recipes/session-revocation/package.json

@@ -5,5 +5,8 @@
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/session-revocation/src/feature.ts

@@ -8,7 +8,7 @@
 //
 // What to copy into your own app:
 //
-//   const db = createDbConnection(config.databaseUrl);
+//   const db = createDbConnection({ url: config.databaseUrl });
 //   const callbacks = createSessionCallbacks({ db });
 //   const server = buildServer({
 //     registry: buildRegistry([

package/samples/recipes/state-machine/package.json

@@ -3,7 +3,9 @@
   "description": "Enforced entity state transitions. No more illegal state changes.",
   "private": true,
   "dependencies": {
-    "@app/define": "file:./.kumiko",
     "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/state-machine/src/entities/invoice.ts

@@ -1,11 +1,11 @@
+import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createMoneyField,
   createSelectField,
   createTextField,
   defineTransitions,
-} from "@app/define";
-import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const INVOICE_STATES = ["draft", "sent", "paid", "cancelled"] as const;
 

package/samples/recipes/state-machine/src/events.ts

@@ -3,6 +3,9 @@
 // strings, so a rename here propagates everywhere instead of silently
 // breaking the reducer.
 
+import type { EventDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
 export const FEATURE_NAME = "billing";
 export const ENTITY_NAME = "invoice";
 
@@ -30,3 +33,19 @@ export function eventName<const TShort extends string>(
 // The auto-generated event the executor emits on create — entity name dot
 // "created", no feature prefix (executor convention).
 export const INVOICE_CREATED_EVENT = `${ENTITY_NAME}.created` as const;
+
+export const emptyEventPayload = z.object({});
+export const statusForcedPayload = z.object({
+  newStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+  fromStatus: z.enum(["draft", "sent", "paid", "cancelled"]),
+});
+
+// The EventDefs r.defineEvent returns inside the feature setup. Handlers receive them so that
+// emitEvent checks each payload against the event's own schema.
+export type InvoiceEvents = {
+  readonly sent: EventDef<z.infer<typeof emptyEventPayload>>;
+  readonly markedPaid: EventDef<z.infer<typeof emptyEventPayload>>;
+  readonly cancelled: EventDef<z.infer<typeof emptyEventPayload>>;
+  readonly reopened: EventDef<z.infer<typeof emptyEventPayload>>;
+  readonly statusForced: EventDef<z.infer<typeof statusForcedPayload>>;
+};