@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

package/dist/stack/request-helper.d.ts

@@ -1,35 +0,0 @@
-import type { Hono } from "hono";
-import type { SessionCreator } from "../api/auth-routes.js";
-import type { JwtHelper } from "../api/jwt.js";
-import type { SessionUser } from "../engine/types/index.js";
-export type BatchCommand = {
-    type: string;
-    payload: unknown;
-};
-export 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: readonly BatchCommand[], user: SessionUser, requestId?: string) => Promise<Response>;
-    raw: (method: string, path: string, body?: unknown, headers?: Record<string, string>) => Promise<Response>;
-    /** write + json + assert isSuccess — returns data directly */
-    writeOk: <T = Record<string, unknown>>(type: string, payload: unknown, user: SessionUser, requestId?: string) => Promise<T>;
-    /** write + json + assert isSuccess === false — returns the structured
-     *  WriteErrorInfo with `httpStatus` filled in from the HTTP response. */
-    writeErr: (type: string, payload: unknown, user: SessionUser) => Promise<import("../errors/index.js").WriteErrorInfo>;
-    /** query + json — returns data directly */
-    queryOk: <T = unknown>(type: string, payload: unknown, user: SessionUser) => Promise<T>;
-    /** query + json + assert the response is an error — returns the structured
-     *  WriteErrorInfo with `httpStatus` filled in from the HTTP response. */
-    queryErr: (type: string, payload: unknown, user: SessionUser) => Promise<import("../errors/index.js").WriteErrorInfo>;
-    /** write + additional HTTP headers (e.g. X-Correlation-ID). Returns the
-     *  raw Response so callers can assert on status + headers + body as needed. */
-    writeWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>;
-    /** query + additional HTTP headers (e.g. X-Forwarded-For). Returns the raw
-     *  Response so callers can assert on status + headers + body as needed. */
-    queryWithHeaders: (type: string, payload: unknown, user: SessionUser, extraHeaders: Record<string, string>) => Promise<Response>;
-};
-export type RequestHelperOptions = {
-    readonly sessionCreator?: SessionCreator;
-};
-export declare function createRequestHelper(app: Hono, jwt: JwtHelper, options?: RequestHelperOptions): RequestHelper;

package/dist/stack/request-helper.js

