@metaobjectsdev/migrate-ts 0.5.0 → 0.6.0-rc.1

package/src/introspect/d1.ts

@@ -0,0 +1,185 @@
+import type {
+  SchemaSnapshot, TableDescriptor, ColumnDescriptor, SnapshotMeta,
+  IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor,
+} from "../types.js";
+import { parseSqliteDefault, sqliteTypeToSqlType, sqliteRuleToAction } from "./sqlite-shared.js";
+
+/**
+ * Runner contract: takes a SQL command string and returns wrangler's raw
+ * JSON envelope stdout. The CLI wires this to a real exec; tests pass a mock.
+ * The runner is responsible for ALL transport concerns (local vs remote,
+ * config path, error mapping). introspectD1 only knows about SQL queries.
+ */
+export type D1Runner = (sql: string) => Promise<string>;
+
+/** Private shorthand for the exec helper used throughout this module. */
+type Exec = (sql: string) => Promise<Record<string, unknown>[]>;
+
+export interface IntrospectD1Options {
+  runner: D1Runner;
+  /**
+   * Documented passthrough — the CLI wiring uses binding/remote/configPath to
+   * construct the runner; introspectD1 itself only dispatches SQL via opts.runner.
+   * They live on the options so the wiring contract is self-documenting at the call site.
+   */
+  binding: string;
+  remote: boolean;
+  configPath: string | undefined;
+}
+
+export async function introspectD1(opts: IntrospectD1Options): Promise<SchemaSnapshot> {
+  const exec: Exec = async (sql: string) => {
+    const stdout = await opts.runner(sql);
+    return parseEnvelope(stdout);
+  };
+
+  const versionRows = await exec("SELECT sqlite_version() AS v");
+  const meta: SnapshotMeta = {
+    sqliteVersion: String(versionRows[0]?.v ?? "0.0.0"),
+  };
+
+  const tableRows = await exec(
+    "SELECT name, sql FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__new_%' ORDER BY name",
+  );
+
+  const tables: TableDescriptor[] = [];
+  for (const t of tableRows) {
+    const name = String(t.name);
+    const createSql = String(t.sql ?? "");
+    // Issue pragma_table_info ONCE per table; extractColumns + extractPrimaryKey
+    // consume the same rows without re-querying (each query is a wrangler round-trip).
+    const tableInfoRows = await readTableInfo(exec, name);
+    const cols = extractColumns(tableInfoRows);
+    const pk = extractPrimaryKey(tableInfoRows);
+    const hasAutoincrement = createSql.toUpperCase().includes("AUTOINCREMENT");
+    if (hasAutoincrement && pk.length === 1) {
+      const pkCol = cols.find((c) => c.name === pk[0]);
+      if (pkCol) pkCol.identity = "increment";
+    }
+    tables.push({
+      name,
+      columns: cols,
+      indexes: await readIndexes(exec, name),
+      foreignKeys: await readForeignKeys(exec, name),
+      primaryKey: pk,
+    });
+  }
+
+  const views = await readViews(exec);
+  return { tables, views, meta };
+}
+
+function parseEnvelope(stdout: string): Record<string, unknown>[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(`failed to parse wrangler JSON output: ${(err as Error).message}`);
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(`unexpected wrangler output shape (expected non-empty array envelope): ${stdout.slice(0, 200)}`);
+  }
+  const envelope = parsed[0];
+  if (envelope === null || typeof envelope !== "object") {
+    throw new Error(`unexpected wrangler output shape (envelope is not an object): ${stdout.slice(0, 200)}`);
+  }
+  const env = envelope as { success?: boolean; error?: string; results?: unknown };
+  if (env.success === false) {
+    throw new Error(`wrangler d1 execute failed: ${env.error ?? "(no error message)"}`);
+  }
+  const results = env.results;
+  if (!Array.isArray(results)) return [];
+  return results as Record<string, unknown>[];
+}
+
+async function readTableInfo(exec: Exec, table: string): Promise<Record<string, unknown>[]> {
+  return exec(`SELECT * FROM pragma_table_info(${sqliteIdent(table)}) ORDER BY cid`);
+}
+
+function extractColumns(rows: Record<string, unknown>[]): ColumnDescriptor[] {
+  return rows.map((r) => {
+    const col: ColumnDescriptor = {
+      name: String(r.name),
+      sqlType: sqliteTypeToSqlType(String(r.type)),
+      nullable: Number(r.notnull) === 0 && Number(r.pk) === 0,
+    };
+    const def = parseSqliteDefault(r.dflt_value === null ? null : String(r.dflt_value));
+    if (def) col.default = def;
+    return col;
+  });
+}
+
+function extractPrimaryKey(rows: Record<string, unknown>[]): string[] {
+  return rows
+    .filter((r) => Number(r.pk) > 0)
+    .sort((a, b) => Number(a.pk) - Number(b.pk))
+    .map((r) => String(r.name));
+}
+
+async function readIndexes(exec: Exec, table: string): Promise<IndexDescriptor[]> {
+  const list = await exec(`SELECT * FROM pragma_index_list(${sqliteIdent(table)})`);
+  const indexes: IndexDescriptor[] = [];
+  for (const ix of list) {
+    if (String(ix.origin) === "pk") continue;
+    if (Number(ix.partial) === 1) continue;
+    const ixName = String(ix.name);
+    const cols = await exec(`SELECT seqno, cid, name FROM pragma_index_info(${sqliteIdent(ixName)}) ORDER BY seqno`);
+    indexes.push({
+      name: ixName,
+      columns: cols.map((c) => String(c.name)),
+      unique: Number(ix.unique) === 1,
+    });
+  }
+  return indexes;
+}
+
+async function readForeignKeys(exec: Exec, table: string): Promise<FkDescriptor[]> {
+  const rows = await exec(`SELECT * FROM pragma_foreign_key_list(${sqliteIdent(table)}) ORDER BY id, seq`);
+  const byId = new Map<number, { refTable: string; cols: string[]; refCols: string[]; onDelete: FkAction; onUpdate: FkAction; }>();
+  for (const r of rows) {
+    const id = Number(r.id);
+    let entry = byId.get(id);
+    if (!entry) {
+      entry = {
+        refTable: String(r.table),
+        cols: [],
+        refCols: [],
+        onDelete: sqliteRuleToAction(String(r.on_delete)),
+        onUpdate: sqliteRuleToAction(String(r.on_update)),
+      };
+      byId.set(id, entry);
+    }
+    entry.cols.push(String(r.from));
+    entry.refCols.push(String(r.to));
+  }
+  return Array.from(byId.entries()).map(([_id, v]) => {
+    const fk: FkDescriptor = {
+      name: `${table}_${v.cols.join("_")}_fk`,
+      columns: v.cols,
+      refTable: v.refTable,
+      refColumns: v.refCols,
+    };
+    if (v.onDelete !== "no-action") fk.onDelete = v.onDelete;
+    if (v.onUpdate !== "no-action") fk.onUpdate = v.onUpdate;
+    return fk;
+  });
+}
+
+async function readViews(exec: Exec): Promise<ViewDescriptor[]> {
+  const rows = await exec(
+    "SELECT name FROM sqlite_master WHERE type='view' AND name NOT LIKE 'sqlite_%' ORDER BY name",
+  );
+  return rows.map((r) => ({ name: String(r.name) }));
+}
+
+/**
+ * Quote a SQLite identifier with double-quotes, escaping any embedded
+ * double-quotes (SQLite identifier escape: "" → literal ").
+ * Used for pragma_* calls where bind params aren't available (wrangler
+ * --command takes a complete SQL string). The introspectSqlite path uses
+ * Kysely tagged templates and doesn't need this.
+ */
+function sqliteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+

