@cosmicdrift/kumiko-bundled-features 0.232.0 → 0.233.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.232.0",
+  "version": "0.233.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>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.232.0",
-    "@cosmicdrift/kumiko-framework": "0.232.0",
-    "@cosmicdrift/kumiko-headless": "0.232.0",
-    "@cosmicdrift/kumiko-renderer": "0.232.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.232.0",
-    "@cosmicdrift/kumiko-types": "0.232.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.233.0",
+    "@cosmicdrift/kumiko-framework": "0.233.0",
+    "@cosmicdrift/kumiko-headless": "0.233.0",
+    "@cosmicdrift/kumiko-renderer": "0.233.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.233.0",
+    "@cosmicdrift/kumiko-types": "0.233.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.232.0",
-    "@cosmicdrift/kumiko-locale-es": "0.232.0"
+    "@cosmicdrift/kumiko-locale-de": "0.233.0",
+    "@cosmicdrift/kumiko-locale-es": "0.233.0"
   }
 }

package/src/cap-overview/__tests__/usage-math.test.ts

@@ -22,6 +22,10 @@ describe("computeFraction", () => {
   test("used 0 of a positive limit -> 0", () => {
     expect(computeFraction(0, 5)).toBe(0);
   });
+
+  test("limit null (unlimited) -> 0, regardless of used", () => {
+    expect(computeFraction(165, null)).toBe(0);
+  });
 });
 
 describe("computeUnclampedFraction", () => {
@@ -37,6 +41,10 @@ describe("computeUnclampedFraction", () => {
   test("used 3 of limit 5 -> 0.6, same as the clamped case", () => {
     expect(computeUnclampedFraction(3, 5)).toBe(0.6);
   });
+
+  test("limit null (unlimited) -> 0, regardless of used", () => {
+    expect(computeUnclampedFraction(165, null)).toBe(0);
+  });
 });
 
 describe("computeTone", () => {
@@ -57,4 +65,8 @@ describe("computeTone", () => {
   test("fraction >= 1 -> danger", () => {
     expect(computeTone(1)).toBe("danger");
   });
+
+  test("unlimited (limit null) never escalates to warn/danger", () => {
+    expect(computeTone(computeFraction(165, null))).toBe("default");
+  });
 });

package/src/cap-overview/changes.json

@@ -4,5 +4,11 @@
     "type": "improvement",
     "title": "Add cap-overview feature: tier + cap usage visibility per tenant.",
     "detail": "New read-only bundled feature. SystemAdmin gets a paged, searchable tenant list with tier/billing columns and per-cap usage bars, plus a per-tenant dashboard reachable from the list. TenantAdmin gets a 'My usage' dashboard showing their own tenant's cap usage as cards. Reads tier-engine, billing-foundation and tenant projections plus caller-supplied CapSpec usage callbacks; every handler enforces explicit tenant scoping (no ambient tenant filter, cross-tenant reads require SystemAdmin + acknowledgeCrossTenant)."
+  },
+  {
+    "version": "0.233.0",
+    "type": "improvement",
+    "title": "CapSpec.limit can now return null for an unlimited usage meter.",
+    "detail": "A CapSpec's `limit(tier)` may now return `null` to mean unlimited: the cap is still counted (used shows the raw count) but never capped, has no percent, and renders no progress bar or badge. This is a distinct meaning from `limit <= 0`, which unchanged still means 'not part of this tier' and renders as 0/0%."
   }
 ]

package/src/cap-overview/handlers/caps-usage.query.ts

@@ -86,7 +86,8 @@ export function createCapsUsageQuery(caps: readonly CapSpec[]): QueryHandlerDefi
             limit,
             fraction,
             tone: computeTone(fraction),
-            percent: Math.round(computeUnclampedFraction(used, limit) * 100),
+            percent:
+              limit === null ? null : Math.round(computeUnclampedFraction(used, limit) * 100),
             ...(cap.icon !== undefined && { icon: cap.icon }),
             ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
           };

package/src/cap-overview/types.ts

@@ -14,7 +14,9 @@ export type CapIconKey = "file" | "hash" | "database" | "users" | "mail" | "gaug
 export type CapSpec = {
   readonly id: string;
   readonly label: string;
-  readonly limit: (tier: string) => number;
+  // `null` = unlimited (a pure usage meter: counted but never capped).
+  // `<= 0` = not part of this tier — existing, unchanged meaning (usage-math.ts).
+  readonly limit: (tier: string) => number | null;
   // `null` means "no measurement exists yet for this cap" (not "0 used") —
   // callers that haven't wired up instrumentation return null instead of a
   // number they don't actually have.
@@ -44,7 +46,8 @@ export type CapUsage = {
   // `null` means not measured yet — `fraction`/`tone` stay non-nullable
   // (0 / "default") so no consumer needs null-arithmetic to render.
   readonly used: number | null;
-  readonly limit: number;
+  // `limit: null` means unlimited — a pure usage meter with no cap to hit.
+  readonly limit: number | null;
   readonly fraction: number;
 };
 

package/src/cap-overview/usage-math.ts

@@ -7,21 +7,23 @@ import type { CapUsageTone } from "./types";
 const WARN_THRESHOLD = 0.8;
 const DANGER_THRESHOLD = 1;
 
-// limit <= 0 means "not part of this tier" — 0, never NaN/Infinity.
-function rawFraction(used: number, limit: number): number {
+// limit === null means unlimited (no cap to measure against); limit <= 0
+// means "not part of this tier" — both render as 0, never NaN/Infinity.
+function rawFraction(used: number, limit: number | null): number {
+  if (limit === null) return 0;
   if (limit <= 0) return 0;
   const fraction = used / limit;
   return Number.isFinite(fraction) ? fraction : 0;
 }
 
-export function computeFraction(used: number, limit: number): number {
+export function computeFraction(used: number, limit: number | null): number {
   return Math.min(1, Math.max(0, rawFraction(used, limit)));
 }
 
 // Unclamped — for display of the over-limit case (e.g. "140%"). Bar width
 // and tone still use the clamped computeFraction; only percent shows the
 // real ratio.
-export function computeUnclampedFraction(used: number, limit: number): number {
+export function computeUnclampedFraction(used: number, limit: number | null): number {
   return rawFraction(used, limit);
 }
 

package/src/cap-overview/web/__tests__/cap-cards-panel.test.tsx

@@ -96,6 +96,19 @@ function nullCapRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta
   };
 }
 
+function unlimitedCapRow(overrides: Partial<CapUsageWithMeta> = {}): CapUsageWithMeta {
+  return {
+    id: "cap-unlimited",
+    label: "cap.label.unlimited",
+    tone: "default",
+    percent: null,
+    used: 165,
+    limit: null,
+    fraction: 0,
+    ...overrides,
+  };
+}
+
 beforeEach(() => {
   queryState = { data: { rows: [] }, loading: false, error: null };
   useQuerySpy.mockClear();
@@ -233,6 +246,46 @@ describe("CapCardsPanel", () => {
     expect(screen.getAllByTestId("cap-usage-bar")).toHaveLength(1);
   });
 
+  test("an unlimited cap (limit: null) shows the raw used count, no denominator, no percent badge, no bar", () => {
+    queryState = {
+      data: { rows: [unlimitedCapRow()] },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getByTestId("cap-card").textContent).toContain("165");
+    expect(screen.queryByText("165 / null")).toBeNull();
+    expect(screen.queryByText("165 / 0")).toBeNull();
+    expect(screen.queryByText("null%")).toBeNull();
+    expect(screen.queryByText("0%")).toBeNull();
+    expect(screen.queryByTestId("cap-usage-bar")).toBeNull();
+  });
+
+  test("a limited card and an unlimited card in the same panel each render their own state", () => {
+    queryState = {
+      data: {
+        rows: [
+          capRow({ id: "c1", label: "Storage", used: 3, limit: 10, tone: "default", percent: 30 }),
+          unlimitedCapRow({ id: "c2", label: "Api calls" }),
+        ],
+      },
+      loading: false,
+      error: null,
+    };
+
+    renderPanel(undefined);
+
+    expect(screen.getAllByTestId("cap-card")).toHaveLength(2);
+    expect(screen.getByText("3 / 10")).toBeTruthy();
+    expect(screen.getByText("30%")).toBeTruthy();
+    expect(screen.getAllByTestId("cap-usage-bar")).toHaveLength(1);
+    expect(screen.getAllByTestId("cap-card")[1]?.textContent).toContain("165");
+    expect(screen.queryByText("165 / null")).toBeNull();
+    expect(screen.queryByText("null%")).toBeNull();
+  });
+
   test("loading with empty rows shows the loading text instead of the empty state", () => {
     queryState = { data: null, loading: true, error: null };
 

package/src/cap-overview/web/__tests__/cap-usage-bar.test.tsx

@@ -73,4 +73,40 @@ describe("CapUsageBar", () => {
     expect(fillClass()).not.toContain("bg-primary");
     expect(fillClass()).not.toContain("bg-status-critical");
   });
+
+  test("renders the raw used count instead of a bar when limit is null (unlimited)", () => {
+    const usage: CapUsage = { used: 165, limit: null, fraction: 0 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("cap-usage-bar")).toBeNull();
+    expect(screen.getByTestId("cap-usage-unlimited").textContent).toBe("165");
+  });
+
+  test("renders nothing for an unlimited cap when showLabel is false", () => {
+    const usage: CapUsage = { used: 165, limit: null, fraction: 0 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} showLabel={false} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("cap-usage-bar")).toBeNull();
+    expect(screen.queryByTestId("cap-usage-unlimited")).toBeNull();
+  });
+
+  test("not-measured wins over unlimited when both used and limit are null", () => {
+    const usage: CapUsage = { used: null, limit: null, fraction: 0 };
+    render(
+      <Wrapper>
+        <CapUsageBar usage={usage} />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("cap-usage-not-measured")).toBeTruthy();
+    expect(screen.queryByTestId("cap-usage-unlimited")).toBeNull();
+  });
 });

package/src/cap-overview/web/cap-cards-panel.tsx

@@ -35,11 +35,9 @@ const CAP_ICONS: Record<CapIconKey, ComponentType<{ className?: string }>> = {
   gauge: Gauge,
 };
 
-// Narrows `percent` to non-null alongside `used` — the query handler only
-// ever sets both or neither, but the type doesn't encode that link.
-function isMeasured(
-  cap: CapUsageWithMeta,
-): cap is CapUsageWithMeta & { used: number; percent: number } {
+// Narrows `used` only — `percent` can independently be null for an
+// unlimited cap (limit: null) even though used is measured.
+function isMeasured(cap: CapUsageWithMeta): cap is CapUsageWithMeta & { used: number } {
   return cap.used !== null;
 }
 
@@ -89,12 +87,18 @@ export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNod
             key={cap.id}
             icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
             label={t(cap.label)}
-            value={isMeasured(cap) ? `${cap.used} / ${cap.limit}` : "—"}
+            value={
+              !isMeasured(cap)
+                ? "—"
+                : cap.limit === null
+                  ? String(cap.used)
+                  : `${cap.used} / ${cap.limit}`
+            }
             {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
             testId="cap-card"
           >
             <div className="flex flex-col gap-2">
-              {isMeasured(cap) && (
+              {cap.percent !== null && (
                 <div className="flex items-center justify-between gap-2">
                   <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
                 </div>

package/src/cap-overview/web/cap-usage-bar.tsx

@@ -24,6 +24,15 @@ export function CapUsageBar({
     );
   }
 
+  if (usage.limit === null) {
+    // A progress bar with no denominator says nothing — show the raw count instead.
+    return showLabel ? (
+      <Text variant="small" testId="cap-usage-unlimited">
+        {String(usage.used)}
+      </Text>
+    ) : null;
+  }
+
   return (
     <div className="flex flex-col gap-1">
       {Progress ? (

package/src/cap-overview/web/cap-usage-cell.tsx

@@ -7,9 +7,10 @@ import { CapUsageBar } from "./cap-usage-bar";
 function isCapUsage(value: unknown): value is CapUsage {
   if (typeof value !== "object" || value === null) return false;
   const used = (value as { used?: unknown }).used;
+  const limit = (value as { limit?: unknown }).limit;
   return (
     (typeof used === "number" || used === null) &&
-    typeof (value as { limit?: unknown }).limit === "number" &&
+    (typeof limit === "number" || limit === null) &&
     typeof (value as { fraction?: unknown }).fraction === "number"
   );
 }

package/src/sessions/__tests__/sessions-screens.boot.test.ts

@@ -36,6 +36,19 @@ describe("sessions screens + query access alignment (kumiko-framework#255)", ()
     }
   });
 
+  test("session-list timestamp columns declare renderer.format (fw#2569)", () => {
+    const sessions = createSessionsFeature();
+    const list = sessions.screens[SESSION_LIST_SCREEN_ID];
+    if (list?.type !== "projectionList") throw new Error("expected projectionList");
+    for (const field of ["createdAt", "expiresAt", "revokedAt"] as const) {
+      const column = list.columns.find(
+        (c): c is Exclude<(typeof list.columns)[number], string> =>
+          typeof c !== "string" && c.field === field,
+      );
+      expect(column?.renderer).toEqual({ format: "timestamp" });
+    }
+  });
+
   test("session-list row-action navigates to session-detail with entityId 'id'", () => {
     const sessions = createSessionsFeature();
     const list = sessions.screens[SESSION_LIST_SCREEN_ID];

package/src/sessions/feature.ts

@@ -4,12 +4,7 @@ import {
   type SessionStoreProvider,
 } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
-import {
-  access,
-  defineFeature,
-  type FeatureDefinition,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { SESSION_DETAIL_SCREEN_ID, SESSION_LIST_SCREEN_ID, SessionQueries } from "./constants";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { cleanupJob } from "./handlers/cleanup.job";
 import { detailQuery } from "./handlers/detail.query";
 import { listQuery } from "./handlers/list.query";
@@ -19,6 +14,7 @@ import { revokeAllForUserWrite } from "./handlers/revoke-all-for-user.write";
 import { revokeAllOthersWrite } from "./handlers/revoke-all-others.write";
 import { SESSIONS_I18N } from "./i18n";
 import { userSessionEntity } from "./schema/user-session";
+import { sessionDetailScreen, sessionListScreen } from "./screens";
 import {
   createSessionCallbacks,
   type SessionAllOthersRevoker,
@@ -211,70 +207,8 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
 
     r.translations({ keys: SESSIONS_I18N });
 
-    const listAccess = { roles: access.admin };
-
-    r.screen({
-      id: SESSION_LIST_SCREEN_ID,
-      type: "projectionList",
-      query: SessionQueries.list,
-      // Mirrors list.query's own fallback (unrecognised/absent sort → createdAt
-      // desc) — kept in sync by hand, boot-validator only requires the field
-      // be present once the query accepts `sort` (fw#2230).
-      defaultSort: { field: "createdAt", dir: "desc" },
-      columns: [
-        { field: "id", label: "sessions.list.col.id" },
-        { field: "userId", label: "sessions.list.col.userId" },
-        { field: "createdAt", label: "sessions.list.col.createdAt" },
-        { field: "expiresAt", label: "sessions.list.col.expiresAt" },
-        { field: "revokedAt", label: "sessions.list.col.revokedAt" },
-      ],
-      rowActions: [
-        {
-          kind: "navigate",
-          id: "open",
-          label: "sessions.list.action.open",
-          screen: SESSION_DETAIL_SCREEN_ID,
-          entityId: "id",
-          rowClick: true,
-        },
-      ],
-      access: listAccess,
-    });
-    r.screen({
-      id: SESSION_DETAIL_SCREEN_ID,
-      type: "projectionDetail",
-      query: SessionQueries.detail,
-      listScreenId: SESSION_LIST_SCREEN_ID,
-      layout: {
-        sections: [
-          {
-            fields: [
-              "id",
-              "userId",
-              // The shim (projection-detail-shim.ts) stamps every field as
-              // type:"text" — field.renderer is the only way this screen
-              // type reaches real per-type formatting instead of a raw ISO
-              // string (fw#2245).
-              { field: "createdAt", renderer: { format: "timestamp" } },
-              { field: "expiresAt", renderer: { format: "timestamp" } },
-              { field: "revokedAt", renderer: { format: "timestamp" } },
-              "ip",
-              "userAgent",
-            ],
-          },
-        ],
-      },
-      fieldLabels: {
-        id: "sessions.detail.field.id",
-        userId: "sessions.detail.field.userId",
-        createdAt: "sessions.detail.field.createdAt",
-        expiresAt: "sessions.detail.field.expiresAt",
-        revokedAt: "sessions.detail.field.revokedAt",
-        ip: "sessions.detail.field.ip",
-        userAgent: "sessions.detail.field.userAgent",
-      },
-      access: listAccess,
-    });
+    r.screen(sessionListScreen);
+    r.screen(sessionDetailScreen);
     r.nav({
       id: "session-list",
       label: "sessions:nav.sessionList",

package/src/sessions/screens.ts

@@ -0,0 +1,84 @@
+import {
+  access,
+  type ProjectionDetailScreenDefinition,
+  type ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { SESSION_DETAIL_SCREEN_ID, SESSION_LIST_SCREEN_ID, SessionQueries } from "./constants";
+
+const listAccess = { roles: access.admin };
+
+export const sessionListScreen: ProjectionListScreenDefinition = {
+  id: SESSION_LIST_SCREEN_ID,
+  type: "projectionList",
+  query: SessionQueries.list,
+  // Mirrors list.query's own fallback (unrecognised/absent sort → createdAt
+  // desc) — kept in sync by hand, boot-validator only requires the field
+  // be present once the query accepts `sort` (fw#2230).
+  defaultSort: { field: "createdAt", dir: "desc" },
+  columns: [
+    { field: "id", label: "sessions.list.col.id" },
+    { field: "userId", label: "sessions.list.col.userId" },
+    {
+      field: "createdAt",
+      label: "sessions.list.col.createdAt",
+      renderer: { format: "timestamp" },
+    },
+    {
+      field: "expiresAt",
+      label: "sessions.list.col.expiresAt",
+      renderer: { format: "timestamp" },
+    },
+    {
+      field: "revokedAt",
+      label: "sessions.list.col.revokedAt",
+      renderer: { format: "timestamp" },
+    },
+  ],
+  rowActions: [
+    {
+      kind: "navigate",
+      id: "open",
+      label: "sessions.list.action.open",
+      screen: SESSION_DETAIL_SCREEN_ID,
+      entityId: "id",
+      rowClick: true,
+    },
+  ],
+  access: listAccess,
+};
+
+export const sessionDetailScreen: ProjectionDetailScreenDefinition = {
+  id: SESSION_DETAIL_SCREEN_ID,
+  type: "projectionDetail",
+  query: SessionQueries.detail,
+  listScreenId: SESSION_LIST_SCREEN_ID,
+  layout: {
+    sections: [
+      {
+        fields: [
+          "id",
+          "userId",
+          // The shim (projection-detail-shim.ts) stamps every field as
+          // type:"text" — field.renderer is the only way this screen
+          // type reaches real per-type formatting instead of a raw ISO
+          // string (fw#2245).
+          { field: "createdAt", renderer: { format: "timestamp" } },
+          { field: "expiresAt", renderer: { format: "timestamp" } },
+          { field: "revokedAt", renderer: { format: "timestamp" } },
+          "ip",
+          "userAgent",
+        ],
+      },
+    ],
+  },
+  fieldLabels: {
+    id: "sessions.detail.field.id",
+    userId: "sessions.detail.field.userId",
+    createdAt: "sessions.detail.field.createdAt",
+    expiresAt: "sessions.detail.field.expiresAt",
+    revokedAt: "sessions.detail.field.revokedAt",
+    ip: "sessions.detail.field.ip",
+    userAgent: "sessions.detail.field.userAgent",
+  },
+  access: listAccess,
+};

package/src/tenant/__tests__/members-screens.boot.test.ts

@@ -54,6 +54,20 @@ describe("tenant members screen + handler access alignment", () => {
     }
   });
 
+  test("members screen timestamp columns declare renderer.format (fw#2569)", () => {
+    const tenant = createTenantFeature();
+    const screen = tenant.screens[MEMBERS_SCREEN_ID];
+    if (screen?.type !== "projectionList")
+      throw new Error("expected members screen to be projectionList");
+    for (const field of ["createdAt", "lastSeenAt"] as const) {
+      const column = screen.columns.find(
+        (c): c is Exclude<(typeof screen.columns)[number], string> =>
+          typeof c !== "string" && c.field === field,
+      );
+      expect(column?.renderer).toEqual({ format: "timestamp" });
+    }
+  });
+
   test("cancel-invitation row action is only visible on pending rows and cancels via TenantHandlers.cancelInvitation", () => {
     const tenant = createTenantFeature();
     const screen = tenant.screens[MEMBERS_SCREEN_ID];

package/src/tenant/screens.ts

@@ -91,8 +91,16 @@ export function createMembersScreen(options?: {
         label: "tenant.members.col.status",
         renderer: { react: { __component: MEMBER_STATUS_CELL_COMPONENT } },
       },
-      { field: "createdAt", label: "tenant.members.col.created" },
-      { field: "lastSeenAt", label: "tenant.members.col.lastActivity" },
+      {
+        field: "createdAt",
+        label: "tenant.members.col.created",
+        renderer: { format: "timestamp" },
+      },
+      {
+        field: "lastSeenAt",
+        label: "tenant.members.col.lastActivity",
+        renderer: { format: "timestamp" },
+      },
     ],
     defaultSort: { field: "createdAt", dir: "desc" },
     searchable: true,