@cosmicdrift/kumiko-samples 0.353.0 → 0.354.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.353.0",
+  "version": "0.354.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.353.0",
+  "version": "0.354.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -17,7 +17,8 @@
   "kumiko": {
     "runtime": "runtime",
     "bunOnlyExports": [
-      "./template-resolver/testing"
+      "./template-resolver/testing",
+      "./tenant-lifecycle/testing"
     ]
   },
   "exports": {
@@ -81,12 +82,14 @@
     "./files-tenant-data": "./src/files-tenant-data/index.ts",
     "./user-data-rights": "./src/user-data-rights/index.ts",
     "./user-data-rights/web": "./src/user-data-rights/web/index.ts",
+    "./user-data-rights/email-templates": "./src/user-data-rights/email-templates.ts",
     "./user-data-rights-defaults": "./src/user-data-rights-defaults/index.ts",
     "./tenant": "./src/tenant/index.ts",
     "./tenant/constants": "./src/tenant/constants.ts",
     "./tenant/web": "./src/tenant/web/index.ts",
     "./tenant/seeding": "./src/tenant/seeding.ts",
     "./tenant-lifecycle": "./src/tenant-lifecycle/index.ts",
+    "./tenant-lifecycle/testing": "./src/tenant-lifecycle/testing.ts",
     "./tenant-handover": "./src/tenant-handover/index.ts",
     "./tenant/testing": "./src/tenant/testing.ts",
     "./user": "./src/user/index.ts",
@@ -96,6 +99,7 @@
     "./user-profile/web": "./src/user-profile/web/index.ts",
     "./auth-email-password": "./src/auth-email-password/index.ts",
     "./auth-email-password/constants": "./src/auth-email-password/constants.ts",
+    "./auth-email-password/email-templates": "./src/auth-email-password/email-templates.ts",
     "./auth-email-password/seeding": "./src/auth-email-password/seeding.ts",
     "./auth-email-password/testing": "./src/auth-email-password/testing.ts",
     "./auth-email-password/web": "./src/auth-email-password/web/index.ts",
@@ -411,6 +415,10 @@
         "types": "./dist/user-data-rights/index.d.ts",
         "default": "./dist/user-data-rights/index.js"
       },
+      "./user-data-rights/email-templates": {
+        "types": "./dist/user-data-rights/email-templates.d.ts",
+        "default": "./dist/user-data-rights/email-templates.js"
+      },
       "./user-data-rights/web": {
         "types": "./dist/user-data-rights/web/index.d.ts",
         "default": "./dist/user-data-rights/web/index.js"
@@ -439,6 +447,10 @@
         "types": "./dist/tenant-lifecycle/index.d.ts",
         "default": "./dist/tenant-lifecycle/index.js"
       },
+      "./tenant-lifecycle/testing": {
+        "types": "./dist/tenant-lifecycle/testing.d.ts",
+        "default": "./dist/tenant-lifecycle/testing.js"
+      },
       "./tenant-handover": {
         "types": "./dist/tenant-handover/index.d.ts",
         "default": "./dist/tenant-handover/index.js"
@@ -471,6 +483,10 @@
         "types": "./dist/auth-email-password/index.d.ts",
         "default": "./dist/auth-email-password/index.js"
       },
