@cosmicdrift/kumiko-samples 0.384.0 → 0.385.0

package/packages/bundled-features/src/auth-email-password/web/auth-form-primitives.tsx

@@ -1,17 +1,14 @@
-// Shared Web-Primitives für die Auth-Screens. Nur noch Layout/Style-
-// Helpers — Form/Field/Input/Button/Banner kommen jetzt über
-// usePrimitives() aus dem Framework-Vertrag, damit Native dieselben
-// Auth-Screens rendern kann (renderer-native registriert eigene
-// Implementations).
+// Shared web primitives for the auth screens. Only layout/style helpers are
+// left here; Form/Field/Input/Button/Banner come through usePrimitives() from
+// the framework contract, so apps and tests can override the implementations
+// via PrimitivesProvider.
 //
-//   <AuthCard>          — Card-Wrapper für die Auth-Screen-Layouts
-//                         (full-screen, zentriert, max-w-sm). Web-only;
-//                         eine Native-Variante landet bei Bedarf
-//                         daneben (z.B. SafeArea + ScrollView).
-//   parseUrlToken       — URL-Param-Helper (window.location.search).
+//   <AuthCard>          — card wrapper for the auth screen layouts
+//                         (full-screen, centered, max-w-sm). Web-only.
+//   parseUrlToken       — URL param helper (window.location.search).
 //
