@cosmicdrift/kumiko-framework 0.215.5 → 0.215.7

package/src/stack/__tests__/request-helper.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import { Hono } from "hono";
+import type { JwtHelper } from "../../api/jwt";
+import type { SessionUser } from "../../engine/types";
+import { createRequestHelper } from "../request-helper";
+
+const user: SessionUser = {
+  id: "u1",
+  tenantId: "t1",
+  roles: ["member"],
+};
+
+function jwtStub() {
+  const signed: unknown[] = [];
+  const jwt = {
+    sign: async (payload: unknown) => {
+      signed.push(payload);
+      return `j.${Buffer.from(JSON.stringify(payload)).toString("base64url")}`;
+    },
+  } as unknown as JwtHelper;
+  return { jwt, signed };
+}
+
+function appRecording(
+  handler: (c: {
+    req: { json: () => Promise<unknown>; header: (n: string) => string | undefined };
+  }) => Response | Promise<Response>,
+) {
+  const calls: { path: string; auth?: string; extraHeaders: Record<string, string | undefined> }[] =
+    [];
+  const app = new Hono();
+  for (const path of ["/api/write", "/api/query", "/api/command", "/api/batch"]) {
+    app.post(path, async (c) => {
+      calls.push({
+        path,
+        auth: c.req.header("authorization"),
+        extraHeaders: { "x-trace": c.req.header("x-trace") },
+      });
+      return handler({ req: { json: () => c.req.json(), header: (n) => c.req.header(n) } });
+    });
+  }
+  return { app, calls };
+}
+
+describe("createRequestHelper", () => {
+  test("writeOk posts JSON to /api/write and resolves the success data", async () => {
+    const { app, calls } = appRecording(() =>
+      Response.json({ isSuccess: true, data: { written: true } }),
+    );
+    const { jwt } = jwtStub();
+    const http = createRequestHelper(app, jwt);
+
+    const data = await http.writeOk("todo.create", { title: "x" }, user);
+    expect(data).toEqual({ written: true });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.path).toBe("/api/write");
+    expect(calls[0]!.auth).toMatch(/^Bearer j\./);
+  });
+
+  test("sessionCreator is consulted once per user and its sid reaches the jwt", async () => {
+    let creations = 0;
+    const { app } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const { jwt, signed } = jwtStub();
+    const http = createRequestHelper(app, jwt, {
+      sessionCreator: async () => {
+        creations += 1;
+        return "sid-42";
+      },
+    });
+
+    await http.writeOk("a.b", {}, user);
+    await http.queryOk("c.d", {}, user);
+    expect(creations).toBe(1);
+    expect(signed).toHaveLength(2);
+    expect(signed[0]).toMatchObject({ id: "u1", tenantId: "t1", sid: "sid-42" });
+  });
+
+  test("user-provided sid skips the sessionCreator entirely", async () => {
+    const { app } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const { jwt, signed } = jwtStub();
+    let creations = 0;
+    const http = createRequestHelper(app, jwt, {
+      sessionCreator: async () => {
+        creations += 1;
+        throw new Error("must not be called");
+      },
+    });
+    await http.writeOk("a.b", {}, { ...user, sid: "pre-set" });
+    expect(creations).toBe(0);
+    expect(signed[0]).toMatchObject({ sid: "pre-set" });
+  });
+
+  test("writeOk surfaces the formatted failure including cause details", async () => {
+    const { app } = appRecording(() =>
+      Response.json(
+        {
+          error: {
+            code: "internal_error",
+            details: { causeName: "DbError", causeMessage: "connection lost" },
+          },
+        },
+        { status: 500 },
+      ),
+    );
+    const http = createRequestHelper(app, jwtStub().jwt);
+    expect(http.writeOk("todo.create", {}, user)).rejects.toThrow(
+      'Expected write "todo.create" to succeed but got error: internal_error (DbError: connection lost)',
+    );
+  });
+
+  test("queryErr returns the wire error plus http status, but throws on success", async () => {
+    const failing = appRecording(() =>
+      Response.json({ error: { code: "validation_failed", message: "nope" } }, { status: 400 }),
+    );
+    const http = createRequestHelper(failing.app, jwtStub().jwt);
+    const err = await http.queryErr("q.type", {}, user);
+    expect(err.code).toBe("validation_failed");
+    expect(err.httpStatus).toBe(400);
+
+    const succeeding = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const http2 = createRequestHelper(succeeding.app, jwtStub().jwt);
+    expect(http2.queryErr("q.type", {}, user)).rejects.toThrow(
+      'Expected query "q.type" to fail but it succeeded',
+    );
+  });
+
+  test("batch posts the commands array unchanged to /api/batch", async () => {
+    const bodies: unknown[] = [];
+    const app = new Hono();
+    app.post("/api/batch", async (c) => {
+      bodies.push(await c.req.json());
+      return Response.json({ isSuccess: true, data: [] });
+    });
+    const http = createRequestHelper(app, jwtStub().jwt);
+    await http.batch(
+      [
+        { type: "a", payload: { x: 1 } },
+        { type: "b", payload: {} },
+      ],
+      user,
+      "req-9",
+    );
+    expect(bodies[0]).toEqual({
+      commands: [
+        { type: "a", payload: { x: 1 } },
+        { type: "b", payload: {} },
+      ],
+      requestId: "req-9",
+    });
+  });
+
+  test("extra headers are forwarded alongside the auth header", async () => {
+    const { app, calls } = appRecording(() => Response.json({ isSuccess: true, data: {} }));
+    const http = createRequestHelper(app, jwtStub().jwt);
+    await http.writeWithHeaders("a.b", {}, user, { "x-trace": "tr-1" });
+    expect(calls[0]!.extraHeaders["x-trace"]).toBe("tr-1");
+    expect(calls[0]!.auth).toMatch(/^Bearer /);
+  });
+});