+      "./auth-email-password/email-templates": {
+        "types": "./dist/auth-email-password/email-templates.d.ts",
+        "default": "./dist/auth-email-password/email-templates.js"
+      },
       "./auth-email-password/constants": {
         "types": "./dist/auth-email-password/constants.d.ts",
         "default": "./dist/auth-email-password/constants.js"

package/packages/bundled-features/src/agent-tools/agent-doc-lint.ts

@@ -4,6 +4,8 @@ import type {
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  handlerFieldLabelKey,
+  handlerTitleKey,
   isAgentVisibleScreen,
   QnTypes,
   qn,
@@ -11,12 +13,14 @@ import {
   toKebab,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { systemOnlyPropertyNames } from "./agent-manifest.js";
 
 export const AgentDocGapKinds = {
   handlerSchemaNotExpressible: "handler-schema-not-expressible",
   handlerWithoutDescription: "handler-without-description",
   customScreenWithoutDescription: "custom-screen-without-description",
   exposedEntityWithoutDescription: "exposed-entity-without-description",
+  handlerWithoutTranslation: "handler-without-translation",
 } as const;
 
 export type AgentDocGapKind = (typeof AgentDocGapKinds)[keyof typeof AgentDocGapKinds];
@@ -144,6 +148,58 @@ function exposedEntityDocGaps(feature: FeatureDefinition): readonly AgentDocGap[
   return gaps;
 }
 
+function actionFormHandlerQns(features: readonly FeatureDefinition[]): ReadonlySet<string> {
+  const handlerQns = new Set<string>();
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens ?? {})) {
+      if (screen.type === "actionForm") handlerQns.add(screen.handler);
+    }
+  }
+  return handlerQns;
+}
+
+function agentVisibleInputFieldNames(schema: z.ZodType): readonly string[] {
+  if (!(schema instanceof z.ZodObject)) return [];
+  const fieldNames = Object.keys(schema.shape);
+  try {
+    const systemOnly = new Set(systemOnlyPropertyNames(z.toJSONSchema(schema, { io: "input" })));
+    return fieldNames.filter((field) => !systemOnly.has(field));
+  } catch {
+    // skip: a schema without JSON Schema form is reported as its own gap kind
+    return fieldNames;
+  }
+}
+
+function translationGapsOfFeature(
+  feature: FeatureDefinition,
+  coveredHandlerQns: ReadonlySet<string>,
+): readonly AgentDocGap[] {
+  const gaps: AgentDocGap[] = [];
+  // The client resolves translation keys verbatim (no feature prefix), so only
+  // fully spelled-out keys count.
+  const translated = new Set(Object.keys(feature.translations ?? {}));
+  for (const [name, def] of Object.entries(feature.writeHandlers ?? {})) {
+    if (!resolveAgentExposure(def, "write").expose) continue;
+    if (feature.handlerEntityMappings?.[name] !== undefined) continue;
+    const handlerQn = qn(toKebab(feature.name), QnTypes.write, toKebab(name));
+    if (coveredHandlerQns.has(handlerQn)) continue;
+    const missing = [
+      handlerTitleKey(handlerQn),
+      ...agentVisibleInputFieldNames(def.schema).map((field) =>
+        handlerFieldLabelKey(handlerQn, field),
+      ),
+    ].filter((key) => !translated.has(key));
+    if (missing.length === 0) continue;
+    gaps.push({
+      qn: handlerQn,
+      feature: feature.name,
+      kind: AgentDocGapKinds.handlerWithoutTranslation,
+      message: `This write handler has no entity and no actionForm screen, so its title and field labels can only come from translations — missing keys: ${missing.join(", ")}.`,
+    });
+  }
+  return gaps;
+}
+
 export function findAgentDocGaps(features: readonly FeatureDefinition[]): readonly AgentDocGap[] {
   const gaps: AgentDocGap[] = [];
   for (const feature of features) {
@@ -161,6 +217,16 @@ export function findAgentDocGaps(features: readonly FeatureDefinition[]): readon
   return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
 }
 
+// Kept out of findAgentDocGaps on purpose: the published agent-manifest guard
+// fails on every gap that function returns, and these are advisory.
+export function findHandlerTranslationGaps(
+  features: readonly FeatureDefinition[],
+): readonly AgentDocGap[] {
+  const coveredHandlerQns = actionFormHandlerQns(features);
+  const gaps = features.flatMap((feature) => translationGapsOfFeature(feature, coveredHandlerQns));
+  return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
+}
+
 export function formatAgentDocGap(gap: AgentDocGap): string {
   return `${gap.qn} — ${gap.message}`;
 }

package/packages/bundled-features/src/agent-tools/agent-manifest.ts

@@ -194,16 +194,22 @@ function buildFeatures(
 
 // Agent dispatch never runs as a system identity, so properties the engine only
 // honors for system callers would be silently dropped — hide them from the tool.
-function withoutSystemOnlyProperties(
-  jsonSchema: Record<string, unknown>,
-): Readonly<Record<string, unknown>> {
+export function systemOnlyPropertyNames(jsonSchema: Record<string, unknown>): readonly string[] {
   const properties = jsonSchema["properties"];
-  if (typeof properties !== "object" || properties === null) return jsonSchema;
-  const hidden = Object.entries(properties)
+  if (typeof properties !== "object" || properties === null) return [];
+  return Object.entries(properties)
     .filter(
       ([, property]) => (property as Record<string, unknown>)[SYSTEM_ONLY_JSON_SCHEMA_KEY] === true,
     )
     .map(([name]) => name);
+}
+
+function withoutSystemOnlyProperties(
+  jsonSchema: Record<string, unknown>,
+): Readonly<Record<string, unknown>> {
+  const properties = jsonSchema["properties"];
+  if (typeof properties !== "object" || properties === null) return jsonSchema;
+  const hidden = systemOnlyPropertyNames(jsonSchema);
   if (hidden.length === 0) return jsonSchema;
   const required = jsonSchema["required"];
   return {

package/packages/bundled-features/src/agent-tools/feature.ts

@@ -1,5 +1,9 @@
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import { findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint.js";
+import {
+  findAgentDocGaps,
+  findHandlerTranslationGaps,
+  formatAgentDocGap,
+} from "./agent-doc-lint.js";
 
 export const AGENT_TOOLS_FEATURE_NAME = "agent-tools";
 
@@ -19,8 +23,15 @@ export function createAgentToolsFeature(): FeatureDefinition {
     // would turn every incrementally-documented app into an outage.
     r.bootCheck(({ features }) => {
       const gaps = findAgentDocGaps(features);
+      const warningCount = findHandlerTranslationGaps(features).length;
+      if (warningCount > 0) {
+        // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps
+        console.warn(
+          `[agent-tools] ${warningCount} agent-exposed write handler(s) lack title/field-label translations — run \`kumiko agent lint\` for details.`,
+        );
+      }
       if (gaps.length === 0) {
-        // skip: no documentation gaps, nothing to warn about
+        // skip: no blocking documentation gaps, nothing more to warn about
         return;
       }
       // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps

package/packages/bundled-features/src/agent-tools/index.ts

@@ -1,5 +1,10 @@
 export type { AgentDocGap, AgentDocGapKind } from "./agent-doc-lint.js";
-export { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint.js";
+export {
+  AgentDocGapKinds,
+  findAgentDocGaps,
+  findHandlerTranslationGaps,
+  formatAgentDocGap,
+} from "./agent-doc-lint.js";
 export { buildAgentManifest } from "./agent-manifest.js";
 export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.js";
 export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.js";

package/packages/bundled-features/src/agent-tools/tool-dispatch.ts

@@ -1,5 +1,5 @@
-import { runAsDirectCallEntry } from "@cosmicdrift/kumiko-framework/api";
 import type { SessionUser, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import { runAsDirectCallEntry } from "@cosmicdrift/kumiko-framework/internal/request-context";
 import { FILTER_OPS, isRecord } from "./filter-ops.js";
 import type { ToolDispatchDescriptor } from "./types.js";
 

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.354.0",
+    "type": "breaking",
+    "title": "Invitations pin the invitee's membership version; superseded accept no longer relies on timestamps",
+    "migration": "New nullable column read_tenant_invitations.membership_version: run `kumiko schema generate` and apply the migration before deploying. Invitations issued before the migration keep the timestamp comparison."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "Login, MFA verify and MFA preauth setup follow the server landingPath when no valid next parameter is present",
+    "detail": "AuthGate onSuccess receives the landing path. A validated next parameter still wins; a landing path equal to the current path is not followed, so the screen does not reload itself."
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "Signup-confirm and invite-signup-complete store the request locale on the new user and in the session"
+  },
+  {
+    "version": "0.354.0",
+    "type": "fix",
+    "title": "INITIAL_SIGNUP_ROLES stays [\"TenantAdmin\", \"Admin\"] as a transition",
+    "detail": "New self-signup owners hold TenantAdmin plus the legacy Admin literal, because handlers that gate on the Admin literal would otherwise lock them out. Both roles show in Team, Members until those handlers gate on access.admin. This supersedes the earlier note that the owner role is only TenantAdmin.",
+    "migration": "Move your own handlers that gate on the Admin literal to access.admin; after that the Admin entry can be dropped from the constant."
+  },
   {
     "version": "0.348.0",
     "type": "fix",

package/packages/bundled-features/src/auth-email-password/handlers/change-password.write.ts

@@ -22,6 +22,7 @@ export const changePasswordWrite = defineWriteHandler({
   }),
   access: { roles: access.authenticated },
   escapeHatch: {
+    grants: ["systemIdentity"],
     reason:
       "Reads the caller's own passwordHash (privileged-only field) via ctx.queryAs(SYSTEM, ...) " +
       "and writes the new hash via ctx.writeAs(SYSTEM, user:update) — the caller's own " +

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -41,7 +41,7 @@ import {
   tenantInvitationsTable,
 } from "../../tenant/invitation-table.js";
 // kumiko-lint-ignore cross-feature-import membership grant for a privileged cross-tenant add
-import { grantInvitedMembershipRole, invitationIssuedAt } from "../../tenant/invited-membership.js";
+import { grantInvitedMembershipRole } from "../../tenant/invited-membership.js";
 // kumiko-lint-ignore cross-feature-import global roles granted on invite accept live on the user row
 import {
   grantInvitedGlobalRoles,
@@ -150,6 +150,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
         readonly role: string;
         readonly globalRoles: unknown;
         readonly version: number;
+        readonly membershipVersion: number | null;
         readonly insertedAt: Temporal.Instant;
         readonly modifiedAt: Temporal.Instant | null;
       };
@@ -224,7 +225,7 @@ export function createInviteAcceptWithLoginHandler(opts: InviteAcceptWithLoginOp
           userId,
           tenantId: invitationTenantId,
           role: invitationRole,
-          invitationIssuedAt: invitationIssuedAt(invitation),
+          invitation,
         });
         if (!grant.isSuccess) return grant;
 

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept.write.ts

@@ -33,7 +33,7 @@ import {
   tenantInvitationsTable,
 } from "../../tenant/invitation-table.js";
 // kumiko-lint-ignore cross-feature-import membership grant for a privileged cross-tenant add (like provisionSignupAccount)
-import { grantInvitedMembershipRole, invitationIssuedAt } from "../../tenant/invited-membership.js";
+import { grantInvitedMembershipRole } from "../../tenant/invited-membership.js";
 // kumiko-lint-ignore cross-feature-import global roles granted on invite accept live on the user row
 import {
   grantInvitedGlobalRoles,
@@ -110,6 +110,7 @@ export function createInviteAcceptHandler() {
         readonly role: string;
         readonly globalRoles: unknown;
         readonly version: number;
+        readonly membershipVersion: number | null;
         readonly insertedAt: Temporal.Instant;
         readonly modifiedAt: Temporal.Instant | null;
       };
@@ -154,7 +155,7 @@ export function createInviteAcceptHandler() {
           userId: event.user.id,
           tenantId: invitationTenantId,
           role: invitationRole,
-          invitationIssuedAt: invitationIssuedAt(invitation),
+          invitation,
         });
         if (!grant.isSuccess) return grant;
         const { alreadyMember } = grant.data;

package/packages/bundled-features/src/auth-email-password/handlers/invite-create.write.ts

@@ -40,6 +40,8 @@ import {
   tenantInvitationEntity,
   tenantInvitationsTable,
 } from "../../tenant/invitation-table.js";
+// kumiko-lint-ignore cross-feature-import membership version read is owned by the tenant feature
+import { membershipVersionOf } from "../../tenant/invited-membership.js";
 // kumiko-lint-ignore cross-feature-import membership-role validation owned by tenant-feature
 import {
   findForbiddenMembershipRole,
@@ -49,6 +51,8 @@ import {
 } from "../../tenant/membership-roles.js";
 // kumiko-lint-ignore cross-feature-import global-role options are owned by the user feature
 import { GLOBAL_ROLE_OPTIONS } from "../../user/constants.js";
+// kumiko-lint-ignore cross-feature-import invitee lookup by email reads the user row
+import { userTable } from "../../user/schema/user.js";
 import { AUTH_INVITE_DEFAULT_TTL_MINUTES } from "../constants.js";
 import type { AuthMailLocale } from "../email-templates.js";
 import { renderInviteEmail } from "../email-templates.js";
@@ -144,6 +148,20 @@ function checkAssignableInviteRole(
   return undefined;
 }
 
+// 0 = the invitee has no membership in the tenant yet (or no account at all).
+async function currentMembershipVersion(
+  ctx: HandlerContext,
+  tenantId: string,
+  email: string,
+): Promise<number> {
+  const user = await ctx.db.global(userTable).fetchOne<{ readonly id: string }>({
+    email,
+    isDeleted: false,
+  });
+  if (!user) return 0;
+  return membershipVersionOf(ctx.db, tenantId, user.id);
+}
+
 async function issueInvitation(
   opts: InviteCreateOptions,
   ttlSeconds: number,
@@ -166,6 +184,7 @@ async function issueInvitation(
   // The unique index allows one row per (tenantId, email). Whatever its
   // status, a re-invite resets it to pending with a fresh token.
   const existing = await ctx.db.fetchOne(tenantInvitationsTable, { tenantId, email });
+  const membershipVersion = await currentMembershipVersion(ctx, tenantId, email);
 
   let invitationId: string;
   if (existing) {
@@ -193,6 +212,7 @@ async function issueInvitation(
           globalRoles: [...request.globalRoles],
           status: INVITATION_STATUS.pending,
           invitedBy: inviter.id,
+          membershipVersion,
           expiresAt,
         },
       },
@@ -208,6 +228,7 @@ async function issueInvitation(
         globalRoles: [...request.globalRoles],
         status: INVITATION_STATUS.pending,
         invitedBy: inviter.id,
+        membershipVersion,
         expiresAt,
       },
       inviter,

package/packages/bundled-features/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -32,7 +32,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
-import { decryptStoredPii } from "../../shared/index.js";
+import { decryptStoredPii, registrationLocaleFromRequest } from "../../shared/index.js";
 // kumiko-lint-ignore cross-feature-import invite-flow
 import {
   INVITATION_STATUS,
@@ -161,11 +161,13 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
         // @cast-boundary db-runner — helpers use only the query API that
         // DbConnection and DbTx share.
         const dbConn = ctx.db.unsafeRaw() as DbConnection;
+        const registrationLocale = registrationLocaleFromRequest();
         const { id: userId } = await seedUserWithPassword(dbConn, {
           email: invitationEmail,
           password: event.payload.password,
           displayName: invitationEmail.split("@")[0] ?? invitationEmail,
           emailVerified: true,
+          ...registrationLocale,
           ...(invitationGlobalRoles.length > 0 && { roles: invitationGlobalRoles }),
         });
 
@@ -221,6 +223,7 @@ export function createInviteSignupCompleteHandler(opts: InviteSignupCompleteOpti
           id: userId,
           tenantId: invitationTenantId,
           roles: mergedRoles,
+          ...registrationLocale,
         };
 
         committed = true;

package/packages/bundled-features/src/auth-email-password/handlers/login.write.ts

@@ -277,6 +277,7 @@ export function createLoginHandler(opts: LoginHandlerOptions = {}) {
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
+      grants: ["systemIdentity", "unsafeRaw"],
       reason:
         "Unauthenticated login has no caller identity yet — it looks up the user row by " +
         "email via ctx.queryAs(SYSTEM, ...) and resolves tenant membership via " +

package/packages/bundled-features/src/auth-email-password/handlers/reset-password.write.ts

@@ -28,6 +28,7 @@ export function createResetPasswordHandler(opts: ResetPasswordOptions) {
     access: { roles: ["anonymous"] },
     rateLimit: { per: "ip+handler", limit: 20, windowSeconds: 60 },
     escapeHatch: {
+      grants: ["systemIdentity"],
       reason:
         "Anonymous token holder has no session — runConfirmTokenFlow loads and updates the " +
         "target user via ctx.writeAs(SYSTEM, user:update) to set the new password hash.",

package/packages/bundled-features/src/auth-email-password/handlers/signup-confirm.write.ts

@@ -39,6 +39,7 @@ import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import {
   findSignupHandoverProvider,
+  registrationLocaleFromRequest,
   SIGNUP_HANDOVER_BENIGN_CLAIM_REJECTION_CODE,
   type SignupHandoverBinding,
 } from "../../shared/index.js";
@@ -186,6 +187,8 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
         // den Tenant-Namen + sein eigenes displayName später ändern.
         const displayName = email.split("@")[0] ?? email;
 
+        const registrationLocale = registrationLocaleFromRequest();
+
         let provisioned: { readonly userId: string; readonly tenantId: TenantId };
         try {
           provisioned = await provisionSignupAccount(
@@ -198,6 +201,7 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
               tenantKey,
               // Generated slug as default name: no personal data (the email) in the tenant name.
               tenantName: tenantKey,
+              ...registrationLocale,
             },
             // #1463: seedTenant's postSave hooks (tier-engine's auto-default-
             // tier, an app's auto-default-compliance) must fire on self-signup
@@ -222,6 +226,7 @@ export function createSignupConfirmHandler(opts: SignupConfirmOptions = {}) {
           id: provisioned.userId,
           tenantId: provisioned.tenantId,
           roles: [...INITIAL_SIGNUP_ROLES],
+          ...registrationLocale,
         };
 
         // Claim BEFORE spending the signup token or the binding below and