@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/db/query-api.ts

@@ -0,0 +1,22 @@
+// Legacy re-export shim — query-api.ts hat früher drizzle gewrapped.
+// Heute liegen die Helpers in src/bun-db/. Wir re-exportieren von dort
+// damit existing imports `@cosmicdrift/kumiko-framework/db` weiterhin
+// funktionieren während wir die Callers schrittweise auf den direkten
+// bun-db-Import migrieren.
+
+export type {
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+  WhereValue,
+} from "../db/query";
+export {
+  asRawClient,
+  deleteMany,
+  fetchOne,
+  insertMany,
+  insertOne,
+  selectMany,
+  transaction,
+  updateMany,
+} from "../db/query";

package/src/db/query.ts

@@ -0,0 +1,30 @@
+// Provider-neutrale Query-API. Re-exported aus bun-db/query.
+// Alle Consumer importieren von hier, nicht direkt aus bun-db/.
+export {
+  type AnyDb,
+  asRawClient,
+  coerceRow,
+  countWhere,
+  type DeleteManyBatchedOptions,
+  type DeleteManyBatchedResult,
+  deleteMany,
+  deleteManyBatched,
+  extractTableInfo,
+  fetchOne,
+  type IncrementCounterOptions,
+  incrementCounter,
+  insertMany,
+  insertOne,
+  type OrderByClause,
+  type SelectOptions,
+  selectMany,
+  type TableInfo,
+  transaction,
+  type UpsertOnConflictOptions,
+  updateMany,
+  upsertByPk,
+  upsertOnConflict,
+  type WhereObject,
+  type WhereOperator,
+  type WhereValue,
+} from "../bun-db/query";

package/src/db/reference-data.ts

@@ -1,13 +1,20 @@
-import { eq } from "drizzle-orm";
+import { fetchOne, insertOne, updateMany } from "../db/query";
 import type { ReferenceDataDef } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types";
 import type { DbConnection, DbRow } from "./connection";
 import type { TableColumns } from "./dialect";
-import { toSnakeCase } from "./table-builder";
 
 // biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
 type Table = TableColumns<any>;
 
