@cosmicdrift/kumiko-framework 0.366.0 → 0.368.0

package/dist/testing/db-cleanup.js

@@ -1,31 +0,0 @@
-import { deleteMany } from "../db/query.js";
-// A full-table wipe (empty where) only needs the table name — give deleteMany
-// a minimal-but-canonical EntityTableMeta so extractTableInfo accepts it
-// without inferring columns.
-function tableFromName(name) {
-    return { tableName: name, columns: [], indexes: [], source: "unmanaged" };
-}
-function resolveClearableTable(table) {
-    if (typeof table === "string")
-        return tableFromName(table);
-    if (typeof table === "object" &&
-        table !== null &&
-        "tableName" in table &&
-        typeof table.tableName === "string") {
-        return table;
-    }
-    return table;
-}
-/** Delete all rows from each table (order preserved — FK-sensitive callers order explicitly). */
-export async function clearTables(db, tables) {
-    for (const table of tables) {
-        // Test-teardown truncate: resolveClearableTable returns `unknown` (string
-        // name or table object). The brand-strip cast is the sanctioned bypass —
-        // clearing a managed projection between tests is not a production write.
-        await deleteMany(db, resolveClearableTable(table), {});
-    }
-}
-/** Alias — same as clearTables, reads better in beforeEach. */
-export async function resetTestTables(db, tables) {
-    await clearTables(db, tables);
-}

package/dist/testing/expect-error.d.ts

@@ -1,2 +0,0 @@
-import type { WriteErrorInfo } from "../errors/index.js";
-export declare function expectErrorIncludes(err: WriteErrorInfo | string | null | undefined, substring: string): void;

package/dist/testing/expect-error.js

@@ -1,22 +0,0 @@
-import { expect } from "bun:test";
-// Vitest's toContain doesn't operate on plain objects, so after the move from
-// string errors to typed WriteErrorInfo the legacy `expect(error).toContain(x)`
-// assertions break. This helper concatenates code, message, and serialized
-// details so existing substring checks against short reason strings keep
-// working without each call site needing to know the new shape.
-//
-// Accepts `string | null` too, so call sites that still get raw strings
-// (e.g. helpers that haven't moved to typed errors yet) keep working.
-export function expectErrorIncludes(err, substring) {
-    let haystack;
-    if (err === null || err === undefined) {
-        haystack = String(err);
-    }
-    else if (typeof err === "string") {
-        haystack = err;
-    }
-    else {
-        haystack = `${err.code} ${err.message} ${JSON.stringify(err.details ?? {})}`;
-    }
-    expect(haystack).toContain(substring);
-}

package/dist/testing/file-provider-contract.d.ts

@@ -1,2 +0,0 @@
-import type { FileStorageProvider } from "../files/types.js";
-export declare function describeFileProviderContract(name: string, factory: () => FileStorageProvider | Promise<FileStorageProvider>): void;

package/dist/testing/file-provider-contract.js

