@pikku/migrator-sql 0.12.2

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# @pikku/migrator-sql
+
+## 0.12.2
+
+### Patch Changes
+
+- f970f8f: Rename `@pikku/db-migrator` to `@pikku/migrator-sql`.
+
+  It applies `.sql` files and keeps their bookkeeping; it is not a database
+  service, and `db-` read as though it were one. Nothing was ever published under
+  the old name, so there is no alias to keep.
+
+## 0.12.1
+
+### Patch Changes
+
+- a057bec: Extract the SQL migration applier into `@pikku/migrator-sql`, so the CLI is no longer the only thing that can run one.
+
+  A shipped standalone bundle has to apply the same migrations to the same database as `pikku db migrate`, from a machine with no checkout. That only works if both agree on the bookkeeping table, the file hash and the file order — a second implementation that differs in any of the three reads every migration the other applied as drifted and refuses to go on.
+
+  Nothing about the CLI's behaviour changes; the algorithm, the `sql_migrations` table and the drift error moved intact.
+
+- a057bec: Give a standalone bundle a command line.
+
+  An operator holding a standalone artifact on a machine had one thing they could
+  do with it: start it. Applying the migrations it needs meant a checkout of the
+  project and a second copy of the CLI on a production box, and answering "which
+  build is this" meant asking whoever ran the deploy.
+
+  The bundle now takes a command. `serve` remains the default, so an existing
+  `node bundle.js` is unchanged. `version` prints the version the project declared
+  at build time. `db migrate` and `db status` apply and report the migrations that
+  now ship beside the bundle under `db/<engine>/` — the same path Fabric's build
+  container stages them to, so the two producers of an artifact cannot disagree
+  about where the SQL lives. `backup <path>` writes a consistent copy of a SQLite
+  database with `VACUUM INTO`; on postgres it refuses and names `pg_dump`, which
+  is the tool for it.
+
+  Both engines are supported: a postgres build migrates over the connection it
+  already opens. `PostgresMigrationClient` grew an optional `begin`, because a
+  pooled client is free to answer `BEGIN`, the migration and `COMMIT` on three
+  different connections — which leaves a failed migration half applied with
+  nothing to roll back.
+
+  There is deliberately no way to invoke an RPC. A running server already answers
+  them with auth, sessions and middleware applied; an in-process invoke would
+  answer them with none of that.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The SQL migration applier, and nothing that knows where it is running.
+ *
+ * Two programs apply the same migrations to the same database: `pikku db
+ * migrate` from a checkout, and a shipped standalone bundle from a machine that
+ * has no checkout. They have to agree on the bookkeeping table, the hash, and
+ * the file order, because the second runs against a database the first has
+ * already written to — a second implementation that differs in any of the three
+ * reports every migration the other applied as drifted.
+ */
+export { migrate, baselineMigrations, pendingMigrations, MigrationDriftError, MIGRATION_TRACKING_TABLE, type MigrationExecutor, type MigrateResult, type AppliedMigration, } from './sql-migrator.js';
+export { assertSnakeCaseIdentifiers, findCamelCaseIdentifiers, stripSqlComments, CamelCaseIdentifierError, type CamelCaseIdentifier, } from './migration-identifiers.js';
+export { splitStatements, bareTableName, tableCreationSql, } from './schema-sql.js';

package/dist/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * The SQL migration applier, and nothing that knows where it is running.
+ *
+ * Two programs apply the same migrations to the same database: `pikku db
+ * migrate` from a checkout, and a shipped standalone bundle from a machine that
+ * has no checkout. They have to agree on the bookkeeping table, the hash, and
+ * the file order, because the second runs against a database the first has
+ * already written to — a second implementation that differs in any of the three
+ * reports every migration the other applied as drifted.
+ */
+export { migrate, baselineMigrations, pendingMigrations, MigrationDriftError, MIGRATION_TRACKING_TABLE, } from './sql-migrator.js';
+export { assertSnakeCaseIdentifiers, findCamelCaseIdentifiers, stripSqlComments, CamelCaseIdentifierError, } from './migration-identifiers.js';
+export { splitStatements, bareTableName, tableCreationSql, } from './schema-sql.js';

package/dist/src/migration-identifiers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Catching camelCase columns at migrate time, before they can half-work.
+ *
+ * Pikku's Kysely runs with `CamelCasePlugin`, so `priceCents` in TypeScript is
+ * `price_cents` in SQL and nothing else. A migration that declares the column
+ * *as* `priceCents` is not merely unconventional — it is broken in the one way
+ * that hides itself: `.selectAll()` compiles to `SELECT *` and never names an
+ * identifier, so the table reads back perfectly, while the first query that
+ * names the column (`.select(['animal.priceCents'])`) asks for `price_cents`
+ * and gets `no such column`. The usual conclusion is that the plugin is broken,
+ * and the usual response is a raw `sql` template or a retreat to `.selectAll()`
+ * — both of which keep the real cause alive.
+ *
+ * There is no exception to escape. Even the Better Auth schema `db generate`
+ * writes is snake_case (`email_verified`, `user_id`), because Better Auth is
+ * handed the app's own Kysely and its camelCase field names compile the same
+ * way everyone else's do.
+ */
+/** A camelCase identifier a migration declares, and what it should have said. */
+export interface CamelCaseIdentifier {
+    file: string;
+    table: string;
+    /** `null` when the table name itself is the offender. */
+    column: string | null;
+    suggestion: string;
+}
+export declare class CamelCaseIdentifierError extends Error {
+    readonly offenders: CamelCaseIdentifier[];
+    constructor(offenders: CamelCaseIdentifier[]);
+}
+/**
+ * Strip comments so a word in prose can never be read as an identifier.
+ *
+ * `splitStatements` already skips over comments when it looks for a boundary,
+ * but it hands back the statement with them still in it, and `-- the userId
+ * column` would otherwise be flagged. Quoting rules are honoured for the same
+ * reason they are there: `'a -- b'` is a string, not a comment.
+ */
+export declare function stripSqlComments(sql: string): string;
+/**
+ * Every camelCase identifier one migration file declares.
+ *
+ * Only declarations are read — a `CREATE TABLE` column list and an `ALTER TABLE
+ * … ADD COLUMN`. Everywhere else an identifier merely refers to something that
+ * was declared somewhere, and reporting those would name the same mistake once
+ * per reference while adding nothing to the fix.
+ */
+export declare function findCamelCaseIdentifiers(file: string, sql: string): CamelCaseIdentifier[];
+/**
+ * Bail unless every migration on disk is snake_case throughout.
+ *
+ * Reports all of them at once: a camelCase column is rarely alone, and a
+ * one-at-a-time failure turns a single edit into one migrate run per column.
+ */
+export declare function assertSnakeCaseIdentifiers(migrations: Array<{
+    name: string;
+    sql: string;
+}>): void;

