@rexezuge/tooling 0.0.0-stage → 1.0.0

package/src/scripts/wrangler-config/resources.ts

@@ -0,0 +1,330 @@
+/**
+ * Creating the resources `wrangler.jsonc` names, and writing their real ids over
+ * the placeholders.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/wrangler-config/resources.ts`.
+ *
+ * The placeholder rule: a template carries an all-zero id meaning "resolve me",
+ * and a config carrying one cannot be deployed. So provisioning walks the config,
+ * creates what is missing, and patches the id in place. A placeholder with nothing
+ * to create it *under* — a KV id with no binding, a D1 id with no name — is
+ * refused rather than skipped, because a silently skipped placeholder is a deploy
+ * that fails later with no link back to the reason.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { parse } from 'jsonc-parser';
+import { parseWranglerTableRows } from '../lib/wrangler-table';
+import {
+  CONFIG_PATH,
+  DEFAULT_HEX_ID,
+  DEFAULT_KV_NAMESPACE_NAMES,
+  DEFAULT_SECRET_STORE_NAME,
+  DEFAULT_UUID,
+  DEFAULT_WORKER_NAME,
+  VECTORIZE_DIMENSIONS,
+  type D1Database,
+  type KVNamespace,
+  type SecretStore,
+  type WranglerConfig,
+} from './types';
+import { parseJsonArray, runWrangler } from './cli';
+import { readConfig, writeConfig, writeConfigValue } from './patches';
+
+/** What `ensure*` did, so a caller can act on the difference. */
+export interface Provisioned {
+  id: string;
+  created: boolean;
+}
+
+/** The id a D1 database is reported under, whichever key the CLI used. */
+export function getD1Id(database: D1Database): string | undefined {
+  return database.uuid ?? database.database_id ?? database.id;
+}
+
+export function listD1Databases(): D1Database[] {
+  return parseJsonArray<D1Database>(runWrangler(['d1', 'list', '--json']), 'wrangler d1 list --json');
+}
+
+/**
+ * The D1 database `binding` names, created when it does not exist.
+ *
+ * Whether it was created is reported, not inferred: a database created moments ago
+ * holds no user data, so a backup workflow must refuse to upload its empty dump.
+ * The caller cannot re-derive that from the config, because this very function
+ * patches the placeholder away before the reader ever runs.
+ */
+export function ensureD1Database(databaseName: string): Provisioned {
+  let database = listD1Databases().find((candidate) => candidate.name === databaseName);
+  let created = false;
+  if (database === undefined) {
+    console.log(`Creating D1 database: ${databaseName}`);
+    runWrangler(['d1', 'create', databaseName]);
+    database = listD1Databases().find((candidate) => candidate.name === databaseName);
+    created = true;
+  }
+  const databaseId = database === undefined ? undefined : getD1Id(database);
+  if (databaseId === undefined || databaseId === '') {
+    throw new Error(`Unable to discover D1 database ID for ${databaseName}.`);
+  }
+  return { id: databaseId, created };
+}
+
+export function listKVNamespaces(): KVNamespace[] {
+  return parseJsonArray<KVNamespace>(runWrangler(['kv', 'namespace', 'list']), 'wrangler kv namespace list');
+}
+
+/** The namespace name a binding's namespace is created under. */
+export function getKVNamespaceName(config: WranglerConfig, binding: string): string {
+  return DEFAULT_KV_NAMESPACE_NAMES[binding] ?? `${config.name ?? DEFAULT_WORKER_NAME}-${binding.toLowerCase()}`;
+}
+
+export function ensureKVNamespace(config: WranglerConfig, binding: string): Provisioned {
+  const namespaceName = getKVNamespaceName(config, binding);
+  const candidateNames = new Set([namespaceName, `${config.name ?? DEFAULT_WORKER_NAME}-${binding}`, binding]);
+  let namespace = listKVNamespaces().find((candidate) => {
+    const candidateName = candidate.title ?? candidate.name;
+    return candidate.id !== undefined && candidateName !== undefined && candidateNames.has(candidateName);
+  });
+  let created = false;
+  if (namespace === undefined) {
+    console.log(`Creating KV namespace: ${namespaceName}`);
+    runWrangler(['kv', 'namespace', 'create', namespaceName]);
+    namespace = listKVNamespaces().find(
+      (candidate) => candidate.id !== undefined && (candidate.title ?? candidate.name) === namespaceName,
+    );
+    created = true;
+  }
+  if (namespace?.id === undefined) {
+    throw new Error(`Unable to discover KV namespace ID for ${namespaceName}.`);
+  }
+  return { id: namespace.id, created };
+}
+
+/** The bindings a deployment always needs, whether or not a custom config lists them. */
+export function getRequiredKvBindings(): string[] {
+  return Object.keys(DEFAULT_KV_NAMESPACE_NAMES);
+}
+
+/**
+ * Add the always-needed KV bindings a hand-written config left out.
+ *
+ * A config supplied through `WRANGLER_JSONC` is edited by hand and drifts; without
+ * this the worker starts with an unbound `CACHE` and fails on the first read.
+ */
+export function ensureRequiredKvBindings(content: string, config: WranglerConfig): string {
+  const existing = new Set((config.kv_namespaces ?? []).map((namespace) => namespace.binding).filter((binding) => binding !== undefined));
+  const missing = getRequiredKvBindings().filter((binding) => !existing.has(binding));
+  if (missing.length === 0) {
+    return content;
+  }
+  const next = [...(config.kv_namespaces ?? [])];
+  for (const binding of missing) {
+    console.log(`Adding missing KV namespace binding: ${binding}`);
+    next.push({ binding, id: DEFAULT_HEX_ID });
+  }
+  return writeConfigValue(content, ['kv_namespaces'], next);
+}
+
+/** The stores in a `secrets-store store list` table. */
+export function parseSecretStoresTable(output: string): SecretStore[] {
+  const stores: SecretStore[] = [];
+  // Through the shared table parser rather than a second inline split: `wrangler`
+  // renders through `cli-table3`, whose cells are separated by U+2502 and are *not*
+  // space-aligned, so a parser written for aligned output silently matches nothing
+  // — which reads as "the store does not exist" and makes provisioning create a
+  // duplicate.
+  for (const row of parseWranglerTableRows(output)) {
+    const name = row[0];
+    const id = row[1];
+    // Store ids are 32 hex characters; a row without one is a header, a border, or
+    // an unrelated column, and is skipped rather than stored with an undefined id.
+    if (name !== undefined && id !== undefined && /^[a-f0-9]{32}$/i.test(id)) {
+      stores.push({ name, id });
+    }
+  }
+  return stores;
+}
+
+export function listSecretStores(): SecretStore[] {
+  const output = runWrangler(['secrets-store', 'store', 'list', '--remote']);
+  try {
+    return parseJsonArray<SecretStore>(output, 'wrangler secrets-store store list --remote');
+  } catch {
+    // The subcommand prints a table rather than JSON on some versions.
+    return parseSecretStoresTable(output);
+  }
+}
+
+export function ensureSecretStore(): string {
+  const stores = listSecretStores();
+  const existing = stores.find((candidate) => candidate.name === DEFAULT_SECRET_STORE_NAME) ?? stores[0];
+  if (existing !== undefined) {
+    return existing.id;
+  }
+  console.log(`Creating Secrets Store: ${DEFAULT_SECRET_STORE_NAME}`);
+  const output = runWrangler(['secrets-store', 'store', 'create', DEFAULT_SECRET_STORE_NAME, '--remote']);
+  const createdStoreId = /ID:\s*([a-f0-9]{32})/i.exec(output)?.[1];
+  if (createdStoreId !== undefined) {
+    return createdStoreId;
+  }
+  // The create output did not name the id, so read it back rather than guessing.
+  const refreshed = listSecretStores();
+  const store = refreshed.find((candidate) => candidate.name === DEFAULT_SECRET_STORE_NAME) ?? refreshed[0];
+  if (store?.id === undefined) {
+    throw new Error(`Unable to discover Secrets Store ID for ${DEFAULT_SECRET_STORE_NAME}.`);
+  }
+  return store.id;
+}
+
+/** Create a queue when it is absent, reporting whether it had to be created. */
+export function ensureQueue(queueName: string): boolean {
+  try {
+    runWrangler(['queues', 'info', queueName]);
+    console.log(`Queue ${queueName} already exists.`);
+    return false;
+  } catch {
+    console.log(`Creating queue: ${queueName}`);
+    runWrangler(['queues', 'create', queueName]);
+    return true;
+  }
+}
+
+/**
+ * Queue names a deployment needs, in first-seen order.
+ *
+ * Producers and consumers name the same queue twice — one queue, two roles — and a
+ * name appearing in both must be created once. Pure so it is testable without
+ * wrangler.
+ */
+export function queueNamesIn(config: WranglerConfig): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const producer of config.queues?.producers ?? []) {
+    if (producer.queue === '' || seen.has(producer.queue)) continue;
+    seen.add(producer.queue);
+    names.push(producer.queue);
+  }
+  for (const consumer of config.queues?.consumers ?? []) {
+    if (consumer.queue === '' || seen.has(consumer.queue)) continue;
+    seen.add(consumer.queue);
+    names.push(consumer.queue);
+  }
+  return names;
+}
+
+export function ensureVectorizeIndex(indexName: string, dimensions: number): void {
+  try {
+    runWrangler(['vectorize', 'info', indexName]);
+    console.log(`Vectorize index ${indexName} already exists.`);
+  } catch {
+    console.log(`Creating Vectorize index: ${indexName} with ${dimensions} dimensions`);
+    runWrangler(['vectorize', 'create', indexName, `--dimensions=${dimensions}`, '--metric=cosine']);
+  }
+}
+
+/** Replace each placeholder D1 `database_id` with a real one. */
+function provisionD1Databases(content: string, config: WranglerConfig, created: string[]): string {
+  let patched = content;
+  for (const [index, database] of config.d1_databases?.entries() ?? []) {
+    if (database.database_id !== DEFAULT_UUID) continue;
+    if (database.database_name === undefined || database.database_name === '') {
+      throw new Error(`D1 database binding ${database.binding ?? index} has a placeholder database_id but no database_name.`);
+    }
+    const resolved = ensureD1Database(database.database_name);
+    if (resolved.created) {
+      created.push(`d1:${database.database_name}`);
+    }
+    console.log(`Using D1 database ${database.database_name}: ${resolved.id}`);
+    patched = writeConfigValue(patched, ['d1_databases', index, 'database_id'], resolved.id);
+  }
+  return patched;
+}
+
+/** Replace each placeholder KV namespace id with a real one. */
+function provisionKvNamespaces(content: string, config: WranglerConfig, created: string[]): string {
+  let patched = content;
+  for (const [index, namespace] of config.kv_namespaces?.entries() ?? []) {
+    if (namespace.id !== DEFAULT_HEX_ID) continue;
+    if (namespace.binding === undefined || namespace.binding === '') {
+      throw new Error(`KV namespace at index ${index} has a placeholder id but no binding.`);
+    }
+    const resolved = ensureKVNamespace(config, namespace.binding);
+    const namespaceName = getKVNamespaceName(config, namespace.binding);
+    if (resolved.created) {
+      created.push(`kv:${namespaceName}`);
+    }
+    console.log(`Using KV namespace ${namespaceName}: ${resolved.id}`);
+    patched = writeConfigValue(patched, ['kv_namespaces', index, 'id'], resolved.id);
+  }
+  return patched;
+}
+
+/**
+ * Point every placeholder Secrets Store `store_id` at one store, creating it if
+ * absent. `existed` is read **before** the create, because whether the store was
+ * created is what the caller reports.
+ */
+function provisionSecretStore(content: string, config: WranglerConfig, created: string[]): string {
+  const placeholders = (config.secrets_store_secrets ?? [])
+    .map((secret, index) => ({ secret, index }))
+    .filter(({ secret }) => secret.store_id === DEFAULT_HEX_ID);
+  if (placeholders.length === 0) {
+    return content;
+  }
+  const existed = listSecretStores().some((store) => store.name === DEFAULT_SECRET_STORE_NAME);
+  const storeId = ensureSecretStore();
+  if (!existed) {
+    created.push(`secrets-store:${DEFAULT_SECRET_STORE_NAME}`);
+  }
+  console.log(`Using Secrets Store: ${storeId}`);
+  return placeholders.reduce((patched, { index }) => writeConfigValue(patched, ['secrets_store_secrets', index, 'store_id'], storeId), content);
+}
+
+/**
+ * Create every resource the config names, and write the real ids over the
+ * placeholders.
+ *
+ * Returns what it had to create, as `<kind>:<name>` — returned rather than logged,
+ * because a caller acts on it: the backup workflow refuses to export a D1 database
+ * that appears here, since one created moments ago holds no user data and an empty
+ * dump uploaded on schedule is a false sense of safety.
+ */
+export function provisionWranglerResources(): string[] {
+  const created: string[] = [];
+  let { content, config } = readConfig();
+
+  content = ensureRequiredKvBindings(content, config);
+  config = parse(content) as WranglerConfig;
+
+  // Each of the three below re-parses before it patches, because each writes into
+  // the config text the previous one produced. They are separate functions because
+  // they are separate resources with separate rules, and one loop holding all
+  // three would read as a single resource list with the differences hidden in the
+  // bodies.
+  content = provisionD1Databases(content, config, created);
+  config = parse(content) as WranglerConfig;
+
+  content = provisionKvNamespaces(content, config, created);
+  config = parse(content) as WranglerConfig;
+
+  content = provisionSecretStore(content, config, created);
+
+  writeConfig(content);
+
+  config = parse(content) as WranglerConfig;
+  for (const queueName of queueNamesIn(config)) {
+    if (ensureQueue(queueName)) {
+      created.push(`queue:${queueName}`);
+    }
+  }
+
+  // Vectorize indexes are name-based, so nothing in the file is patched — but the
+  // created names are still reported like every other resource, so a deploy log
+  // shows what appeared.
+  for (const binding of config.vectorize ?? []) {
+    ensureVectorizeIndex(binding.index_name, VECTORIZE_DIMENSIONS);
+  }
+
+  return created;
+}

