@cosmicdrift/kumiko-samples 0.367.0 → 0.368.0

package/samples/recipes/state-machine/src/handlers/transitions.ts

@@ -3,135 +3,142 @@
 // little extra logic (amount-check, verb routing, dedicated forced-event)
 // and stay inline so the variation is visible at the call site.
 
-import { defineWriteHandler, guardTransition } from "@app/define";
+import {
+  defineWriteHandler,
+  emitEvent,
+  guardTransition,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { z } from "zod";
 import { INVOICE_STATES, INVOICE_TRANSITIONS } from "../entities/invoice";
-import { ENTITY_NAME, eventName, INVOICE_EVENTS } from "../events";
+import { ENTITY_NAME, type InvoiceEvents } from "../events";
 import { type InvoiceStatus, loadInvoiceState } from "../reducer";
 import { successResult, transitionHandler } from "./_helpers";
 
 const adminOnly = { roles: ["Admin"] } as const;
 
-// --- Standard transitions (same shape, different target status) ---
-
-export const invoiceSend = transitionHandler({
-  name: "invoice:send",
-  toStatus: "sent",
-  eventType: eventName(INVOICE_EVENTS.sent),
-  access: adminOnly,
-});
-
-export const invoiceCancel = transitionHandler({
-  name: "invoice:cancel",
-  toStatus: "cancelled",
-  eventType: eventName(INVOICE_EVENTS.cancelled),
-  access: adminOnly,
-});
-
-export const invoiceReopen = transitionHandler({
-  name: "invoice:reopen",
-  toStatus: "draft",
-  eventType: eventName(INVOICE_EVENTS.reopened),
-  access: adminOnly,
-});
-
-// --- markPaid: same shape + business rule (amount must be > 0).
-//     The amount is reduced from the event stream, so the check stays
-//     consistent with everything else (no out-of-band DB query).
-
-export const invoiceMarkPaid = defineWriteHandler({
-  name: "invoice:mark-paid",
-  schema: z.object({ id: z.uuid() }),
-  access: { roles: ["Accounting"] },
-  handler: async (event, ctx) => {
-    const state = await loadInvoiceState(ctx, event.payload.id);
-    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
-
-    guardTransition(INVOICE_TRANSITIONS, state.status as InvoiceStatus, "paid");
-
-    if (state.amount === 0) {
-      return failUnprocessable("cannot_pay_zero_amount");
-    }
-
-    await ctx.appendEvent({
-      aggregateId: event.payload.id,
-      aggregateType: ENTITY_NAME,
-      type: eventName(INVOICE_EVENTS.markedPaid),
-      payload: {},
-    });
-
-    return successResult(event.payload.id, "paid", state.status);
-  },
-});
-
-// --- updateStatus: relies on the pipeline's auto transition guard.
-//     Routes the requested status to the matching domain event so the audit
-//     log still reads as a workflow step ("invoice-sent"), not a generic
-//     "status set to ...".
-
-// `as const satisfies` keeps the literal-strings alive (so each value is
-// `"billing:event:invoice-..."` literally typed, not just `string`) AND
-// type-checks the shape against `Record<InvoiceStatus, string>` —
-// missing-status entries fail at compile-time. Strict-mode for
-// ctx.appendEvent kicks in because `VERB_TO_EVENT[target]` resolves to
-// a union of literal event-names, all of which are augmented keys.
-const VERB_TO_EVENT = {
-  draft: eventName(INVOICE_EVENTS.reopened),
-  sent: eventName(INVOICE_EVENTS.sent),
-  paid: eventName(INVOICE_EVENTS.markedPaid),
-  cancelled: eventName(INVOICE_EVENTS.cancelled),
-} as const satisfies Record<InvoiceStatus, string>;
-
-export const invoiceUpdateStatus = defineWriteHandler({
-  name: "invoice:update-status",
-  schema: z.object({
-    id: z.uuid(),
-    changes: z.object({
+export function createInvoiceTransitionHandlers(events: InvoiceEvents) {
+  // --- Standard transitions (same shape, different target status) ---
+
+  const invoiceSend = transitionHandler({
+    name: "invoice:send",
+    toStatus: "sent",
+    event: events.sent,
+    access: adminOnly,
+  });
+
+  const invoiceCancel = transitionHandler({
+    name: "invoice:cancel",
+    toStatus: "cancelled",
+    event: events.cancelled,
+    access: adminOnly,
+  });
+
+  const invoiceReopen = transitionHandler({
+    name: "invoice:reopen",
+    toStatus: "draft",
+    event: events.reopened,
+    access: adminOnly,
+  });
+
+  // --- markPaid: same shape + business rule (amount must be > 0).
+  //     The amount is reduced from the event stream, so the check stays
+  //     consistent with everything else (no out-of-band DB query).
+
+  const invoiceMarkPaid = defineWriteHandler({
+    name: "invoice:mark-paid",
+    schema: z.object({ id: z.uuid() }),
+    access: { roles: ["Accounting"] },
+    handler: async (event, ctx) => {
+      const state = await loadInvoiceState(ctx, event.payload.id);
+      if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+      guardTransition(INVOICE_TRANSITIONS, state.status as InvoiceStatus, "paid");
+
+      if (state.amount === 0) {
+        return failUnprocessable("cannot_pay_zero_amount");
+      }
+
+      await emitEvent(ctx, events.markedPaid, {
+        aggregateId: event.payload.id,
+        aggregateType: ENTITY_NAME,
+        payload: {},
+      });
+
+      return successResult(event.payload.id, "paid", state.status);
+    },
+  });
+
+  // --- updateStatus: relies on the pipeline's auto transition guard.
+  //     Routes the requested status to the matching domain event so the audit
+  //     log still reads as a workflow step ("invoice-sent"), not a generic
+  //     "status set to ...".
+
+  // `satisfies Record<InvoiceStatus, ...>` makes a missing status a compile error.
+  const verbToEvent = {
+    draft: events.reopened,
+    sent: events.sent,
+    paid: events.markedPaid,
+    cancelled: events.cancelled,
+  } satisfies Record<InvoiceStatus, InvoiceEvents["sent"]>;
+
+  const invoiceUpdateStatus = defineWriteHandler({
+    name: "invoice:update-status",
+    schema: z.object({
+      id: z.uuid(),
+      changes: z.object({
+        status: z.enum(INVOICE_STATES),
+      }),
+    }),
+    access: adminOnly,
+    // No skipTransitionGuard — pipeline auto-guards.
+    handler: async (event, ctx) => {
+      const state = await loadInvoiceState(ctx, event.payload.id);
+      if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+      const target = event.payload.changes.status;
+      await emitEvent(ctx, verbToEvent[target], {
+        aggregateId: event.payload.id,
+        aggregateType: ENTITY_NAME,
+        payload: {},
+      });
+
+      return successResult(event.payload.id, target, state.status);
+    },
+  });
+
+  // --- forceStatus: skips the guard and emits a dedicated "forced" event so
+  //     admin overrides stay visually distinct from normal workflow events in
+  //     the audit log.
+
+  const invoiceForceStatus = defineWriteHandler({
+    name: "invoice:force-status",
+    schema: z.object({
+      id: z.uuid(),
       status: z.enum(INVOICE_STATES),
     }),
-  }),
-  access: adminOnly,
-  // No skipTransitionGuard — pipeline auto-guards.
-  handler: async (event, ctx) => {
-    const state = await loadInvoiceState(ctx, event.payload.id);
-    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
-
-    const target = event.payload.changes.status;
-    await ctx.appendEvent({
-      aggregateId: event.payload.id,
-      aggregateType: ENTITY_NAME,
-      type: VERB_TO_EVENT[target],
-      payload: {},
-    });
-
-    return successResult(event.payload.id, target, state.status);
-  },
-});
-
-// --- forceStatus: skips the guard and emits a dedicated "forced" event so
-//     admin overrides stay visually distinct from normal workflow events in
-//     the audit log.
-
-export const invoiceForceStatus = defineWriteHandler({
-  name: "invoice:force-status",
-  schema: z.object({
-    id: z.uuid(),
-    status: z.enum(INVOICE_STATES),
-  }),
-  access: adminOnly,
-  unsafeSkipTransitionGuard: true,
-  handler: async (event, ctx) => {
-    const state = await loadInvoiceState(ctx, event.payload.id);
-    if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
-
-    await ctx.appendEvent({
-      aggregateId: event.payload.id,
-      aggregateType: ENTITY_NAME,
-      type: eventName(INVOICE_EVENTS.statusForced),
-      payload: { newStatus: event.payload.status, fromStatus: state.status as InvoiceStatus },
-    });
-
-    return successResult(event.payload.id, event.payload.status, state.status);
-  },
-});
+    access: adminOnly,
+    unsafeSkipTransitionGuard: true,
+    handler: async (event, ctx) => {
+      const state = await loadInvoiceState(ctx, event.payload.id);
+      if (!state) return failNotFound(ENTITY_NAME, event.payload.id);
+
+      await emitEvent(ctx, events.statusForced, {
+        aggregateId: event.payload.id,
+        aggregateType: ENTITY_NAME,
+        payload: { newStatus: event.payload.status, fromStatus: state.status as InvoiceStatus },
+      });
+
+      return successResult(event.payload.id, event.payload.status, state.status);
+    },
+  });
+
+  return {
+    invoiceSend,
+    invoiceCancel,
+    invoiceReopen,
+    invoiceMarkPaid,
+    invoiceUpdateStatus,
+    invoiceForceStatus,
+  };
+}

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

@@ -7,7 +7,7 @@
 // and update the relevant `case` in `reduceInvoice` — that's the whole
 // contract.
 
-import type { HandlerContext } from "@app/define";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { eventName, INVOICE_CREATED_EVENT, INVOICE_EVENTS } from "./events";
 
 export type InvoiceStatus = "draft" | "sent" | "paid" | "cancelled";

package/samples/recipes/state-machine/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/tags-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/tenant-isolation/package.json

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

package/samples/recipes/tenant-settings/package.json

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

package/samples/recipes/tier-admin/package.json

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

package/samples/recipes/timezones/package.json

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

package/samples/recipes/tsconfig.base.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Single source of truth \u2014 check-app-tsc reads this template and overlays the @app/define branch for codegen recipes. Paths are relative to samples/recipes/<name>/.",
+  "_comment": "Single source of truth \u2014 check-app-tsc reads this template. Paths are relative to samples/recipes/<name>/.",
   "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "paths": {

package/samples/recipes/user-data-rights/package.json

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

package/samples/recipes/user-data-rights/src/feature.ts

@@ -16,8 +16,12 @@
 //   - HTTP-Endpoints fuer create/list
 //   - Compliance-Profile-Wiring + Cron-Scheduling
 
-import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  deleteMany,
+  deriveEntityTableMeta,
+  selectMany,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createTextField,

package/samples/recipes/user-profile/package.json

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

package/samples/recipes/user-profile/src/feature.ts

@@ -14,7 +14,7 @@
 //   })
 
 import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
@@ -59,7 +59,7 @@ export function composeAccountApp(): FeatureDefinition[] {
     createAuthEmailPasswordFeature(),
     createDataRetentionFeature(),
     createComplianceProfilesFeature(),
-    authFoundationFeature,
+    createAuthFoundationFeature(),
     createPersonalAccessTokensFeature({ scopes: {} }),
     createSessionsFeature(),
     createFilesFeature(),

package/samples/recipes/webhook-step/package.json

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

package/samples/recipes/wizard-form/package.json

@@ -15,6 +15,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/workflow-engine/package.json

@@ -5,5 +5,8 @@
   "scripts": {
     "test": "bun test",
     "test:run": "bun test"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "workspace:*"
   }
 }

package/samples/recipes/workflow-engine/src/db/queries/suspended-runs.ts

@@ -1,5 +1,8 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
+import {
+  asRawClient,
+  type DbRunner,
+  toPostgresArrayLiteral,
+} from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectExpiredSuspensionEvents(
   db: DbRunner,

package/samples/recipes/writeform-section/package.json

@@ -15,6 +15,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/packages/bundled-features/src/file-provider-s3-env/feature.ts

@@ -1,58 +0,0 @@
-// kumiko-feature-version: 1
-//
-// file-provider-s3-env — S3 file provider configured entirely from
-// process.env. ONE shared bucket for ALL tenants: wire it by setting the
-// `S3_*` env vars + mounting — no per-tenant admin seeding and no
-// `secrets`-feature dependency.
-//
-// **vs file-provider-s3:** the config-based `"s3"` provider owns per-tenant
-// config keys + an encrypted `s3.secretAccessKey` secret (per-tenant
-// buckets, admin-seeded). This `"s3-env"` provider reads one credential set
-// from env and serves every tenant from one bucket — the
-// Hetzner-Object-Storage / single-bucket deploy case. Tenant isolation
-// still holds: file keys carry the tenant (export ZIPs:
-// `exports/<tenantId>/<jobId>.zip`) or are globally-unique UUIDs (fileRefs).
-//
-// **Pattern-Vorbild:** mirrors file-provider-inmemory (zero admin seeding,
-// only the file-foundation plugin-point required).
-//
-// **Env vars** (read by createS3ProviderFromEnv, prefix `S3_`):
-//   required — S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY
-//   optional — S3_ENDPOINT (S3-compat stores incl. Hetzner Object Storage),
-//              S3_FORCE_PATH_STYLE
-// Missing required vars throw on the FIRST file op (inside the export cron).
-// The user-data-rights boot guard surfaces that at boot instead.
-
-import type {
-  FileProviderContext,
-  FileProviderPlugin,
-} from "@cosmicdrift/kumiko-bundled-features/file-foundation";
-import { createS3ProviderFromEnv } from "@cosmicdrift/kumiko-bundled-features/files-provider-s3";
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
-import type { FileStorageProvider } from "@cosmicdrift/kumiko-framework/files";
-
-const FEATURE_NAME = "file-provider-s3-env";
-
-export const fileProviderS3EnvFeature = defineFeature(FEATURE_NAME, (r) => {
-  r.describe(
-    'Registers an `"s3-env"` provider for `file-foundation` that reads one S3 credential set from `process.env` (`S3_BUCKET`/`S3_REGION`/`S3_ACCESS_KEY`/`S3_SECRET_KEY`, optional `S3_ENDPOINT`/`S3_FORCE_PATH_STYLE`) and serves every tenant from one shared bucket — no per-tenant config or secret seeding. Use this for single-bucket S3-compatible deploys (e.g. Hetzner Object Storage); use `file-provider-s3` instead when each tenant needs its own bucket/credentials.',
-  );
-  r.uiHints({
-    displayLabel: "File Provider · S3 (env)",
-    category: "storage",
-    recommended: false,
-  });
-  // No requires on "config" or "secrets" — credentials come from
-  // env, not the per-tenant config + secrets store. Only the file-foundation
-  // plugin-extension-point must be mounted.
-  r.requires({ features: ["file-foundation"] });
-
-  const plugin: FileProviderPlugin = {
-    // tenantId ignored: one shared bucket serves all tenants (isolation via
-    // tenant-prefixed / UUID keys). Built fresh per call like file-provider-s3;
-    // the S3 client opens no connection at construction.
-    build: async (_ctx: FileProviderContext, _tenantId: string): Promise<FileStorageProvider> =>
-      createS3ProviderFromEnv(), // @wrapper-known semantic-alias
-  };
-  r.useExtension("fileProvider", "s3-env", plugin);
-});