@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/tenant-settings.md

@@ -0,0 +1,275 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/tenant-settings. Do not edit. -->
+
+# 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.
+
+## README
+
+# Recipe: Tenant-Settings
+
+**What this shows:** how a per-tenant Currency + Locale default fills a
+money/locale field on create — without hard-coding `"EUR"`/`"de"` as a field
+literal, the mistake that cost a sibling project (phronexsis) a retrofit once
+a second tenant needed a different default.
+
+## Pattern
+
+```ts illustration
+import {
+  createEntity,
+  createMoneyField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { defineCreateWithTenantDefaults } from "@cosmicdrift/kumiko-bundled-features/tenant-settings";
+
+export const invoiceEntity = createEntity({
+  table: "read_invoices",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    amount: createMoneyField({ required: true }),
+    language: createSelectField({ options: ["en", "de", "fr"] as const }),
+  },
+});
+
+export const invoiceFeature = defineFeature("invoice", (r) => {
+  r.entity("invoice", invoiceEntity);
+  r.writeHandler(
+    defineCreateWithTenantDefaults("invoice", invoiceEntity, {
+      access: { roles: ["Admin"] },
+      currencyFields: ["amount"],
+      localeField: "language",
+    }),
+  );
+  // update/delete/list/detail stay the plain defineEntity*Handler factories —
+  // only create needs the tenant-default fill-in.
+});
+```
+
+Mount `createTenantSettingsFeature()` alongside — it provisions the two
+config keys (`tenant-settings:config:currency`, `tenant-settings:config:locale`)
+that `defineCreateWithTenantDefaults` reads:
+
+```ts illustration
+import { createTenantSettingsFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-settings";
+
+const features = [createConfigFeature(), createTenantSettingsFeature(), invoiceFeature];
+```
+
+`createTenantSettingsFeature(opts)` takes `currencies`, `defaultCurrency`,
+`defaultLocale`, `write` — an app with its own supported-currency list or
+role vocabulary overrides those instead of forking the feature.
+
+## Why the schema needs a special case
+
+`buildInsertSchema` always makes `currency` required *inside* a money field's
+value object, even when the field itself is optional — a caller literally
+cannot submit `{ amount: 1000 }` against the plain `defineEntityCreateHandler`.
+`defineCreateWithTenantDefaults` swaps in its own schema (`.extend()` over the
+same `buildInsertSchema` output, with just the declared `currencyFields`
+relaxed) so the caller *can* omit `currency`, then fills it from
+`ctx.config(TenantSettingsConfig.currency)` before delegating to the same
+`executor.create()` the generic factory uses.
+
+## Settings-Hub
+
+Both keys declare `mask`, so they surface in the self-populating Settings-Hub
+(Tenant-Audience) without a hand-written `r.screen`/`r.nav` — same mechanism
+as [managed-config](/en/samples/recipes-managed-config/). A `TenantAdmin`
+changes them from **Settings → Tenant → Default Currency / Default Locale**.
+
+## Flow
+
+1. No tenant override yet → a new invoice gets the *feature's own* default
+   (`"EUR"`/`"en"`, set via `createTenantSettingsFeature()`'s own defaults).
+2. Tenant sets `currency` to `"CHF"` and `locale` to `"de"` via the
+   Settings-Hub (or `config:write:set` directly).
+3. A new invoice that doesn't specify `amount.currency`/`language` picks up
+   `"CHF"`/`"de"` — no entity code changed, no second migration.
+4. A caller that *does* specify `amount.currency` still wins — the tenant
+   setting only fills gaps, it never overrides an explicit value.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Covers the happy path above (tenant defaults fill gaps; explicit caller
+values still win). Creating without a `tenant-settings` mount is not a
+supported fallback — mount the feature (or the recipe's stack) first.
+
+## What's not in this recipe
+
+- **Timezone, number-format, week-start** — deliberately out of scope; add
+  them as further config keys on the same feature when a real consumer needs
+  them, don't speculate ahead of a use case.
+- **A dedicated locale-options select** — `locale` is a free-text ISO-639-1(-region)
+  field validated by regex, not a fixed enum, because the framework doesn't
+  own which languages an app supports. An app with a fixed language list
+  builds its own `createTenantConfig("select", {...})` key if it wants a
+  dropdown instead of `TenantSettingsConfig.locale`.
+
+## Related samples
+
+- [managed-config](/en/samples/recipes-managed-config/) — the `mask` +
+  Settings-Hub mechanism these keys rely on, explained in depth.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// End-to-end over real HTTP: a tenant's currency/locale setting flows into
+// a new invoice's money/locale fields without the caller specifying them.
+
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import {
+  configValuesTable,
+  createConfigAccessorFactory,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { createTenantSettingsFeature } from "@cosmicdrift/kumiko-bundled-features/tenant-settings";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  pushEntityProjectionTables,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { invoiceEntity, invoiceFeature } from "../feature";
+
+const tenantId = testTenantId(1);
+const admin: SessionUser = { id: "admin-1", tenantId, roles: ["Admin"] };
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const resolver = createConfigResolver();
+  stack = await setupTestStack({
+    features: [createConfigFeature(), createTenantSettingsFeature(), invoiceFeature],
+    extraContext: ({ registry }) => ({
+      configResolver: resolver,
+      _configAccessorFactory: createConfigAccessorFactory(registry, resolver),
+    }),
+  });
+  await unsafePushTables(stack.db, { configValuesTable });
+  await unsafeCreateEntityTable(stack.db, invoiceEntity);
+  await createEventsTable(stack.db);
+  await pushEntityProjectionTables(stack, stack.registry);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+test("no tenant override yet — new invoice gets the feature's own default (EUR/en)", async () => {
+  const invoice = await stack.http.writeOk<{
+    data: {
+      amount: { amount: number; currency: string; amountScaled: number; amountMinor: number };
+      language: string;
+    };
+  }>("invoice:write:invoice:create", { title: "Invoice 1", amount: { amount: 1000 } }, admin);
+  expect(invoice.data.amount).toEqual({
+    amount: 1000,
+    currency: "EUR",
+    amountScaled: 100_000,
+    amountMinor: 100_000,
+  });
+  expect(invoice.data.language).toBe("en");
+});
+
+test("tenant sets CHF/de — a new invoice without explicit values picks up the tenant setting", async () => {
+  await stack.http.writeOk(
+    "config:write:set",
+    { key: "tenant-settings:config:currency", value: "CHF" },
+    admin,
+  );
+  await stack.http.writeOk(
+    "config:write:set",
+    { key: "tenant-settings:config:locale", value: "de" },
+    admin,
+  );
+
+  const invoice = await stack.http.writeOk<{
+    data: {
+      amount: { amount: number; currency: string; amountScaled: number; amountMinor: number };
+      language: string;
+    };
+  }>("invoice:write:invoice:create", { title: "Invoice 2", amount: { amount: 2000 } }, admin);
+
+  expect(invoice.data.amount).toEqual({
+    amount: 2000,
+    currency: "CHF",
+    amountScaled: 200_000,
+    amountMinor: 200_000,
+  });
+  expect(invoice.data.language).toBe("de");
+});
+
+test("an explicit value in the payload wins over the tenant setting", async () => {
+  const invoice = await stack.http.writeOk<{
+    data: {
+      amount: { amount: number; currency: string; amountScaled: number; amountMinor: number };
+    };
+  }>(
+    "invoice:write:invoice:create",
+    { title: "Invoice 3", amount: { amount: 3000, currency: "USD" } },
+    admin,
+  );
+  expect(invoice.data.amount).toEqual({
+    amount: 3000,
+    currency: "USD",
+    amountScaled: 300_000,
+    amountMinor: 300_000,
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+// Consuming tenant-settings: an `invoice` entity whose `amount` (money) and
+// `language` (locale) are auto-filled from the tenant's currency/locale
+// setting when the caller omits them — instead of hard-coding "EUR"/"en" on
+// the field, the mistake this recipe exists to prevent (solon#P19).
+
+import { defineCreateWithTenantDefaults } from "@cosmicdrift/kumiko-bundled-features/tenant-settings";
+import {
+  createEntity,
+  createMoneyField,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+export const invoiceEntity = createEntity({
+  table: "read_invoices",
+  fields: {
+    title: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    amount: createMoneyField({ required: true }),
+    language: createSelectField({ options: ["en", "de", "fr"] as const }),
+  },
+});
+
+const ACCESS = { roles: ["Admin"] } as const;
+
+export const invoiceFeature = defineFeature("invoice", (r) => {
+  r.entity("invoice", invoiceEntity);
+  r.writeHandler(
+    defineCreateWithTenantDefaults("invoice", invoiceEntity, {
+      access: ACCESS,
+      currencyFields: ["amount"],
+      localeField: "language",
+    }),
+  );
+});
+```

package/agents/examples/tier-admin.md

@@ -0,0 +1,347 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/tier-admin. Do not edit. -->
+
+# 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.
+
+## README
+
+# Tier Admin
+
+Manually assign a pricing tier to a tenant — without a billing purchase
+and without writing the projection by hand. The recipe shows the
+SystemAdmin-only operator flow plus the subtlety that makes it correct:
+the grant updates the in-memory resolver cache synchronously, so
+toggleable features unlock in the same request.
+
+## What it shows
+
+- **`tier-engine:write:set-tenant-tier`** — a SystemAdmin assigns a tier
+  to *any* tenant, cross-tenant. Stamps `source: "manual"` so a future
+  Stripe → tier sync won't overwrite the grant.
+- **`tier-engine:query:get-tenant-tier`** — SystemAdmin reads back which
+  tier a tenant is on plus its source (`"manual"` vs `"billing"`).
+- **`tier-engine:query:tier-options`** — lists the configured tier names
+  so the admin UI doesn't have to hard-code them.
+- **`notes-export`** — a `r.toggleable()` feature the `pro` tier unlocks.
+  It appears in a tenant's effective-features set only when its tier lists
+  it (`pro` does, `free` does not).
+- **Cache-sync invariant** — the manual grant updates the resolver cache
+  the same request, not just the projection. `notes-export` is in the
+  tenant's effective set immediately after the set call — same request,
+  before any cache refresh, replay, or restart.
+
+## Feature composition
+
+```
+config       → tenant config (tier-engine dependency)
+tenant       → tenant records for cross-tenant grants
+tier-engine  → set-tenant-tier, get-tenant-tier, tier-options
+notes-export → r.toggleable() domain feature unlocked by pro tier
+```
+
+## Flow
+
+1. SystemAdmin calls `set-tenant-tier` for a **foreign** tenant with
+   `tier: "pro"` → event lands in the target tenant's stream,
+   `source: "manual"`.
+2. `get-tenant-tier` read-back confirms tier + source (billing sync must
+   not overwrite manual grants).
+3. `tier-options` returns keys from your static `TierMap` — no hard-coded
+   tier list in the UI.
+4. Resolver built **before** the grant now reports `notes-export` in the
+   tenant's effective set — same process, no rebuild (cache-sync proof).
+
+## Why the cache invariant matters
+
+`set-tenant-tier` writes through the event-store executor directly. That
+path bypasses the `postSave` entity-hook the resolver normally uses to
+invalidate the cache after a tier-assignment change. Without an explicit
+cache update the grant would persist (next request would see it) but
+*this* request still sees the old tier — surprising for an operator who
+just clicked "set tier to pro".
+
+The feature wires `onAssigned` into `createSetTenantTierWrite` for
+exactly this reason.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+bun test src/__tests__/feature.integration.test.ts
+```
+
+Integration test proves:
+
+- Cross-tenant grant + read-back with `source: "manual"`
+- `tier-options` matches `TierMap` keys
+- Idempotent re-grant updates the same aggregate
+- TenantAdmin without SystemAdmin → 403
+- Resolver sees `notes-export` immediately after grant (cache-sync)
+
+## Related samples
+
+- [apps-cap-billing-demo](/en/samples/apps-cap-billing-demo/) — tier from
+  billing webhooks + cap enforcement.
+- [recipes-encrypted-tenant-config](/en/samples/recipes-encrypted-tenant-config/) —
+  per-tenant config keys gated by tier.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Tier Admin — integration test.
+//
+// Drives the SystemAdmin-only operator flow end-to-end against the real
+// dispatcher + DB:
+//   1. SystemAdmin sits in his own tenant.
+//   2. He grants a tier to a FOREIGN tenant via set-tenant-tier.
+//   3. get-tenant-tier (cross-tenant read) returns tier:"pro",
+//      source:"manual" — proving the grant landed in the target stream
+//      and is marked as a manual grant (Stripe sync won't overwrite it).
+//   4. tier-options returns the TierMap keys without hard-coding.
+
+import { afterAll, beforeAll, beforeEach, expect, test } from "bun:test";
+import { randomBytes } from "node:crypto";
+import {
+  configValuesTable,
+  createConfigFeature,
+  createConfigResolver,
+} from "@cosmicdrift/kumiko-bundled-features/config";
+import { createTenantFeature, tenantEntity } from "@cosmicdrift/kumiko-bundled-features/tenant";
+import {
+  TierEngineHandlers,
+  TierEngineQueries,
+  tierAssignmentEntity,
+} from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/db";
+import { findTierResolverUsage, isTierResolverPlugin } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createTestEnvelopeCipher } from "@cosmicdrift/kumiko-framework/testing";
+import { appTierMap, NOTES_EXPORT_FEATURE, notesExportFeature, tierEngineForApp } from "../feature";
+
+const encryptionKey = randomBytes(32).toString("base64");
+const configFeature = createConfigFeature();
+const tenantFeature = createTenantFeature();
+const recipeFeatures = [configFeature, tenantFeature, tierEngineForApp, notesExportFeature];
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  const encryption = createTestEnvelopeCipher(encryptionKey);
+  const configResolver = createConfigResolver({ cipher: encryption });
+
+  stack = await setupTestStack({
+    features: recipeFeatures,
+    extraContext: { configResolver, configEncryption: encryption },
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tierAssignmentEntity);
+  await unsafePushTables(stack.db, { configValuesTable });
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe(
+    "TRUNCATE read_tier_assignments, kumiko_events RESTART IDENTITY CASCADE",
+  );
+});
+
+type GrantResult = { tenantId: string; tier: string; isNew: boolean };
+type GrantRow = { tier: string; source: string };
+type Options = { tiers: ReadonlyArray<string> };
+
+test("SystemAdmin grants a foreign tenant the 'pro' tier without billing", async () => {
+  const adminTenant = testTenantId(1);
+  const targetTenant = testTenantId(2);
+  const sysadmin = createTestUser({ id: 1, tenantId: adminTenant, roles: ["SystemAdmin"] });
+
+  // (1) Grant — cross-tenant write. SystemAdmin sits in adminTenant, the
+  // tier-assignment event lands in targetTenant's stream.
+  const grant = await stack.http.writeOk<GrantResult>(
+    TierEngineHandlers.setTenantTier,
+    { tenantId: targetTenant, tier: "pro" },
+    sysadmin,
+  );
+  expect(grant.tenantId).toBe(targetTenant);
+  expect(grant.tier).toBe("pro");
+  expect(grant.isNew).toBe(true);
+
+  // (2) Read-back via get-tenant-tier — cross-tenant query. source:"manual"
+  // is the load-bearing field: it tells a future Stripe → tier sync NOT
+  // to overwrite the operator-set tier.
+  const row = await stack.http.queryOk<GrantRow>(
+    TierEngineQueries.getTenantTier,
+    { tenantId: targetTenant },
+    sysadmin,
+  );
+  expect(row.tier).toBe("pro");
+  expect(row.source).toBe("manual");
+});
+
+test("tier-options returns the configured TierMap keys (no hard-coding)", async () => {
+  const sysadmin = createTestUser({
+    id: 2,
+    tenantId: testTenantId(3),
+    roles: ["SystemAdmin"],
+  });
+
+  const opts = await stack.http.queryOk<Options>(TierEngineQueries.tierOptions, {}, sysadmin);
+
+  expect(opts.tiers).toEqual(Object.keys(appTierMap));
+});
+
+test("upsert is idempotent — re-granting updates the same aggregate", async () => {
+  const sysadmin = createTestUser({
+    id: 3,
+    tenantId: testTenantId(4),
+    roles: ["SystemAdmin"],
+  });
+  const target = testTenantId(5);
+
+  const first = await stack.http.writeOk<GrantResult>(
+    TierEngineHandlers.setTenantTier,
+    { tenantId: target, tier: "free" },
+    sysadmin,
+  );
+  expect(first.isNew).toBe(true);
+
+  const second = await stack.http.writeOk<GrantResult>(
+    TierEngineHandlers.setTenantTier,
+    { tenantId: target, tier: "pro" },
+    sysadmin,
+  );
+  expect(second.isNew).toBe(false);
+  expect(second.tier).toBe("pro");
+});
+
+test("TenantAdmin without SystemAdmin role cannot grant a foreign tenant a tier", async () => {
+  const tenantAdmin = createTestUser({
+    id: 4,
+    tenantId: testTenantId(6),
+    roles: ["TenantAdmin"],
+  });
+  const target = testTenantId(7);
+
+  const res = await stack.http.write(
+    TierEngineHandlers.setTenantTier,
+    { tenantId: target, tier: "pro" },
+    tenantAdmin,
+  );
+  expect(res.status).toBe(403);
+});
+
+test("set-tenant-tier lights up the tenant's toggleable feature in the resolver — same request, not a projection re-read", async () => {
+  const adminTenant = testTenantId(8);
+  const targetTenant = testTenantId(9);
+  const sysadmin = createTestUser({ id: 5, tenantId: adminTenant, roles: ["SystemAdmin"] });
+
+  // Build the resolver BEFORE the grant, so its in-memory cache is warm with
+  // the pre-grant state. The only path for notes-export to appear afterwards
+  // is the synchronous onAssigned cache update inside set-tenant-tier — not a
+  // fresh projection read at build time.
+  const usage = findTierResolverUsage(recipeFeatures);
+  if (!usage) throw new Error("setup failure: no tier-resolver plugin registered");
+  if (!isTierResolverPlugin(usage.options)) {
+    throw new Error("setup failure: tier-resolver registration has no build() plugin");
+  }
+  const resolver = await usage.options.build({
+    db: stack.db,
+    registry: stack.registry,
+  });
+  expect(resolver(targetTenant).has(NOTES_EXPORT_FEATURE)).toBe(false);
+
+  // SystemAdmin grants "pro" cross-tenant. set-tenant-tier writes through the
+  // event-store executor, which skips the postSave hook that would otherwise
+  // invalidate the cache — so the write calls onAssigned explicitly.
+  await stack.http.writeOk(
+    TierEngineHandlers.setTenantTier,
+    { tenantId: targetTenant, tier: "pro" },
+    sysadmin,
+  );
+
+  // Same process, no rebuild / replay / restart: the resolver already sees
+  // the pro features. Drop onAssigned from createSetTenantTierWrite and this
+  // assertion stays false — the projection updates, the cache does not.
+  expect(resolver(targetTenant).has(NOTES_EXPORT_FEATURE)).toBe(true);
+});
+```
+
+### src/feature.ts
+
+```ts
+// Tier Admin Sample
+//
+// Shows the SystemAdmin-only operator flow: assigning a tier to *any*
+// tenant without a billing purchase. The app side is intentionally tiny —
+// the recipe is the bundled tier-engine itself, configured with the app's
+// own TierMap. The integration test exercises the cross-tenant grant
+// (set-tenant-tier), the read-back (get-tenant-tier returning
+// source:"manual"), and the option-list (tier-options) end-to-end.
+
+import {
+  createTierEngineFeature,
+  type TierMap,
+} from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+// --- App caps ---
+//
+// Each app picks its own cap dimensions. Here a tiny example: how many
+// notes a tenant may keep. The TierMap is generic in this cap-shape so
+// downstream code stays type-safe end-to-end.
+
+export type AppCaps = { readonly maxNotes: number };
+
+// --- The toggleable feature a paid tier unlocks ---
+//
+// A `r.toggleable()` feature shows up in a tenant's effective-features set
+// exactly when its tier lists it. "pro" lists it below; "free" does not.
+// This is what makes the cache-sync invariant observable: granting "pro"
+// must light this feature up in the resolver the same request, not after a
+// refresh, replay, or restart.
+
+export const NOTES_EXPORT_FEATURE = "notes-export";
+
+export const notesExportFeature = defineFeature(NOTES_EXPORT_FEATURE, (r) => {
+  r.toggleable({ default: false });
+});
+
+// --- Tier map ---
+//
+// "free" + "pro" — the operator picks one of these names when granting
+// a tier manually. "pro" unlocks the notes-export toggleable feature; the
+// integration test grants "pro" and then reaches that feature in the same
+// request, proving the cache-sync invariant end-to-end.
+
+export const appTierMap: TierMap<AppCaps> = {
+  free: { features: [], caps: { maxNotes: 5 } },
+  pro: { features: [NOTES_EXPORT_FEATURE], caps: { maxNotes: 100 } },
+};
+
+// --- Configured tier-engine ---
+//
+// `defaultTier: "free"` means every new tenant starts on free via the
+// `inTransaction` entity hook the tier-engine registers — no app code
+// needed. `tierMap` makes `tier-options` return ["free", "pro"] so the
+// tier-admin screen can populate its picker without hard-coding.
+
+export const tierEngineForApp = createTierEngineFeature<AppCaps>({
+  defaultTier: "free",
+  tierMap: appTierMap,
+});
+```