@c4t4/heyamigo 0.8.15 → 0.9.1

package/dist/channels/adapter.js

@@ -0,0 +1,24 @@
+// Channel adapter interface. The sender worker drains the outbound
+// queue, parses each row's address (wa:dm:..., tg:dm:..., etc.), and
+// dispatches to the adapter for the matching channel. Adapters are
+// the *only* place that talks to a channel SDK (Baileys, Telegram bot,
+// whatever). Workers stay channel-agnostic.
+// Distinguishes between "the channel said no, try again later" and
+// "the message itself is broken." Sender worker uses this to decide
+// retry vs DLQ.
+export class TransientChannelError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'TransientChannelError';
+    }
+}
+export class PermanentChannelError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'PermanentChannelError';
+    }
+}

package/dist/channels/baileys.js

@@ -0,0 +1,158 @@
+// Baileys (WhatsApp) channel adapter. Wraps the existing wa/sender.ts
+// behind the ChannelAdapter interface so the sender worker stays
+// channel-agnostic.
+//
+// The WASocket is created in src/wa/socket.ts and replaced on each
+// reconnect. Boot path (or the connection callback) calls
+// setBaileysSocket(sock) so the adapter always points at the live one.
+import { readFileSync, statSync } from 'fs';
+import { basename, extname } from 'path';
+import { PermanentChannelError, TransientChannelError, } from './adapter.js';
+let activeSocket = null;
+export function setBaileysSocket(sock) {
+    activeSocket = sock;
+}
+const MIME_MAP = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.mp4': 'video/mp4',
+    '.avi': 'video/avi',
+    '.mov': 'video/quicktime',
+    '.mkv': 'video/x-matroska',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.opus': 'audio/opus',
+    '.m4a': 'audio/mp4',
+    '.wav': 'audio/wav',
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.zip': 'application/zip',
+};
+function mimeFor(filePath, fallback) {
+    if (fallback)
+        return fallback;
+    const ext = extname(filePath).toLowerCase();
+    return MIME_MAP[ext] ?? 'application/octet-stream';
+}
+function requireSocket() {
+    if (!activeSocket) {
+        // Socket isn't ready — sender worker should not have tried. This
+        // becomes "retry later" so the message stays in queue until WA
+        // reconnects.
+        throw new TransientChannelError('baileys socket not connected');
+    }
+    return activeSocket;
+}
+function requireFile(path) {
+    try {
+        const stat = statSync(path);
+        const buf = readFileSync(path);
+        return { buf, bytes: stat.size };
+    }
+    catch (err) {
+        throw new PermanentChannelError(`media file unreadable: ${path} (${err.message})`, err);
+    }
+}
+// Map a Baileys send error onto our transient/permanent classification.
+// Network/connection issues → transient. Anything else (invalid jid,
+// payload, etc.) → permanent.
+function classifyBaileysError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Heuristic: Baileys throws "connection closed" / "timed out" /
+    // "socket" for transient stuff; everything else assume permanent.
+    const transientHints = [
+        'connection closed',
+        'connection lost',
+        'timed out',
+        'timeout',
+        'socket',
+        'lost connection',
+        'no connection',
+    ];
+    const lower = message.toLowerCase();
+    if (transientHints.some((h) => lower.includes(h))) {
+        return new TransientChannelError(message, err);
+    }
+    return new PermanentChannelError(message, err);
+}
+async function sendOne(sock, jid, msg) {
+    const quoteOpts = msg.quoteMsgId
+        ? // Baileys quoting actually needs the full WAMessage to embed in
+            // contextInfo; we only have the id. For now we send without
+            // quoting in that case (future: cache recent WAMessages keyed
+            // by id so we can rehydrate the quote target).
+            undefined
+        : undefined;
+    switch (msg.kind) {
+        case 'text':
+            if (!msg.text) {
+                throw new PermanentChannelError('text outbound has no body');
+            }
+            return sock.sendMessage(jid, { text: msg.text }, quoteOpts);
+        case 'image': {
+            if (!msg.mediaPath) {
+                throw new PermanentChannelError('image outbound missing mediaPath');
+            }
+            const { buf } = requireFile(msg.mediaPath);
+            return sock.sendMessage(jid, { image: buf, caption: msg.text ?? undefined }, quoteOpts);
+        }
+        case 'video': {
+            if (!msg.mediaPath) {
+                throw new PermanentChannelError('video outbound missing mediaPath');
+            }
+            const { buf } = requireFile(msg.mediaPath);
+            return sock.sendMessage(jid, {
+                video: buf,
+                caption: msg.text ?? undefined,
+                mimetype: mimeFor(msg.mediaPath, msg.mediaMime),
+            }, quoteOpts);
+        }
+        case 'audio': {
+            if (!msg.mediaPath) {
+                throw new PermanentChannelError('audio outbound missing mediaPath');
+            }
+            const { buf } = requireFile(msg.mediaPath);
+            return sock.sendMessage(jid, { audio: buf, mimetype: mimeFor(msg.mediaPath, msg.mediaMime) }, quoteOpts);
+        }
+        case 'document': {
+            if (!msg.mediaPath) {
+                throw new PermanentChannelError('document outbound missing mediaPath');
+            }
+            const { buf } = requireFile(msg.mediaPath);
+            return sock.sendMessage(jid, {
+                document: buf,
+                mimetype: mimeFor(msg.mediaPath, msg.mediaMime),
+                fileName: basename(msg.mediaPath),
+                caption: msg.text ?? undefined,
+            }, quoteOpts);
+        }
+    }
+}
+export const baileysAdapter = {
+    channel: 'wa',
+    async send(externalId, msg) {
+        const sock = requireSocket();
+        let sent;
+        try {
+            sent = await sendOne(sock, externalId, msg);
+        }
+        catch (err) {
+            throw classifyBaileysError(err);
+        }
+        const msgId = sent?.key?.id;
+        if (!msgId) {
+            // Baileys returned without an id; treat as transient so we retry
+            // (rather than silently losing track of whether the send happened).
+            throw new TransientChannelError('baileys send returned no message id');
+        }
+        return { msgId };
+    },
+};