@@ -1,144 +0,0 @@
-function formatFailure(kind, type, body) {
-    const parsed = body;
-    const code = (typeof parsed.error === "object" ? parsed.error?.code : undefined) ??
-        (typeof parsed.error === "string" ? parsed.error : "unknown");
-    const details = typeof parsed.error === "object" && parsed.error?.details !== undefined
-        ? parsed.error.details
-        : undefined;
-    const causeMessage = details && typeof details === "object" && "causeMessage" in details
-        ? String(details.causeMessage ?? "")
-        : "";
-    const causeName = details && typeof details === "object" && "causeName" in details
-        ? String(details.causeName ?? "")
-        : "";
-    if (code === "internal_error" && (causeMessage || causeName)) {
-        return `Expected ${kind} "${type}" to succeed but got error: ${code} (${causeName}: ${causeMessage})`;
-    }
-    if (details !== undefined) {
-        return `Expected ${kind} "${type}" to succeed but got error: ${code} — ${JSON.stringify(details)}`;
-    }
-    return `Expected ${kind} "${type}" to succeed but got error: ${code}`;
-}
-export function createRequestHelper(app, jwt, options = {}) {
-    // sid per (user.id, tenantId), not one mint per authHeader() call:
-    // sessionCreator opens a live session row, so an unmemoized call mints a
-    // fresh one on every request a test makes for the same user — tests
-    // asserting on session counts / massRevoker / revokeAllOthers behavior
-    // then see extra live sids that have nothing to do with what they're
-    // testing. Keyed on tenantId too — the same user.id can hold sessions in
-    // more than one tenant, and sessionCreator writes the row scoped to
-    // `user.tenantId` (session-callbacks.ts), so a user.id-only key would
-    // hand a cross-tenant test its wrong tenant's sid.
-    // Cache the Promise (not the settled sid) so two concurrent authHeader
-    // calls for the same key share one mint instead of racing on a miss.
-    const sidByUserKey = new Map();
-    async function authHeader(user) {
-        let forJwt = user;
-        if (options.sessionCreator && !user.sid) {
-            const key = `${user.id}:${user.tenantId}`;
-            let sidPromise = sidByUserKey.get(key);
-            if (sidPromise === undefined) {
-                sidPromise = options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
-                sidByUserKey.set(key, sidPromise);
-            }
-            const sid = await sidPromise;
-            forJwt = { ...user, sid };
-        }
-        const token = await jwt.sign(forJwt);
-        return { Authorization: `Bearer ${token}` };
-    }
-    async function req(method, path, body, headers) {
-        const init = {
-            method,
-            headers: { "Content-Type": "application/json", ...headers },
-        };
-        if (body)
-            init.body = JSON.stringify(body);
-        return app.request(path, init);
-    }
-    async function writeRaw(type, payload, user, requestId) {
-        const headers = await authHeader(user);
-        return req("POST", "/api/write", { type, payload, requestId }, headers);
-    }
-    async function queryRaw(type, payload, user) {
-        const headers = await authHeader(user);
-        return req("POST", "/api/query", { type, payload }, headers);
-    }
-    return {
-        write: writeRaw,
-        query: queryRaw,
-        async command(type, payload, user) {
-            const headers = await authHeader(user);
-            return req("POST", "/api/command", { type, payload }, headers);
-        },
-        async batch(commands, user, requestId) {
-            const headers = await authHeader(user);
-            return req("POST", "/api/batch", { commands, requestId }, headers);
-        },
-        raw: req,
-        async writeOk(type, payload, user, requestId) {
-            const res = await writeRaw(type, payload, user, requestId);
-            // wire-body shape direkt nach JSON.parse — Caller-Code prüft danach
-            // selber ob isSuccess/error/data tatsächlich da sind.
-            const rawBody = await res.json();
-            const body = rawBody;
-            // Success path still has { isSuccess: true, data }. Error responses now
-            // follow the error-contract shape { error: { code, i18nKey, ... } } with
-            // a 4xx/5xx status — no isSuccess flag. Detect either.
-            if (body.isSuccess !== true) {
-                throw new Error(formatFailure("write", type, body));
-            }
-            return body.data; // @cast-boundary engine-bridge
-        },
-        async writeErr(type, payload, user) {
-            const res = await writeRaw(type, payload, user);
-            const rawErrorBody = await res.json();
-            const body = rawErrorBody;
-            if (body.isSuccess === true) {
-                throw new Error(`Expected write "${type}" to fail but it succeeded`);
-            }
-            const wire = body.error;
-            if (!wire || typeof wire !== "object" || typeof wire.code !== "string") {
-                throw new Error(`Expected error response for "${type}" but got unexpected shape: ${JSON.stringify(body)}`);
-            }
-            // The wire body doesn't carry httpStatus (it would be redundant with
-            // the HTTP response status). Fill it in from res.status so callers can
-            // assert against either code OR status without a second request round.
-            return { ...wire, httpStatus: res.status };
-        },
-        async queryOk(type, payload, user) {
-            const res = await queryRaw(type, payload, user);
-            const rawBody = await res.json();
-            const body = rawBody;
-            // res.ok mirrors writeOk's isSuccess assertion — belt-and-suspenders
-            // in case a future non-dispatcher rejection skips the error-contract shape.
-            if (!res.ok || body.error !== undefined) {
-                throw new Error(`${formatFailure("query", type, body)} [HTTP ${res.status}]`);
-            }
-            return body.data; // @cast-boundary engine-bridge
-        },
-        async queryErr(type, payload, user) {
-            const res = await queryRaw(type, payload, user);
-            const rawErrorBody = await res.json();
-            const body = rawErrorBody;
-            if (res.ok) {
-                throw new Error(`Expected query "${type}" to fail but it succeeded`);
-            }
-            const wire = body.error;
-            if (!wire || typeof wire !== "object" || typeof wire.code !== "string") {
-                throw new Error(`Expected error response for "${type}" but got unexpected shape: ${JSON.stringify(body)}`);
-            }
-            // Same rationale as writeErr: the wire body has no httpStatus (it would
-            // be redundant with the HTTP response status), so fill it in here.
-            return { ...wire, httpStatus: res.status };
-        },
-        async writeWithHeaders(type, payload, user, extraHeaders) {
-            const authHeaders = await authHeader(user);
-            return req("POST", "/api/write", { type, payload }, { ...authHeaders, ...extraHeaders });
-        },
-        async queryWithHeaders(type, payload, user, extraHeaders) {
-            const authHeaders = await authHeader(user);
-            return req("POST", "/api/query", { type, payload }, { ...authHeaders, ...extraHeaders });
-        },
-    };
-}