+const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+
+function hasColumn(table: Table, field: string): boolean {
+  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
+  if (typeof cols !== "object" || cols === null) return false;
+  return field in (cols as Record<string, unknown>);
+}
+
 /**
  * Seed reference data at boot time.
  * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
@@ -31,43 +38,33 @@ export async function seedReferenceData(
     const firstKey = Object.keys(firstRow)[0];
     if (!firstKey) continue;
     const upsertKey = def.upsertKey ?? firstKey;
-    const snakeKey = toSnakeCase(upsertKey);
 
     for (const row of def.data) {
       const keyValue = row[upsertKey];
       if (keyValue === undefined) continue;
 
-      // Check if row exists
-      const [existing] = await db
-        .select()
-        .from(table)
-        .where(eq(table[upsertKey] ?? table[snakeKey], keyValue))
-        .limit(1);
+      const existing = (await fetchOne(db, table, { [upsertKey]: keyValue })) as DbRow | undefined;
 
       if (existing) {
-        // Update if any field changed
-        const existingData = existing as DbRow;
         const changes: Record<string, unknown> = {};
         for (const [field, value] of Object.entries(row)) {
           if (field === upsertKey) continue;
-          if (existingData[field] !== value) {
+          if (existing[field] !== value) {
             changes[field] = value;
           }
         }
         if (Object.keys(changes).length > 0) {
-          await db
-            .update(table)
-            .set(changes)
-            .where(eq(table[upsertKey] ?? table[snakeKey], keyValue));
+          await updateMany(db, table, changes, { [upsertKey]: keyValue });
           updated++;
         }
       } else {
-        await db.insert(table).values({
-          ...row,
-          tenantId: SYSTEM_TENANT_ID,
-          version: 1,
-          insertedAt: Temporal.Now.instant(),
-        });
+        // Only add framework columns if the table actually has them.
+        // Drizzle used to filter extra fields silently; bunInsertOne doesn't.
+        const values: Record<string, unknown> = { ...row };
+        if (hasColumn(table, "tenantId")) values["tenantId"] = SYSTEM_TENANT_ID;
+        if (hasColumn(table, "version")) values["version"] = 1;
+        if (hasColumn(table, "insertedAt")) values["insertedAt"] = Temporal.Now.instant();
+        await insertOne(db, table, values);
         inserted++;
       }
     }

package/src/db/render-ddl.ts

@@ -0,0 +1,57 @@
+// Pure renderer: EntityTableMeta → SQL DDL statements.
+// Wird vom Migrate-Generator (Phase 2 — CLI-Tool `kumiko migrate generate`)
+// genutzt um initial-SQL-Files zu schreiben. Output ist Start-Form für
+// User-Review — App-Author darf das SQL danach hand-editieren (extra-Index,
+// partial-Index, BRIN, custom-clauses) bevor committed wird.
+//
+// NO-MAGIC-ON-DATA: dieser Renderer wird NIE zur App-Runtime aufgerufen.
+// Nur Build-Step. Runner liest checked-in SQL, nicht Renderer-Output.
+
+import { pgTypeToSqlType } from "./dialect";
+import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta";
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+function renderColumn(col: ColumnMeta): string {
+  const parts: string[] = [quoteIdent(col.name), pgTypeToSqlType(col.pgType)];
+  if (col.identity) parts.push("GENERATED ALWAYS AS IDENTITY");
+  if (col.primaryKey) parts.push("PRIMARY KEY");
+  if (col.defaultSql !== undefined) parts.push(`DEFAULT ${col.defaultSql}`);
+  if (col.notNull && !col.primaryKey) parts.push("NOT NULL");
+  return parts.join(" ");
+}
+
+function renderIndex(tableName: string, idx: IndexMeta): string {
+  const kind = idx.unique === true ? "UNIQUE INDEX" : "INDEX";
+  const colList = idx.columns.map(quoteIdent).join(", ");
+  if (idx.needsManualWhere === true) {
+    return [
+      `-- WARN: partial-index "${idx.name}" needs a WHERE clause that the`,
+      `--       generator can't render (entity uses drizzle sql\`…\` AST).`,
+      `--       Add the WHERE manually before applying:`,
+      `-- CREATE ${kind} IF NOT EXISTS ${quoteIdent(idx.name)} ON ${quoteIdent(tableName)} (${colList}) WHERE <your-condition>;`,
+    ].join("\n");
+  }
+  const where = idx.whereSql !== undefined ? ` WHERE ${idx.whereSql}` : "";
+  return `CREATE ${kind} IF NOT EXISTS ${quoteIdent(idx.name)} ON ${quoteIdent(tableName)} (${colList})${where};`;
+}
+
+export function renderTableDdl(meta: EntityTableMeta): readonly string[] {
+  const colLines = meta.columns.map(renderColumn);
+  const lines: string[] = [...colLines];
+  if (meta.compositePrimaryKey !== undefined) {
+    const pkCols = meta.compositePrimaryKey.columns.map(quoteIdent).join(",");
+    lines.push(`CONSTRAINT ${quoteIdent(meta.compositePrimaryKey.name)} PRIMARY KEY(${pkCols})`);
+  }
+  const create = `CREATE TABLE IF NOT EXISTS ${quoteIdent(meta.tableName)} (\n  ${lines.join(",\n  ")}\n);`;
+  const indexes = meta.indexes.map((idx) => renderIndex(meta.tableName, idx));
+  return [create, ...indexes];
+}
+
+export function renderTablesDdl(metas: readonly EntityTableMeta[]): readonly string[] {
+  const stmts: string[] = [];
+  for (const m of metas) stmts.push(...renderTableDdl(m));
+  return stmts;
+}

package/src/db/row-helpers.ts

@@ -1,53 +1,4 @@
-import { and, type SQL } from "drizzle-orm";
-import type { DbRow } from "./connection";
-import type { TableColumns } from "./dialect";
+// Legacy re-export shim — fetchOne lebt jetzt in src/bun-db/query.ts.
 
-// biome-ignore lint/suspicious/noExplicitAny: Mirrors the erased ProjectionTable / event-store-executor pattern — the framework doesn't know user column shapes.
-type AnyTable = TableColumns<any>;
-
-// Minimal DB surface fetchOne uses — structurally satisfied by raw DbRunner
-// (connection / tx) AND TenantDb (tenant-scoped wrapper). Both expose the
-// same `select().from().where().limit()` chain with compatible rows, so the
-// helper types against the shared shape instead of a union that TS can't
-// narrow cleanly.
-type SelectChainDb = {
-  select: () => {
-    from: (table: AnyTable) => {
-      where: (cond: SQL | undefined) => {
-        limit: (n: number) => PromiseLike<readonly Record<string, unknown>[]>;
-      };
-    };
-  };
-};
-
-// SELECT * FROM <table> WHERE <...conditions> LIMIT 1 → first row or undefined.
-// Collapses the "const [row] = await db.select()...limit(1)" destructure
-// that repeats in every detail-query-style handler and existence-check.
-//
-// Conditions are variadic and non-empty — the tuple `[SQL, ...SQL[]]` rejects
-// `fetchOne(db, table)` (would silently pick any row) and `fetchOne(db, table,
-// undefined)` (would do the same) at compile time. Multiple conditions are
-// combined with AND.
-//
-//   const existing = await fetchOne<{ id: number }>(db, userTable,
-//     eq(userTable.email, payload.email));
-//   if (existing) return writeFailure(new ConflictError({ ... }));
-//
-//   const row = await fetchOne(db, membershipTable,
-//     eq(membershipTable.userId, userId),
-//     eq(membershipTable.tenantId, tenantId),
-//   );
-//
-// For dynamic condition arrays (length known only at runtime), spread
-// explicitly: `fetchOne(db, table, first, ...rest)`. Raw `...arr` with
-// `arr: SQL[]` won't type-check because TS can't prove the array is non-
-// empty — a feature, not a bug.
-export async function fetchOne<TRow = DbRow>(
-  db: SelectChainDb,
-  table: AnyTable,
-  ...conditions: readonly [SQL, ...SQL[]]
-): Promise<TRow | undefined> {
-  const where = conditions.length === 1 ? conditions[0] : and(...conditions);
-  const rows = await db.select().from(table).where(where).limit(1);
-  return rows[0] as TRow | undefined; // @cast-boundary db-row
-}
+export type { WhereObject } from "../db/query";
+export { fetchOne } from "../db/query";

package/src/db/schema-inspection.ts

@@ -1,4 +1,3 @@
-import { sql } from "drizzle-orm";
 import type { DbConnection, DbTx } from "./connection";
 
 // True when `<fullyQualifiedName>` refers to an existing relation in the
@@ -18,8 +17,22 @@ export async function tableExists(
   db: DbConnection | DbTx,
   fullyQualifiedName: string,
 ): Promise<boolean> {
-  const rows = await db.execute<{ exists: boolean }>(
-    sql`SELECT to_regclass(${fullyQualifiedName}) IS NOT NULL AS exists`,
-  );
+  const dbAny = db as unknown as {
+    $client?: {
+      unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
+    };
+    session?: {
+      client?: {
+        unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
+      };
+    };
+    unsafe?: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
+  };
+  const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
+  const rows = await (
+    client as {
+      unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
+    }
+  ).unsafe(`SELECT to_regclass($1) IS NOT NULL AS exists`, [fullyQualifiedName]);
   return rows[0]?.exists ?? false;
 }

package/src/db/sql-inventory.ts

@@ -0,0 +1,208 @@
+/**
+ * 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\//,
+  /\/packages\/bundled-features\/src\/[^/]+\/db\/queries\//,
+  /\/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,
+    },
+  };
+}
+
+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");
+}