package/dist/src/migration-identifiers.js

@@ -0,0 +1,262 @@
+/**
+ * Catching camelCase columns at migrate time, before they can half-work.
+ *
+ * Pikku's Kysely runs with `CamelCasePlugin`, so `priceCents` in TypeScript is
+ * `price_cents` in SQL and nothing else. A migration that declares the column
+ * *as* `priceCents` is not merely unconventional — it is broken in the one way
+ * that hides itself: `.selectAll()` compiles to `SELECT *` and never names an
+ * identifier, so the table reads back perfectly, while the first query that
+ * names the column (`.select(['animal.priceCents'])`) asks for `price_cents`
+ * and gets `no such column`. The usual conclusion is that the plugin is broken,
+ * and the usual response is a raw `sql` template or a retreat to `.selectAll()`
+ * — both of which keep the real cause alive.
+ *
+ * There is no exception to escape. Even the Better Auth schema `db generate`
+ * writes is snake_case (`email_verified`, `user_id`), because Better Auth is
+ * handed the app's own Kysely and its camelCase field names compile the same
+ * way everyone else's do.
+ */
+import { splitStatements } from './schema-sql.js';
+export class CamelCaseIdentifierError extends Error {
+    offenders;
+    constructor(offenders) {
+        const lines = offenders.map((o) => `  ${o.file}  ${o.column === null ? o.table : `${o.table}.${o.column}`}  →  ${o.suggestion}`);
+        super(`[PKU-DB-CAMEL] Migrations declare camelCase identifiers.\n\n` +
+            `Pikku's Kysely runs with CamelCasePlugin, which maps camelCase in TypeScript\n` +
+            `to snake_case in SQL. A camelCase column half-works: \`.selectAll()\` emits\n` +
+            `\`SELECT *\` so the table reads fine, but naming the column compiles it to\n` +
+            `snake_case and the database answers \`no such column\`.\n\n` +
+            `${lines.join('\n')}\n\n` +
+            `Fix the column definition in the migration file itself and replay your dev\n` +
+            `database from scratch. Do not write a RENAME COLUMN migration — that leaves\n` +
+            `the banned identifier in a SQL file forever.`);
+        this.offenders = offenders;
+        this.name = 'CamelCaseIdentifierError';
+    }
+}
+/**
+ * Strip comments so a word in prose can never be read as an identifier.
+ *
+ * `splitStatements` already skips over comments when it looks for a boundary,
+ * but it hands back the statement with them still in it, and `-- the userId
+ * column` would otherwise be flagged. Quoting rules are honoured for the same
+ * reason they are there: `'a -- b'` is a string, not a comment.
+ */
+export function stripSqlComments(sql) {
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            const start = i;
+            i++;
+            while (i < sql.length) {
+                if (sql[i] === '\\' && ch === "'") {
+                    i += 2;
+                    continue;
+                }
+                if (sql[i] === ch) {
+                    if (sql[i + 1] === ch) {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            out += sql.slice(start, i);
+            continue;
+        }
+        if (ch === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i);
+            i = end === -1 ? sql.length : end;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            i = end === -1 ? sql.length : end + 2;
+            // A block comment can span lines, and removing it outright would join two
+            // statements onto one line. A space keeps the tokens either side apart.
+            out += ' ';
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+const IDENTIFIER = String.raw `"[^"]*"|\`[^\`]*\`|\[[^\]]*\]|[A-Za-z_][A-Za-z_0-9$]*`;
+const CREATE_TABLE = new RegExp(String.raw `^CREATE\s+(?:TEMP(?:ORARY)?\s+|UNLOGGED\s+)*TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(\S+?)\s*\(`, 'i');
+const ALTER_TABLE = new RegExp(String.raw `^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:ONLY\s+)?(\S+)`, 'i');
+const ADD_COLUMN = new RegExp(String.raw `^\s*ADD\s+(?:COLUMN\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(${IDENTIFIER})`, 'i');
+const COLUMN_NAME = new RegExp(String.raw `^\s*(${IDENTIFIER})`);
+/**
+ * The words that open a table-level constraint rather than a column.
+ *
+ * Only consulted for an unquoted first token: `"check"` in quotes is a column
+ * named check, however unwise, and skipping it would let `"checkedAt"`'s
+ * neighbours hide behind it.
+ */
+const CONSTRAINT_KEYWORDS = new Set([
+    'constraint',
+    'primary',
+    'foreign',
+    'unique',
+    'check',
+    'exclude',
+    'index',
+    'key',
+    'like',
+    'period',
+    'fulltext',
+    'spatial',
+]);
+/** Drop the quoting a dialect happens to use, leaving the identifier itself. */
+const unquote = (name) => /^["`[]/.test(name) ? name.slice(1, -1) : name;
+const isCamelCase = (name) => /[a-z][A-Z]/.test(name);
+const toSnakeCase = (name) => name.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+/**
+ * Walk `sql` from `from` and return the offsets just inside and just outside
+ * the parenthesised group that starts there, or `null` if it never closes.
+ *
+ * Quote-aware, because a `)` inside `DEFAULT ')'` closes nothing.
+ */
+function parenSpan(sql, from) {
+    let depth = 0;
+    let i = from;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i++;
+            while (i < sql.length && sql[i] !== ch)
+                i++;
+            i++;
+            continue;
+        }
+        if (ch === '(') {
+            depth++;
+            if (depth === 1)
+                from = i + 1;
+        }
+        else if (ch === ')') {
+            depth--;
+            if (depth === 0)
+                return { start: from, end: i };
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * Split a definition list on the commas that separate its items.
+ *
+ * The commas inside `NUMERIC(10,2)`, a `CHECK (x IN ('a','b'))` or a compound
+ * `PRIMARY KEY (a, b)` belong to those and not to the list, so only depth zero
+ * counts.
+ */
+function splitTopLevel(list) {
+    const items = [];
+    let depth = 0;
+    let start = 0;
+    let i = 0;
+    while (i < list.length) {
+        const ch = list[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i++;
+            while (i < list.length && list[i] !== ch)
+                i++;
+            i++;
+            continue;
+        }
+        if (ch === '(')
+            depth++;
+        else if (ch === ')')
+            depth--;
+        else if (ch === ',' && depth === 0) {
+            items.push(list.slice(start, i));
+            start = i + 1;
+        }
+        i++;
+    }
+    items.push(list.slice(start));
+    return items.filter((item) => item.trim().length > 0);
+}
+/**
+ * Every camelCase identifier one migration file declares.
+ *
+ * Only declarations are read — a `CREATE TABLE` column list and an `ALTER TABLE
+ * … ADD COLUMN`. Everywhere else an identifier merely refers to something that
+ * was declared somewhere, and reporting those would name the same mistake once
+ * per reference while adding nothing to the fix.
+ */
+export function findCamelCaseIdentifiers(file, sql) {
+    const offenders = [];
+    for (const statement of splitStatements(stripSqlComments(sql))) {
+        const create = CREATE_TABLE.exec(statement);
+        if (create) {
+            const table = unquote(create[1].split('.').pop());
+            if (isCamelCase(table)) {
+                offenders.push({
+                    file,
+                    table,
+                    column: null,
+                    suggestion: toSnakeCase(table),
+                });
+            }
+            const span = parenSpan(statement, create.index + create[0].length - 1);
+            if (!span)
+                continue;
+            for (const item of splitTopLevel(statement.slice(span.start, span.end))) {
+                const name = COLUMN_NAME.exec(item)?.[1];
+                if (!name)
+                    continue;
+                if (CONSTRAINT_KEYWORDS.has(name.toLowerCase()))
+                    continue;
+                const column = unquote(name);
+                if (isCamelCase(column)) {
+                    offenders.push({
+                        file,
+                        table,
+                        column,
+                        suggestion: toSnakeCase(column),
+                    });
+                }
+            }
+            continue;
+        }
+        const alter = ALTER_TABLE.exec(statement);
+        if (!alter)
+            continue;
+        const table = unquote(alter[1].split('.').pop());
+        // Postgres lets one ALTER carry several actions, and only the ADDs declare.
+        for (const action of splitTopLevel(statement.slice(alter[0].length).replace(/;\s*$/, ''))) {
+            const name = ADD_COLUMN.exec(action)?.[1];
+            if (!name)
+                continue;
+            if (CONSTRAINT_KEYWORDS.has(name.toLowerCase()))
+                continue;
+            const column = unquote(name);
+            if (isCamelCase(column)) {
+                offenders.push({
+                    file,
+                    table,
+                    column,
+                    suggestion: toSnakeCase(column),
+                });
+            }
+        }
+    }
+    return offenders;
+}
+/**
+ * Bail unless every migration on disk is snake_case throughout.
+ *
+ * Reports all of them at once: a camelCase column is rarely alone, and a
+ * one-at-a-time failure turns a single edit into one migrate run per column.
+ */
+export function assertSnakeCaseIdentifiers(migrations) {
+    const offenders = migrations.flatMap(({ name, sql }) => findCamelCaseIdentifiers(name, sql));
+    if (offenders.length > 0)
+        throw new CamelCaseIdentifierError(offenders);
+}

package/dist/src/postgres/index.d.ts

@@ -0,0 +1 @@
+export { PostgresMigrationExecutor, type PostgresMigrationClient, } from './postgres-migrator.js';

package/dist/src/postgres/index.js

@@ -0,0 +1 @@
+export { PostgresMigrationExecutor, } from './postgres-migrator.js';

package/dist/src/postgres/postgres-migrator.d.ts

@@ -0,0 +1,27 @@
+import type { MigrationExecutor, AppliedMigration } from '../sql-migrator.js';
+export interface PostgresMigrationClient {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec?(sql: string): Promise<unknown>;
+    /**
+     * Run a migration and its bookkeeping row on one connection.
+     *
+     * A pooled client is free to answer `BEGIN`, the migration and `COMMIT` on
+     * three different connections, which leaves a transaction open on one and the
+     * DDL committed outside it on another — a failed migration then stays half
+     * applied with nothing to roll back. A client that hands out a connection
+     * implements this; one that only ever has a single connection does not need
+     * to, and the statement pair below is correct for it.
+     */
+    begin?<T>(handler: (client: PostgresMigrationClient) => Promise<T>): Promise<T>;
+}
+export declare class PostgresMigrationExecutor implements MigrationExecutor {
+    private readonly client;
+    constructor(client: PostgresMigrationClient);
+    ensureTrackingTable(): Promise<void>;
+    getApplied(): Promise<AppliedMigration[]>;
+    recordMigration(name: string, hash: string): Promise<void>;
+    runMigration(sql: string, name: string, hash: string): Promise<void>;
+    private applyOn;
+}

package/dist/src/postgres/postgres-migrator.js

@@ -0,0 +1,49 @@
+import { MIGRATION_TRACKING_TABLE as TRACKING_TABLE } from '../sql-migrator.js';
+export class PostgresMigrationExecutor {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async ensureTrackingTable() {
+        await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+        name       TEXT PRIMARY KEY,
+        hash       TEXT NOT NULL,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `);
+    }
+    async getApplied() {
+        const { rows } = await this.client.query(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`);
+        return rows;
+    }
+    async recordMigration(name, hash) {
+        await this.client.query(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES ($1, $2)`, [name, hash]);
+    }
+    async runMigration(sql, name, hash) {
+        if (typeof this.client.begin === 'function') {
+            await this.client.begin(async (tx) => {
+                await this.applyOn(tx, sql, name, hash);
+            });
+            return;
+        }
+        await this.client.query('BEGIN');
+        try {
+            await this.applyOn(this.client, sql, name, hash);
+            await this.client.query('COMMIT');
+        }
+        catch (err) {
+            await this.client.query('ROLLBACK');
+            throw err;
+        }
+    }
+    async applyOn(client, sql, name, hash) {
+        if (typeof client.exec === 'function') {
+            await client.exec(sql);
+        }
+        else {
+            await client.query(sql);
+        }
+        await client.query(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES ($1, $2)`, [name, hash]);
+    }
+}

package/dist/src/schema-sql.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading a schema source's own SQL back out, one table at a time.
+ *
+ * A source hands `db generate` both what must exist (`tables`) and what creates
+ * it (`sql`). The column map is a comparison surface — it answers "is this
+ * table there, and does it have these columns" — and it is deliberately lossy:
+ * primary keys, foreign keys, uniqueness, check constraints and indexes are all
+ * absent from it. So the moment the generator has to *create* something, the
+ * only honest source is the SQL, and this is what pulls the relevant part of it
+ * out.
+ */
+/**
+ * Split a SQL script into its top-level statements, semicolons included.
+ *
+ * A naive `split(';')` is wrong in a way that only shows up later: a semicolon
+ * inside a string literal, a quoted identifier or a comment is not a statement
+ * boundary, and cutting there yields two fragments that are each valid-looking
+ * and neither of which does what the original did.
+ */
+export declare function splitStatements(sql: string): string[];
+/**
+ * Reduce a written table name to the form two sources can be compared on.
+ *
+ * The same table is `two_factor` to one writer, `"two_factor"` to Kysely and
+ * `public.two_factor` to Postgres introspection. Dropping the schema qualifier,
+ * the quoting and the case is the only shape all three agree on.
+ */
+export declare function bareTableName(name: string): string;
+/**
+ * Every statement in `sql` that builds `table`, in the order the source wrote
+ * them.
+ *
+ * The `CREATE TABLE` and its indexes, plus any `ALTER TABLE` the source uses to
+ * hang a constraint on it afterwards — which together are what the column list
+ * cannot express. Source order is preserved because it is load-bearing: an
+ * index cannot precede its table, and a table cannot precede one it references.
+ *
+ * An empty result means the source's SQL does not visibly create the table.
+ * That is a real answer rather than a failure — a source may create a table
+ * from something other than a literal `CREATE TABLE` — and the caller is
+ * expected to fall back rather than emit nothing.
+ */
+export declare function tableCreationSql(sql: string, table: string): string[];

package/dist/src/schema-sql.js

@@ -0,0 +1,135 @@
+/**
+ * Reading a schema source's own SQL back out, one table at a time.
+ *
+ * A source hands `db generate` both what must exist (`tables`) and what creates
+ * it (`sql`). The column map is a comparison surface — it answers "is this
+ * table there, and does it have these columns" — and it is deliberately lossy:
+ * primary keys, foreign keys, uniqueness, check constraints and indexes are all
+ * absent from it. So the moment the generator has to *create* something, the
+ * only honest source is the SQL, and this is what pulls the relevant part of it
+ * out.
+ */
+/**
+ * Split a SQL script into its top-level statements, semicolons included.
+ *
+ * A naive `split(';')` is wrong in a way that only shows up later: a semicolon
+ * inside a string literal, a quoted identifier or a comment is not a statement
+ * boundary, and cutting there yields two fragments that are each valid-looking
+ * and neither of which does what the original did.
+ */
+export function splitStatements(sql) {
+    const statements = [];
+    let start = 0;
+    let i = 0;
+    const closeQuote = (quote) => {
+        i++;
+        while (i < sql.length) {
+            if (sql[i] === '\\' && quote === "'") {
+                i += 2;
+                continue;
+            }
+            if (sql[i] === quote) {
+                // A doubled quote is an escaped one, not the end of the literal.
+                if (sql[i + 1] === quote) {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                return;
+            }
+            i++;
+        }
+    };
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            closeQuote(ch);
+            continue;
+        }
+        if (ch === '-' && sql[i + 1] === '-') {
+            const end = sql.indexOf('\n', i);
+            i = end === -1 ? sql.length : end + 1;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            const end = sql.indexOf('*/', i + 2);
+            i = end === -1 ? sql.length : end + 2;
+            continue;
+        }
+        // Postgres dollar quoting: everything between `$tag$` and its twin is a
+        // literal, and a function body written that way is full of semicolons.
+        if (ch === '$') {
+            const tag = /^\$[A-Za-z_0-9]*\$/.exec(sql.slice(i));
+            if (tag) {
+                const end = sql.indexOf(tag[0], i + tag[0].length);
+                i = end === -1 ? sql.length : end + tag[0].length;
+                continue;
+            }
+        }
+        if (ch === ';') {
+            const statement = sql.slice(start, i + 1).trim();
+            if (statement.length > 1)
+                statements.push(statement);
+            start = i + 1;
+        }
+        i++;
+    }
+    // A script whose last statement has no trailing semicolon still ran it.
+    const tail = sql.slice(start).trim();
+    if (tail.length > 0)
+        statements.push(tail);
+    return statements;
+}
+/**
+ * Reduce a written table name to the form two sources can be compared on.
+ *
+ * The same table is `two_factor` to one writer, `"two_factor"` to Kysely and
+ * `public.two_factor` to Postgres introspection. Dropping the schema qualifier,
+ * the quoting and the case is the only shape all three agree on.
+ */
+export function bareTableName(name) {
+    const last = name.split('.').pop() ?? name;
+    return last.replace(/^["'`[]|["'`\]]$/g, '').toLowerCase();
+}
+const CREATE_TABLE = /^CREATE\s+(?:TEMP(?:ORARY)?\s+|UNLOGGED\s+)*TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([^\s(]+)/i;
+const CREATE_INDEX = /^CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?\S+\s+ON\s+(?:ONLY\s+)?([^\s(]+)/i;
+const ALTER_TABLE = /^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:ONLY\s+)?([^\s(]+)/i;
+/**
+ * Every statement in `sql` that builds `table`, in the order the source wrote
+ * them.
+ *
+ * The `CREATE TABLE` and its indexes, plus any `ALTER TABLE` the source uses to
+ * hang a constraint on it afterwards — which together are what the column list
+ * cannot express. Source order is preserved because it is load-bearing: an
+ * index cannot precede its table, and a table cannot precede one it references.
+ *
+ * An empty result means the source's SQL does not visibly create the table.
+ * That is a real answer rather than a failure — a source may create a table
+ * from something other than a literal `CREATE TABLE` — and the caller is
+ * expected to fall back rather than emit nothing.
+ */
+export function tableCreationSql(sql, table) {
+    const wanted = bareTableName(table);
+    const statements = [];
+    let creates = false;
+    for (const statement of splitStatements(sql)) {
+        const create = CREATE_TABLE.exec(statement);
+        if (create && bareTableName(create[1]) === wanted) {
+            creates = true;
+            statements.push(statement);
+            continue;
+        }
+        const index = CREATE_INDEX.exec(statement);
+        if (index && bareTableName(index[1]) === wanted) {
+            statements.push(statement);
+            continue;
+        }
+        const alter = ALTER_TABLE.exec(statement);
+        if (alter && bareTableName(alter[1]) === wanted) {
+            statements.push(statement);
+        }
+    }
+    // Indexes and alters without the table they belong to would fail on their own,
+    // and their presence says the table came from somewhere this cannot read.
+    return creates ? statements : [];
+}

package/dist/src/sql-migrator.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export declare const MIGRATION_TRACKING_TABLE = "sql_migrations";
+export declare class MigrationDriftError extends Error {
+    readonly file: string;
+    readonly recordedHash: string;
+    readonly currentHash: string | null;
+    readonly appliedAt: string;
+    constructor(file: string, recordedHash: string, currentHash: string | null, appliedAt: string, migrationsDir: string);
+}
+export interface MigrateResult {
+    applied: string[];
+    skipped: string[];
+}
+export interface AppliedMigration {
+    name: string;
+    hash: string;
+    applied_at: string;
+}
+/**
+ * Provider-agnostic migration executor. Implement this for each DB dialect.
+ * Each method maps to a single DB operation; all file I/O and hashing lives
+ * in the shared `migrate()` function above.
+ */
+export interface MigrationExecutor {
+    ensureTrackingTable(): Promise<void>;
+    getApplied(): Promise<AppliedMigration[]>;
+    runMigration(sql: string, name: string, hash: string): Promise<void>;
+    /**
+     * Record a migration as applied without running its SQL.
+     *
+     * For a database that already contains what the migration describes, because
+     * something created those tables before anyone wrote them down. Only ever
+     * called once the caller has confirmed that is actually true — recording a
+     * migration whose tables are absent leaves a database permanently behind with
+     * no pending migration to reveal it.
+     */
+    recordMigration(name: string, hash: string): Promise<void>;
+}
+export declare function migrate(executor: MigrationExecutor, migrationsDir: string): Promise<MigrateResult>;
+/**
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
+ */
+/**
+ * The migrations on disk that the database has not recorded.
+ *
+ * Deliberately not derived by the caller: "pending" has to mean the same set
+ * `migrate` is about to apply, and that is filename order over `*.sql` minus
+ * what is recorded — not whatever a directory listing happens to return.
+ */
+export declare function pendingMigrations(migrationsDir: string, applied: AppliedMigration[]): string[];
+export declare function baselineMigrations(executor: MigrationExecutor, migrationsDir: string): Promise<string[]>;

package/dist/src/sql-migrator.js

@@ -0,0 +1,147 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertSnakeCaseIdentifiers } from './migration-identifiers.js';
+/**
+ * The migrator's own bookkeeping table, which belongs to no dialect and to no
+ * project's schema.
+ *
+ * Every introspector hides it for that reason. Leaving it visible on one
+ * dialect and not the other is not cosmetic: a schema source exported from a
+ * database that has been migrated would publish `sql_migrations` as one of its
+ * own tables, and the consumer — which also has it — would then read the source
+ * as partially covered and emit column deltas instead of the source's own SQL,
+ * silently dropping its primary keys, indexes and constraints.
+ */
+export const MIGRATION_TRACKING_TABLE = 'sql_migrations';
+export class MigrationDriftError extends Error {
+    file;
+    recordedHash;
+    currentHash;
+    appliedAt;
+    constructor(file, recordedHash, currentHash, appliedAt, migrationsDir) {
+        const onDisk = currentHash === null
+            ? 'file missing on disk'
+            : `sha256:${currentHash.slice(0, 8)}…`;
+        super(`[PKU-DB-DRIFT] ${migrationsDir}/${file}\n\n` +
+            `Migration content has changed since it was applied.\n` +
+            `  recorded:  sha256:${recordedHash.slice(0, 8)}…  applied ${appliedAt}\n` +
+            `  on disk:   ${onDisk}\n\n` +
+            `If this edit was intentional, write a new forward migration to revert the change.\n` +
+            `Production migrations are immutable.`);
+        this.file = file;
+        this.recordedHash = recordedHash;
+        this.currentHash = currentHash;
+        this.appliedAt = appliedAt;
+        this.name = 'MigrationDriftError';
+    }
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * Apply pending migrations from `migrationsDir/*.sql` using the supplied
+ * executor. Hashes raw file bytes on apply; subsequent runs re-hash and bail
+ * with `MigrationDriftError` if any applied file has changed on disk.
+ */
+/**
+ * The migrations on disk, or none.
+ *
+ * A project that has never generated a migration has no directory to read, and
+ * that is the ordinary first-run state rather than a failure — it is precisely
+ * the project `db generate` exists to serve.
+ */
+const migrationFiles = (migrationsDir) => existsSync(migrationsDir)
+    ? readdirSync(migrationsDir)
+        .filter((f) => f.endsWith('.sql'))
+        .sort()
+    : [];
+/**
+ * Re-hash every applied migration and bail if one has changed on disk.
+ *
+ * Applies to baselining as much as to migrating: recording a file as applied
+ * only means anything if the file is still the one that was applied.
+ */
+function assertNoDrift(applied, migrationsDir) {
+    for (const row of applied) {
+        let currentHash = null;
+        try {
+            currentHash = sha256(readFileSync(join(migrationsDir, row.name)));
+        }
+        catch {
+            currentHash = null;
+        }
+        if (currentHash !== row.hash) {
+            throw new MigrationDriftError(row.name, row.hash, currentHash, row.applied_at, migrationsDir);
+        }
+    }
+}
+/**
+ * Every migration on disk, read once.
+ *
+ * The identifier check reads all of them and not just the pending ones, so that
+ * whether a migration is rejected depends on the files alone. A camelCase
+ * column that had already been applied somewhere would otherwise pass on that
+ * machine and fail on a fresh checkout, which is the opposite of deterministic.
+ */
+const readMigrations = (migrationsDir) => migrationFiles(migrationsDir).map((name) => ({
+    name,
+    sql: readFileSync(join(migrationsDir, name), 'utf8'),
+}));
+export async function migrate(executor, migrationsDir) {
+    assertSnakeCaseIdentifiers(readMigrations(migrationsDir));
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
+    const result = { applied: [], skipped: [] };
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name)) {
+            result.skipped.push(name);
+            continue;
+        }
+        const raw = readFileSync(join(migrationsDir, name));
+        const hash = sha256(raw);
+        await executor.runMigration(raw.toString('utf8'), name, hash);
+        result.applied.push(name);
+    }
+    return result;
+}
+/**
+ * Record every pending migration as applied, without running any of it.
+ *
+ * The escape hatch for a database that already has the tables a migration
+ * creates — the shape you get when a runtime bootstrapped its own schema at
+ * boot and the migration writing it down was authored afterwards. Running that
+ * migration would fail on every existing deployment; skipping it forever would
+ * leave the history lying. Recording it says what is true.
+ *
+ * Deliberately unconditional here. Whether the database really does match is a
+ * question about schemas, not migration files, so the caller answers it first
+ * and this only runs once it has.
+ */
+/**
+ * The migrations on disk that the database has not recorded.
+ *
+ * Deliberately not derived by the caller: "pending" has to mean the same set
+ * `migrate` is about to apply, and that is filename order over `*.sql` minus
+ * what is recorded — not whatever a directory listing happens to return.
+ */
+export function pendingMigrations(migrationsDir, applied) {
+    const appliedNames = new Set(applied.map((row) => row.name));
+    return migrationFiles(migrationsDir).filter((name) => !appliedNames.has(name));
+}
+export async function baselineMigrations(executor, migrationsDir) {
+    await executor.ensureTrackingTable();
+    const applied = await executor.getApplied();
+    assertNoDrift(applied, migrationsDir);
+    const appliedNames = new Set(applied.map((r) => r.name));
+    const recorded = [];
+    for (const name of migrationFiles(migrationsDir)) {
+        if (appliedNames.has(name))
+            continue;
+        await executor.recordMigration(name, sha256(readFileSync(join(migrationsDir, name))));
+        recorded.push(name);
+    }
+    return recorded;
+}

package/dist/src/sqlite/index.d.ts

@@ -0,0 +1,3 @@
+export { SqliteMigrationExecutor, dropTrackingTable } from './sqlite-migrator.js';
+export { loadSqliteRuntime } from './sqlite-runtime.js';
+export type { SqliteRuntime, SyncSqliteChanges, SyncSqliteDatabase, SyncSqliteStatement, } from './sqlite-runtime.js';

package/dist/src/sqlite/index.js

@@ -0,0 +1,2 @@
+export { SqliteMigrationExecutor, dropTrackingTable } from './sqlite-migrator.js';
+export { loadSqliteRuntime } from './sqlite-runtime.js';

package/dist/src/sqlite/sqlite-migrator.d.ts

@@ -0,0 +1,11 @@
+import type { MigrationExecutor, AppliedMigration } from '../sql-migrator.js';
+import type { SyncSqliteDatabase } from './sqlite-runtime.js';
+export declare class SqliteMigrationExecutor implements MigrationExecutor {
+    private readonly db;
+    constructor(db: SyncSqliteDatabase);
+    ensureTrackingTable(): Promise<void>;
+    getApplied(): Promise<AppliedMigration[]>;
+    recordMigration(name: string, hash: string): Promise<void>;
+    runMigration(sql: string, name: string, hash: string): Promise<void>;
+}
+export declare function dropTrackingTable(db: SyncSqliteDatabase): void;

package/dist/src/sqlite/sqlite-migrator.js

@@ -0,0 +1,41 @@
+import { MIGRATION_TRACKING_TABLE as TRACKING_TABLE } from '../sql-migrator.js';
+export class SqliteMigrationExecutor {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async ensureTrackingTable() {
+        this.db.exec(`CREATE TABLE IF NOT EXISTS ${TRACKING_TABLE} (
+         name       TEXT PRIMARY KEY,
+         hash       TEXT NOT NULL,
+         applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+       )`);
+    }
+    async getApplied() {
+        return this.db
+            .prepare(`SELECT name, hash, applied_at FROM ${TRACKING_TABLE} ORDER BY name`)
+            .all();
+    }
+    async recordMigration(name, hash) {
+        this.db
+            .prepare(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES (?, ?)`)
+            .run(name, hash);
+    }
+    async runMigration(sql, name, hash) {
+        this.db.exec('BEGIN');
+        try {
+            this.db.exec(sql);
+            this.db
+                .prepare(`INSERT INTO ${TRACKING_TABLE} (name, hash) VALUES (?, ?)`)
+                .run(name, hash);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+}
+export function dropTrackingTable(db) {
+    db.exec(`DROP TABLE IF EXISTS ${TRACKING_TABLE}`);
+}

package/dist/src/sqlite/sqlite-runtime-bun.d.ts

@@ -0,0 +1,2 @@
+import type { SqliteRuntime } from './sqlite-runtime.js';
+export declare const bunSqliteRuntime: SqliteRuntime;

package/dist/src/sqlite/sqlite-runtime-bun.js

@@ -0,0 +1,62 @@
+import { Database } from 'bun:sqlite';
+class BunSqliteStatement {
+    stmt;
+    reader;
+    constructor(stmt, reader) {
+        this.stmt = stmt;
+        this.reader = reader;
+    }
+    all(...parameters) {
+        return this.stmt.all(...parameters);
+    }
+    get(...parameters) {
+        return (this.stmt.get(...parameters) ?? null);
+    }
+    iterate(...parameters) {
+        return this.stmt.iterate(...parameters);
+    }
+    run(...parameters) {
+        const result = this.stmt.run(...parameters);
+        return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+        };
+    }
+}
+class BunSqliteDatabase {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    exec(sql) {
+        // bun:sqlite throws "no valid SQL statement" on comment-only/empty input
+        // (e.g. a placeholder dev-seed.sql); node:sqlite silently no-ops. Match node's
+        // tolerance by skipping when nothing executable remains after stripping
+        // comments. The original `sql` is still exec'd verbatim when non-empty.
+        const executable = sql
+            .replace(/--[^\n]*/g, '')
+            .replace(/\/\*[\s\S]*?\*\//g, '')
+            .trim();
+        if (executable.length === 0)
+            return;
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        return new BunSqliteStatement(this.db.prepare(sql), isReaderSql(sql));
+    }
+    close() {
+        this.db.close();
+    }
+}
+function isReaderSql(sql) {
+    const normalized = sql.trimStart().toUpperCase();
+    return (normalized.startsWith('SELECT') ||
+        normalized.startsWith('WITH') ||
+        normalized.startsWith('PRAGMA') ||
+        normalized.startsWith('EXPLAIN'));
+}
+export const bunSqliteRuntime = {
+    open(filename) {
+        return new BunSqliteDatabase(new Database(filename));
+    },
+};

package/dist/src/sqlite/sqlite-runtime-node.d.ts

@@ -0,0 +1,2 @@
+import type { SqliteRuntime } from './sqlite-runtime.js';
+export declare function createNodeSqliteRuntime(): Promise<SqliteRuntime>;

package/dist/src/sqlite/sqlite-runtime-node.js

@@ -0,0 +1,78 @@
+class NodeSqliteStatement {
+    stmt;
+    reader;
+    constructor(stmt, sql) {
+        this.stmt = stmt;
+        // node:sqlite StatementSync does not have a .reader property
+        // (that's a better-sqlite3 API). Fall back to SQL inspection when absent.
+        if (stmt.reader !== undefined) {
+            this.reader = Boolean(stmt.reader);
+        }
+        else {
+            const upper = sql.trimStart().toUpperCase();
+            this.reader =
+                upper.startsWith('SELECT') ||
+                    upper.startsWith('WITH') ||
+                    upper.startsWith('PRAGMA') ||
+                    upper.startsWith('EXPLAIN') ||
+                    upper.startsWith('VALUES') ||
+                    /\bRETURNING\b/.test(upper);
+        }
+    }
+    all(...parameters) {
+        return this.stmt.all(...parameters);
+    }
+    get(...parameters) {
+        return this.stmt.get(...parameters) ?? null;
+    }
+    iterate(...parameters) {
+        return this.stmt.iterate(...parameters);
+    }
+    run(...parameters) {
+        const result = this.stmt.run(...parameters);
+        return {
+            changes: result.changes,
+            lastInsertRowid: result.lastInsertRowid,
+        };
+    }
+}
+class NodeSqliteDatabase {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    prepare(sql) {
+        return new NodeSqliteStatement(this.db.prepare(sql), sql);
+    }
+    close() {
+        this.db.close();
+    }
+}
+async function importNodeSqlite() {
+    const dynamicImport = new Function('return import("node:sqlite")');
+    try {
+        return await dynamicImport();
+    }
+    catch (error) {
+        // node ships node:sqlite unflagged only from 24. The raw failure is
+        // ERR_UNKNOWN_BUILTIN_MODULE, which reads like a broken install rather than
+        // a runtime that is simply too old — so say which it is and how to get past it.
+        if (error?.code === 'ERR_UNKNOWN_BUILTIN_MODULE') {
+            throw new Error(`This needs node:sqlite, which Node ${process.versions.node} does not provide ` +
+                `(it is unflagged from Node 24). Either upgrade Node, or run the CLI on bun, ` +
+                `which has it: \`bunx --bun pikku <command>\`.`, { cause: error });
+        }
+        throw error;
+    }
+}
+export async function createNodeSqliteRuntime() {
+    const { DatabaseSync } = await importNodeSqlite();
+    return {
+        open(filename) {
+            return new NodeSqliteDatabase(new DatabaseSync(filename));
+        },
+    };
+}

package/dist/src/sqlite/sqlite-runtime.d.ts

@@ -0,0 +1,20 @@
+export interface SyncSqliteChanges {
+    changes: number | bigint;
+    lastInsertRowid: number | bigint;
+}
+export interface SyncSqliteStatement {
+    reader: boolean;
+    all(...parameters: unknown[]): unknown[];
+    get(...parameters: unknown[]): unknown | null;
+    iterate(...parameters: unknown[]): IterableIterator<unknown>;
+    run(...parameters: unknown[]): SyncSqliteChanges;
+}
+export interface SyncSqliteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): SyncSqliteStatement;
+    close(): void;
+}
+export interface SqliteRuntime {
+    open(filename: string): SyncSqliteDatabase;
+}
+export declare function loadSqliteRuntime(): Promise<SqliteRuntime>;

package/dist/src/sqlite/sqlite-runtime.js

@@ -0,0 +1,13 @@
+let runtimePromise;
+export async function loadSqliteRuntime() {
+    runtimePromise ??= (async () => {
+        const isBunRuntime = typeof globalThis.Bun !== 'undefined';
+        if (isBunRuntime) {
+            const { bunSqliteRuntime } = await import('./sqlite-runtime-bun.js');
+            return bunSqliteRuntime;
+        }
+        const { createNodeSqliteRuntime } = await import('./sqlite-runtime-node.js');
+        return createNodeSqliteRuntime();
+    })();
+    return runtimePromise;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pikku/migrator-sql",
+  "version": "0.12.2",
+  "description": "The SQL migration applier shared by the Pikku CLI and the standalone runtime",
+  "author": "yasser.fadl@gmail.com",
+  "license": "MIT",
+  "module": "dist/src/index.js",
+  "main": "dist/src/index.js",
+  "type": "module",
+  "scripts": {
+    "tsc": "tsc",
+    "ncu": "npx npm-check-updates",
+    "build": "tsc -b",
+    "test": "bash run-tests.sh",
+    "test:watch": "bash run-tests.sh --watch",
+    "test:coverage": "bash run-tests.sh --coverage",
+    "prepublishOnly": "yarn build"
+  },
+  "engines": {
+    "node": ">=22.10"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@types/node": "^22",
+    "tsx": "^4.23.12",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./sqlite": "./dist/src/sqlite/index.js",
+    "./postgres": "./dist/src/postgres/index.js"
+  }
+}

package/run-tests.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+# Parse command line arguments
+WATCH_MODE=false
+COVERAGE_MODE=false
+
+for arg in "$@"
+do
+    case $arg in
+        --watch)
+        WATCH_MODE=true
+        shift
+        ;;
+        --coverage)
+        COVERAGE_MODE=true
+        shift
+        ;;
+    esac
+done
+
+# Build the command
+CMD="node --import tsx --test --test-force-exit src/**/*.test.ts"
+
+if [ "$WATCH_MODE" = true ]; then
+    CMD="$CMD --watch"
+fi
+
+if [ "$COVERAGE_MODE" = true ]; then
+    CMD="$CMD --experimental-test-coverage"
+fi
+
+# Execute the command
+eval $CMD