package/src/introspect/index.ts

@@ -10,5 +10,6 @@ export async function introspect(db: Kysely<Record<string, unknown>>, dialect: D
   switch (dialect) {
     case "postgres": return introspectPostgres(db);
     case "sqlite":   return introspectSqlite(db);
+    case "d1":       throw new Error("d1 introspect goes through introspectD1, not introspect() — wrangler does not use a Kysely driver");
   }
 }

package/src/introspect/sqlite-shared.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared SQLite catalog helpers used by both the Kysely-based introspector
+ * (sqlite.ts) and the wrangler-based D1 introspector (d1.ts).
+ *
+ * All three routines are pure mappings of SQLite's declared type / pragma
+ * values to canonical migrate-ts types and carry no I/O dependencies.
+ */
+import type { ColumnDefault, FkAction } from "../types.js";
+import type { SqlType } from "../sql-type.js";
+
+export const SQLITE_EXPR_DEFAULT_PATTERNS = [
+  /^current_timestamp$/i,
+  /^current_date$/i,
+  /^current_time$/i,
+  /\(.*\)/,
+] as const;
+
+export function parseSqliteDefault(raw: string | null): ColumnDefault | undefined {
+  if (raw === null || raw === undefined || raw === "") return undefined;
+  const isExpr = SQLITE_EXPR_DEFAULT_PATTERNS.some((re) => re.test(raw));
+  if (isExpr) return { kind: "expr", value: raw };
+  // SQLite stores literal string defaults with surrounding quotes.
+  const cleaned = raw.replace(/^'(.*)'$/, "$1");
+  return { kind: "literal", value: cleaned };
+}
+
+export function sqliteTypeToSqlType(declaredType: string): SqlType {
+  const t = declaredType.trim().toUpperCase();
+
+  // SQLite's type affinity is loose; we honor the declared type literally for round-trip stability.
+  // Affinity rules per sqlite.org/datatype3.html — adapted to canonical SqlType.
+
+  // text affinity
+  const varcharMatch = /^(?:VARCHAR|CHAR|CHARACTER|TEXT)\((\d+)\)$/.exec(t);
+  if (varcharMatch) return { kind: "text", maxLength: parseInt(varcharMatch[1] ?? "0", 10) };
+  if (/TEXT|CLOB|VARCHAR|CHAR/.test(t)) return { kind: "text" };
+
+  // numeric affinity
+  const numMatch = /^(?:NUMERIC|DECIMAL)\((\d+)(?:,\s*(\d+))?\)$/.exec(t);
+  if (numMatch) {
+    const out: SqlType = { kind: "numeric" };
+    if (numMatch[1]) out.precision = parseInt(numMatch[1], 10);
+    if (numMatch[2]) out.scale = parseInt(numMatch[2], 10);
+    return out;
+  }
+  if (t === "BOOLEAN" || t === "BOOL") return { kind: "boolean" };
+  if (t === "DATE") return { kind: "date" };
+  if (t === "DATETIME" || t === "TIMESTAMP") return { kind: "timestamp", withTimezone: false };
+
+  // integer affinity (SQLite stores all INTEGER as 64-bit internally).
+  // Distinguish INT (32-bit) from INTEGER/BIGINT (64-bit) for round-trip fidelity:
+  // the emitter uses "INT" for integer{32} and "INTEGER" for integer{64}.
+  if (t === "INT" || t === "SMALLINT" || t === "TINYINT") return { kind: "integer", bits: 32 };
+  if (/INT/.test(t)) return { kind: "integer", bits: 64 };
+
+  // real affinity
+  if (/REAL|FLOA|DOUB/.test(t)) return { kind: "real" };
+
+  // blob affinity
+  if (t === "BLOB" || t === "") return { kind: "blob" };
+
+  // numeric affinity fallback
+  if (/NUMERIC|DECIMAL/.test(t)) return { kind: "numeric" };
+
+  // json (libsql/sqlite have JSON1)
+  if (t === "JSON") return { kind: "json" };
+
+  return { kind: "text" };
+}
+
+export function sqliteRuleToAction(rule: string): FkAction {
+  const r = rule.toUpperCase();
+  if (r === "CASCADE") return "cascade";
+  if (r === "SET NULL") return "set-null";
+  if (r === "RESTRICT") return "restrict";
+  return "no-action";
+}