package/dist/channels/index.js

@@ -0,0 +1,16 @@
+// Channel adapter registry. Sender worker calls getChannelAdapter(name)
+// keyed off the parsed address.channel.
+import { baileysAdapter } from './baileys.js';
+const REGISTRY = {
+    wa: baileysAdapter,
+    // tg: telegramAdapter, // Phase 8
+};
+export function getChannelAdapter(channel) {
+    const adapter = REGISTRY[channel];
+    if (!adapter) {
+        throw new Error(`no channel adapter registered for channel="${channel}"`);
+    }
+    return adapter;
+}
+export { setBaileysSocket } from './baileys.js';
+export { PermanentChannelError, TransientChannelError, } from './adapter.js';

package/dist/config.js

@@ -70,6 +70,10 @@ const ConfigSchema = z.object({
         errorMessage: z.string(),
         maxMessageAgeMs: z.number(),
         showStats: z.boolean().default(true),
+        // Hard cap on outbound media size enforced by the sender worker.
+        // Default 25MB matches WhatsApp's published per-message media limit
+        // for most kinds. Set to null to disable the check.
+        maxOutboundMediaBytes: z.number().int().positive().nullable().default(25 * 1024 * 1024),
     }),
     storage: z.object({
         messagesDir: z.string(),

package/dist/db/address.js

@@ -0,0 +1,72 @@
+// Channel-agnostic address shape. Inbound, outbound, async, browser,
+// and crons all carry an Address string. Sender worker parses the
+// channel prefix and dispatches to the matching ChannelAdapter.
+//
+// Serialized form (the wire shape stored in DB columns):
+//   wa:dm:17867@s.whatsapp.net
+//   wa:group:120363@g.us
+//   tg:dm:user_12345
+//   tg:group:-100123456
+//   system:cron:42
+//
+// First two segments are well-known. The third is the platform-native
+// external id, kept verbatim — easier to debug, lossless round-trip.
+export function formatAddress(addr) {
+    return `${addr.channel}:${addr.scope}:${addr.externalId}`;
+}
+export function parseAddress(s) {
+    const idx1 = s.indexOf(':');
+    const idx2 = s.indexOf(':', idx1 + 1);
+    if (idx1 < 0 || idx2 < 0) {
+        throw new Error(`bad address (need channel:scope:external_id): ${s}`);
+    }
+    const channel = s.slice(0, idx1);
+    const scope = s.slice(idx1 + 1, idx2);
+    const externalId = s.slice(idx2 + 1);
+    if (!externalId)
+        throw new Error(`bad address (empty external id): ${s}`);
+    return { channel, scope, externalId };
+}
+// Convert a raw Baileys JID into our address form. JID suffixes:
+//   @s.whatsapp.net → wa:dm
+//   @g.us           → wa:group
+//   @lid            → wa:dm (LID identities; canonicalized to wa:dm)
+//   @newsletter     → wa:group (broadcast/channel, treat as group-like)
+//
+// The full JID stays in externalId so it round-trips losslessly.
+export function jidToAddress(jid) {
+    if (jid.endsWith('@g.us')) {
+        return { channel: 'wa', scope: 'group', externalId: jid };
+    }
+    if (jid.endsWith('@newsletter')) {
+        return { channel: 'wa', scope: 'group', externalId: jid };
+    }
+    if (jid.endsWith('@s.whatsapp.net') || jid.endsWith('@lid')) {
+        return { channel: 'wa', scope: 'dm', externalId: jid };
+    }
+    // Unknown WA jid shape — preserve verbatim, default to DM.
+    return { channel: 'wa', scope: 'dm', externalId: jid };
+}
+// Reverse: pull the platform-native id back out. For WA this is the
+// JID; ChannelAdapter implementations use it directly.
+export function addressToExternalId(addr) {
+    const a = typeof addr === 'string' ? parseAddress(addr) : addr;
+    return a.externalId;
+}
+// Convenience predicates.
+export function isGroup(addr) {
+    const a = typeof addr === 'string' ? parseAddress(addr) : addr;
+    return a.scope === 'group';
+}
+export function isDm(addr) {
+    const a = typeof addr === 'string' ? parseAddress(addr) : addr;
+    return a.scope === 'dm';
+}
+// System addresses for bot-internal flows (cron-fired self-prompts,
+// task-spawned messages without an originating chat).
+export function systemCronAddress(cronId) {
+    return `system:cron:${cronId}`;
+}
+export function systemTaskAddress(taskId) {
+    return `system:task:${taskId}`;
+}

package/dist/db/check.js

@@ -0,0 +1,74 @@
+// Schema drift detector. Runs after migrations succeed. Compares the
+// live database's table set against the set drizzle's schema.ts
+// declares, refuses to start on mismatch.
+//
+// What this catches:
+//   - "Forgot to run `drizzle-kit generate` after editing schema.ts"
+//     → migration didn't include the new table; drift detected.
+//   - "Someone ran `ALTER TABLE` directly in prod" → extra columns or
+//     missing columns vs. schema.ts.
+//
+// What this does NOT catch (intentionally — keeps the check simple
+// and predictable):
+//   - Column type changes that SQLite stored compatibly.
+//   - Index differences (drizzle doesn't always emit identical CREATE
+//     INDEX text; comparing index DDL is fragile).
+//   - Drift in non-drizzle tables (e.g. __drizzle_migrations itself).
+//
+// If we ever need stricter checking, add it here behind a config flag.
+// Start strict-but-narrow; loosen if it bites.
+import { getTableConfig, SQLiteTable } from 'drizzle-orm/sqlite-core';
+import { logger } from '../logger.js';
+import * as schema from './schema.js';
+export class SchemaDriftError extends Error {
+    diffs;
+    constructor(diffs) {
+        super(`schema drift detected:\n  - ${diffs.join('\n  - ')}`);
+        this.diffs = diffs;
+        this.name = 'SchemaDriftError';
+    }
+}
+export function checkSchemaDrift(db) {
+    const diffs = [];
+    // Discover declared tables by walking the schema module's exports.
+    // SQLiteTable is a real class; instanceof is the cleanest discriminator.
+    const declared = Object.values(schema)
+        .filter((v) => v instanceof SQLiteTable)
+        .map(t => getTableConfig(t));
+    const liveTables = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__drizzle_%'")
+        .all();
+    const liveTableNames = new Set(liveTables.map(r => r.name));
+    for (const t of declared) {
+        if (!liveTableNames.has(t.name)) {
+            diffs.push(`missing table: ${t.name}`);
+            continue;
+        }
+        const liveCols = db
+            .prepare(`PRAGMA table_info(${t.name})`)
+            .all();
+        const liveColNames = new Set(liveCols.map(c => c.name));
+        const declaredColNames = new Set(t.columns.map(c => c.name));
+        for (const c of t.columns) {
+            if (!liveColNames.has(c.name)) {
+                diffs.push(`${t.name}: missing column "${c.name}"`);
+            }
+        }
+        for (const name of liveColNames) {
+            if (!declaredColNames.has(name)) {
+                diffs.push(`${t.name}: unexpected column "${name}" (drift)`);
+            }
+        }
+    }
+    // Unexpected tables (drift from out-of-band CREATE TABLE)
+    for (const name of liveTableNames) {
+        if (!declared.some(t => t.name === name)) {
+            diffs.push(`unexpected table "${name}" (drift)`);
+        }
+    }
+    if (diffs.length > 0) {
+        logger.fatal({ diffs }, 'schema drift detected; bot refuses to start');
+        throw new SchemaDriftError(diffs);
+    }
+    logger.debug({ tables: declared.map(t => t.name) }, 'schema check passed');
+}

package/dist/db/identity-sync.js

@@ -0,0 +1,147 @@
+// Derive persons + identities from existing config/access.json. Runs
+// at boot, idempotently. The file stays authoritative; the DB rows
+// are a *derived view* so future queue rows can reference person_id
+// without joining against the file every time.
+//
+// No schema change to access.json. Phase 0 doesn't touch the file.
+// Person mapping:
+//   - config.owner.number             → person-owner
+//   - each entry in access.users      → person-<sanitized-number>
+//   - each entry in access.dms.allowed → ensure a person exists
+//   - groups are addresses, not persons — skipped
+//
+// Re-running the sync on every boot:
+//   - upserts display_name (in case access.json was edited)
+//   - adds new identities (in case the owner added a number)
+//   - never deletes (avoid surprise data loss; explicit cleanup
+//     command can come later)
+import { eq } from 'drizzle-orm';
+import { config } from '../config.js';
+import { logger } from '../logger.js';
+import { jidToAddress, formatAddress } from './address.js';
+import { getDb } from './index.js';
+import { identities, persons } from './schema.js';
+import { getAccess } from '../wa/whitelist.js';
+const OWNER_PERSON_ID = 'person-owner';
+function personIdForNumber(number) {
+    // Strip non-digits, prefix with 'person-'. Stable + deterministic.
+    const sanitized = number.replace(/\D/g, '');
+    return `person-${sanitized}`;
+}
+function dmAddressFor(number) {
+    const sanitized = number.replace(/\D/g, '');
+    return formatAddress(jidToAddress(`${sanitized}@s.whatsapp.net`));
+}
+function collectSeeds() {
+    const access = getAccess();
+    const now = Math.floor(Date.now() / 1000);
+    void now;
+    const out = new Map();
+    // Owner
+    if (config.owner.number) {
+        out.set(OWNER_PERSON_ID, {
+            id: OWNER_PERSON_ID,
+            displayName: 'Owner',
+            addresses: [dmAddressFor(config.owner.number)],
+        });
+    }
+    // Users
+    for (const [number, entry] of Object.entries(access.users ?? {})) {
+        const id = number === config.owner.number ? OWNER_PERSON_ID : personIdForNumber(number);
+        const existing = out.get(id);
+        const addr = dmAddressFor(number);
+        if (existing) {
+            if (entry.name)
+                existing.displayName = entry.name;
+            if (!existing.addresses.includes(addr))
+                existing.addresses.push(addr);
+        }
+        else {
+            out.set(id, {
+                id,
+                displayName: entry.name ?? null,
+                addresses: [addr],
+            });
+        }
+    }
+    // DM allowed — ensure persons exist, even without a name
+    for (const dm of access.dms?.allowed ?? []) {
+        const id = dm.number === config.owner.number ? OWNER_PERSON_ID : personIdForNumber(dm.number);
+        const addr = dmAddressFor(dm.number);
+        const existing = out.get(id);
+        if (existing) {
+            if (!existing.addresses.includes(addr))
+                existing.addresses.push(addr);
+        }
+        else {
+            out.set(id, { id, displayName: null, addresses: [addr] });
+        }
+    }
+    return [...out.values()];
+}
+// Idempotent upsert. Inserts new rows; updates display_name on existing
+// person rows (in case it was filled in later); never deletes.
+export function syncIdentitiesFromAccess() {
+    const db = getDb();
+    const seeds = collectSeeds();
+    const now = Math.floor(Date.now() / 1000);
+    let personsUpserted = 0;
+    let identitiesUpserted = 0;
+    db.transaction((tx) => {
+        for (const seed of seeds) {
+            const existing = tx
+                .select()
+                .from(persons)
+                .where(eq(persons.id, seed.id))
+                .all();
+            if (existing.length === 0) {
+                tx.insert(persons)
+                    .values({
+                    id: seed.id,
+                    displayName: seed.displayName,
+                    timezone: config.owner.timezone,
+                    createdAt: now,
+                })
+                    .run();
+                personsUpserted++;
+            }
+            else if (seed.displayName &&
+                existing[0].displayName !== seed.displayName) {
+                tx.update(persons)
+                    .set({ displayName: seed.displayName })
+                    .where(eq(persons.id, seed.id))
+                    .run();
+                personsUpserted++;
+            }
+            for (const addr of seed.addresses) {
+                const have = tx
+                    .select()
+                    .from(identities)
+                    .where(eq(identities.address, addr))
+                    .all();
+                if (have.length === 0) {
+                    tx.insert(identities)
+                        .values({ personId: seed.id, address: addr, addedAt: now })
+                        .run();
+                    identitiesUpserted++;
+                }
+                // If have.length > 0 but personId differs, leave it — manual
+                // merge required. Don't reassign silently.
+            }
+        }
+    });
+    logger.info({ personsUpserted, identitiesUpserted, seeded: seeds.length }, 'identity sync from access.json complete');
+    return { personsUpserted, identitiesUpserted };
+}
+// Lookup helper used by the inbound resolution step (in later phases).
+// Returns null if the address has no matching person — caller decides
+// whether to auto-create or treat as stranger.
+export function personIdForAddress(address) {
+    const db = getDb();
+    const row = db
+        .select({ personId: identities.personId })
+        .from(identities)
+        .where(eq(identities.address, address))
+        .get();
+    return row?.personId ?? null;
+}

package/dist/db/index.js

@@ -0,0 +1,44 @@
+// Process-wide SQLite handle. Initialized once at boot in src/index.ts
+// (and in any other entry point that needs DB access, like `setup`).
+// Workers and other modules get the handle via `getDb()` — never open
+// their own.
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { resolve } from 'path';
+import * as schema from './schema.js';
+import { runMigrations } from './migrate.js';
+import { checkSchemaDrift } from './check.js';
+let rawDb = null;
+let ormDb = null;
+export function dbPath() {
+    return resolve(process.cwd(), 'storage', 'heyamigo.db');
+}
+// Run migrations + drift check + open the singleton. Call once per
+// process at boot. Idempotent — subsequent calls return the existing
+// handle without re-migrating.
+export function initDb() {
+    if (ormDb)
+        return ormDb;
+    const path = dbPath();
+    rawDb = runMigrations(path);
+    checkSchemaDrift(rawDb);
+    ormDb = drizzle(rawDb, { schema });
+    return ormDb;
+}
+export function getDb() {
+    if (!ormDb)
+        throw new Error('db not initialized; call initDb() at boot');
+    return ormDb;
+}
+export function getRawDb() {
+    if (!rawDb)
+        throw new Error('db not initialized; call initDb() at boot');
+    return rawDb;
+}
+// Used by graceful shutdown.
+export function closeDb() {
+    if (rawDb) {
+        rawDb.close();
+        rawDb = null;
+        ormDb = null;
+    }
+}

package/dist/db/migrate.js

@@ -0,0 +1,113 @@
+// Migration runner. Called once at boot from src/index.ts before any
+// worker spins up. Order: pre-migration backup → drizzle migrator →
+// drift check (in src/db/check.ts). If anything throws, the bot
+// refuses to start.
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator';
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from '../logger.js';
+// Resolve `migrations/` relative to the package install, not cwd. When
+// installed via npm, the bot runs from the user's project dir but the
+// migration SQL files ship inside @c4t4/heyamigo. From src/db/migrate.ts:
+//   dist/db/migrate.js  ←  __filename
+//   dist/db/            ←  dirname
+//   dist/               ←  ../
+//   <pkg root>/         ←  ../../
+//   <pkg root>/migrations
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const MIGRATIONS_FOLDER = resolve(PKG_ROOT, 'migrations');
+const BACKUP_DIR_NAME = 'backups';
+const KEEP_PRE_MIGRATION_BACKUPS = 10;
+// VACUUM INTO is atomic and produces a fully consistent copy even
+// while the DB is being written to. Trivial insurance before any
+// schema change. Skip if no pending migrations to avoid noise on
+// no-op boots.
+function preMigrationBackup(dbPath) {
+    // Cheap check: open the DB, ask the migrator what would happen.
+    // We can't easily query "what's pending" without invoking drizzle's
+    // internals, so instead we check whether our migrations folder has
+    // more entries than the drizzle tracking table claims.
+    const sqlFiles = existsSync(MIGRATIONS_FOLDER)
+        ? readdirSync(MIGRATIONS_FOLDER).filter(f => f.endsWith('.sql'))
+        : [];
+    if (sqlFiles.length === 0)
+        return null;
+    let appliedCount = 0;
+    if (existsSync(dbPath)) {
+        const probe = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            const row = probe
+                .prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name='__drizzle_migrations'")
+                .get();
+            if (row.n > 0) {
+                const counted = probe
+                    .prepare('SELECT count(*) AS n FROM __drizzle_migrations')
+                    .get();
+                appliedCount = counted.n;
+            }
+        }
+        finally {
+            probe.close();
+        }
+    }
+    if (appliedCount >= sqlFiles.length)
+        return null; // up to date, nothing to back up for
+    const backupDir = resolve(dirname(dbPath), BACKUP_DIR_NAME);
+    mkdirSync(backupDir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = resolve(backupDir, `pre-migration-${ts}.db`);
+    if (existsSync(dbPath)) {
+        const tmp = new Database(dbPath, { readonly: true, fileMustExist: true });
+        try {
+            tmp.exec(`VACUUM INTO '${backupPath.replace(/'/g, "''")}'`);
+        }
+        finally {
+            tmp.close();
+        }
+        logger.info({ backupPath }, 'pre-migration backup written');
+    }
+    else {
+        // No DB yet — nothing to back up. Boot will create it fresh.
+        return null;
+    }
+    rotatePreMigrationBackups(backupDir);
+    return backupPath;
+}
+function rotatePreMigrationBackups(backupDir) {
+    const files = readdirSync(backupDir)
+        .filter(f => f.startsWith('pre-migration-') && f.endsWith('.db'))
+        .map(f => ({ name: f, path: resolve(backupDir, f), mtime: statSync(resolve(backupDir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+    const toDelete = files.slice(KEEP_PRE_MIGRATION_BACKUPS);
+    for (const f of toDelete) {
+        try {
+            unlinkSync(f.path);
+        }
+        catch (err) {
+            logger.warn({ err, file: f.name }, 'failed to delete old backup');
+        }
+    }
+}
+export function runMigrations(dbPath) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const backupPath = preMigrationBackup(dbPath);
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL'); // required for litestream
+    db.pragma('foreign_keys = ON');
+    const drizzleDb = drizzle(db);
+    try {
+        migrate(drizzleDb, { migrationsFolder: MIGRATIONS_FOLDER });
+    }
+    catch (err) {
+        logger.fatal({ err, backupPath }, 'migration failed; refusing to start. restore the pre-migration backup if needed.');
+        db.close();
+        throw err;
+    }
+    if (backupPath) {
+        logger.info('migrations applied successfully');
+    }
+    return db;
+}