@bockit/sequel 0.0.0-stage → 0.2.0

package/dist/binaries/platform.d.ts

@@ -0,0 +1,3 @@
+export declare const PLATFORMS: readonly ['darwin-arm64', 'linux-x64', 'linux-arm64'];
+export type Platform = (typeof PLATFORMS)[number];
+export declare function currentPlatform(os?: string, arch?: string): Platform;

package/dist/binaries/platform.js

@@ -0,0 +1,10 @@
+import { SequelError } from '../errors.js';
+export const PLATFORMS = ['darwin-arm64', 'linux-x64', 'linux-arm64'];
+// sequel's name for the platform it runs on. Each manifest entry maps it to the tool's own name.
+export function currentPlatform(os = process.platform, arch = process.arch) {
+    const platform = `${os}-${arch}`;
+    if (!PLATFORMS.includes(platform)) {
+        throw new SequelError(`sequel does not support ${platform}. Its pinned tools are built for ${PLATFORMS.join(', ')}.`);
+    }
+    return platform;
+}

package/dist/binaries/unpack.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformEntry } from './manifest.ts';
+export declare function unpack(asset: string, entry: PlatformEntry, workDir: string): Promise<string>;

package/dist/binaries/unpack.js

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { createGunzip } from 'node:zlib';
+import { SequelError } from '../errors.js';
+const run = promisify(execFile);
+// Extracts the executable from a verified asset into `workDir`, and returns its path.
+// Only call this after the asset's checksum has passed.
+export async function unpack(asset, entry, workDir) {
+    const output = path.join(workDir, 'executable');
+    switch (entry.archive) {
+        case 'none':
+            return asset;
+        case 'gz':
+            await pipeline(createReadStream(asset), createGunzip(), createWriteStream(output));
+            return output;
+        case 'tar.gz': {
+            const member = entry.member;
+            const dir = path.join(workDir, 'unpacked');
+            await mkdir(dir);
+            try {
+                // The system tar, present on every supported platform. Only the named member is
+                // extracted, and both GNU tar and bsdtar refuse members that escape `dir`.
+                await run('tar', ['-xzf', asset, '-C', dir, member]);
+            }
+            catch (error) {
+                throw new SequelError(`Could not extract ${member} from ${entry.asset} with tar: ${error.message.trim()}`);
+            }
+            return path.join(dir, member);
+        }
+    }
+}

package/dist/binaries/verify.d.ts

@@ -0,0 +1,2 @@
+export declare function sha256File(file: string): Promise<string>;
+export declare function verifySha256(file: string, expected: string, what: string): Promise<void>;

package/dist/binaries/verify.js

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { SequelError } from '../errors.js';
+export async function sha256File(file) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+// Refuses a file whose sha256 isn't the one recorded in the manifest. `what` names it.
+export async function verifySha256(file, expected, what) {
+    const actual = await sha256File(file);
+    if (actual !== expected) {
+        throw new SequelError(`${what} failed its checksum: expected sha256 ${expected}, got ${actual}. It was not used.`);
+    }
+}

package/dist/check.d.ts

@@ -0,0 +1,9 @@
+import { type ResolvedConfig } from './config/resolve-config.ts';
+export type CheckFailure = {
+    problem: string;
+    details: string[];
+    fix: string;
+};
+export declare function runChecks(config: ResolvedConfig, log: (message: string) => void): Promise<CheckFailure[]>;
+export declare function lineChanges(current: string, next: string): string[];
+export declare function checkFailureMessage(failures: CheckFailure[]): string;

package/dist/check.js