package/src/scripts/wrangler-config/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared paths, placeholders and shape definitions for the wrangler config helpers.
+ *
+ * Provenance: ported from Edge-Sonic's `scripts/lib/wrangler-config/types.ts`.
+ * Every script that reads or writes `wrangler.jsonc` resolves it here, so the
+ * backup workflow cannot end up inspecting a different file than the deploy
+ * materialized.
+ *
+ * The paths default to `process.cwd()`, which is the repo root in every consumer:
+ * the scripts run as `pnpm exec tsx scripts/deploy/…` from there. `WRANGLER_CONFIG_PATH`
+ * / `WRANGLER_TEMPLATE_PATH` override them for a caller that is not in the repo
+ * root, which is the one case the cwd default gets wrong.
+ */
+
+import path from 'node:path';
+
+/** The config the deploy targets. */
+export const CONFIG_PATH = process.env['WRANGLER_CONFIG_PATH'] ?? path.join(process.cwd(), 'wrangler.jsonc');
+
+/** The committed template the config is materialized from. */
+export const TEMPLATE_PATH = process.env['WRANGLER_TEMPLATE_PATH'] ?? path.join(process.cwd(), 'apps/api/wrangler.template.jsonc');
+
+/**
+ * The id a template carries for a D1 database that does not exist yet.
+ *
+ * `provisionWranglerResources` replaces it with a real id; the backup scripts
+ * refuse to export while it is still in place, because a database that was just
+ * created holds no user data.
+ */
+export const DEFAULT_UUID = '00000000-0000-0000-0000-000000000000';
+
+/** The placeholder for a KV namespace id and for a Secrets Store id. */
+export const DEFAULT_HEX_ID = '00000000000000000000000000000000';
+
+/** The Secrets Store name a deployment uses. */
+export const DEFAULT_SECRET_STORE_NAME = 'default';
+
+/**
+ * Fallback when the config declares no `name`, used to derive resource names.
+ *
+ * Overridable per consumer with `WRANGLER_WORKER_NAME`, which keeps the default
+ * honest rather than baking one repo's name into the kit.
+ */
+export const DEFAULT_WORKER_NAME = process.env['WRANGLER_WORKER_NAME'] ?? 'my-worker';
+
+/**
+ * KV bindings a deployment always needs, and the namespace each maps to.
+ *
+ * A consumer whose worker has no cache binding passes an empty map; a consumer
+ * with one names it here or leaves the derived `<worker>-<BINDING>` convention.
+ */
+export const DEFAULT_KV_NAMESPACE_NAMES: Record<string, string> = {
+  CACHE: `${DEFAULT_WORKER_NAME}-cache`,
+};
+
+/** Dimensions of a Vectorize index this kit provisions. */
+export const VECTORIZE_DIMENSIONS = 1024;
+
+/**
+ * The parsed shape of a wrangler config.
+ *
+ * `vars` is widened with `null` on purpose: jsonc-parser yields `null` for an
+ * explicit `vars: null`, and the vars-patch path must be able to reject that
+ * rather than treat the field as absent.
+ */
+export interface WranglerConfig {
+  name?: string;
+  $version?: number;
+  vars?: Record<string, unknown> | null;
+  d1_databases?: Array<{
+    binding?: string;
+    database_id?: string;
+    database_name?: string;
+  }>;
+  kv_namespaces?: Array<{
+    binding?: string;
+    id?: string;
+  }>;
+  secrets_store_secrets?: Array<{
+    binding?: string;
+    store_id?: string;
+    secret_name?: string;
+  }>;
+  queues?: {
+    producers?: Array<{ binding: string; queue: string }>;
+    consumers?: Array<{ queue: string }>;
+  };
+  vectorize?: Array<{
+    binding: string;
+    index_name: string;
+  }>;
+}
+
+/** A D1 database as `wrangler d1 list --json` reports one. */
+export interface D1Database {
+  name?: string;
+  uuid?: string;
+  id?: string;
+  database_id?: string;
+}
+
+/** A KV namespace as `wrangler kv namespace list` reports one. */
+export interface KVNamespace {
+  title?: string;
+  name?: string;
+  id?: string;
+}
+
+/** A Secrets Store as `wrangler secrets-store store list` reports one. */
+export interface SecretStore {
+  name: string;
+  id: string;
+}