package/src/testing/__tests__/multipart-helper.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { buildMultipartBody } from "../multipart-helper";
+
+describe("buildMultipartBody", () => {
+  test("serializes text fields so a Response can parse them back", async () => {
+    const fd = new FormData();
+    fd.set("title", "hello world");
+    fd.set("count", "42");
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    expect(contentType).toMatch(/^multipart\/form-data; boundary=kumikoBnd/i);
+
+    const parsed = await new Response(body, {
+      headers: { "content-type": contentType },
+    }).formData();
+    expect(parsed.get("title")).toBe("hello world");
+    expect(parsed.get("count")).toBe("42");
+  });
+
+  test("carries file name and bytes through", async () => {
+    const fd = new FormData();
+    fd.set("doc", new File(["PDF-bytes"], "report.pdf", { type: "application/pdf" }));
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    const text = typeof body === "string" ? body : await new Response(body).text();
+
+    expect(contentType).toMatch(/^multipart\/form-data; boundary=kumikoBnd/i);
+    expect(text).toContain('filename="report.pdf"');
+    expect(text).toContain("PDF-bytes");
+    expect(text.endsWith(`--${contentType.split("boundary=")[1]}--\r\n`)).toBe(true);
+  });
+
+  test("mixed fields and files round-trip together", async () => {
+    const fd = new FormData();
+    fd.set("note", "attached");
+    fd.set("file", new File(["abc"], "a.txt"));
+
+    const { body, contentType } = await buildMultipartBody(fd);
+    const parsed = await new Response(body, {
+      headers: { "content-type": contentType },
+    }).formData();
+    expect(parsed.get("note")).toBe("attached");
+    // Structural check: happy-dom and bun can expose different File realms,
+    // so instanceof would fail depending on file order in the same process.
+    const file = parsed.get("file") as { name?: string; size?: number } | null;
+    expect(file?.name).toBe("a.txt");
+    expect(file?.size).toBe(3);
+  });
+});

package/src/db/__tests__/sql-inventory.test.ts