@@ -0,0 +1,178 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ensureBinary } from './binaries/ensure-binary.js';
+import { requireDatabase } from './config/resolve-config.js';
+import { SequelError } from './errors.js';
+import { readExtrasSnapshot } from './extras/snapshot.js';
+import { checkModules } from './generate/generate-modules.js';
+import { findQueryFolders } from './generate/modules.js';
+import { deployTo } from './migrate/deploy.js';
+import { diffMigrationsToSchema } from './migrate/drift.js';
+import { findMigrations } from './migrate/files.js';
+import { formatFinding, lintMigrations, migrationsToLint } from './migrate/lint.js';
+import { readSchemaFiles, validateSchema } from './schema/schema.js';
+import { unsupportedColumns } from './schema/unsupported.js';
+// SPEC §3's `check`: brings the test database up to the latest migration, then runs every check
+// and returns every failure, in SPEC's order. It writes no files. A check that can't run because
+// an earlier one failed (drift needs a valid schema, say) is skipped, and the earlier failure
+// says why. With external migrations it checks only the generated modules (SPEC §2).
+export async function runChecks(config, log) {
+    const testUrl = requireDatabase(config, 'test');
+    const failures = [];
+    const fail = (order, failure) => failures.push({ order, failure });
+    const expected = async (order, problem, fix, body) => {
+        try {
+            return await body();
+        }
+        catch (error) {
+            if (!(error instanceof SequelError))
+                throw error;
+            fail(order, { problem, details: [error.message], fix });
+            return undefined;
+        }
+    };
+    // With external migrations, the test database is as the other tool left it, and only the
+    // generated modules are checked. The skip is said, never silent.
+    if (config.externalMigrations) {
+        log(`Skipped drift, lint, the extras snapshot and schema validation: this app's migrations are managed elsewhere (\`externalMigrations\` in ${path.basename(config.configFile)}).`);
+        await checkGeneratedModules(config, testUrl, expected, (failure) => fail(1, failure));
+        return failures.map((entry) => entry.failure);
+    }
+    const shown = (file) => path.relative(config.root, file);
+    // The schema folder.
+    const files = await expected(5, "The schema folder can't be read", "Fix the config's `schema`, then run `sequel check` again.", () => readSchemaFiles(config.schema, config.root));
+    let schemaValid = false;
+    if (files !== undefined) {
+        const message = validateSchema(files, config.root);
+        if (message === undefined)
+            schemaValid = true;
+        else {
+            fail(5, {
+                problem: "The schema folder doesn't validate",
+                details: [message],
+                fix: 'Fix the schema. `sequel validate` shows the same errors.',
+            });
+        }
+    }
+    // The migrations, and the test database.
+    const migrations = await expected(2, "The migrations can't be read", 'Fix the files named, then run `sequel check` again.', () => findMigrations(config.migrations, { root: config.root }));
+    const deployed = migrations !== undefined &&
+        (await expected(1, "The test database can't be brought up to the latest migration", 'Fix the migration named, then run `sequel check` again.', async () => {
+            await deployTo(config, testUrl, { log, quietWhenCurrent: true });
+            return true;
+        })) === true;
+    // 1. Generated modules.
+    if (deployed)
+        await checkGeneratedModules(config, testUrl, expected, (failure) => fail(1, failure));
+    // 2. Drift.
+    if (migrations !== undefined && files !== undefined && schemaValid) {
+        const diff = await expected(2, "Drift between the migrations and the schema folder can't be checked", 'Fix the problem named, then run `sequel check` again.', () => diffMigrationsToSchema({ config, migrations, files }));
+        if (diff?.changed) {
+            fail(2, {
+                problem: 'The migrations and the schema folder differ. Replayed, the migrations need this to match the schema',
+                details: [diff.sql.trimEnd()],
+                fix: 'Run `sequel migrate new <name>` to write a migration for the difference, or change the schema to match the migrations.',
+            });
+        }
+    }
+    // 3. Lint after the cut-over.
+    if (migrations !== undefined) {
+        const findings = await expected(3, "The migrations can't be linted", 'Fix the problem named, then run `sequel check` again.', async () => lintMigrations({
+            squawk: await ensureBinary('squawk'),
+            migrations: migrationsToLint(migrations, config.lint.cutover),
+            root: config.root,
+            ...(files === undefined ? {} : { unsupported: unsupportedColumns(files) }),
+        }));
+        if (findings !== undefined && findings.length > 0) {
+            fail(3, {
+                problem: `Migrations after the lint cut-over have ${findings.length} lint finding${findings.length === 1 ? '' : 's'}`,
+                details: findings.map(formatFinding),
+                fix: 'Fix each, or suppress a Squawk finding with `-- squawk-ignore <rule> -- <reason>`. `sequel migrate lint` lists them.',
+            });
+        }
+    }
+    // 4. The extras snapshot.
+    if (deployed) {
+        const next = await readExtrasSnapshot(testUrl);
+        const current = await readFile(config.snapshot, 'utf8').catch(() => undefined);
+        if (current !== next) {
+            fail(4, {
+                problem: current === undefined
+                    ? `The extras snapshot ${shown(config.snapshot)} is missing`
+                    : `The extras snapshot ${shown(config.snapshot)} is stale`,
+                details: current === undefined ? [] : lineChanges(current, next),
+                fix: 'Run `sequel extras`, and commit the snapshot.',
+            });
+        }
+    }
+    return failures.sort((a, b) => a.order - b.order).map((entry) => entry.failure);
+}
+// Generates the modules as `generate` would, against the test database as it stands, and
+// compares them with the modules in place: stale, missing or orphaned.
+async function checkGeneratedModules(config, testUrl, expected, fail) {
+    const shown = (file) => path.relative(config.root, file);
+    const modules = await expected(1, "The query modules can't be generated", 'Fix the queries named. `sequel generate` reports the same errors.', async () => checkModules({
+        sqlc: await ensureBinary('sqlc'),
+        databaseUrl: testUrl,
+        folders: await findQueryFolders(config.queries),
+        bigint: config.types.bigint,
+        root: config.root,
+    }));
+    if (modules === undefined)
+        return;
+    const details = [
+        ...modules.stale.map((file) => `stale: ${shown(file)}`),
+        ...modules.missing.map((file) => `missing: ${shown(file)}`),
+        ...modules.orphaned.map((file) => `orphaned: ${shown(file)} (its query file is gone)`),
+    ];
+    if (details.length > 0) {
+        fail({
+            problem: 'Generated modules are out of date',
+            details,
+            fix: 'Run `sequel generate`, and commit the result.',
+        });
+    }
+}
+// The lines that differ, from a longest-common-subsequence diff: `-` for the snapshot as
+// committed, `+` for the database. Snapshots are small, so the quadratic table is fine.
+export function lineChanges(current, next) {
+    const a = current.split('\n');
+    const b = next.split('\n');
+    const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            const row = lcs[i];
+            row[j] =
+                a[i] === b[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], row[j + 1]);
+        }
+    }
+    const changes = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length || j < b.length) {
+        if (i < a.length && j < b.length && a[i] === b[j]) {
+            i++;
+            j++;
+        }
+        else if (i < a.length &&
+            (j === b.length ||
+                lcs[i + 1][j] >= lcs[i][j + 1])) {
+            changes.push(`- ${a[i++]}`);
+        }
+        else {
+            changes.push(`+ ${b[j++]}`);
+        }
+    }
+    return changes;
+}
+export function checkFailureMessage(failures) {
+    const blocks = failures.map((failure, i) => {
+        const details = failure.details
+            .flatMap((detail) => detail.split('\n'))
+            .map((line) => `     ${line}`);
+        return [`${i + 1}. ${failure.problem}:`, ...details, `   Fix: ${failure.fix}`].join('\n');
+    });
+    return `sequel check found ${failures.length} problem${failures.length === 1 ? '' : 's'}:\n\n${blocks.join('\n\n')}`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { ensureBinary } from './binaries/ensure-binary.js';
+import { checkFailureMessage, runChecks } from './check.js';
+import { loadConfig } from './config/load-config.js';
+import { requireDatabase } from './config/resolve-config.js';
+import { SequelError } from './errors.js';
+import { readExtrasSnapshot } from './extras/snapshot.js';
+import { writeAtomically } from './files.js';
+import { generateModules } from './generate/generate-modules.js';
+import { findQueryFolders } from './generate/modules.js';
+import { watchAndRerun } from './generate/watch.js';
+import { databaseName } from './db/connection.js';
+import { adoptPrismaFiles, adoptPrismaHistory, PRISMA_LOCK_FILE } from './migrate/adopt-prisma.js';
+import { deployTo } from './migrate/deploy.js';
+import { findMigrations, readMigrationFile } from './migrate/files.js';
+import { lintFailureMessage, lintMigrations, migrationsToLint } from './migrate/lint.js';
+import { newMigration } from './migrate/new.js';
+import { assertValidSchema, formatSchemaFiles, readSchemaFiles, schemaWarnings, } from './schema/schema.js';
+import { unsupportedColumns } from './schema/unsupported.js';
+const OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+    config: { type: 'string', short: 'c' },
+    watch: { type: 'boolean' },
+    'allow-out-of-order': { type: 'boolean' },
+};
+async function validate(context) {
+    const config = await loadManaged(context);
+    const files = await readSchemaFiles(config.schema, config.root);
+    assertValidSchema(files, config.root);
+    for (const warning of schemaWarnings(files, config.root)) {
+        out(`${warning.shown}:${warning.line}: warning: ${warning.message}`);
+    }
+    out(`The schema is valid: ${plural(files.length, 'file')} in ${shown(config, config.schema)}.`);
+}
+async function format(context) {
+    const config = await loadManaged(context);
+    const changed = await formatSchemaFiles(await readSchemaFiles(config.schema, config.root), config.root);
+    for (const file of changed)
+        out(`Formatted ${shown(config, file)}`);
+    if (changed.length === 0)
+        out(`The schema is already formatted.`);
+}
+async function migrateNew(context) {
+    const config = await loadManaged(context);
+    const { file, findings } = await newMigration({ config, name: context.positionals[0] });
+    if (file === undefined) {
+        out('The migrations already match the schema: no migration written.');
+        return;
+    }
+    out(`Wrote ${shown(config, file)}`);
+    if (findings.length > 0) {
+        throw new SequelError(`${lintFailureMessage(findings)}\n${shown(config, file)} stays written: fix it before committing.`);
+    }
+    out('Lint: no findings.');
+}
+async function migrateLint(context) {
+    const config = await loadManaged(context);
+    const migrations = context.positionals.length > 0
+        ? await Promise.all(context.positionals.map(async (given) => {
+            const file = path.resolve(given);
+            if (!existsSync(file))
+                throw new SequelError(`${given} does not exist.`);
+            return readMigrationFile(file, config.root);
+        }))
+        : migrationsToLint(await findMigrations(config.migrations, { root: config.root }), config.lint.cutover);
+    // The index rule reads the schema folder; without one, it is skipped.
+    const schema = await readSchemaFiles(config.schema, config.root).catch((error) => {
+        if (error instanceof SequelError)
+            return undefined;
+        throw error;
+    });
+    const findings = await lintMigrations({
+        squawk: await ensureBinary('squawk'),
+        migrations,
+        root: config.root,
+        ...(schema === undefined ? {} : { unsupported: unsupportedColumns(schema) }),
+    });
+    if (findings.length > 0)
+        throw new SequelError(lintFailureMessage(findings));
+    out(`${plural(migrations.length, 'migration file')} linted: no findings.`);
+}
+async function migrateAdoptPrisma(context) {
+    const config = await loadManaged(context);
+    const url = requireDatabase(config, 'target');
+    const files = await adoptPrismaFiles(config.migrations, config.root);
+    for (const { from, to } of files.renamed) {
+        out(`Renamed ${shown(config, from)} to ${shown(config, to)}`);
+    }
+    if (files.lockRemoved) {
+        out(`Removed ${shown(config, path.join(config.migrations, PRISMA_LOCK_FILE))}`);
+    }
+    if (files.renamed.length > 0 || files.lockRemoved) {
+        out('Commit the renamed files. Their contents are unchanged, so their checksums still match.');
+    }
+    else {
+        out("Files: none in Prisma's layout, so nothing to rename.");
+    }
+    const migrations = await findMigrations(config.migrations, { root: config.root });
+    const history = await adoptPrismaHistory({ url, migrations });
+    const database = databaseName(url);
+    if (history.status === 'adopted') {
+        out(`History: created sequel_migrations on ${database} from ${plural(history.rows, 'applied Prisma migration')}. _prisma_migrations is left as it was.`);
+    }
+    else if (history.status === 'already-adopted') {
+        out(`History: ${database} already has sequel_migrations, so nothing to adopt.`);
+    }
+    else {
+        out(`History: ${database} has no Prisma history (_prisma_migrations), so nothing to adopt. \`sequel migrate deploy\` creates sequel's history.`);
+    }
+}
+async function migrateDeploy(context) {
+    const config = await loadManaged(context);
+    await deployTo(config, requireDatabase(config, 'target'), {
+        allowOutOfOrder: context.flags['allow-out-of-order'],
+        log: out,
+    });
+}
+async function generate(context) {
+    const config = await load(context);
+    const url = requireDatabase(config, 'test');
+    const once = async () => {
+        // With external migrations, the test database is typed as the other tool left it.
+        if (!config.externalMigrations) {
+            await deployTo(config, url, { log: out, quietWhenCurrent: true });
+        }
+        const folders = await findQueryFolders(config.queries);
+        const result = await generateModules({
+            sqlc: await ensureBinary('sqlc'),
+            databaseUrl: url,
+            folders,
+            bigint: config.types.bigint,
+            root: config.root,
+        });
+        for (const file of result.written)
+            out(`Wrote ${shown(config, file)}`);
+        for (const file of result.deleted)
+            out(`Deleted ${shown(config, file)}: its query file is gone`);
+        if (result.written.length === 0 && result.deleted.length === 0) {
+            out(`The generated modules are up to date (${plural(result.unchanged.length, 'module')}).`);
+        }
+    };
+    if (!context.flags.watch) {
+        await once();
+        return;
+    }
+    const stop = new AbortController();
+    process.once('SIGINT', () => stop.abort());
+    process.once('SIGTERM', () => stop.abort());
+    const folders = await findQueryFolders(config.queries);
+    if (!config.externalMigrations)
+        folders.push(config.migrations);
+    await watchAndRerun({
+        folders,
+        run: once,
+        onError: (error) => process.stderr.write(`${describeError(error)}\n`),
+        signal: stop.signal,
+    });
+}
+async function extras(context) {
+    const config = await loadManaged(context);
+    const url = requireDatabase(config, 'test');
+    await deployTo(config, url, { log: out, quietWhenCurrent: true });
+    const next = await readExtrasSnapshot(url);
+    const current = await readFile(config.snapshot, 'utf8').catch(() => undefined);
+    if (current === next) {
+        out(`The extras snapshot is up to date: ${shown(config, config.snapshot)}`);
+        return;
+    }
+    await mkdir(path.dirname(config.snapshot), { recursive: true });
+    await writeAtomically(config.snapshot, next);
+    out(`Wrote ${shown(config, config.snapshot)}`);
+}
+async function check(context) {
+    const config = await load(context);
+    const failures = await runChecks(config, out);
+    if (failures.length > 0)
+        throw new SequelError(checkFailureMessage(failures));
+    out('All checks passed.');
+}
+function load(context) {
+    return loadConfig({ config: context.config });
+}
+// For the commands that act on the schema, the migrations or the extras snapshot: they refuse
+// when another tool manages them, before connecting, reading a file or fetching a binary.
+async function loadManaged(context) {
+    const config = await load(context);
+    if (config.externalMigrations) {
+        throw new SequelError(`\`sequel ${context.name}\` is off: ${path.basename(config.configFile)} sets \`externalMigrations\`, so another tool manages this app's schema and migrations, and sequel only types its queries. To have sequel manage them, remove \`externalMigrations\`.`);
+    }
+    return config;
+}
+function shown(config, file) {
+    return path.relative(config.root, file) || '.';
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function out(message) {
+    process.stdout.write(`${message}\n`);
+}
+const COMMANDS = {
+    validate: {
+        usage: 'validate',
+        summary: 'Check the schema folder, printing each error with its file and line.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: validate,
+    },
+    format: {
+        usage: 'format',
+        summary: 'Format every file in the schema folder in place.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: format,
+    },
+    'migrate new': {
+        usage: 'migrate new <name>',
+        summary: 'Diff the migration history against the schema and write a new migration.',
+        flags: [],
+        args: { min: 1, max: 1 },
+        run: migrateNew,
+    },
+    'migrate lint': {
+        usage: 'migrate lint [file…]',
+        summary: 'Lint the files given, or every migration after the lint cut-over.',
+        flags: [],
+        args: { min: 0, max: Infinity },
+        run: migrateLint,
+    },
+    'migrate adopt-prisma': {
+        usage: 'migrate adopt-prisma',
+        summary: "Move from Prisma's migration files and history to sequel's.",
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: migrateAdoptPrisma,
+    },
+    'migrate deploy': {
+        usage: 'migrate deploy [--allow-out-of-order]',
+        summary: 'Apply pending migrations to the target database.',
+        flags: ['allow-out-of-order'],
+        args: { min: 0, max: 0 },
+        run: migrateDeploy,
+    },
+    generate: {
+        usage: 'generate [--watch]',
+        summary: 'Migrate the test database, then write a typed module beside each query file.',
+        flags: ['watch'],
+        args: { min: 0, max: 0 },
+        run: generate,
+    },
+    extras: {
+        usage: 'extras',
+        summary: 'Migrate the test database, then rewrite the extras snapshot.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: extras,
+    },
+    check: {
+        usage: 'check',
+        summary: 'Fail on stale generated code, drift, lint findings or a stale snapshot.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: check,
+    },
+};
+function help() {
+    const width = Math.max(...Object.values(COMMANDS).map((command) => command.usage.length));
+    const lines = Object.values(COMMANDS).map((command) => `  ${command.usage.padEnd(width)}  ${command.summary}`);
+    return [
+        'Usage: sequel <command> [options]',
+        '',
+        'Commands:',
+        ...lines,
+        '',
+        'Options:',
+        `  ${'-c, --config <file>'.padEnd(width)}  The config file. Default: sequel.config.ts`,
+        `  ${'-h, --help'.padEnd(width)}  Show this help.`,
+        '',
+    ].join('\n');
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        // parseArgs reports unknown and malformed options as TypeErrors with a clear message.
+        throw new SequelError(`${error.message}\nRun \`sequel --help\` for usage.`);
+    }
+    const { values, positionals } = parsed;
+    const [first, second] = positionals;
+    const name = first === 'migrate' && second !== undefined ? `migrate ${second}` : first;
+    if (values.help || name === undefined) {
+        process.stdout.write(help());
+        return;
+    }
+    const command = COMMANDS[name];
+    if (command === undefined) {
+        const hint = first === 'migrate'
+            ? 'migrate needs a subcommand: new, lint, adopt-prisma or deploy.'
+            : `Unknown command \`${first}\`.`;
+        throw new SequelError(`${hint}\nRun \`sequel --help\` for usage.`);
+    }
+    for (const flag of ['watch', 'allow-out-of-order']) {
+        if (values[flag] && !command.flags.includes(flag)) {
+            throw new SequelError(`\`sequel ${name}\` has no --${flag} option. Usage: sequel ${command.usage}`);
+        }
+    }
+    const args = positionals.slice(name.split(' ').length);
+    if (args.length < command.args.min || args.length > command.args.max) {
+        throw new SequelError(`Usage: sequel ${command.usage}`);
+    }
+    await command.run({
+        name,
+        config: values.config,
+        positionals: args,
+        flags: {
+            watch: values.watch ?? false,
+            'allow-out-of-order': values['allow-out-of-order'] ?? false,
+        },
+    });
+}
+// An expected failure is its message alone; anything else keeps its stack.
+function describeError(error) {
+    if (error instanceof SequelError)
+        return error.message;
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+try {
+    await main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`${describeError(error)}\n`);
+    process.exitCode = 1;
+}

package/dist/config/define-config.d.ts

@@ -0,0 +1,24 @@
+export type SequelConfig = {
+    schema?: string;
+    migrations?: string;
+    queries?: string | string[];
+    snapshot?: string;
+    databases?: {
+        target?: string | undefined;
+        test?: string | undefined;
+        shadow?: string | undefined;
+    };
+    timeouts?: {
+        lockMs?: number;
+        statementMs?: number;
+    };
+    lint?: {
+        cutover?: string;
+    };
+    types?: {
+        bigint?: BigintMode;
+    };
+    externalMigrations?: boolean;
+};
+export type BigintMode = 'string' | 'number' | 'bigint';
+export declare function defineConfig(config: SequelConfig): SequelConfig;

package/dist/config/define-config.js

@@ -0,0 +1,4 @@
+// An identity function that exists for its types: `export default defineConfig({ … })`.
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/load-config.d.ts

@@ -0,0 +1,6 @@
+import { type ResolvedConfig } from './resolve-config.ts';
+export declare const CONFIG_FILE = "sequel.config.ts";
+export declare function loadConfig(options?: {
+    config?: string;
+    cwd?: string;
+}): Promise<ResolvedConfig>;