@burdenoff/fe-libs 2026.1021.8 → 2026.1021.9

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@burdenoff/fe-libs",
-  "version": "2026.1021.8",
+  "version": "2026.1021.9",
   "description": "Burdenoff frontend primitives and domain libraries",
   "type": "module",
   "bin": {
     "graphql-schema-drift": "./scripts/graphql-schema-drift/cli.ts",
-    "a11y-audit": "./scripts/a11y-audit/cli.ts"
+    "a11y-audit": "./scripts/a11y-audit/cli.ts",
+    "burdenoff-i18n": "./scripts/i18n/cli.ts"
   },
   "imports": {
     "#lib/*": "./src/lib/*",
@@ -159,6 +160,10 @@
     },
     "./shared/tokens/tokens.css": "./src/shared/tokens/tokens.css",
     "./shared/styles": "./src/shared/styles/index.css",
+    "./scripts/i18n": {
+      "types": "./scripts/i18n/index.ts",
+      "import": "./scripts/i18n/index.ts"
+    },
     "./vite": {
       "types": "./src/vite/index.ts",
       "import": "./src/vite/index.ts"
@@ -301,6 +306,8 @@
     "scripts/graphql-schema-drift/README.md",
     "scripts/a11y-audit/*.ts",
     "scripts/a11y-audit/README.md",
+    "scripts/i18n/*.ts",
+    "scripts/i18n/README.md",
     "README.md",
     "LICENSE"
   ],
@@ -315,7 +322,7 @@
     "test:package-livekit-optional": "node scripts/validate-livekit-optional.mjs",
     "verify:package": "node scripts/verify-package-contents.mjs",
     "test:handsfree-browser": "node scripts/handsfree-browser-run.mjs",
-    "test": "bun test scripts/graphql-schema-drift/__tests__ scripts/a11y-audit/__tests__ src/credentials src/connections src/storage src/shared/assistant src/shared/components src/shared/graphql/links/sse-link.test.ts src/shared/graphql/fetch.test.ts src/shared/graphql/prepareWorkspaceRequest.test.ts src/shared/graphql/client.test.ts src/shared/utils/apollo.test.ts src/shared/utils/canvasTokens.test.ts src/shared/graphql/tourWorkspaceAuth.test.ts src/shared/config/gatewayUrls.test.ts src/shared/config/authBridgeUrls.test.ts src/shared/config/shellRoutes.test.ts src/shared/config/gatewayFallback.test.ts scripts/__tests__ src/shared/config/products.test.ts src/shared/config/productSlug.test.ts src/shared/hooks/shell/useProducts.test.ts src/shared/providers/shell/brandAttribute.test.ts src/chrome/ProductSwitcher.test.ts src/shared/utils/gatewayFetchRewrite.test.ts src/shared/utils/authCookie.test.ts src/shared/utils/redirectAllowlist.test.ts src/shared/providers/shell/ProfileStorageManager.test.ts src/shared/providers/AppShellProvider.test.ts src/shared/providers/shell/interpolate.test.ts src/shared/providers/shell/resolveTranslation.test.ts src/shared/providers/shell/I18nProvider.render.test.tsx src/shared/providers/shell/I18nProvider.client.test.tsx src/shared/providers/shell/translationStore.test.ts src/shared/providers/shell/translationLayers.test.ts src/shared/providers/shell/directionMode.test.ts src/shared/providers/shell/authProvider/ssoRelay.test.ts src/shared/providers/shell/authProvider/useAuthActions.signOut.test.tsx src/shared/providers/shell/personaSurfaceRemote.test.ts src/shared/providers/shell/workspaceSwitch.client.test.tsx src/shared/events/sinks/RybbitSink.test.ts src/shell-native src/shared/native src/shared/navigation src/shared/tours src/chrome/__tests__ src/ui/__tests__",
+    "test": "bun test scripts/graphql-schema-drift/__tests__ scripts/a11y-audit/__tests__ scripts/i18n/__tests__ src/credentials src/connections src/storage src/shared/assistant src/shared/components src/shared/graphql/links/sse-link.test.ts src/shared/graphql/fetch.test.ts src/shared/graphql/prepareWorkspaceRequest.test.ts src/shared/graphql/client.test.ts src/shared/utils/apollo.test.ts src/shared/utils/canvasTokens.test.ts src/shared/graphql/tourWorkspaceAuth.test.ts src/shared/config/gatewayUrls.test.ts src/shared/config/authBridgeUrls.test.ts src/shared/config/shellRoutes.test.ts src/shared/config/gatewayFallback.test.ts scripts/__tests__ src/shared/config/products.test.ts src/shared/config/productSlug.test.ts src/shared/hooks/shell/useProducts.test.ts src/shared/providers/shell/brandAttribute.test.ts src/chrome/ProductSwitcher.test.ts src/shared/utils/gatewayFetchRewrite.test.ts src/shared/utils/authCookie.test.ts src/shared/utils/redirectAllowlist.test.ts src/shared/providers/shell/ProfileStorageManager.test.ts src/shared/providers/AppShellProvider.test.ts src/shared/providers/shell/interpolate.test.ts src/shared/providers/shell/resolveTranslation.test.ts src/shared/providers/shell/I18nProvider.render.test.tsx src/shared/providers/shell/I18nProvider.client.test.tsx src/shared/providers/shell/translationStore.test.ts src/shared/providers/shell/translationLayers.test.ts src/shared/providers/shell/directionMode.test.ts src/shared/providers/shell/authProvider/ssoRelay.test.ts src/shared/providers/shell/authProvider/useAuthActions.signOut.test.tsx src/shared/providers/shell/personaSurfaceRemote.test.ts src/shared/providers/shell/workspaceSwitch.client.test.tsx src/shared/events/sinks/RybbitSink.test.ts src/shell-native src/shared/native src/shared/navigation src/shared/tours src/chrome/__tests__ src/ui/__tests__",
     "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run lint:sanity && bun run format && bun run type:check && bun run test && bun run build && bun run verify:package'",
     "switch:status": "bun scripts/deps-mode.ts status",
     "switch:remote": "bun scripts/deps-mode.ts remote",

