Skip to content
Kumiko

cap-overview

Read-only visibility into per-tenant tier assignment and cap usage. SystemAdmin gets a platform-wide tenant list with usage bars; tenant admins (or the roles in usageVisibleTo) get their own tenant’s usage as dashboard cards. Reads tier-engine, billing-foundation, and tenant data plus app-owned usage tables via caller-supplied CapSpec callbacks — never writes.

Quick example

Section titled “Quick example”

From apps-use-all-bundled — the smallest working mount:

// Smoke-entrypoint for use-all-bundled. CI runs this with
// KUMIKO_DRY_RUN_ENV=boot to exercise validators across every bundled
// feature without an actual postgres/redis. See package.json `boot`
// script + ../README.md.


import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
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 { BUNDLED_LISTS } from "../src/bundled-lists";
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;


const envSchema = composeEnvSchema({
  core: frameworkCoreEnvSchema,
  features: APP_FEATURES,
});


await runProdApp({
  features: BOOT_FEATURES,
  featureToggles: true,
  envSchema,
  validateBootOptions: VALIDATE_BOOT_OPTIONS,
  bundledLists: BUNDLED_LISTS,
  // Smoke-only: exercises the hard PII boot gate + blind-index gate with
  // every bundled feature mounted. Real apps wire createPgKmsAdapter(...).
  kms: new InMemoryKmsAdapter(),
  blindIndexKey: Buffer.alloc(32, 7).toString("base64"),
  // migrations default ("./kumiko/migrations") — boot mode exits before the
  // schema drift gate, the path here is only the runProdApp default.
  // auth.admin triggers composeFeatures(includeBundled:true) — auto-mounts
  // config + user + tenant + auth-email-password. Boot mode exits
  // before admin seeding runs, the value is only a stub for the types.
  auth: {
    admin: {
      email: "smoke@use-all-bundled.local",
      password: "smoke-only-never-deployed",
      displayName: "Smoke Admin",
      memberships: [
        {
          tenantId: SMOKE_TENANT_ID,
          tenantKey: "smoke",
          tenantName: "Use-All-Bundled Smoke",
          roles: ["TenantAdmin"],
        },
      ],
    },
    // Coverage for auth-self-registration toggle (#1521 Option A).
    signup: AUTH_COMPOSE_OPTIONS.signup,
    invite: AUTH_COMPOSE_OPTIONS.invite,
    passwordReset: AUTH_COMPOSE_OPTIONS.passwordReset,
    emailVerification: AUTH_COMPOSE_OPTIONS.emailVerification,
    accountUnlock: AUTH_COMPOSE_OPTIONS.accountUnlock,
  },
});

📄 On GitHub: samples/apps/use-all-bundled/bin/main.ts

Live preview

Section titled “Live preview”
cap-overview feature preview

How it fits

Section titled “How it fits”

What this feature needs to run (Requires).

flowchart TB
  n_cap_overview["cap-overview"]
  subgraph how_reqs["Requires"]
    n_tenant["tenant"]
    n_tier_engine["tier-engine"]
    n_billing_foundation["billing-foundation"]
  end
  n_tenant --> n_cap_overview
  n_tier_engine --> n_cap_overview
  n_billing_foundation --> n_cap_overview

Getting started

Section titled “Getting started”

Start with apps-use-all-bundled for a step-by-step walkthrough with runnable code and integration tests.

Dependencies

Section titled “Dependencies”