@cosmicdrift/kumiko-framework 0.255.2 → 0.257.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.255.2",
+  "version": "0.257.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.255.2",
+    "@cosmicdrift/kumiko-types": "0.257.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.255.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.257.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/build-app-schema-settings-hub.test.ts

@@ -189,6 +189,10 @@ describe("buildAppSchema — Settings-Hub inline placement", () => {
     const ok = defineFeature("ok", (r) => {
       r.config({ keys: { fee: createSystemConfig("number", { mask: { title: "ok.fee" } }) } });
       r.workspace({ id: "w", label: "W", nav: ["config:nav:audience-system"] });
+      // mask.title is unconditionally required (fw#2313) — irrelevant to what
+      // this test actually asserts (audience-nav QN exemption), but boot
+      // still needs it translated.
+      r.translations({ keys: { "ok.fee": { en: "Fee" } } });
     });
     expect(() => validateBoot([ok])).not.toThrow();
 

package/src/engine/__tests__/required-surface-keys.test.ts

@@ -8,6 +8,7 @@ import {
   requiredKeysFromWorkspace,
   screenTitleKey,
 } from "../../i18n/required-surface-keys";
+import { i18nKey } from "../i18n-key";
 import type {
   ConfigEditScreenDefinition,
   EntityEditScreenDefinition,
@@ -216,3 +217,49 @@ describe("dot-form labels + treatDotFormAsKey (fw#2260)", () => {
     expect(requiredKeysFromNav(nav, { treatDotFormAsKey: true })).toContain("billing.settings");
   });
 });
+
+// fw#2313: a hand-written dot-form label ("sessions.list.col.id") is
+// indistinguishable from literal display text ("actions.open") — isI18nKey
+// only recognizes it once the author marks it explicitly via i18nKey().
+describe("dot-form label opt-in (fw#2313)", () => {
+  test("unmarked dot-form label is not required (regression guard for literal display text)", () => {
+    const screen: EntityListScreenDefinition = {
+      id: "fw2313-list",
+      type: "entityList",
+      entity: "widget",
+      columns: ["name"],
+      rowActions: [
+        {
+          id: "open",
+          label: "actions.open",
+          handler: "fw2313:write:widget:open",
+        },
+      ],
+    };
+    const keys = requiredKeysFromScreen("fw2313", screen);
+    expect(keys).not.toContain("actions.open");
+  });
+
+  test("i18nKey()-marked dot-form label is required", () => {
+    const screen: EntityListScreenDefinition = {
+      id: "fw2313-list",
+      type: "entityList",
+      entity: "widget",
+      columns: ["name"],
+      rowActions: [
+        {
+          id: "open",
+          label: i18nKey("fw2313.optin.col.alpha"),
+          handler: "fw2313:write:widget:open",
+        },
+      ],
+    };
+    const keys = requiredKeysFromScreen("fw2313", screen);
+    expect(keys).toContain("fw2313.optin.col.alpha");
+  });
+
+  test("i18nKey()-marked nav label is required", () => {
+    const nav = { id: "fw2313-nav", label: i18nKey("fw2313.optin.nav.beta") };
+    expect(requiredKeysFromNav(nav)).toContain("fw2313.optin.nav.beta");
+  });
+});

package/src/engine/boot-validator/__tests__/i18n-keys.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { buildConfigFeatureSchema } from "../../build-config-feature-schema";
 import { access, createTenantConfig } from "../../config-helpers";
 import { defineFeature } from "../../define-feature";
+import { i18nKey } from "../../i18n-key";
 import { createRegistry } from "../../registry";
 import { isFieldsEditSection } from "../../screen-helpers";
 import type { ConfigEditScreenDefinition } from "../../types";
@@ -195,3 +196,72 @@ describe("validateI18nSurfaceKeys — gated configEdit section description (PR #
     expect(withoutDescription.description).toBeUndefined();
   });
 });
