create-kumiko-app 0.367.0 → 0.369.0

package/feature-manifest.json

@@ -407,7 +407,7 @@
     },
     {
       "name": "channel-email",
-      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
+      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send the notifications declared with `tenantTransport: true` through the sending tenant's own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`; every other notification (password reset, sign-in) always goes through the app `transport`. `transport` may be left out when `tenantTransport` is set; a mail that then has no transport fails with `missing_credentials`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -725,7 +725,7 @@
     },
     {
       "name": "delivery",
-      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
+      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (the `runProdApp` and `runDevApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. An app serving its own (e.g. legacy) unsubscribe links renders the same result page with `renderUnsubscribeResultPage({ kind, locale })`. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
       "toggleableDefault": null,
       "requires": [
         "tenant"
@@ -1507,7 +1507,7 @@
     },
     {
       "name": "mail-foundation",
-      "description": "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.",
+      "description": "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature`: notifications declared with `tenantTransport: true` then go through the tenant's own transport when it has a provider and through the app transport otherwise. Tenant admins pick the provider and fill in its settings on the generated Email sending settings screen; an empty provider is a valid choice and means the platform sends.",
       "toggleableDefault": null,
       "requires": [
         "config"
@@ -1531,8 +1531,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1603,8 +1603,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1624,8 +1624,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1645,8 +1645,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "TenantAdmin",
@@ -1669,8 +1669,8 @@
           },
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "all"
@@ -1689,8 +1689,8 @@
           "bounds": null,
           "pattern": null,
           "writeRoles": [
-            "TenantAdmin",
-            "SystemAdmin"
+            "system",
+            "TenantAdmin"
           ],
           "readRoles": [
             "all"
@@ -2191,7 +2191,7 @@
     },
     {
       "name": "secrets",
-      "description": "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: [\"TenantAdmin\"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins).",
+      "description": "Stores arbitrary per-tenant secrets (API keys, tokens, credentials) encrypted at rest using AES-256 with a KEK loaded from `KUMIKO_SECRETS_MASTER_KEY_V1` (and successive versions for rotation). Read a secret in handlers via `ctx.secrets.get(tenantId, handle)`, which automatically appends a `tenantSecretRead` audit event so every access is traceable. A `rotate` job re-encrypts all envelopes after a KEK version bump. The `set`/`delete`/`list` handlers share one access rule — default { roles: [\"TenantAdmin\"] }; adopt the host's role vocabulary with createSecretsFeature({ roles }) or open it to every authenticated tenant user with { access: { openToAll: { reason } } } (larger blast radius: any tenant member can then read secret previews and write/delete secrets, not just admins). Server-side code writes a tenant secret with `dispatchSystemWrite({ handlerQn: \"secrets:write:set\", payload, tenantId })`: set and delete also admit the in-process system identity, so such writes pass the same declared-key and value checks.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-kumiko-app",
-  "version": "0.367.0",
+  "version": "0.369.0",
   "description": "`bun create kumiko-app <name>` — scaffold a new Kumiko app with an interactive feature picker.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -27,10 +27,10 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.367.0",
-    "@cosmicdrift/kumiko-framework": "0.367.0",
-    "@cosmicdrift/kumiko-server-runtime": "0.367.0",
-    "@cosmicdrift/kumiko-testing": "0.367.0",
+    "@cosmicdrift/kumiko-dev-server": "0.369.0",
+    "@cosmicdrift/kumiko-framework": "0.369.0",
+    "@cosmicdrift/kumiko-server-runtime": "0.369.0",
+    "@cosmicdrift/kumiko-testing": "0.369.0",
     "@inquirer/core": "^10.0.0",
     "@inquirer/prompts": "^7.4.0"
   },

package/src/feature-constructors.ts

@@ -7,11 +7,6 @@
 // subscription-mollie, file-provider-s3, managed-pages, tier-engine) are
 // intentionally absent — the picker hides them, the user wires them by
 // hand after scaffold.
-//
-// Naming inconsistency is intentional and historical: most features expose
-// `create<Pascal>Feature` factories, a handful export the FeatureDefinition
-// object directly. The callExpression captures that: `()` for factories,
-// bare name for objects.
 
 import type { ScaffoldFeatureEntry } from "@cosmicdrift/kumiko-dev-server";
 
@@ -32,8 +27,8 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   "auth-foundation": {
     name: "auth-foundation",
     importPath: "@cosmicdrift/kumiko-bundled-features/auth-foundation",
-    exportName: "authFoundationFeature",
-    callExpression: "authFoundationFeature",
+    exportName: "createAuthFoundationFeature",
+    callExpression: "createAuthFoundationFeature()",
   },
   "personal-access-tokens": {
     name: "personal-access-tokens",
@@ -85,8 +80,8 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   "cap-counter": {
     name: "cap-counter",
     importPath: "@cosmicdrift/kumiko-bundled-features/cap-counter",
-    exportName: "capCounterFeature",
-    callExpression: "capCounterFeature",
+    exportName: "createCapCounterFeature",
+    callExpression: "createCapCounterFeature()",
   },
   "step-dispatcher": {
     name: "step-dispatcher",
@@ -105,14 +100,14 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   "file-foundation": {
     name: "file-foundation",
     importPath: "@cosmicdrift/kumiko-bundled-features/file-foundation",
-    exportName: "fileFoundationFeature",
-    callExpression: "fileFoundationFeature",
+    exportName: "createFileFoundationFeature",
+    callExpression: "createFileFoundationFeature()",
   },
   "file-provider-inmemory": {
     name: "file-provider-inmemory",
     importPath: "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory",
-    exportName: "fileProviderInMemoryFeature",
-    callExpression: "fileProviderInMemoryFeature",
+    exportName: "createFileProviderInMemoryFeature",
+    callExpression: "createFileProviderInMemoryFeature()",
   },
 
   // --- Notifications ---
@@ -125,20 +120,20 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   "mail-foundation": {
     name: "mail-foundation",
     importPath: "@cosmicdrift/kumiko-bundled-features/mail-foundation",
-    exportName: "mailFoundationFeature",
-    callExpression: "mailFoundationFeature",
+    exportName: "createMailFoundationFeature",
+    callExpression: "createMailFoundationFeature()",
   },
   "mail-transport-inmemory": {
     name: "mail-transport-inmemory",
     importPath: "@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory",
-    exportName: "mailTransportInMemoryFeature",
-    callExpression: "mailTransportInMemoryFeature",
+    exportName: "createMailTransportInMemoryFeature",
+    callExpression: "createMailTransportInMemoryFeature()",
   },
   "mail-transport-smtp": {
     name: "mail-transport-smtp",
     importPath: "@cosmicdrift/kumiko-bundled-features/mail-transport-smtp",
-    exportName: "mailTransportSmtpFeature",
-    callExpression: "mailTransportSmtpFeature",
+    exportName: "createMailTransportSmtpFeature",
+    callExpression: "createMailTransportSmtpFeature()",
   },
   "channel-in-app": {
     name: "channel-in-app",
@@ -163,8 +158,8 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   "billing-foundation": {
     name: "billing-foundation",
     importPath: "@cosmicdrift/kumiko-bundled-features/billing-foundation",
-    exportName: "billingFoundationFeature",
-    callExpression: "billingFoundationFeature",
+    exportName: "createBillingFoundationFeature",
+    callExpression: "createBillingFoundationFeature()",
   },
 
   // --- Compliance ---
@@ -221,8 +216,8 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   readiness: {
     name: "readiness",
     importPath: "@cosmicdrift/kumiko-bundled-features/readiness",
-    exportName: "readinessFeature",
-    callExpression: "readinessFeature",
+    exportName: "createReadinessFeature",
+    callExpression: "createReadinessFeature()",
   },
 
   // --- Content ---
@@ -237,14 +232,14 @@ export const FEATURE_CONSTRUCTORS: Readonly<Record<string, ScaffoldFeatureEntry>
   tags: {
     name: "tags",
     importPath: "@cosmicdrift/kumiko-bundled-features/tags",
-    exportName: "tagsFeature",
-    callExpression: "tagsFeature",
+    exportName: "createTagsFeature",
+    callExpression: "createTagsFeature()",
   },
   "custom-fields": {
     name: "custom-fields",
     importPath: "@cosmicdrift/kumiko-bundled-features/custom-fields",
-    exportName: "customFieldsFeature",
-    callExpression: "customFieldsFeature",
+    exportName: "createCustomFieldsFeature",
+    callExpression: "createCustomFieldsFeature()",
   },
 };