@@ -1,81 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import {
-  formatReport,
-  isRawSqlAllowed,
-  joinPath,
-  scanRepo,
-  toBaselineJson,
-} from "../sql-inventory";
-
-const cleanups: string[] = [];
-
-afterEach(async () => {
-  for (const dir of cleanups) {
-    await Bun.spawn(["rm", "-rf", dir]).exited;
-  }
-  cleanups.length = 0;
-});
-
-async function tempRepo(files: Record<string, string>): Promise<string> {
-  const root = joinPath(import.meta.dir, `.tmp-sql-inv-${crypto.randomUUID()}`);
-  cleanups.push(root);
-  await Promise.all(
-    Object.entries(files).map(([rel, content]) => Bun.write(joinPath(root, rel), content)),
-  );
-  return root;
-}
-
-describe("sql-inventory", () => {
-  test("isRawSqlAllowed permits db/queries and bun-db/query", () => {
-    expect(isRawSqlAllowed("/repo/packages/framework/src/db/queries/event-store.ts")).toBe(true);
-    expect(isRawSqlAllowed("/repo/packages/framework/src/bun-db/query.ts")).toBe(true);
-    expect(
-      isRawSqlAllowed("/repo/packages/bundled-features/src/sessions/db/queries/cleanup.ts"),
-    ).toBe(true);
-    expect(isRawSqlAllowed("/repo/samples/apps/marketing-demo/src/db/queries/seed-counts.ts")).toBe(
-      true,
-    );
-    expect(isRawSqlAllowed("/repo/bin/commands/schema.ts")).toBe(true);
-    expect(isRawSqlAllowed("/repo/scripts/codemod-bun-db-swap.ts")).toBe(true);
-    expect(
-      isRawSqlAllowed("/repo/packages/bundled-features/src/sessions/handlers/cleanup.job.ts"),
-    ).toBe(false);
-  });
-
-  test("scanRepo classifies production vs test hits", async () => {
-    const root = await tempRepo({
-      "packages/framework/src/db/queries/demo.ts": `export async function x(db: unknown) {
-  return asRawClient(db).unsafe("SELECT 1");
-}`,
-      "packages/framework/src/handlers/bad.ts": `export async function y(db: unknown) {
-  return asRawClient(db).unsafe("DELETE FROM read_users");
-}`,
-      "packages/framework/src/__tests__/ok.integration.ts": `await asRawClient(db).unsafe("DELETE FROM read_users");`,
-    });
-
-    const report = await scanRepo(root);
-    expect(report.summary.byBucket.allowed).toBeGreaterThanOrEqual(1);
-    expect(report.summary.byBucket.tests).toBeGreaterThanOrEqual(1);
-    expect(report.summary.byBucket.disallowed).toBeGreaterThanOrEqual(1);
-    expect(formatReport(report)).toContain("sql inventory");
-  });
-
-  test("toBaselineJson normalizes machine-specific root + scannedAt, keeps the rest", async () => {
-    const root = await tempRepo({
-      "packages/framework/src/handlers/bad.ts": `export async function y(db: unknown) {
-  return asRawClient(db).unsafe("DELETE FROM read_users");
-}`,
-    });
-
-    const report = await scanRepo(root);
-    expect(report.root).toBe(root);
-    expect(report.scannedAt).not.toBe("");
-
-    const parsed = JSON.parse(toBaselineJson(report));
-    expect(parsed.root).toBe(".");
-    expect(parsed.scannedAt).toBe("");
-    expect(parsed.root).not.toContain(root);
-    expect(parsed.summary.disallowed).toBe(report.summary.disallowed);
-    expect(parsed.hits).toHaveLength(report.hits.length);
-  });
-});

package/src/db/sql-inventory.ts