@@ -1,102 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-const bytes = (s) => new TextEncoder().encode(s);
-const decode = (u) => new TextDecoder().decode(u);
-async function* fromChunks(chunks) {
-    for (const c of chunks)
-        yield c;
-}
-// Mirrors describeKmsAdapterContract (crypto/__tests__/kms-adapter-contract.ts):
-// pins the FileStorageProvider contract against whatever implementation the
-// factory returns. Provider-specific behavior (error messages, buffer
-// copies, multipart details) stays in each provider's dedicated tests.
-export function describeFileProviderContract(name, factory) {
-    describe(`${name} — FileStorageProvider contract`, () => {
-        let provider;
-        // Self-cleaning: every key this contract creates gets deleted in
-        // afterEach, so a persistent backend (local `kumiko dev` against a
-        // long-lived Minio, as opposed to CI's ephemeral one) doesn't leak
-        // `contract/<uuid>` objects into the next developer's session. delete()
-        // on a key that was never actually written is covered by the
-        // "no-op on a missing key" contract test above, so tracking generated
-        // keys unconditionally (even ones a test never got around to writing)
-        // is safe.
-        let writtenKeys;
-        function trackedKey(ext) {
-            const key = `contract/${crypto.randomUUID()}.${ext}`;
-            writtenKeys.push(key);
-            return key;
-        }
-        beforeEach(async () => {
-            provider = await factory();
-            writtenKeys = [];
-        });
-        afterEach(async () => {
-            for (const key of writtenKeys)
-                await provider.delete(key);
-        });
-        test("write + read roundtrip preserves bytes", async () => {
-            const key = trackedKey("bin");
-            await provider.write(key, bytes("hello contract"));
-            expect(decode(await provider.read(key))).toBe("hello contract");
-        });
-        test("write on an existing key overwrites it (last-write-wins)", async () => {
-            const key = trackedKey("bin");
-            await provider.write(key, bytes("first"));
-            await provider.write(key, bytes("second"));
-            expect(decode(await provider.read(key))).toBe("second");
-        });
-        test("read throws for a missing key", async () => {
-            await expect(provider.read(`contract/missing-${crypto.randomUUID()}`)).rejects.toThrow();
-        });
-        test("exists reflects write + delete", async () => {
-            const key = trackedKey("txt");
-            expect(await provider.exists(key)).toBe(false);
-            await provider.write(key, bytes("x"));
-            expect(await provider.exists(key)).toBe(true);
-            await provider.delete(key);
-            expect(await provider.exists(key)).toBe(false);
-        });
-        test("delete on a missing key is a no-op", async () => {
-            await expect(provider.delete(`contract/never-existed-${crypto.randomUUID()}`)).resolves.toBeUndefined();
-        });
-        test("writeStream + readStream roundtrip preserves bytes", async () => {
-            const key = trackedKey("stream");
-            await provider.writeStream(key, fromChunks([bytes("foo"), bytes("bar")]));
-            let out = "";
-            for await (const chunk of provider.readStream(key))
-                out += decode(chunk);
-            expect(out).toBe("foobar");
-        });
-        test("readStream on a missing key throws on the first chunk pull", async () => {
-            const it = provider
-                .readStream(`contract/missing-${crypto.randomUUID()}`)[Symbol.asyncIterator]();
-            await expect(it.next()).rejects.toThrow();
-        });
-        test("list returns only keys under the given prefix", async () => {
-            const group = `contract/list-${crypto.randomUUID()}`;
-            const keyA = `${group}/a.txt`;
-            const keyB = `${group}/b.txt`;
-            const outsideKey = `contract/list-${crypto.randomUUID()}/c.txt`;
-            writtenKeys.push(keyA, keyB, outsideKey);
-            await provider.write(keyA, bytes("a"));
-            await provider.write(keyB, bytes("b"));
-            await provider.write(outsideKey, bytes("c"));
-            const listed = await provider.list(`${group}/`);
-            expect(new Set(listed)).toEqual(new Set([keyA, keyB]));
-        });
-        test("list on a prefix with no matches returns an empty array", async () => {
-            const listed = await provider.list(`contract/list-missing-${crypto.randomUUID()}/`);
-            expect(listed).toEqual([]);
-        });
-        test("getSignedUrl, when implemented, returns a URL string", async () => {
-            // skip: getSignedUrl is optional on the contract — feature-detected
-            if (!provider.getSignedUrl)
-                return;
-            const key = trackedKey("txt");
-            await provider.write(key, bytes("signed"));
-            const url = await provider.getSignedUrl(key, 60);
-            expect(typeof url).toBe("string");
-            expect(url.length).toBeGreaterThan(0);
-        });
-    });
-}

package/dist/testing/http-cookies.d.ts

@@ -1,7 +0,0 @@
-export type ParsedSetCookie = {
-    readonly value: string;
-    readonly raw: string;
-};
-export declare function getSetCookies(res: Response): Map<string, ParsedSetCookie>;
-export declare function getSetCookieValue(res: Response, name: string): string | undefined;
-export declare function getSetCookieRaw(res: Response, name: string): string | undefined;

package/dist/testing/http-cookies.js

@@ -1,47 +0,0 @@
-// Shared Set-Cookie parser for tests. Cookie-auth tests (auth-middleware,
-// csrf-middleware, auth-routes, auth.integration) all need the same
-// primitive: "given a Response, give me the cookies the server tried to
-// set". Before this helper each test file rolled its own — three near-
-// duplicates that drift the moment one adds Domain/Partitioned/Priority
-// parsing the others don't.
-//
-// The helper returns both the parsed value AND the raw string so callers
-// can assert on attributes like SameSite, HttpOnly, Max-Age without a
-// second parse step.
-// Pull every Set-Cookie the response carries. Prefers the standard
-// `Headers.getSetCookie()` (Node 20+, Bun, modern undici/whatwg-fetch);
-// falls back to the single-header-value for environments that don't
-// expose it. The fallback path only sees the FIRST cookie if multiple
-// were set in one response — a limitation of RFC 7230 headers — which
-// is acceptable here because tests that set multiple cookies run on a
-// runtime that supports getSetCookie.
-export function getSetCookies(res) {
-    const getter = res.headers.getSetCookie; // @cast-boundary engine-bridge
-    const raws = getter ? getter.call(res.headers) : [res.headers.get("set-cookie") ?? ""];
-    const out = new Map();
-    for (const raw of raws) {
-        if (!raw)
-            continue;
-        const first = raw.split(";")[0];
-        if (!first)
-            continue;
-        const eq = first.indexOf("=");
-        if (eq === -1)
-            continue;
-        const name = first.slice(0, eq).trim();
-        const value = first.slice(eq + 1).trim();
-        out.set(name, { value, raw });
-    }
-    return out;
-}
-// Convenience for the common case: "give me the value of cookie X".
-// Returns undefined when the cookie isn't set — no throw, so negative
-// assertions read cleanly (`expect(cookies.get("foo")).toBeUndefined()`).
-export function getSetCookieValue(res, name) {
-    return getSetCookies(res).get(name)?.value;
-}
-// Raw Set-Cookie header for attribute assertions
-// (`expect(raw).toMatch(/SameSite=Lax/)`). Returns undefined when missing.
-export function getSetCookieRaw(res, name) {
-    return getSetCookies(res).get(name)?.raw;
-}