package/src/test/integration-migrations.test.ts

@@ -0,0 +1,169 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterAll, describe, expect, it } from 'vitest';
+import { createMigrationHelper, executableStatements, readMigrationFiles, splitSql, type D1DatabaseLike, type D1PreparedStatementLike, type MigrationFile } from './integration-migrations';
+
+const created: string[] = [];
+
+function tempTree(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), 'migrations-'));
+  created.push(root);
+  for (const [name, content] of Object.entries(files)) {
+    const path = join(root, name);
+    mkdirSync(join(path, '..'), { recursive: true });
+    writeFileSync(path, content, 'utf8');
+  }
+  return root;
+}
+
+afterAll(() => {
+  for (const root of created) rmSync(root, { recursive: true, force: true });
+});
+
+/**
+ * A fake D1: records what it was asked to run, and refuses a statement it does not
+ * recognise, so a suite can assert the helper split the file the way SQLite would
+ * have to.
+ */
+function fakeD1(options: { batch?: boolean } = {}): D1DatabaseLike & { ran: string[] } {
+  const ran: string[] = [];
+  const prepare = (sql: string): D1PreparedStatementLike => ({
+    run: async () => {
+      ran.push(sql);
+    },
+  });
+  const base: D1DatabaseLike & { ran: string[] } = { prepare, ran };
+  if (options.batch !== false) {
+    return {
+      ...base,
+      batch: async (statements) => {
+        for (const statement of statements) await statement.run();
+      },
+    };
+  }
+  return base;
+}
+
+describe('readMigrationFiles', () => {
+  it('reads every .sql file in apply order, and ignores the lock', () => {
+    const dir = tempTree({
+      'migrations.lock.json': '{}',
+      '0002_more.sql': 'SELECT 2;',
+      '0001_init.sql': 'SELECT 1;',
+      'notes.md': 'ignored',
+    });
+    expect(readMigrationFiles(dir).map((file) => file.name)).toStrictEqual(['0001_init.sql', '0002_more.sql']);
+  });
+});
+
+describe('splitSql', () => {
+  it('splits on semicolons outside strings and comments', () => {
+    expect(splitSql('SELECT 1; SELECT 2;')).toStrictEqual(['SELECT 1', 'SELECT 2']);
+  });
+
+  it('keeps semicolons inside quoted strings', () => {
+    expect(splitSql("INSERT INTO t VALUES ('a;b');")).toStrictEqual(["INSERT INTO t VALUES ('a;b')"]);
+  });
+
+  it('keeps doubled-quote escapes inside strings', () => {
+    expect(splitSql("INSERT INTO t VALUES ('it''s; fine');")).toStrictEqual(["INSERT INTO t VALUES ('it''s; fine')"]);
+  });
+
+  it('folds comment-only runs into one statement the executable filter drops', () => {
+    // The splitter does not judge executability — it only knows statement
+    // boundaries. Comments stay attached to the statement they sit above; a
+    // comment-only run comes back as its comment text, and the executable filter
+    // (isExecutable) is what keeps it off the wire.
+    const sql = '-- a note about the migration;\nCREATE TABLE a (id TEXT);\n/* trailing block */;';
+    expect(splitSql(sql)).toStrictEqual(['-- a note about the migration;\nCREATE TABLE a (id TEXT)', '/* trailing block */']);
+    expect(executableStatements(sql)).toStrictEqual(['-- a note about the migration;\nCREATE TABLE a (id TEXT)']);
+  });
+
+  it('does not split inside a CREATE TRIGGER body', () => {
+    const sql = `CREATE TRIGGER t AFTER INSERT ON x BEGIN UPDATE y SET a = 1; UPDATE y SET b = 2; END;`;
+    // Statements come back trimmed, without the terminating semicolon.
+    expect(splitSql(sql)).toStrictEqual(['CREATE TRIGGER t AFTER INSERT ON x BEGIN UPDATE y SET a = 1; UPDATE y SET b = 2; END']);
+  });
+
+  it('does not treat a table named trigger as a trigger body', () => {
+    const sql = 'CREATE TABLE trigger (id TEXT); INSERT INTO trigger VALUES (1);';
+    expect(splitSql(sql)).toStrictEqual(['CREATE TABLE trigger (id TEXT)', 'INSERT INTO trigger VALUES (1)']);
+  });
+});
+
+describe('createMigrationHelper', () => {
+  it('applies every file, in order, once per database', async () => {
+    const dir = tempTree({ '0001_init.sql': 'CREATE TABLE a (id TEXT);', '0002_more.sql': 'CREATE TABLE b (id TEXT);' });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    const db = fakeD1();
+
+    await helper.applyMigrations(db);
+    await helper.applyMigrations(db);
+
+    expect(db.ran).toStrictEqual(['CREATE TABLE a (id TEXT)', 'CREATE TABLE b (id TEXT)']);
+  });
+
+  it('applies a closed range by filename, and can start from a pre-migration shape', async () => {
+    const dir = tempTree({
+      '0001_init.sql': 'CREATE TABLE a (id TEXT);',
+      '0002_upgrade.sql': 'ALTER TABLE a ADD COLUMN email TEXT;',
+      '0003_more.sql': 'CREATE TABLE c (id TEXT);',
+    });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    const db = fakeD1();
+
+    await helper.applyMigrations(db, { to: '0001_init.sql' });
+    expect(db.ran).toStrictEqual(['CREATE TABLE a (id TEXT)']);
+
+    await helper.applyMigrations(db, { from: '0002_upgrade.sql' });
+    // `from` without `to` runs to the end of the set — 0002 and 0003 both.
+    expect(db.ran).toStrictEqual(['CREATE TABLE a (id TEXT)', 'ALTER TABLE a ADD COLUMN email TEXT', 'CREATE TABLE c (id TEXT)']);
+  });
+
+  it('falls back to a per-statement loop when the binding cannot batch', async () => {
+    const dir = tempTree({ '0001_init.sql': 'CREATE TABLE a (id TEXT); CREATE TABLE b (id TEXT);' });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    const db = fakeD1({ batch: false });
+
+    await helper.applyMigrations(db);
+
+    expect(db.ran).toStrictEqual(['CREATE TABLE a (id TEXT)', 'CREATE TABLE b (id TEXT)']);
+    expect('batch' in db).toBe(false);
+  });
+
+  it('names the file and the statement when a batch fails', async () => {
+    const dir = tempTree({ '0001_init.sql': 'CREATE TABLE a (id TEXT);' });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    const db: D1DatabaseLike = {
+      prepare: () => ({ run: async () => undefined }),
+      batch: async () => {
+        throw new Error('no such table: a');
+      },
+    };
+
+    await expect(helper.applyMigrations(db)).rejects.toThrow(/0001_init\.sql: batch of 1 statements failed/);
+  });
+
+  it('refuses an unknown range endpoint, naming what is available', async () => {
+    const dir = tempTree({ '0001_init.sql': 'SELECT 1;' });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    await expect(helper.applyMigrations(fakeD1(), { from: '0009_missing.sql' })).rejects.toThrow(/Unknown migration file: 0009_missing\.sql/);
+  });
+
+  it('reports one file\'s SQL without reading the others', () => {
+    const dir = tempTree({ '0001_init.sql': 'SELECT 1;', '0002_more.sql': 'SELECT 2;' });
+    const helper = createMigrationHelper({ migrationsDir: dir });
+    expect(helper.migrationSqlOf('0002_more.sql')).toBe('SELECT 2;');
+    expect(helper.migrationSql()).toBe('SELECT 1;\nSELECT 2;');
+    expect(helper.migrationFileNames()).toStrictEqual(['0001_init.sql', '0002_more.sql']);
+  });
+
+  it('accepts injected files, for a harness that embeds the SQL at build time', async () => {
+    const files: MigrationFile[] = [{ name: 'all.sql', sql: 'CREATE TABLE a (id TEXT);' }];
+    const helper = createMigrationHelper({ migrationsDir: '/nonexistent', files });
+    const db = fakeD1();
+    await helper.applyMigrations(db);
+    expect(db.ran).toStrictEqual(['CREATE TABLE a (id TEXT)']);
+  });
+});