@@ -1,232 +0,0 @@
-/**
- * Raw-SQL inventory — shared allowlist for `kumiko sql-inventory` and
- * `guard-raw-sql` (Phase 5). Scans TypeScript sources for escape-hatch patterns.
- *
- * Bun-only I/O: Bun.Glob + Bun.file (no node:fs, no node:path).
- */
-
-/** POSIX path join without Node path module. */
-export function joinPath(base: string, ...segments: string[]): string {
-  return [base, ...segments]
-    .join("/")
-    .replace(/\/+/g, "/")
-    .replace(/\/\.\//g, "/");
-}
-
-export type SqlInventoryKind = "unsafe" | "asRawClient" | "delete_from" | "execute";
-
-export type SqlInventoryHit = {
-  readonly file: string;
-  readonly line: number;
-  readonly kind: SqlInventoryKind;
-  readonly allowed: boolean;
-  readonly snippet: string;
-};
-
-export type SqlInventoryReport = {
-  readonly scannedAt: string;
-  readonly root: string;
-  readonly hits: readonly SqlInventoryHit[];
-  readonly summary: {
-    readonly total: number;
-    readonly disallowed: number;
-    readonly byKind: Readonly<Record<SqlInventoryKind, number>>;
-    readonly byBucket: {
-      readonly allowed: number;
-      readonly tests: number;
-      readonly disallowed: number;
-    };
-  };
-};
-
-/** Paths where `.unsafe()` / `asRawClient()` are permitted (Phase 5 guard). */
-export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
-  /\/packages\/framework\/src\/db\/queries\//,
-  /\/packages\/framework\/src\/db\/migrate-runner\.ts$/,
-  /\/packages\/framework\/src\/db\/schema-inspection\.ts$/,
-  /\/packages\/framework\/src\/db\/render-ddl\.ts$/,
-  /\/packages\/framework\/src\/db\/sql-inventory\.ts$/,
-  /\/packages\/framework\/src\/bun-db\/query\.ts$/,
-  /\/packages\/framework\/src\/testing\//,
-  // ponytail: explicit enumeration — blanket regex auto-allowed any new .unsafe()
-  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
-  /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
-  /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
-  /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
-  /\/bundled-features\/src\/custom-fields\/db\/queries\/quota\.ts$/,
-  /\/bundled-features\/src\/custom-fields\/db\/queries\/retention\.ts$/,
-  /\/bundled-features\/src\/custom-fields\/db\/queries\/user-data-rights\.ts$/,
-  /\/bundled-features\/src\/delivery\/db\/queries\/preferences\.ts$/,
-  /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
-  /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
-  /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
-  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
-  /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
-  /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
-  /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
-  /\/packages\/framework\/src\/engine\/steps\/unsafe-projection-/,
-  /\/samples\/(apps|recipes)\/[^/]+\/src\/db\/queries\//,
-  /\/bin\/commands\//,
-  /\/scripts\/codemod-/,
-  /\/__tests__\//,
-  /\/scripts\/sql-inventory\.ts$/,
-  /\/bin\/_lib\//,
-];
-
-const SCAN_DIRS = ["packages", "samples", "scripts", "bin"] as const;
-
-const SKIP_PATH_PARTS = ["/node_modules/", "/dist/", "/.kumiko/"] as const;
-
-const PATTERNS: ReadonlyArray<{ readonly kind: SqlInventoryKind; readonly re: RegExp }> = [
-  { kind: "unsafe", re: /\.unsafe\s*\(/ },
-  { kind: "asRawClient", re: /asRawClient\s*\(/ },
-  { kind: "delete_from", re: /DELETE\s+FROM/i },
-  { kind: "execute", re: /\.execute\s*\(/ },
-];
-
-const TS_GLOB = new Bun.Glob("**/*.{ts,tsx}");
-
-function normalizePathForMatch(filePath: string): string {
-  return filePath.startsWith("/") ? filePath : `/${filePath}`;
-}
-
-export function isRawSqlAllowed(filePath: string): boolean {
-  const normalized = normalizePathForMatch(filePath);
-  return RAW_SQL_ALLOWLIST.some((re) => re.test(normalized));
-}
-
-function isTestPath(filePath: string): boolean {
-  return /\/__tests__\//.test(normalizePathForMatch(filePath));
-}
-
-function bucketFor(hit: SqlInventoryHit): "allowed" | "tests" | "disallowed" {
-  if (isTestPath(hit.file)) return "tests";
-  if (hit.allowed) return "allowed";
-  return "disallowed";
-}
-
-function shouldSkipRelativePath(rel: string): boolean {
-  return SKIP_PATH_PARTS.some((part) => rel.includes(part));
-}
-
-function directoryExists(path: string): boolean {
-  return Bun.spawnSync(["test", "-d", path]).exitCode === 0;
-}
-
-async function collectTsFiles(repoRoot: string): Promise<string[]> {
-  const out: string[] = [];
-  for (const sub of SCAN_DIRS) {
-    const cwd = joinPath(repoRoot, sub);
-    if (!directoryExists(cwd)) continue;
-    for await (const rel of TS_GLOB.scan({ cwd, onlyFiles: true })) {
-      const normalized = rel.replace(/\0/g, "");
-      if (!normalized || shouldSkipRelativePath(normalized)) continue;
-      out.push(joinPath(sub, normalized));
-    }
-  }
-  return out;
-}
-
-function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): void {
-  const lines = text.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const trimmed = line.trim();
-    if (
-      trimmed.startsWith("//") ||
-      trimmed.startsWith("*") ||
-      trimmed.startsWith("/**") ||
-      trimmed.startsWith("/*")
-    ) {
-      continue;
-    }
-    for (const { kind, re } of PATTERNS) {
-      if (!re.test(line)) continue;
-      hits.push({
-        file: relPath,
-        line: i + 1,
-        kind,
-        allowed: isRawSqlAllowed(relPath),
-        snippet: trimmed.slice(0, 120),
-      });
-    }
-  }
-}
-
-export async function scanRepo(repoRoot: string): Promise<SqlInventoryReport> {
-  const relFiles = await collectTsFiles(repoRoot);
-  const hits: SqlInventoryHit[] = [];
-
-  for (const rel of relFiles) {
-    const abs = joinPath(repoRoot, rel);
-    const text = await Bun.file(abs).text();
-    scanFileText(rel, text, hits);
-  }
-
-  const byKind: Record<SqlInventoryKind, number> = {
-    unsafe: 0,
-    asRawClient: 0,
-    delete_from: 0,
-    execute: 0,
-  };
-  let disallowed = 0;
-  const byBucket = { allowed: 0, tests: 0, disallowed: 0 };
-  for (const h of hits) {
-    byKind[h.kind]++;
-    const b = bucketFor(h);
-    byBucket[b]++;
-    if (b === "disallowed") disallowed++;
-  }
-
-  return {
-    scannedAt: new Date().toISOString(),
-    root: repoRoot,
-    hits,
-    summary: {
-      total: hits.length,
-      disallowed,
-      byKind,
-      byBucket,
-    },
-  };
-}
-
-// Serialize for the checked-in baseline. `root` (absolute scan path) and
-// `scannedAt` (run timestamp) are machine-/run-specific noise that churned the
-// baseline on every regen; --compare-baseline reads only summary.disallowed.
-// Pin them to stable placeholders so the committed file is reproducible.
-export function toBaselineJson(report: SqlInventoryReport): string {
-  const stable: SqlInventoryReport = { ...report, root: ".", scannedAt: "" };
-  return `${JSON.stringify(stable, null, 2)}\n`;
-}
-
-export function formatReport(report: SqlInventoryReport): string {
-  const lines: string[] = [
-    "--- sql inventory ---",
-    `  scanned:   ${report.scannedAt}`,
-    `  root:      ${report.root}`,
-    `  total:     ${report.summary.total}`,
-    `  allowed:   ${report.summary.byBucket.allowed}`,
-    `  tests:     ${report.summary.byBucket.tests}`,
-    `  disallowed:${report.summary.disallowed}`,
-    `  unsafe:    ${report.summary.byKind.unsafe}`,
-    `  asRawClient:${report.summary.byKind.asRawClient}`,
-    `  DELETE FROM strings: ${report.summary.byKind.delete_from}`,
-    `  .execute:  ${report.summary.byKind.execute}`,
-    "---",
-  ];
-
-  const bad = report.hits.filter((h) => bucketFor(h) === "disallowed");
-  if (bad.length === 0) {
-    lines.push("  (no disallowed production hits)");
-  } else {
-    lines.push("  disallowed (production):");
-    for (const h of bad.slice(0, 40)) {
-      lines.push(`    ${h.kind.padEnd(12)} ${h.file}:${h.line}  ${h.snippet}`);
-    }
-    if (bad.length > 40) {
-      lines.push(`    … +${bad.length - 40} more`);
-    }
-  }
-  return lines.join("\n");
-}