package/dist/testing/late-bound.d.ts

@@ -1,9 +0,0 @@
-export type LateBoundHolder<T> = {
-    /** Store the concrete value. Must be called before any trampoline fires. */
-    set(value: T): void;
-    /** Fetch the concrete value or throw if set() hasn't been called yet. */
-    get(): T;
-    /** True after set() has been called. */
-    isReady(): boolean;
-};
-export declare function createLateBoundHolder<T>(label?: string): LateBoundHolder<T>;

package/dist/testing/late-bound.js

@@ -1,31 +0,0 @@
-// Late-bound reference for values that only exist AFTER setupTestStack
-// returns — typically the session-callbacks, which close over stack.db.
-//
-// Without this helper, integration tests repeat the same trampoline
-// pattern (let real; async wrapper; null-check on each call). The holder
-// inverts the dependency: the test passes the trampolines into setupTestStack
-// first, then injects the concrete impl once db is available.
-//
-// Production wiring (runDevApp / runProdApp) doesn't reuse this — those
-// wrappers inline an equivalent let-closure-throw pattern to avoid the
-// runtime-isolation cross from dev → test packages. Same idea, different
-// file.
-export function createLateBoundHolder(label = "value") {
-    let value;
-    let isSet = false;
-    return {
-        set(v) {
-            value = v;
-            isSet = true;
-        },
-        get() {
-            if (!isSet) {
-                throw new Error(`late-bound ${label} accessed before set() was called`);
-            }
-            return value;
-        },
-        isReady() {
-            return isSet;
-        },
-    };
-}

package/dist/testing/manual-clock.d.ts

@@ -1,14 +0,0 @@
-import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
-type ClockStep = {
-    readonly hours?: number;
-    readonly minutes?: number;
-    readonly seconds?: number;
-    readonly milliseconds?: number;
-};
-export type ManualClock = Clock & {
-    set(instant: Temporal.Instant): void;
-    advance(step: ClockStep): void;
-};
-export declare function createManualClock(start: Temporal.Instant): ManualClock;
-export {};

package/dist/testing/manual-clock.js

@@ -1,12 +0,0 @@
-export function createManualClock(start) {
-    let current = start;
-    return {
-        now: () => current,
-        set: (instant) => {
-            current = instant;
-        },
-        advance: (step) => {
-            current = current.add(step);
-        },
-    };
-}

package/dist/testing/multipart-helper.d.ts

@@ -1,22 +0,0 @@
-/**
- * Serializes a FormData instance to multipart/form-data bytes.
- *
- * Returns the encoded body and the Content-Type header value (including the
- * generated boundary). Pass both directly to app.request or fetch.
- */
-export declare function buildMultipartBody(fd: FormData): Promise<{
-    body: BodyInit;
-    contentType: string;
-}>;
-/**
- * Patches File[Symbol.hasInstance] so that cross-realm Blob objects returned
- * by Hono's parseBody() pass `instanceof File` checks in bun:test.
- *
- * In bun:test the multipart parser runs in a different JS realm than the test
- * globals, so the Blob/File constructors differ. The patch replaces the
- * prototype-chain check with a duck-type check: an object with string `.name`,
- * number `.size`, and function `.arrayBuffer` is treated as a File.
- *
- * Safe to call multiple times (idempotent via the `_patched` marker).
- */
-export declare function patchFileInstanceofForBunTest(): void;

package/dist/testing/multipart-helper.js

