@cosmicdrift/kumiko-framework 0.398.0 → 0.400.0

package/agents/api/testing-helpers.md

@@ -0,0 +1,189 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/testing/src/helpers/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-testing/helpers
+
+Import from `@cosmicdrift/kumiko-testing/helpers`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function buildMultipartBody(fd: FormData): Promise<{ body: BodyInit; contentType: string; }>; // Serializes a FormData instance to multipart/form-data bytes.
+function burst(stack: { dbPoolMax: number; }, count: number, request: (index: number) => Promise<Response>): Promise<BurstResult>;
+function captureClosedConnectionError(url?: string): Promise<unknown>;
+function clearTables(db: AnyDb, tables: ClearableTable[]): Promise<void>; // Delete all rows from each table (order preserved — FK-sensitive callers order explicitly).
+function consoleCallsFromNamespace(spy: ConsoleSpyLike, namespace: string): ReadonlyArray<ReadonlyArray<unknown>>;
+function consoleCallsMentioning(spy: ConsoleSpyLike, fragment: string): ReadonlyArray<ReadonlyArray<unknown>>;
+function createBarrier(options: { expected: number; timeoutMs?: number; }): Barrier;
+function createLateBoundHolder<T>(label?): LateBoundHolder<T>;
+function createManualClock(start: Temporal.Instant): ManualClock;
+function createMutableMasterKeyProvider(initial: MasterKeyProvider): MutableMasterKeyProvider;
+function createRecordingProvider(options?: ObservabilityOptions): RecordingProvider;
+function createTestEnvelopeCipher(keyBase64?: string, opts?: EnvelopeCipherOptions): EnvelopeCipher;
+function createTestMasterKeyProvider(keyBase64?: string): MasterKeyProvider;
+function createTestStoredEvent(overrides?: Partial<StoredEvent>): StoredEvent;
+function deleteRowViaEventStore(db: DbConnection, target: EventStoreWriteTarget, where: WhereObject, scope?: EventStoreWriteScope): Promise<void>;
+function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<number>;
+function deleteRowsViaEventStore(db: DbConnection, target: EventStoreWriteTarget, where: WhereObject, scope?: EventStoreWriteScope): Promise<void>; // Deletes every row matching `where`, each through its own event-store delete.
+function describeFileProviderContract(name: string, factory: () => FileStorageProvider | Promise<FileStorageProvider>): void;
+function expectError(result: WriteResult, matcher?: string): asserts result is { isSuccess: false; error: WriteErrorInfo; };
+function expectErrorIncludes(err: WriteErrorInfo | string | null | undefined, substring: string): void;
+function expectRoleRestrictedHandlersDenyForeignRole(stack: Pick<TestStack, "registry" | "http">, options?: { minimumHandlerCount?: number; probeUser?: SessionUser; }): Promise<CheckedHandlerCounts>; // Contract test: every role-restricted write/query handler in the stack rejects a signed-in caller who holds none of its roles with 403 access_denied, over real HTTP.
+function expectSuccess<T>(result: WriteResult<T>): asserts result is { isSuccess: true; data: T; };
+function generateE2ESpec(registry: Registry, options?: E2EGeneratorOptions): E2ETestSpec[];
+function generateZodFixture(schema: z.ZodTypeAny): unknown;
+function getSetCookieRaw(res: Response, name: string): string | undefined;
+function getSetCookieValue(res: Response, name: string): string | undefined;
+function getSetCookies(res: Response): Map<string, ParsedSetCookie>;
+function isRealProviderRun(env?: Readonly<Record<string, string | undefined>>): boolean;
+function patchFileInstanceofForBunTest(): void; // Patches File[Symbol.hasInstance] so that cross-realm Blob objects returned by Hono's parseBody() pass `instanceof File` checks in bun:test.
+function readSseFrames(response: Response, options: ReadSseFramesOptions): Promise<SseFrame[]>;
+function requireRealProviders(): void;
+function resetTestTables(db: AnyDb, tables: ClearableTable[]): Promise<void>; // Alias — same as clearTables, reads better in beforeEach.
+function rolesOf(access: AccessRule | undefined): string[];
+function runInRowLevelSecurityScope<T>(scope: RowLevelSecurityScope, fn: () => T): T;
+function runInSystemRowLevelSecurityScope<T>(reason: string, fn: () => T): T;
+function seedRow<TRow = unknown>(db: AnyDb, table: SeedTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+function seedRowViaEventStore(db: DbConnection, table: EventStoreWriteTarget["table"], values: Readonly<Record<string, unknown>>): Promise<void>;
+function seedRows<TRow = unknown>(db: AnyDb, table: SeedTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function sleep(ms: number): Promise<unknown>;
+function tenantRowLevelSecurityScope(tenantId: TenantId): RowLevelSecurityScope;
+function terminateBackendsByApplicationName(admin: AdminClient, applicationName: string): Promise<void>;
+function testDatabaseUrl(): string;
+function updateRowViaEventStore(db: DbConnection, target: EventStoreWriteTarget, where: WhereObject, changes: Readonly<Record<string, unknown>>, scope?: EventStoreWriteScope): Promise<void>;
+function updateRows<TRow = unknown>(db: AnyDb, table: SeedTable, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function waitFor(fn: () => void | boolean | Promise<void | boolean>, options?: { delays?: number[]; }): Promise<void>; // Polls a condition with escalating timeouts.
+function withBootValidatorFixture(features: FeatureDefinition[]): FeatureDefinition[]; // Test-fixture helper: satisfy entityList + i18n boot rules without bloating every makeFeature.
+function withEnv<T>(overrides: Readonly<Record<string, string | undefined>>, run: () => T | Promise<T>): Promise<T>;
+function withoutAmbientTemporal<T>(fn: () => T | Promise<T>): Promise<T>; // Run `fn` with `globalThis.Temporal` deleted, then restore.
+function zipWithEntries(...entryNames: string[]): Uint8Array;
+```
+
+## Constants
+
+```ts
+const REAL_PROVIDERS_ENV: "KUMIKO_REAL_PROVIDERS";
+const sharedItemEntity;
+const sharedItemTable;
+const sharedUserEntity;
+const sharedUserTable;
+const sharedWidgetEntity: EntityDefinition<{ name: EntityTextFieldDef & { required: true; }; }, "tenant">;
+const sharedWidgetTable: EntityTable<EntityDefinition<{ name: EntityTextFieldDef & { required: true; }; }, "tenant">>;
+```
+
+## Types
+
+```ts
+type Barrier = {
+  arrive: () => Promise<void>;
+  skip: () => void;
+  arrived: number;
+  skipped: number;
+};
+type BurstResult = {
+  responses: Response[];
+  statuses: Readonly<Record<number, number>>;
+};
+type ClearableTable = // EntityTableMeta, a built table, or a plain table name string.
+  | string
+  | {
+    tableName?: string;
+  }
+  | unknown
+;
+type ConsoleSpyLike = {
+  mock: {
+    calls: ReadonlyArray<ReadonlyArray<unknown>>;
+  };
+};
+type E2EGeneratorOptions = {
+  tenantPlaceholder?: string;
+};
+type E2ETestSpec =
+  | {
+    kind: "list-renders";
+    screenQn: string;
+    title: string;
+    urlPath: string;
+  }
+  | {
+    kind: "list-has-fixture-row";
+    screenQn: string;
+    title: string;
+    urlPath: string;
+    writeHandlerQn: string;
+    fixture: Readonly<Record<string, unknown>>;
+    identifyingValue: string;
+  }
+  | {
+    kind: "edit-validates-required";
+    screenQn: string;
+    title: string;
+    urlPath: string;
+    requiredFields: string[];
+  }
+  | {
+    kind: "edit-save-persists";
+    screenQn: string;
+    title: string;
+    urlPath: string;
+    listUrlPath?: string;
+    fills: EditFillOp[];
+    identifyingValue: string;
+    identifyingField: string;
+  }
+;
+type EditFillOp =
+  | {
+    kind: "fill";
+    field: string;
+    value: string;
+  }
+  | {
+    kind: "check";
+    field: string;
+    value: boolean;
+  }
+  | {
+    kind: "select";
+    field: string;
+    value: string;
+  }
+;
+type EventStoreWriteScope = {
+  tenantId?: TenantId; // Tenant of the acting system user and of the tenant-bound db; defaults to the system tenant.
+  streamTenantId?: TenantId; // Address a stream that lives on another tenant than the actor's.
+};
+type EventStoreWriteTarget = {
+  table: ExecutorArgs[0];
+  entity: ExecutorArgs[1];
+  entityName: string;
+};
+type LateBoundHolder<T> = {
+  set(value: T): void; // Store the concrete value.
+  get(): T; // Fetch the concrete value or throw if set() hasn't been called yet.
+  isReady(): boolean; // True after set() has been called.
+};
+type ManualClock = Clock & {
+  set(instant: Temporal.Instant): void;
+  advance(step: ClockStep): void;
+};
+type MutableMasterKeyProvider = MasterKeyProvider & {
+  replace(next: MasterKeyProvider): void;
+};
+type ParsedSetCookie = {
+  value: string;
+  raw: string;
+};
+type RecordingProvider = ObservabilityProvider & {
+  spans: RecordedSpan[];
+  metricEvents: MetricEvent[];
+  spansByName(name: string): RecordedSpan[];
+  spansByTraceId(traceId: string): RecordedSpan[];
+  reset(): void;
+};
+type SseFrame = {
+  event: string | undefined;
+  data: string;
+  id: string | undefined;
+};
+```

package/agents/api/testing-stack.md

@@ -0,0 +1,144 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/testing/src/stack/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-testing/stack
+
+Import from `@cosmicdrift/kumiko-testing/stack`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function applicationRoleUrlOf(url: string, dbName: string): string; // URL of database `dbName` on the host of `url`, logged in as TEST_APPLICATION_ROLE with the password of `url` (the caller's TEST_DATABASE_URL).
+function createEventCollector(): EventCollector;
+function createRequestHelper(app: Hono, jwt: JwtHelper, options?: RequestHelperOptions): RequestHelper;
+function createTestDb(arg?: string | CreateTestDbOptions): Promise<TestDb>;
+function createTestRedis(opts?: CreateTestRedisOptions): Promise<TestRedis>;
+function drainEventConsumers(stack: Pick<TestStack, "db" | "eventDispatcher">, consumerNames: [ string, ...string[] ], options?: { maxPasses?: number; }): Promise<void>;
+function pushEntityProjectionTables(stack: DbHolder, registry: Registry): Promise<void>; // Push all implicit-projection tables — one per `r.entity()` — that the registry knows about.
+function resetEventStore(stack: { db: unknown; eventDispatcher?: EventDispatcher; }, extraTables?: (unknown | string)[]): Promise<void>; // Wipes event store + framework-state + the given feature read-models in one TRUNCATE, then re-registers the event-consumer state rows.
+function setupTestStack(options: TestStackOptions): Promise<TestStack>;
+function unsafeCreateEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<void>; // Bypass: creates an entity-table directly without going through the full registry.
+function unsafeEnsureEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<boolean>;
+function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>, options?: { rowLevelSecurity?: RowLevelSecurityMode; }): Promise<void>; // Bypass: pushes table definitions to the database directly.
+```
+
+## Constants
+
+```ts
+const DEFAULT_TEST_DB_POOL_MAX: 10;
+const TEST_APPLICATION_ROLE: "kumiko_app";
+```
+
+## Types
+
+```ts
+type CreateTestDbOptions = {
+  baseUrl?: string;
+  dbName?: string;
+  persistent?: boolean;
+  poolMax?: number;
+  outsideTransactionPoolMax?: number;
+  templateDbName?: string; // Clone this already-migrated database instead of starting empty.
+  applicationRole?: boolean; // Own the database as the non-bypass application role and enforce row-level security on the pools.
+};
+type EventCollector = {
+  sse: SseEvent[];
+  postSave: SaveContext[];
+  reset(): void; // Clears all collected events — call in beforeEach for per-test isolation
+};
+type RequestHelper = {
+  write: (type: string, payload: unknown, user: SessionUser, requestId?: string) => Promise<Response>;
+  query: (type: string, payload: unknown, user: SessionUser) => Promise<Response>;
+  command: (type: string, payload: unknown, user: SessionUser) => Promise<Response>;
+  batch: (commands: BatchCommand[], user: SessionUser, requestId?: string) => Promise<Response>;
+  raw: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<Response>;
+  writeOk: <T = Record<string, unknown>>(type: string, payload: unknown, user: SessionUser, requestId?: string) => Promise<T>; // write + json + assert isSuccess — returns data directly
+  writeErr: (type: string, payload: unknown, user: SessionUser) => Promise<WriteErrorInfo>; // write + json + assert isSuccess === false — returns the structured WriteErrorInfo with `httpStatus` filled in from the HTTP response.
+  queryOk: <T = unknown>(type: string, payload: unknown, user: SessionUser) => Promise<T>; // query + json — returns data directly
+  queryErr: (type: string, payload: unknown, user: SessionUser) => Promise<WriteErrorInfo>; // query + json + assert the response is an error — returns the structured WriteErrorInfo with `httpStatus` filled in from the HTTP response.
+  writeWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>; // write + additional HTTP headers (e.g. X-Correlation-ID).
+  queryWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>; // query + additional HTTP headers (e.g. X-Forwarded-For).
+};
+type TestDb = {
+  db: DbConnection;
+  poolMax: number;
+  outsideTransactionDb: DbConnection;
+  client: PgListenClient;
+  dbName: string;
+  cleanup: () => Promise<void>;
+};
+type TestRedis = {
+  redis: Redis;
+  redisUrl: string;
+  keyPrefix: string; // The per-test `keyPrefix` on `redis`, e.g. `kt:1a2b3c4d:`.
+  flushNamespace: () => Promise<void>; // Delete every key this test created (prefix-scoped).
+  cleanup: () => Promise<void>;
+};
+type TestStack = {
+  app: Hono;
+  jwt: JwtHelper;
+  registry: Registry;
+  db: DbConnection; // Sees every tenant's rows (system scope) at rowLevelSecurity "on".
+  unscopedDb: DbConnection; // The enforced pool the services use: a statement without a scope sees no tenant row.
+  dbPoolMax: number; // Resolved connection pool size of `db`.
+  redis: TestRedis;
+  cacheSync: ClosableCacheSyncBus;
+  search: SearchAdapter;
+  events: EventCollector;
+  http: RequestHelper;
+  observability: ObservabilityProvider;
+  sseBroker: SseBroker;
+  dispatcher: Dispatcher;
+  context: AppContext;
+  eventDispatcher?: EventDispatcher;
+  lifecycle?: Lifecycle;
+  jobRunner?: JobRunner;
+  drainJobs: () => Promise<void>;
+  cleanup: () => Promise<void>;
+};
+type TestStackOptions = {
+  features: FeatureDefinition[];
+  systemHooks?: ("sse" | "search")[]; // System hooks to wire up.
+  lifecycleSystemHooks?: SystemHooks; // Pipeline system hooks handed to buildServer, e.g. the cascade-delete preDelete hook.
+  searchConfig?: {
+    tenantId: TenantId;
+    searchableFields: string[];
+    rankingFields: string[];
+  }; // Search config per tenant — defaults to tenant 1 with all text fields
+  jwtSecret?: string;
+  defaultLocale?: string; // Boot default locale (BCP-47) merged into AppContext before extraContext.
+  extraContext?: Record<string, unknown> | ((deps: { registry: Registry; db: DbConnection; sseBroker: SseBroker; redis: Redis; }) => Record<string, unknown>);
+  authConfig?: AuthRoutesConfig; // Wire up auth routes (login, tenant-switch).
+  files?: {
+    storageProvider: FileStorageProvider;
+  }; // Register a file storage provider so uploads via POST /api/files work and `ctx.services.files.ref(key)` is available to hooks/MSPs.
+  observability?: ObservabilityProvider; // Observability provider — omit for NoopProvider (no spans/metrics).
+  lifecycle?: Lifecycle; // Inject a process lifecycle so tests can drain() and observe /health/ready flipping to 503.
+  sseBroker?: SseBroker; // Replaces the default in-memory broker; the caller owns its lifecycle.
+  rateLimit?: ServerOptions["rateLimit"]; // Wire L1 (global-IP) and/or L2 (auth-endpoint) rate-limit middleware.
+  extraRoutes?: ServerOptions["extraRoutes"]; // Forwarded to buildServer — Integration-Tests that exercise `extraRoutes` MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`), never `createTestDispatcher`.
+  metrics?: ServerOptions["metrics"]; // Forwarded to buildServer like runProdApp.
+  masterKeyProvider?: MasterKeyProvider; // Inject a MasterKeyProvider for secrets-backed tests.
+  effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>; // Feature-toggle resolver.
+  dbName?: string; // Pin the underlying Postgres DB name instead of the default `kumiko_test_<8chars>`.
+  persistentDb?: boolean; // When true, cleanup() keeps the Postgres DB around — the caller owns its lifecycle.
+  dbPoolMax?: number; // Cap on the main app pool (default: driver default).
+  outsideTransactionPoolMax?: number; // Size of the dedicated pool behind ctx.db.outsideTransaction / ctx.outsideTransaction.
+  anonymousAccess?: ServerOptions["anonymousAccess"] | ((deps: { registry: Registry; db: DbConnection; sseBroker: SseBroker; redis: Redis; }) => ServerOptions["anonymousAccess"]); // Forwarded to buildServer — when set, requests without a JWT pass through as anonymous instead of 401.
+  enrichAnonymousAccess?: (base: ServerOptions["anonymousAccess"] | undefined, deps: { registry: Registry; db: DbConnection; }) => Promise<ServerOptions["anonymousAccess"] | undefined>; // Optional post-factory enricher (e.g. merge auth-foundation tenant providers).
+  jobs?: {
+    consumerLane?: JobRunIn;
+    queueNamePrefix?: string; // Default: unique per stack, derived from its test Redis keyPrefix.
+    getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"]; // Source of active tenant ids for `perTenant: true` jobs.
+    runLogger?: (deps: { registry: Registry; db: DbConnection; }) => Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobQueued" | "onJobDropped"> | undefined; // Run-log callbacks (job_runs / tenant job failures), built once registry and db exist.
+  }; // Opt-in JobRunner wired into ctx.services.jobRunner and merged into dispatcherOptions so event-triggered jobs enqueue on commit — mirrors the prod entrypoint's `buildJobRunnerWithHook`.
+  eventDispatcherPollIntervalMs?: number; // Override the event dispatcher's polling-timer interval.
+  entityTables?: boolean; // Opt out of auto-created r.entity() tables for callers that create/migrate them themselves.
+  rateLimitNowMs?: () => number; // Time source of the stack's rate-limit resolver, so tests can freeze the clock instead of racing the window.
+  trustedProxyHops?: number; // Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops` — see there.
+  errorDocs?: ErrorDocsConfig; // Links the app's own error reasons to its own docs (`docsUrl` in error responses); framework reasons keep the framework docs link.
+  sharedRedisWith?: TestStack; // Second stack on the Redis namespace of `owner`: own connection, same keyPrefix, so rate-limit buckets, locks, idempotency keys and the cache-sync channel are shared across both.
+  cacheSync?: boolean; // Publish/receive cache invalidations (tenant timezone, file providers, tier sets) over Redis Pub/Sub, namespaced by this stack's keyPrefix.
+  validateBoot?: "full"; // "full" runs the prod-boot validateBoot over `features` (screens and ref entities across features included).
+  rowLevelSecurity?: RowLevelSecurityMode; // Postgres tenant isolation, as in prod.
+};
+```