package/dist/stack/test-stack.d.ts

@@ -1,192 +0,0 @@
-import type { Hono } from "hono";
-import type { AuthRoutesConfig } from "../api/auth-routes.js";
-import type { JwtHelper } from "../api/jwt.js";
-import { type SseBroker } from "../api/sse-broker.js";
-import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types/index.js";
-import type { ErrorDocsConfig } from "../errors/docs-url.js";
-import { type JobRunner, type JobRunnerOptions } from "../jobs/index.js";
-import type { Lifecycle } from "../lifecycle/index.js";
-import { type ObservabilityProvider } from "../observability/index.js";
-import type { Dispatcher, EventDispatcher, SystemHooks } from "../pipeline/index.js";
-import { type ClosableCacheSyncBus } from "../redis/cache-sync-bus.js";
-import type { SearchAdapter } from "../search/types.js";
-import { type EventCollector } from "./event-collector.js";
-import { type TestRedis } from "./redis.js";
-import { type RequestHelper } from "./request-helper.js";
-export type TestStack = {
-    app: Hono;
-    jwt: JwtHelper;
-    registry: Registry;
-    db: import("../db/index.js").DbConnection;
-    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>;
-};
-export type TestStackOptions = {
-    features: readonly FeatureDefinition[];
-    /** System hooks to wire up. Default: all (sse, search) */
-    systemHooks?: ("sse" | "search")[];
-    /** Pipeline system hooks handed to buildServer, e.g. the cascade-delete preDelete hook. None by default. */
-    lifecycleSystemHooks?: SystemHooks;
-    /** Search config per tenant — defaults to tenant 1 with all text fields */
-    searchConfig?: {
-        tenantId: TenantId;
-        searchableFields: string[];
-        rankingFields: string[];
-    };
-    jwtSecret?: string;
-    /** Extra fields merged into the AppContext (e.g. _notifyFactory, configResolver).
-     *  Can be a function receiving (registry, db, sseBroker) for late binding. */
-    /** Boot default locale (BCP-47) merged into AppContext before extraContext. */
-    defaultLocale?: string;
-    extraContext?: Record<string, unknown> | ((deps: {
-        registry: Registry;
-        db: import("../db/index.js").DbConnection;
-        sseBroker: import("../api/sse-broker.js").SseBroker;
-        redis: import("ioredis").Redis;
-    }) => Record<string, unknown>);
-    /** Wire up auth routes (login, tenant-switch). Leave undefined to skip. */
-    authConfig?: AuthRoutesConfig;
-    /** Register a file storage provider so uploads via POST /api/files work and
-     *  `ctx.files.ref(key)` is available to hooks/MSPs. Omit to skip — tests
-     *  without file handling don't need it. */
-    files?: {
-        storageProvider: import("../files/index.js").FileStorageProvider;
-    };
-    /** Observability provider — omit for NoopProvider (no spans/metrics).
-     *  Pass a ConsoleProvider to see the span tree in stdout, or a custom
-     *  provider (e.g. a recording provider for assertions in tests). */
-    observability?: ObservabilityProvider;
-    /** Inject a process lifecycle so tests can drain() and observe
-     *  /health/ready flipping to 503. Omit if the suite doesn't care. */
-    lifecycle?: Lifecycle;
-    /** Wire L1 (global-IP) and/or L2 (auth-endpoint) rate-limit middleware.
-     *  The resolver is auto-built from the test Redis. Mirrors
-     *  buildServer's `rateLimit` option 1:1 — see there for shape. */
-    rateLimit?: import("../api/server.js").ServerOptions["rateLimit"];
-    /** Forwarded to buildServer — Integration-Tests that exercise `extraRoutes`
-     *  MUST go through here (real HTTP via `stack.http`/`stack.app.fetch`),
-     *  never `createTestDispatcher`. */
-    extraRoutes?: import("../api/server.js").ServerOptions["extraRoutes"];
-    /** Forwarded to buildServer like runProdApp. Without a PrometheusMeter-backed
-     *  `observability` the route answers 503, so spread `resolveObservabilityWiring(token)`
-     *  rather than setting `metrics` alone. */
-    metrics?: import("../api/server.js").ServerOptions["metrics"];
-    /** Inject a MasterKeyProvider for secrets-backed tests. Lands typed in
-     *  AppContext — set/delete/get + rotation job pick it up. Omit for
-     *  suites that don't touch secrets. */
-    masterKeyProvider?: import("../secrets/index.js").MasterKeyProvider;
-    /** Feature-toggle resolver. When present the dispatcher's feature-gate,
-     *  hook-filter, and MSP-filter all consult it; absent = every feature
-     *  treated as always-on. Pass the callback from
-     *  GlobalFeatureToggleRuntime.effectiveFeatures for real DB-backed
-     *  toggles, or a plain `() => new Set<string>(registry.features.keys())`
-     *  to force a specific snapshot in a unit-style setup. */
-    effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
-    /** Pin the underlying Postgres DB name instead of the default
-     *  `kumiko_test_<8chars>`. Forwarded to createTestDb. Primary use
-     *  case: dev servers that want persistent storage across restarts —
-     *  combine with `persistentDb: true`. */
-    dbName?: string;
-    /** When true, cleanup() keeps the Postgres DB around — the caller
-     *  owns its lifecycle. Default false (test contract). Used by
-     *  dev-server wiring to survive hot-reloads. */
-    persistentDb?: boolean;
-    /** Cap on the main app pool (default: driver default). Lets tests saturate it deliberately. */
-    dbPoolMax?: number;
-    /** Size of the dedicated pool behind ctx.dbOutsideTransaction / ctx.outsideTransaction. */
-    outsideTransactionPoolMax?: number;
-    /** Forwarded to buildServer — when set, requests without a JWT pass
-     *  through as anonymous instead of 401. See AnonymousAccessConfig.
-     *  Akzeptiert entweder einen statischen Config-Object ODER eine Factory
-     *  `({registry, db, sseBroker, redis}) => Config` — gleiches Pattern wie
-     *  `extraContext`. Die Factory wird einmal beim Boot aufgerufen, der
-     *  TenantResolver darin closure'd typischerweise `db` für Subdomain-
-     *  Lookups. */
-    anonymousAccess?: import("../api/server.js").ServerOptions["anonymousAccess"] | ((deps: {
-        registry: Registry;
-        db: import("../db/index.js").DbConnection;
-        sseBroker: import("../api/sse-broker.js").SseBroker;
-        redis: import("ioredis").Redis;
-    }) => import("../api/server.js").ServerOptions["anonymousAccess"]);
-    /** Optional post-factory enricher (e.g. merge auth-foundation tenant
-     *  providers). Keeps framework free of a bundled-features dependency. */
-    enrichAnonymousAccess?: (base: import("../api/server.js").ServerOptions["anonymousAccess"] | undefined, deps: {
-        registry: Registry;
-        db: import("../db/index.js").DbConnection;
-    }) => Promise<import("../api/server.js").ServerOptions["anonymousAccess"] | undefined>;
-    /** Opt-in JobRunner wired into ctx.jobRunner and merged into
-     *  dispatcherOptions so event-triggered jobs enqueue on commit — mirrors
-     *  the prod entrypoint's `buildJobRunnerWithHook`. Unlike prod (which
-     *  always builds one), this only builds a runner when `registry.getAllJobs()`
-     *  is non-empty — a deliberate test-stack-only shortcut, not parity.
-     *  Default `undefined`. Pass `consumerLane` only when this test IS the
-     *  sole consumer (otherwise enqueuer-only, avoiding double-running
-     *  `runOnBoot`/cron jobs against a caller-owned consumer). */
-    jobs?: {
-        consumerLane?: JobRunIn;
-        /** Default: unique per stack, derived from its test Redis keyPrefix. Pass
-         *  the same value to every runner that has to share this stack's queues. */
-        queueNamePrefix?: string;
-        /** Source of active tenant ids for `perTenant: true` jobs. Omit when the
-         *  tenant feature is among `options.features` — the framework then
-         *  resolves tenants on its own via that feature's active-tenant-ids
-         *  query, same as prod. Only needed for suites that fan a job over
-         *  tenants without mounting the tenant feature. */
-        getActiveTenantIds?: JobRunnerOptions["getActiveTenantIds"];
-        /** Run-log callbacks (job_runs / tenant job failures), built once registry
-         *  and db exist. The framework can't import the bundled jobs feature, so the
-         *  dev-server wrapper supplies prod's `jobRunLoggerCallbacks` here. They are
-         *  awaited before drainJobs() observes the job's outcome. */
-        runLogger?: (deps: {
-            registry: Registry;
-            db: import("../db/index.js").DbConnection;
-        }) => Pick<JobRunnerOptions, "onJobStart" | "onJobComplete" | "onJobFailed" | "onJobQueued" | "onJobDropped"> | undefined;
-    };
-    /** Override the event dispatcher's polling-timer interval. Default 50ms.
-     *  Tests that assert LISTEN/NOTIFY wake-up latency need this pushed far
-     *  out (e.g. 60_000) so the polling timer can't land inside the
-     *  assertion window and mask a dead subscription — see E.4 (#2042). */
-    eventDispatcherPollIntervalMs?: number;
-    /** Opt out of auto-created r.entity() tables for callers that create/migrate
-     *  them themselves. Default true — false pushes only projection/MSP/
-     *  storeTable sources, same as before fw#3102. */
-    entityTables?: boolean;
-    /** Time source of the stack's rate-limit resolver, so tests can freeze the
-     *  clock instead of racing the window. Default: system time. */
-    rateLimitNowMs?: () => number;
-    /** Forwarded to buildServer's top-level `ServerOptions.trustedProxyHops`
-     *  — see there. Default 0. */
-    trustedProxyHops?: number;
-    /** Links the app's own error reasons to its own docs (`docsUrl` in error responses); framework reasons keep the framework docs link. Passed to buildServer's `ServerOptions.errorDocs`. */
-    errorDocs?: ErrorDocsConfig;
-    /** 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. The derived
-     *  queueNamePrefix is identical too, so both stacks share BullMQ queues.
-     *  Cleanup only disconnects; the owner flushes the namespace and queues, so
-     *  clean up the borrowing stack first. The DB is NOT shared — pass the same
-     *  `dbName` + `persistentDb` for that. */
-    sharedRedisWith?: TestStack;
-    /** Publish/receive cache invalidations (tenant timezone, file providers,
-     *  tier sets) over Redis Pub/Sub, namespaced by this stack's keyPrefix.
-     *  Implied by `sharedRedisWith`; set it on the owner stack too, or its writes
-     *  never reach the borrower. Without it the stack uses a process-local bus. */
-    cacheSync?: boolean;
-    /** "full" runs the prod-boot validateBoot over `features` (screens and ref
-     *  entities across features included). Use it with the app's complete feature
-     *  composition; the default only checks what is safe on a feature subset. */
-    validateBoot?: "full";
-};
-export declare function setupTestStack(options: TestStackOptions): Promise<TestStack>;