+
+// fw#2313: a hand-written dot-form label is indistinguishable from literal
+// display text, so isI18nKey only requires a translation for one explicitly
+// marked via i18nKey() — unmarked dot-form labels must keep failing silently
+// (that's the existing, intentional behavior for literal text like
+// "actions.open"), never crashing boot on their own.
+describe("validateI18nSurfaceKeys — explicit i18nKey() dot-form opt-in (fw#2313)", () => {
+  test("i18nKey()-marked dot-form label without a translation fails boot naming the key", () => {
+    const feature = defineFeature("fw2313boot", (r) => {
+      r.nav({ id: "home", label: i18nKey("fw2313.boot.optin.nav") });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /required translation key missing: "fw2313\.boot\.optin\.nav"/,
+    );
+  });
+
+  test("i18nKey()-marked dot-form label with a translation passes boot", () => {
+    const feature = defineFeature("fw2313boot", (r) => {
+      r.nav({ id: "home", label: i18nKey("fw2313.boot.optin.nav.translated") });
+      r.translations({ keys: { "fw2313.boot.optin.nav.translated": { en: "Home" } } });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("unmarked literal dot-form label never fails boot", () => {
+    const feature = defineFeature("fw2313boot", (r) => {
+      r.nav({ id: "home", label: "fw2313.boot.never-marked.literal" });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});
+
+// The mask.title bypass is unconditional (required-surface-keys.ts,
+// requiredKeysFromFeature) — mask.title is always an i18n key by
+// ConfigKeyDefinition contract, never literal display text, so it needs no
+// i18nKey() marker.
+describe("validateI18nSurfaceKeys — mask.title is unconditionally required (fw#2313)", () => {
+  function maskedFeature(translationKeys: Record<string, { readonly en: string }>) {
+    return defineFeature("fw2313mask", (r) => {
+      r.config({
+        keys: {
+          apiKey: createTenantConfig("text", {
+            write: access.roles("TenantAdmin"),
+            mask: { title: "fw2313.boot.mask.title" },
+          }),
+        },
+      });
+      if (Object.keys(translationKeys).length > 0) {
+        r.translations({ keys: translationKeys });
+      }
+    });
+  }
+
+  test("masked config key without a mask.title translation fails boot", () => {
+    const feature = maskedFeature({});
+    expect(() => validateBoot([configHub, feature])).toThrow(
+      /required translation key missing: "fw2313\.boot\.mask\.title"/,
+    );
+  });
+
+  test("masked config key with a mask.title translation passes boot", () => {
+    const feature = maskedFeature({
+      "fw2313.boot.mask.title": { en: "API Key" },
+      "screen:fw2313mask-tenant.title": { en: "Settings" },
+      "fw2313mask.settings": { en: "Settings" },
+    });
+    expect(() => validateBoot([configHub, feature])).not.toThrow();
+  });
+});

package/src/engine/i18n-key.ts

@@ -0,0 +1,12 @@
+// Dot-form labels are indistinguishable from literal display text ("actions.open"),
+// so authors mark the i18n ones explicitly; the registry is what boot validation reads.
+const explicitDotFormKeys = new Set<string>();
+
+export function i18nKey(value: string): string {
+  explicitDotFormKeys.add(value);
+  return value;
+}
+
+export function isExplicitDotFormKey(value: string): boolean {
+  return explicitDotFormKeys.has(value);
+}

package/src/engine/index.ts

@@ -205,6 +205,7 @@ export {
   filterReadFields,
 } from "./field-access";
 export { resolveName, withResponseData } from "./handler-helpers";
+export { i18nKey } from "./i18n-key";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
 // stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
 // apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES

package/src/i18n/required-surface-keys.ts

@@ -1,3 +1,4 @@
+import { isExplicitDotFormKey } from "../engine/i18n-key";
 import {
   isExtensionEditSection,
   isWriteFormEditSection,
@@ -63,13 +64,14 @@ export function screenTitleKey(screenId: string): string {
 }
 
 function isI18nKey(value: string): boolean {
-  return value.includes(":");
+  return value.includes(":") || isExplicitDotFormKey(value);
 }
 
 /**
  * `treatAsKey` bypasses the colon-only `isI18nKey` check — used by the Settings-Hub
  * generator's dot-form labels (`${feature}.settings`, mask titles), which are
  * always i18n references by construction, never literal display text (fw#2260).
+ * `isI18nKey` itself also accepts dot-form labels explicitly marked via `i18nKey()` (fw#2313).
  */
 function pushKey(out: Set<string>, value: string | undefined, treatAsKey = false): void {
   if (value !== undefined && (treatAsKey || isI18nKey(value))) out.add(value);
@@ -348,7 +350,8 @@ export function requiredKeysFromFeature(feature: FeatureDefinition): readonly st
     for (const key of requiredKeysFromWorkspace(ws)) out.add(key);
   }
   for (const def of Object.values(feature.configKeys)) {
-    pushKey(out, def.mask?.title);
+    // mask.title is always an i18n key by construction (ConfigKeyDefinition contract), not literal text.
+    pushKey(out, def.mask?.title, true);
   }
   collectEntityListFilterKeys(feature, out);