@@ -1,77 +0,0 @@
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-// Workarounds for Bun v1.3.x bun:test limitations with multipart/form-data.
-//
-// Two bugs combine to break file upload tests in bun:test:
-//
-// 1. Content-Type omission: both app.request({body: formData}) and
-//    fetch(url, {body: formData}) stringify FormData via .toString() instead
-//    of serializing it as multipart, so no Content-Type header is set.
-//    Fix: serialize FormData manually via buildMultipartBody().
-//
-// 2. Cross-realm instanceof: Hono's multipart parser creates Blob objects from
-//    a different JS realm than the test globals. In bun:test this means
-//    `parsedValue instanceof File` is always false even when the value has all
-//    File properties. Fix: patchFilInstanceofForBunTest().
-//
-// Both fixes are test-only — production code and real HTTP clients are unaffected.
-/**
- * Serializes a FormData instance to multipart/form-data bytes.
- *
- * Returns the encoded body and the Content-Type header value (including the
- * generated boundary). Pass both directly to app.request or fetch.
- */
-export async function buildMultipartBody(fd) {
-    const boundary = `KumikoBnd${Date.now()}${Math.random().toString(36).slice(2, 8)}`;
-    const enc = new TextEncoder();
-    const parts = [];
-    for (const [name, value] of fd.entries()) {
-        const v = value;
-        if (typeof v === "object" && v !== null && typeof v.arrayBuffer === "function") {
-            parts.push(enc.encode(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"; filename="${v.name ?? "blob"}"\r\nContent-Type: ${v.type || "application/octet-stream"}\r\n\r\n`));
-            parts.push(new Uint8Array(await v.arrayBuffer()));
-            parts.push(enc.encode("\r\n"));
-        }
-        else {
-            parts.push(enc.encode(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${String(value)}\r\n`));
-        }
-    }
-    parts.push(enc.encode(`--${boundary}--\r\n`));
-    const total = parts.reduce((s, p) => s + p.length, 0);
-    const buf = new Uint8Array(total);
-    let off = 0;
-    for (const p of parts) {
-        buf.set(p, off);
-        off += p.length;
-    }
-    return {
-        body: buf,
-        contentType: `multipart/form-data; boundary=${boundary}`,
-    };
-}
-/**
- * Patches File[Symbol.hasInstance] so that cross-realm Blob objects returned
- * by Hono's parseBody() pass `instanceof File` checks in bun:test.
- *
- * In bun:test the multipart parser runs in a different JS realm than the test
- * globals, so the Blob/File constructors differ. The patch replaces the
- * prototype-chain check with a duck-type check: an object with string `.name`,
- * number `.size`, and function `.arrayBuffer` is treated as a File.
- *
- * Safe to call multiple times (idempotent via the `_patched` marker).
- */
-export function patchFileInstanceofForBunTest() {
-    // skip: idempotent re-patch — already installed, nothing to do
-    if (File._kumikoPatched)
-        return;
-    Object.defineProperty(File, Symbol.hasInstance, {
-        value(instance) {
-            if (!isPlainObject(instance))
-                return false;
-            return (typeof instance["name"] === "string" &&
-                typeof instance["size"] === "number" &&
-                typeof instance["arrayBuffer"] === "function");
-        },
-        configurable: true,
-    });
-    File._kumikoPatched = true;
-}

package/dist/testing/mutable-master-key-provider.d.ts

@@ -1,7 +0,0 @@
-import { type EnvelopeCipher, type EnvelopeCipherOptions, type MasterKeyProvider } from "../secrets/index.js";
-export type MutableMasterKeyProvider = MasterKeyProvider & {
-    replace(next: MasterKeyProvider): void;
-};
-export declare function createMutableMasterKeyProvider(initial: MasterKeyProvider): MutableMasterKeyProvider;
-export declare function createTestMasterKeyProvider(keyBase64?: string): MasterKeyProvider;
-export declare function createTestEnvelopeCipher(keyBase64?: string, opts?: EnvelopeCipherOptions): EnvelopeCipher;

package/dist/testing/mutable-master-key-provider.js

@@ -1,35 +0,0 @@
-// Test utility: a MasterKeyProvider wrapper whose backing provider can be
-// swapped mid-test. Use-case: simulating KEK-rotation ("ops flipped
-// CURRENT=2") without rebuilding the whole stack + SecretsContext.
-//
-// Prod analogue: ENV swap + process restart. This helper is purely for
-// tests that want to exercise pre- and post-rotation behaviour in a
-// single suite.
-import { randomBytes } from "node:crypto";
-import { createEnvelopeCipher, createEnvMasterKeyProvider, } from "../secrets/index.js";
-export function createMutableMasterKeyProvider(initial) {
-    let current = initial;
-    return {
-        wrapDek: (dek, scope) => current.wrapDek(dek, scope),
-        unwrapDek: (e, v, scope) => current.unwrapDek(e, v, scope),
-        currentVersion: () => current.currentVersion(),
-        isAvailable: () => current.isAvailable(),
-        replace: (next) => {
-            current = next;
-        },
-    };
-}
-// Single-version env provider for tests — the shape every integration test
-// needs to exercise encrypted config keys / entity fields without caring
-// about keyring mechanics. Pass a fixed key to share it across stacks.
-export function createTestMasterKeyProvider(keyBase64) {
-    return createEnvMasterKeyProvider({
-        env: {
-            KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION: "1",
-            KUMIKO_SECRETS_MASTER_KEY_V1: keyBase64 ?? randomBytes(32).toString("base64"),
-        },
-    });
-}
-export function createTestEnvelopeCipher(keyBase64, opts) {
-    return createEnvelopeCipher(createTestMasterKeyProvider(keyBase64), opts ?? {});
-}

package/dist/testing/observability-recorder.d.ts

@@ -1,9 +0,0 @@
-import { type MetricEvent, type ObservabilityOptions, type ObservabilityProvider, type RecordedSpan } from "../observability/index.js";
-export type RecordingProvider = ObservabilityProvider & {
-    readonly spans: readonly RecordedSpan[];
-    readonly metricEvents: readonly MetricEvent[];
-    spansByName(name: string): readonly RecordedSpan[];
-    spansByTraceId(traceId: string): readonly RecordedSpan[];
-    reset(): void;
-};
-export declare function createRecordingProvider(options?: ObservabilityOptions): RecordingProvider;

package/dist/testing/observability-recorder.js

@@ -1,29 +0,0 @@
-import { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, RecordingMeter, RecordingTracer, } from "../observability/index.js";
-export function createRecordingProvider(options = {}) {
-    const sensitiveConfig = mergeSensitiveConfig(options.sensitiveFilter ?? DEFAULT_SENSITIVE_CONFIG);
-    const spans = [];
-    const metricEvents = [];
-    const tracer = new RecordingTracer({
-        sensitiveConfig,
-        onSpanEnd: (s) => spans.push(s),
-    });
-    const meter = new RecordingMeter((e) => metricEvents.push(e));
-    return {
-        name: "recording",
-        tracer,
-        meter,
-        spans,
-        metricEvents,
-        spansByName(name) {
-            return spans.filter((s) => s.name === name);
-        },
-        spansByTraceId(traceId) {
-            return spans.filter((s) => s.traceId === traceId);
-        },
-        reset() {
-            spans.length = 0;
-            metricEvents.length = 0;
-        },
-        async shutdown() { },
-    };
-}

package/dist/testing/seed.d.ts

@@ -1,9 +0,0 @@
-import { type AnyDb, type WhereObject } from "../bun-db/query.js";
-import type { EntityTableMeta } from "../db/entity-table-meta.js";
-import type { EntityTable } from "../db/table-builder.js";
-type SeedTable = EntityTable | EntityTableMeta;
-export declare function seedRow<TRow = unknown>(db: AnyDb, table: SeedTable, values: Record<string, unknown>): Promise<TRow | undefined>;
-export declare function seedRows<TRow = unknown>(db: AnyDb, table: SeedTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
-export declare function updateRows<TRow = unknown>(db: AnyDb, table: SeedTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
-export declare function deleteRows(db: AnyDb, table: SeedTable, where: WhereObject): Promise<void>;
-export {};

package/dist/testing/seed.js

@@ -1,21 +0,0 @@
-// Test-only ES-bypass: seed / mutate a managed projection directly, skipping
-// the event log. Production code CANNOT do this — the write helpers reject a
-// branded EntityTable at compile time (#742). Tests seed read-model state to
-// arrange a scenario without driving the full event path; a projection rebuild
-// is not part of the test lifecycle, so eventless writes are safe here. The
-// `as EntityTableMeta` strips the executor-only brand at this single sanctioned
-// seam — the signatures mirror the query helpers so a call-site migration is a
-// plain identifier rename.
-import { deleteMany, insertMany, insertOne, updateMany, } from "../bun-db/query.js";
-export function seedRow(db, table, values) {
-    return insertOne(db, table, values);
-}
-export function seedRows(db, table, rows) {
-    return insertMany(db, table, rows);
-}
-export function updateRows(db, table, set, where) {
-    return updateMany(db, table, set, where);
-}
-export function deleteRows(db, table, where) {
-    return deleteMany(db, table, where);
-}