package/src/introspect/sqlite.ts

@@ -1,10 +1,10 @@
 import type { Kysely } from "kysely";
 import { sql } from "kysely";
 import type {
-  SchemaSnapshot, TableDescriptor, ColumnDescriptor, ColumnDefault, SnapshotMeta,
+  SchemaSnapshot, TableDescriptor, ColumnDescriptor, SnapshotMeta,
   IndexDescriptor, FkDescriptor, FkAction, ViewDescriptor,
 } from "../types.js";
-import type { SqlType } from "../sql-type.js";
+import { parseSqliteDefault, sqliteTypeToSqlType, sqliteRuleToAction } from "./sqlite-shared.js";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type RawKysely = Kysely<any>;
@@ -83,66 +83,6 @@ async function readSqlitePrimaryKey(k: RawKysely, table: string): Promise<string
   return rows.rows.map((r) => r.name);
 }
 
-function sqliteTypeToSqlType(declaredType: string): SqlType {
-  const t = declaredType.trim().toUpperCase();
-
-  // SQLite's type affinity is loose; we honor the declared type literally for round-trip stability.
-  // Affinity rules per sqlite.org/datatype3.html — adapted to canonical SqlType.
-
-  // text affinity
-  const varcharMatch = /^(?:VARCHAR|CHAR|CHARACTER|TEXT)\((\d+)\)$/.exec(t);
-  if (varcharMatch) return { kind: "text", maxLength: parseInt(varcharMatch[1] ?? "0", 10) };
-  if (/TEXT|CLOB|VARCHAR|CHAR/.test(t)) return { kind: "text" };
-
-  // numeric affinity
-  const numMatch = /^(?:NUMERIC|DECIMAL)\((\d+)(?:,\s*(\d+))?\)$/.exec(t);
-  if (numMatch) {
-    const out: SqlType = { kind: "numeric" };
-    if (numMatch[1]) out.precision = parseInt(numMatch[1], 10);
-    if (numMatch[2]) out.scale = parseInt(numMatch[2], 10);
-    return out;
-  }
-  if (t === "BOOLEAN" || t === "BOOL") return { kind: "boolean" };
-  if (t === "DATE") return { kind: "date" };
-  if (t === "DATETIME" || t === "TIMESTAMP") return { kind: "timestamp", withTimezone: false };
-
-  // integer affinity (SQLite stores all INTEGER as 64-bit internally).
-  // Distinguish INT (32-bit) from INTEGER/BIGINT (64-bit) for round-trip fidelity:
-  // the emitter uses "INT" for integer{32} and "INTEGER" for integer{64}.
-  if (t === "INT" || t === "SMALLINT" || t === "TINYINT") return { kind: "integer", bits: 32 };
-  if (/INT/.test(t)) return { kind: "integer", bits: 64 };
-
-  // real affinity
-  if (/REAL|FLOA|DOUB/.test(t)) return { kind: "real" };
-
-  // blob affinity
-  if (t === "BLOB" || t === "") return { kind: "blob" };
-
-  // numeric affinity fallback
-  if (/NUMERIC|DECIMAL/.test(t)) return { kind: "numeric" };
-
-  // json (libsql/sqlite have JSON1)
-  if (t === "JSON") return { kind: "json" };
-
-  return { kind: "text" };
-}
-
-const SQLITE_EXPR_DEFAULT_PATTERNS = [
-  /^current_timestamp$/i,
-  /^current_date$/i,
-  /^current_time$/i,
-  /\(.*\)/,                           // anything function-like
-];
-
-function parseSqliteDefault(raw: string | null): ColumnDefault | undefined {
-  if (raw === null || raw === undefined || raw === "") return undefined;
-  const isExpr = SQLITE_EXPR_DEFAULT_PATTERNS.some((re) => re.test(raw));
-  if (isExpr) return { kind: "expr", value: raw };
-  // SQLite stores literal string defaults with surrounding quotes.
-  const cleaned = raw.replace(/^'(.*)'$/, "$1");
-  return { kind: "literal", value: cleaned };
-}
-
 async function readSqliteIndexes(k: RawKysely, table: string): Promise<IndexDescriptor[]> {
   // SELECT * avoids "unique" being treated as a reserved keyword by libsql.
   const listRows = await sql<{ seq: number; name: string; unique: number; origin: string; partial: number }>`
@@ -207,10 +147,3 @@ async function readSqliteForeignKeys(k: RawKysely, table: string): Promise<FkDes
   });
 }
 
-function sqliteRuleToAction(rule: string): FkAction {
-  const r = rule.toUpperCase();
-  if (r === "CASCADE") return "cascade";
-  if (r === "SET NULL") return "set-null";
-  if (r === "RESTRICT") return "restrict";
-  return "no-action";
-}

package/src/referential-actions.ts

@@ -0,0 +1,134 @@
+import {
+  ON_DELETE_DEFAULT_BY_SUBTYPE,
+  ON_UPDATE_DEFAULT,
+  FIELD_ATTR_REQUIRED,
+  IDENTITY_ATTR_FIELDS,
+  TYPE_VALIDATOR,
+  VALIDATOR_SUBTYPE_REQUIRED,
+  type MetaObject,
+  type MetaReferenceIdentity,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+import type { FkAction } from "./types.js";
+import { SetNullNotNullableError } from "./errors.js";
+
+// ---------------------------------------------------------------------------
+// Shared field helpers — exported for use by expected-schema.ts
+// ---------------------------------------------------------------------------
+
+export function readIdentityFields(identity: MetaData): string[] {
+  const raw = identity.ownAttr(IDENTITY_ATTR_FIELDS);
+  if (Array.isArray(raw)) return raw.map(String).filter((s) => s.length > 0);
+  // Fallback: comma-separated string form (defensive; canonical form is array)
+  if (typeof raw === "string") return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return [];
+}
+
+export function findField(entity: MetaObject, name: string): MetaData | undefined {
+  for (const field of entity.fields()) {
+    if (field.name === name) return field;
+  }
+  return undefined;
+}
+
+export function isRequired(field: MetaData): boolean {
+  const attr = field.ownAttr(FIELD_ATTR_REQUIRED);
+  if (attr === true || attr === "true") return true;
+  return field.ownChildren().some(
+    (c) => c.type === TYPE_VALIDATOR && c.subType === VALIDATOR_SUBTYPE_REQUIRED,
+  );
+}
+
+/**
+ * Resolve the referential actions for a foreign key inferred from an
+ * identity.reference, by correlating it with a sibling relationship on the
+ * same entity (matched on target-entity name).
+ *
+ * - No correlated relationship → both undefined (no ON DELETE / ON UPDATE clause).
+ * - With a relationship: onDelete defaults from the relationship subtype
+ *   (composition→cascade, aggregation→set-null, association→restrict);
+ *   onUpdate defaults to "cascade". Explicit @onDelete / @onUpdate override.
+ * - Resolved "no-action" → undefined: introspection in introspect/{postgres,sqlite}.ts
+ *   omits actions when the DB value is "no-action", so the expected side does the same
+ *   to keep round-trip diffs clean.
+ *
+ * If multiple relationships target the same entity (rare), the first one is used.
+ *
+ * The single `as FkAction` cast in normalize() is safe because REFERENTIAL_ACTIONS
+ * (metadata package) and FkAction (migrate-ts/src/types.ts) are the same four-value
+ * set: "cascade" | "set-null" | "restrict" | "no-action". The invariant is
+ * documented in relationship-constants.ts and enforced by both the type system
+ * (FkAction is the union literal) and a runtime-set-equality test in
+ * referential-actions.test.ts.
+ */
+export function resolveReferentialActions(
+  entity: MetaObject,
+  ref: MetaReferenceIdentity,
+): { onDelete: FkAction | undefined; onUpdate: FkAction | undefined } {
+  const target = ref.targetEntity;
+  if (target === undefined) return { onDelete: undefined, onUpdate: undefined };
+
+  // Correlation is by exact-string match. Every fixture in the corpus uses
+  // bare entity names for @objectRef and @references (no `::`-FQN form), so
+  // bare-vs-bare matching is sufficient today. If a future author writes an
+  // FQN value on either side, this find returns undefined and both actions
+  // resolve to undefined (no clause emitted) — surfacing the mismatch as a
+  // silent loss of intent rather than a wrong action. Cross-language ports
+  // should match the same correlation rule.
+  const rel = entity.relationships().find((r) => r.objectRef === target);
+  if (rel === undefined) return { onDelete: undefined, onUpdate: undefined };
+
+  const onDeleteRaw = rel.onDelete ?? ON_DELETE_DEFAULT_BY_SUBTYPE[rel.subType];
+  const onUpdateRaw = rel.onUpdate ?? ON_UPDATE_DEFAULT;
+  return {
+    onDelete: normalize(onDeleteRaw),
+    onUpdate: normalize(onUpdateRaw),
+  };
+}
+
+function normalize(a: string | undefined): FkAction | undefined {
+  if (a === undefined || a === "no-action") return undefined;
+  return a as FkAction;
+}
+
+// ---------------------------------------------------------------------------
+// Set-null / NOT NULL guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a FK whose resolved ON DELETE action is "set-null" does not
+ * contain any NOT NULL column.
+ *
+ * ON DELETE SET NULL requires all FK columns to be nullable. Postgres and
+ * SQLite both reject the combination at DDL execution time.
+ *
+ * Call this from buildExpectedSchema AFTER resolving the referential action
+ * (i.e. after resolveReferentialActions) so that explicit overrides such as
+ * @onDelete: "restrict" are already applied before the check.
+ *
+ * @param entity          The owning entity.
+ * @param ref             The identity.reference node being processed.
+ * @param onDelete        The resolved onDelete action (undefined = no-action).
+ * @param constraintName  The FK constraint name as it will appear in the DDL.
+ */
+export function validateSetNullNullability(
+  entity: MetaObject,
+  ref: MetaReferenceIdentity,
+  onDelete: FkAction | undefined,
+  constraintName: string,
+): void {
+  if (onDelete !== "set-null") return;
+
+  const fkFieldJsNames = readIdentityFields(ref);
+  const offending: string[] = [];
+  for (const jsName of fkFieldJsNames) {
+    const field = findField(entity, jsName);
+    if (field !== undefined && isRequired(field)) {
+      offending.push(jsName);
+    }
+  }
+
+  if (offending.length > 0) {
+    throw new SetNullNotNullableError(entity.name, constraintName, offending);
+  }
+}

package/src/types.ts

@@ -32,6 +32,13 @@ export interface TableDescriptor {
   indexes: IndexDescriptor[];
   foreignKeys: FkDescriptor[];
   primaryKey: string[];              // column names; [] if none
+  /**
+   * Human-readable description threaded from entity `@description`.
+   * Postgres: emitted as `COMMENT ON TABLE … IS '…';` after CREATE TABLE.
+   * SQLite: silently ignored (no native COMMENT support).
+   * Introspect side: not read back in v1 (no change-description variant yet).
+   */
+  description?: string;
 }
 
 export interface ColumnDescriptor {
@@ -40,6 +47,13 @@ export interface ColumnDescriptor {
   nullable: boolean;
   default?: ColumnDefault;
   identity?: "increment" | "uuid";
+  /**
+   * Human-readable description threaded from field `@description`.
+   * Postgres: emitted as `COMMENT ON COLUMN … IS '…';` after CREATE TABLE or ADD COLUMN.
+   * SQLite: silently ignored (no native COMMENT support).
+   * Introspect side: not read back in v1 (no change-description variant yet).
+   */
+  description?: string;
 }
 
 export interface ColumnDefault {
@@ -171,4 +185,4 @@ export interface EmitResult {
   recreatedTables: ReadonlySet<string>;
 }
 
-export type Dialect = "postgres" | "sqlite";
+export type Dialect = "postgres" | "sqlite" | "d1";

package/src/wrangler-config.ts

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, isAbsolute, resolve } from "node:path";
+import TOML from "@iarna/toml";
+
+export interface D1Binding {
+  binding: string;
+  database_name: string;
+  database_id: string;
+  migrations_dir: string | undefined;
+}
+
+export interface WranglerConfig {
+  d1Bindings: D1Binding[];
+}
+
+/**
+ * Walk from `startDir` upward looking for wrangler.toml, wrangler.jsonc, or wrangler.json.
+ * Returns the first match or undefined. Probe order: toml > jsonc > json at each level,
+ * matching wrangler's own resolution order.
+ */
+export function findWranglerConfig(startDir: string): string | undefined {
+  let dir = resolve(startDir);
+  while (true) {
+    const toml = join(dir, "wrangler.toml");
+    if (existsSync(toml)) return toml;
+    const jsonc = join(dir, "wrangler.jsonc");
+    if (existsSync(jsonc)) return jsonc;
+    const json = join(dir, "wrangler.json");
+    if (existsSync(json)) return json;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Parse a wrangler.toml or wrangler.jsonc file. Returns extracted D1 bindings.
+ */
+export function parseWranglerConfig(path: string): WranglerConfig {
+  if (!isAbsolute(path)) path = resolve(path);
+  const raw = readFileSync(path, "utf8");
+  const isJsonc = path.endsWith(".jsonc") || path.endsWith(".json");
+  const obj = isJsonc ? parseJsoncLoose(raw) : (TOML.parse(raw) as Record<string, unknown>);
+  const rawArr = obj.d1_databases;
+  if (rawArr !== undefined && !Array.isArray(rawArr)) {
+    throw new Error(`${path}: d1_databases must be an array (got ${typeof rawArr})`);
+  }
+  const rawBindings: unknown[] = rawArr ?? [];
+  const d1Bindings: D1Binding[] = rawBindings.map((b, i) => {
+    if (b === null || typeof b !== "object") {
+      throw new Error(`${path}: d1_databases[${i}] must be an object`);
+    }
+    const r = b as Record<string, unknown>;
+    if (typeof r.binding !== "string" || r.binding.length === 0) {
+      throw new Error(`${path}: d1_databases[${i}] is missing required 'binding' field`);
+    }
+    return {
+      binding: r.binding,
+      database_name: typeof r.database_name === "string" ? r.database_name : "",
+      database_id: typeof r.database_id === "string" ? r.database_id : "",
+      migrations_dir: typeof r.migrations_dir === "string" ? r.migrations_dir : undefined,
+    };
+  });
+  return { d1Bindings };
+}
+
+/**
+ * Pick a D1 binding by name. If `name` is undefined and there's exactly one
+ * binding, return it. Otherwise throw a helpful error.
+ */
+export function resolveD1Binding(bindings: readonly D1Binding[], name: string | undefined): D1Binding {
+  if (bindings.length === 0) {
+    throw new Error("no d1 bindings found in wrangler config");
+  }
+  if (name === undefined) {
+    if (bindings.length === 1) return bindings[0]!;
+    throw new Error(
+      `multiple d1 bindings in wrangler config; pass --d1 <binding>. Available: ${bindings.map((b) => b.binding).join(", ")}`,
+    );
+  }
+  const found = bindings.find((b) => b.binding === name);
+  if (!found) {
+    throw new Error(
+      `d1 binding '${name}' not found in wrangler config. Available: ${bindings.map((b) => b.binding).join(", ")}`,
+    );
+  }
+  return found;
+}
+
+/**
+ * Minimal JSONC parser: strips `//` line comments and block comments (`/`+`* ... *`+`/`),
+ * then JSON.parse. Wrangler's jsonc is small; this is sufficient.
+ *
+ * Limitation: a `//` sequence inside a JSON string value would be incorrectly
+ * stripped. Wrangler's config vocabulary (UUIDs, identifiers, paths) does not
+ * use such substrings, so this is acceptable in scope.
+ */
+function parseJsoncLoose(raw: string): Record<string, unknown> {
+  const stripped = raw
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:])\/\/.*$/gm, "$1");
+  return JSON.parse(stripped) as Record<string, unknown>;
+}