-// Link-Styles laufen über das Link-Primitive (variant="button"/"muted") —
-// die früheren authButtonClass/authMutedLinkClass sind dorthin gewandert.
+// Link styles go through the Link primitive (variant="button"/"muted"); the
+// former authButtonClass/authMutedLinkClass moved there.
 
 import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
 import { BareFormProvider, cn } from "@cosmicdrift/kumiko-renderer/web";

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -16,7 +16,7 @@ export const unreadCountQuery = defineQueryHandler({
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
-    // bun-db hat keinen aggregate-helper — selectMany alle matching rows,
+    // The query helpers in db/query.ts have no aggregate helper — selectMany alle matching rows,
     // count() in JS. Pragma: unread-counts sind low-cardinality (user-
     // scoped, max ~hunderte rows). Wenn das wachsen sollte: raw .unsafe()
     // mit COUNT(*).

package/packages/bundled-features/src/custom-fields/db/queries/projection.ts

@@ -9,7 +9,7 @@ function quoteTable(tableName: string): string {
 function bindJsonbParam(value: unknown): { sql: string; bound: unknown } {
   // Scalar JSON primitives can't bind directly to ::jsonb — Postgres rejects a
   // bound boolean/number with "cannot cast type boolean/integer to jsonb" (and
-  // Bun.SQL infers boolean[] candidates). Route them through ::text::jsonb with
+  // the driver may infer array candidates). Route them through ::text::jsonb with
   // a JSON-encoded literal. Objects/arrays/strings already bind as ::jsonb.
   if (typeof value === "boolean" || typeof value === "number") {
     return { sql: "$1::text::jsonb", bound: JSON.stringify(value) };

package/packages/bundled-features/src/file-derivatives/feature.ts

@@ -183,7 +183,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
             // answer identically, no name-oracle. fileRefsTable.id is a UUID
             // column — a malformed id must fail here, not at the DB. Without
             // this, an anonymous, internet-facing caller can throw a Postgres
-            // 22P02 on every request (Bun.SQL pools the failed connection), a
+            // 22P02 on every request (the pooled connection is affected), a
             // DoS primitive with no auth required.
             if (!fileRefId || !variant || !VARIANT_NAME_RE.test(variant) || !isUuid(fileRefId)) {
               return c.text("not found", 404);

package/packages/bundled-features/src/ledger/web/index.ts

@@ -1,7 +1,7 @@
 // Client-safe ledger surface: QN constants, the pure recurring helpers
 // (projection + Soll/Ist merge), and the Zod payload schemas (for client-side
 // pre-validation before dispatch) — nothing else. The full `../ledger` entry
-// re-exports the feature/handlers/executor, which pull bun-db/postgres — a
+// re-exports the feature/handlers/executor, which pull postgres-js — a
 // browser bundle that imports from there fails on Node builtins. A client screen
 // (e.g. a rent-cashflow view) imports the dispatch QNs + the pure forecast/merge
 // from HERE, then dispatches via the renderer's useDispatcher.

package/packages/bundled-features/src/notes-history/handlers/add-note.write.ts

@@ -69,7 +69,7 @@ export function createAddNoteHandler(
       let authorName: string | null = null;
       try {
         // read_users is tenant-agnostic → ctx.db.unsafeRaw, not the tenant-scoped ctx.db.
-        // Bun.SQL poisons the whole tx after any error inside it, even one that's
+        // postgres-js poisons the whole tx after any error inside it, even one that's
         // caught — so the lookup runs in a savepoint where available, otherwise directly
         // (pool statements are their own units).
         authorName = await runInSavepointIfSupported(ctx.db.unsafeRaw(), async (sp) => {

package/packages/bundled-features/src/personal-access-tokens/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.385.0",
+    "type": "improvement",
+    "title": "patScopeOptionKey for translating token scope labels",
+    "detail": "The scope labels personal-access-tokens generates from `scopes[domain].label` are English only. `patScopeOptionKey(domain, \"read\" | \"write\")` returns their translation key, so an app feature can add the other locales with `r.translations`.",
+    "migration": "Apps that mount personal-access-tokens and set `requiredLocales` with a locale other than `en` translate each generated scope label (`read`, plus `write` where the domain offers it) under `patScopeOptionKey`."
+  },
   {
     "version": "0.372.0",
     "type": "fix",

package/packages/bundled-features/src/personal-access-tokens/i18n.ts

@@ -8,6 +8,10 @@ const mintFieldKey = (field: string): string =>
 const scopeOptionKey = (grant: string): string =>
   fieldOptionLabelKey(PAT_FEATURE, ACTION_FORM_ENTITY, "scopes", grant);
 
+// The generated scope labels are English only; apps translate them under this key.
+export const patScopeOptionKey = (domain: string, level: "read" | "write"): string =>
+  scopeOptionKey(`${domain}:${level}`);
+
 type LocalizedString = { readonly en: string };
 
 export const PAT_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {

package/packages/bundled-features/src/personal-access-tokens/index.ts

@@ -8,6 +8,7 @@ export {
 } from "./feature.ts";
 export type { CreatePatOptions, PatMfaVerifyResult } from "./handlers/create.write.ts";
 export { hashPatToken, mintPatToken } from "./hash.ts";
+export { patScopeOptionKey } from "./i18n.ts";
 export {
   PAT_REVOKED_AGGREGATE_TYPE,
   PAT_REVOKED_EVENT_QN,

package/packages/bundled-features/src/shared/run-in-sub-transaction.ts

@@ -1,7 +1,7 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 
 // Per-unit sub-transaction (one user, one purged row), nesting-aware across both db shapes:
-//   - top-level connection (Bun.SQL / postgres-js Sql) → `.begin` (BEGIN)
+//   - top-level connection (postgres-js Sql) → `.begin` (BEGIN)
 //   - TransactionSql (inside the dispatcher's outer tx, where every
 //     writeHandler already runs) → `.savepoint` (SAVEPOINT)
 // A TransactionSql has no `.begin`, so the previous unconditional `.begin`

package/samples/apps/use-all-bundled/bin/main.ts

@@ -8,7 +8,12 @@ import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
 import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
-import { APP_FEATURES, AUTH_COMPOSE_OPTIONS, BOOT_FEATURES } from "../src/run-config";
+import {
+  APP_FEATURES,
+  AUTH_COMPOSE_OPTIONS,
+  BOOT_FEATURES,
+  VALIDATE_BOOT_OPTIONS,
+} from "../src/run-config";
 
 const SMOKE_TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;
 
@@ -21,6 +26,7 @@ await runProdApp({
   features: BOOT_FEATURES,
   featureToggles: true,
   envSchema,
+  validateBootOptions: VALIDATE_BOOT_OPTIONS,
   // Smoke-only: exercises the hard PII boot gate + blind-index gate with
   // every bundled feature mounted. Real apps wire createPgKmsAdapter(...).
   kms: new InMemoryKmsAdapter(),

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 86,
+  "featureCount": 87,
   "features": [
     {
       "name": "account-security",
@@ -2070,6 +2070,20 @@
       "secrets": [],
       "writeHandlers": []
     },
+    {
+      "name": "pat-scope-labels",
+      "description": "German labels for the token scopes this sample app declares.",
+      "toggleableDefault": null,
+      "requires": [],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": []
+    },
     {
       "name": "personal-access-tokens",
       "description": "Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the `store_api_tokens` direct-write table; the plaintext is returned once at creation. `create`/`revoke`/`mine` manage a user's own tokens and `available-scopes` lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.",

package/samples/apps/use-all-bundled/kumiko/schema.ts

@@ -11,7 +11,9 @@
 import { collectTableMetas, type EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { composeFeatures } from "@cosmicdrift/kumiko-server-runtime/compose-features";
-import { APP_FEATURES, AUTH_COMPOSE_OPTIONS } from "../src/run-config";
+import { APP_FEATURES, AUTH_COMPOSE_OPTIONS, VALIDATE_BOOT_OPTIONS } from "../src/run-config";
+
+export { VALIDATE_BOOT_OPTIONS };
 
 export const FEATURES: readonly FeatureDefinition[] = composeFeatures(APP_FEATURES, {
   includeBundled: true,

package/samples/apps/use-all-bundled/src/app/dev-app-options.ts

@@ -13,7 +13,7 @@
 import { createTemplateResolverApi } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
 import type { RunDevAppOptions } from "@cosmicdrift/kumiko-dev-server";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES } from "../run-config";
+import { AUTH_COMPOSE_OPTIONS, BOOT_FEATURES, VALIDATE_BOOT_OPTIONS } from "../run-config";
 import { ADMIN_EMAIL, ADMIN_PASSWORD, BETA_TENANT_ID, DEV_TENANT_ID } from "./auth-constants";
 import { invoiceReportsFeature } from "./invoice-reports-feature";
 import { notesFeature } from "./notes-feature";
@@ -30,6 +30,7 @@ export const devAppOptions = {
   // it stays out of APP_FEATURES. appScreensFeature places the user-profile screen.
   features: [...BOOT_FEATURES, appScreensFeature, notesFeature, invoiceReportsFeature],
   featureToggles: true,
+  validateBootOptions: VALIDATE_BOOT_OPTIONS,
   port: Number.parseInt(process.env["PORT"] ?? "4186", 10),
   clientEntry: "./src/app/client.tsx",
   htmlPath: "./public/index.html",

package/samples/apps/use-all-bundled/src/app/pat-scope-labels-feature.ts

@@ -0,0 +1,21 @@
+import { patScopeOptionKey } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+// The scope domains in run-config.ts are the app's choice, so their German
+// labels are too: personal-access-tokens only generates the English ones.
+export const patScopeLabelsFeature = defineFeature("pat-scope-labels", (r) => {
+  r.describe("German labels for the token scopes this sample app declares.");
+  r.translations({
+    keys: {
+      [patScopeOptionKey("pages", "read")]: { de: "Seiten (lesen)" },
+      [patScopeOptionKey("pages", "write")]: { de: "Seiten (lesen & schreiben)" },
+      [patScopeOptionKey("tags", "read")]: { de: "Tags (lesen)" },
+      [patScopeOptionKey("tags", "write")]: { de: "Tags (lesen & schreiben)" },
+      [patScopeOptionKey("notesHistory", "read")]: { de: "Notizen (lesen)" },
+      [patScopeOptionKey("notesHistory", "write")]: { de: "Notizen (lesen & schreiben)" },
+      [patScopeOptionKey("ledger", "read")]: { de: "Hauptbuch (lesen)" },
+      [patScopeOptionKey("ledger", "write")]: { de: "Hauptbuch (lesen & schreiben)" },
+    },
+  });
+  return {};
+});

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -102,6 +102,7 @@ import { DEV_TENANT_ID } from "./app/auth-constants";
 import { CAP_OVERVIEW_CAPS } from "./app/cap-overview-caps";
 import { capOverviewLabelsFeature } from "./app/cap-overview-labels-feature";
 import { collectionLabelsFeature } from "./app/collection-labels-feature";
+import { patScopeLabelsFeature } from "./app/pat-scope-labels-feature";
 
 // Smoke-only stubs. Boot-mode skipt jede operative Methode — diese werden
 // nie aufgerufen, nur typecheck'd.
@@ -161,6 +162,7 @@ export const APP_FEATURES = [
       ledger: { label: "Ledger", read: ["ledger:query:*"], write: ["ledger:write:*"] },
     },
   }),
+  patScopeLabelsFeature,
   createReadinessFeature(),
 
   // delivery + channels
@@ -417,6 +419,9 @@ export const BOOT_FEATURES = APP_FEATURES.filter(
 // Smoke signup — enables createAuthSelfRegistrationToggleFeature via
 // composeFeatures when passed as authOptions (#1521 Option A). Same shape
 // as run{Dev,Prod}App's auth.signup; appUrl is a stub (no real mail in boot).
+// locale-de is mounted, so every translation key must exist in German and English.
+export const VALIDATE_BOOT_OPTIONS = { requiredLocales: ["de", "en"] } as const;
+
 export const AUTH_COMPOSE_OPTIONS = {
   signup: {
     appUrl: "http://localhost:4186/signup",

package/samples/recipes/i18n/README.md

@@ -6,6 +6,7 @@ Feature-scoped translations — 'Hallo' and 'Hello' in the same app.
 
 - `r.translations()` for multi-language feature keys
 - Plurals
+- `requiredLocales`: boot fails when a key misses one of the app's languages
 
 ## Plurals
 
@@ -24,6 +25,20 @@ exist where the locale's grammar needs them:
 `Intl.PluralRules(locale)`, then interpolates `{count}` (and any other
 `{name}` placeholder) into the chosen form.
 
+## Required locales
+
+Without further options boot only checks that each feature is consistent with
+itself. An app that ships fixed languages lists them, and boot then fails on any
+key that misses one of them, including framework keys. Locale packages such as
+`locale-de` count:
+
+```ts illustration
+runProdApp({ ...options, validateBootOptions: { requiredLocales: ["de", "en"] } });
+```
+
+Define the options once and re-export them as `VALIDATE_BOOT_OPTIONS` from
+`kumiko/schema.ts`, so `kumiko-schema validate` checks the same list in CI.
+
 ## Source
 
 Feature entry point: `src/feature.ts`.

package/samples/recipes/i18n/src/feature.ts

@@ -11,20 +11,24 @@ export const greetingFeature = defineFeature("greeting", (r) => {
         de: "Willkommen",
         en: "Welcome",
         fr: "Bienvenue",
+        pl: "Witamy",
       },
       "greeting.goodbye": {
         de: "Auf Wiedersehen",
         en: "Goodbye",
         fr: "Au revoir",
+        pl: "Do widzenia",
       },
       "greeting.hello_name": {
         de: "Hallo, {name}!",
         en: "Hello, {name}!",
         fr: "Bonjour, {name}!",
+        pl: "Cześć, {name}!",
       },
       "greeting.unread_count": {
         de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
         en: { one: "{count} unread message", other: "{count} unread messages" },
+        fr: { one: "{count} message non lu", other: "{count} messages non lus" },
         pl: {
           one: "{count} nieprzeczytana wiadomość",
           few: "{count} nieprzeczytane wiadomości",