package/scripts/i18n/README.md

@@ -0,0 +1,117 @@
+# burdenoff-i18n — shared i18n bundle gates
+
+Every app shell publishes `/i18n-bundle.json`, and the gitops seed jobs
+(`seed:translations --bundle-url=https://app.<domain>/i18n-bundle.json`) write
+it into global-i18n-svc. The seeder replaces rows (DELETE, then INSERT), so a
+bundle that drops a key, or changes a value, changes what production serves.
+
+VibeControls and FluidGrids each kept about 20 i18n scripts to guard this, and
+the copies had drifted apart. The scripts that do not depend on a product live
+here, as one CLI. A shell keeps only the part that reads its own translation
+sources: the extractor and the bundle builder. The commands reach that part
+through a small adapter module.
+
+> **Keep publishing `/i18n-bundle.json`.** It is the seed input. The gitops seed
+> jobs download it, and `served` below reads it. Leave it out only of native
+> IPA/APK packaging.
+
+## Commands
+
+| Command                                                                                  | Fails (exit 1) when                                                                                                                                          |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `verify-shipped [--bundle=<src>] [--warn]`                                               | the installed, compiled packages request a key that the bundle does not define, and the builder did not hold that key back on purpose                        |
+| `digest [<src>] [--order=utf8\|utf16]`                                                   | never; prints the key and row counts plus the set digests as JSON                                                                                            |
+| `diff <base> <proposed> [--allow-updates] [--allow-deletions] [--json=PATH] [--limit=N]` | seeding `<proposed>` over `<base>` would change or delete a row that is served today                                                                         |
+| `served-tree [<src>] [--baseline=<src>] [--reads-leaf-slot=true\|false]`                 | the nested export would serve a key differently from the bundle. With `--baseline`, it fails only when a key that resolves today would be hidden or shadowed |
+
+Exit `2` means the check could not run. That covers a bad config or argument,
+a bundle that is unreadable or malformed, and a check with nothing to look at,
+such as no installed packages. A check that could not run is never reported as
+a pass.
+
+`<src>` can be one of:
+
+- `built`: the adapter's `buildBundle()`, or else `bundleFile`. This is the default.
+- `served`: `servedUrl`.
+- a file path.
+- an `https://` URL. `http://` is refused.
+
+## Install in a shell
+
+`@burdenoff/fe-libs` ships the CLI as the package `bin` `burdenoff-i18n`:
+
+```json
+"i18n:verify-shipped": "burdenoff-i18n verify-shipped",
+"i18n:digest": "burdenoff-i18n digest",
+"i18n:diff-served": "burdenoff-i18n diff served built",
+"i18n:served-tree": "burdenoff-i18n served-tree built --baseline=served"
+```
+
+`i18n.config.json` at the shell root:
+
+```json
+{
+  "product": "fluidgrids",
+  "servedUrl": "https://app.fluidgrids.ai/i18n-bundle.json",
+  "adapter": "scripts/i18n-adapter.ts",
+  "shipped": { "scope": "@burdenoff", "packages": ["microfe-*", "fluidgrids-fe-sdk"] },
+  "readsLeafSlot": true,
+  "digestOrder": "utf8"
+}
+```
+
+Unknown keys are rejected. The defaults are scope `@burdenoff`, packages
+`["microfe-*"]`, `readsLeafSlot: true` (fe-libs ≥ 2026.919.1 reads a branch's
+`_` slot) and `digestOrder: "utf8"`.
+
+The adapter is a TypeScript module that Bun imports. Both exports are optional:
+
+```ts
+import type { I18nAdapter } from '@burdenoff/fe-libs/scripts/i18n';
+import { buildBundle, heldBackKeys } from './build-i18n-bundle'; // the shell's own builder
+import { loadAssistantSeedCopy } from './i18n-assistant-keys';
+
+export const adapter: I18nAdapter = {
+  // The bundle exactly as the build emits it, plus keys it holds back on purpose.
+  async buildBundle() {
+    const built = await buildBundle({ quiet: true });
+    return { bundle: built.bundle, heldBack: heldBackKeys(built) };
+  },
+  // Keys that the shipped code requests but a compiled-call scan cannot see,
+  // e.g. runtime-prefixed assistant keys.
+  async requestedKeys() {
+    const copy = await loadAssistantSeedCopy();
+    return Object.fromEntries(
+      Object.entries(copy).map(([key, fallback]) => [key, { pkg: 'fe-libs assistant', fallback }])
+    );
+  },
+};
+export default adapter;
+```
+
+A shell that writes its bundle to disk can skip the adapter and set
+`"bundleFile": "dist/i18n-bundle.json"`.
+
+## Digests
+
+`digest` hashes each row as `JSON.stringify([key, locale, value])`. It sorts the
+lines in `order`, joins them with `\n` and takes the sha256. Two bundles with
+the same rows therefore have the same digest, whatever order the rows are in.
+`utf8` sorts by UTF-8 bytes (code points), which is how FluidGrids'
+served-bundle fixture was generated. `utf16` sorts by JavaScript's default
+comparison, which is how VibeControls' seed-plan fixtures were generated. The
+two orders differ only for characters outside the Basic Multilingual Plane.
+
+## Programmatic use
+
+`@burdenoff/fe-libs/scripts/i18n` exports the pieces for shell scripts and
+tests:
+
+- bundles: `parseBundle`, `loadBundleSource`, `digestBundle`, `diffBundles`, `setDigest`
+- the nested-export model: `buildNestedDictionary`, `resolvableKeys`, `hidingPrefix`, `compareServed`
+- the compiled-call scan: `shippedKeys`, `collectShippedKeys`
+
+The nested-export model is the single port of global-i18n-svc's
+`buildNestedDictionary` (2026.920.1, BOFF-7458/7459). It replaces the separate
+copies in `vibecontrols-app/scripts/i18n-nested-export.ts` and
+`fluidgrids-app/scripts/i18n-served-tree.ts`.

package/scripts/i18n/bundle.ts

@@ -0,0 +1,250 @@
+/**
+ * Reading, digesting and diffing emitted i18n bundles.
+ *
+ * Every function here is pure except `loadBundleSource`, so the seed contract
+ * (what a bundle would insert, change or delete in production) is unit-testable
+ * without a network or a database.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import type {
+  BundleDiff,
+  BundleDigest,
+  BundleKey,
+  BundleRow,
+  DigestOrder,
+  I18nBundle,
+  RowChange,
+} from './types';
+
+export class BundleError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BundleError';
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate an emitted bundle. A malformed bundle is an error, never an empty
+ * one: a digest or diff of "no rows" would read as "seeds nothing" and pass.
+ * Duplicate keys are refused because the seeded row set would then depend on
+ * which entry the seeder reads last.
+ */
+export function parseBundle(raw: unknown, label = 'bundle'): I18nBundle {
+  if (!isRecord(raw) || !Array.isArray(raw.keys)) {
+    throw new BundleError(`${label}: expected an object with a "keys" array`);
+  }
+  const seen = new Set<string>();
+  const keys: BundleKey[] = [];
+  raw.keys.forEach((entry: unknown, index: number) => {
+    if (!isRecord(entry) || typeof entry.key !== 'string' || entry.key === '') {
+      throw new BundleError(`${label}: keys[${index}] has no "key" string`);
+    }
+    if (!isRecord(entry.values)) {
+      throw new BundleError(`${label}: keys[${index}] (${entry.key}) has no "values" object`);
+    }
+    if (seen.has(entry.key)) {
+      throw new BundleError(`${label}: key "${entry.key}" appears more than once`);
+    }
+    seen.add(entry.key);
+    const values: Record<string, string> = {};
+    for (const [locale, value] of Object.entries(entry.values)) {
+      if (typeof value !== 'string') {
+        throw new BundleError(`${label}: ${entry.key}|${locale} is not a string`);
+      }
+      values[locale] = value;
+    }
+    keys.push({
+      key: entry.key,
+      ...(typeof entry.namespace === 'string' ? { namespace: entry.namespace } : {}),
+      values,
+    });
+  });
+  // The header fields are passed through untouched and never read here, so
+  // the cast only names them; `keys`, the one field read, was validated above.
+  return { ...(raw as Omit<I18nBundle, 'keys'>), keys };
+}
+
+/** Default ceiling for a downloaded bundle; the largest served today is ~12 MB. */
+export const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+
+export interface LoadOptions {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  maxBytes?: number;
+}
+
+/**
+ * Load a bundle from a file path or an `https://` URL. Plain `http://` is
+ * refused: the served bundle is the production seed input, and a digest of a
+ * tampered copy would be worse than no digest.
+ */
+export async function loadBundleSource(
+  source: string,
+  options: LoadOptions = {}
+): Promise<I18nBundle> {
+  const maxBytes = options.maxBytes ?? MAX_BUNDLE_BYTES;
+  if (/^[a-z]+:\/\//i.test(source)) {
+    if (!source.toLowerCase().startsWith('https://')) {
+      throw new BundleError(`${source}: only https:// URLs are accepted`);
+    }
+    const doFetch = options.fetchImpl ?? fetch;
+    const response = await doFetch(source, {
+      signal: AbortSignal.timeout(options.timeoutMs ?? 60_000),
+      headers: { accept: 'application/json' },
+    });
+    if (!response.ok) {
+      throw new BundleError(`${source}: HTTP ${response.status}`);
+    }
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (declared > maxBytes) {
+      throw new BundleError(`${source}: larger than ${maxBytes} bytes`);
+    }
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+      throw new BundleError(`${source}: larger than ${maxBytes} bytes`);
+    }
+    return parseBundle(parseJson(text, source), source);
+  }
+  const text = readFileSync(source, 'utf8');
+  if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+    throw new BundleError(`${source}: larger than ${maxBytes} bytes`);
+  }
+  return parseBundle(parseJson(text, source), source);
+}
+
+function parseJson(text: string, label: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (error) {
+    throw new BundleError(`${label}: not valid JSON (${(error as Error).message})`);
+  }
+}
+
+/** Every `[key, locale, value]` row a bundle seeds, in bundle order. */
+export function bundleRows(bundle: I18nBundle): BundleRow[] {
+  const rows: BundleRow[] = [];
+  for (const { key, values } of bundle.keys) {
+    for (const [locale, value] of Object.entries(values)) rows.push([key, locale, value]);
+  }
+  return rows;
+}
+
+/** The line a row is hashed as: `JSON.stringify([key, locale, value])`. */
+export const rowLine = (row: BundleRow): string => JSON.stringify(row);
+
+/** Compare by UTF-8 bytes, i.e. Unicode code points. */
+export const utf8Order = (a: string, b: string): number =>
+  Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+
+/** Compare by UTF-16 code units (JavaScript's default `<`). */
+export const utf16Order = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+export const ORDERS: Readonly<Record<DigestOrder, (a: string, b: string) => number>> = {
+  utf8: utf8Order,
+  utf16: utf16Order,
+};
+
+/** sha256 of `lines` sorted in `order` and joined with `\n`: equal sets give equal digests. */
+export function setDigest(lines: Iterable<string>, order: DigestOrder = 'utf8'): string {
+  const sorted = [...lines].sort(ORDERS[order]);
+  return createHash('sha256').update(sorted.join('\n'), 'utf8').digest('hex');
+}
+
+/** Counts and set digests of a bundle. */
+export function digestBundle(bundle: I18nBundle, order: DigestOrder = 'utf8'): BundleDigest {
+  const rows = bundleRows(bundle);
+  const rowsByLocale: Record<string, number> = {};
+  for (const [, locale] of rows) rowsByLocale[locale] = (rowsByLocale[locale] ?? 0) + 1;
+  return {
+    keys: bundle.keys.length,
+    rows: rows.length,
+    order,
+    keySetSha256: setDigest(
+      bundle.keys.map((k) => k.key),
+      order
+    ),
+    rowSetSha256: setDigest(rows.map(rowLine), order),
+    rowsByLocale: sortRecord(rowsByLocale),
+  };
+}
+
+function sortRecord(record: Record<string, number>): Record<string, number> {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => utf8Order(a, b)));
+}
+
+/** An unambiguous id for a (key, locale) pair, whatever characters either holds. */
+const pair = (key: string, locale: string): string => JSON.stringify([key, locale]);
+
+function rowMap(bundle: I18nBundle): Map<string, RowChange> {
+  const out = new Map<string, RowChange>();
+  for (const [key, locale, value] of bundleRows(bundle)) {
+    out.set(pair(key, locale), { key, locale, before: value, after: value });
+  }
+  return out;
+}
+
+const byRow = (a: RowChange, b: RowChange): number =>
+  utf8Order(a.key, b.key) || utf8Order(a.locale, b.locale);
+
+/**
+ * What seeding `proposed` over `base` (normally the served bundle) changes:
+ * rows inserted, rows whose value changes, and rows the proposed bundle no
+ * longer carries. The seeder is DELETE-then-INSERT over the bundle, so a
+ * "deletion" here is a translation production would stop serving.
+ */
+export function diffBundles(base: I18nBundle, proposed: I18nBundle): BundleDiff {
+  const before = rowMap(base);
+  const after = rowMap(proposed);
+  const inserts: RowChange[] = [];
+  const updates: RowChange[] = [];
+  const deletions: RowChange[] = [];
+  for (const [id, row] of after) {
+    const old = before.get(id);
+    if (!old) inserts.push({ key: row.key, locale: row.locale, before: null, after: row.after });
+    else if (old.before !== row.after) {
+      updates.push({ key: row.key, locale: row.locale, before: old.before, after: row.after });
+    }
+  }
+  for (const [id, row] of before) {
+    if (!after.has(id)) {
+      deletions.push({ key: row.key, locale: row.locale, before: row.before, after: null });
+    }
+  }
+  const baseKeys = new Set(base.keys.map((k) => k.key));
+  const proposedKeys = new Set(proposed.keys.map((k) => k.key));
+  const insertsByLocale: Record<string, number> = {};
+  for (const row of inserts) insertsByLocale[row.locale] = (insertsByLocale[row.locale] ?? 0) + 1;
+  return {
+    base: { keys: baseKeys.size, rows: before.size },
+    proposed: { keys: proposedKeys.size, rows: after.size },
+    inserts: inserts.sort(byRow),
+    updates: updates.sort(byRow),
+    deletions: deletions.sort(byRow),
+    newKeys: [...proposedKeys].filter((k) => !baseKeys.has(k)).sort(utf8Order),
+    removedKeys: [...baseKeys].filter((k) => !proposedKeys.has(k)).sort(utf8Order),
+    insertsByLocale: sortRecord(insertsByLocale),
+  };
+}
+
+/** One locale's `[key, value]` rows from a bundle, in bundle order. */
+export function localeRows(bundle: I18nBundle, locale: string): Array<[string, string]> {
+  const rows: Array<[string, string]> = [];
+  for (const { key, values } of bundle.keys) {
+    const value = values[locale];
+    if (value !== undefined) rows.push([key, value]);
+  }
+  return rows;
+}
+
+/** Every locale any key of the bundle carries, sorted. */
+export function bundleLocales(bundle: I18nBundle): string[] {
+  const out = new Set<string>();
+  for (const { values } of bundle.keys) for (const locale of Object.keys(values)) out.add(locale);
+  return [...out].sort(utf8Order);
+}