migrane 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A migration runner that knows nothing about your application.
+ *
+ * Handed a {@link Driver} and a list of directories, and that is all it knows:
+ * no ORM, no container, no module registry, no dependency it makes you adopt.
+ * Drivers live behind their own import path, so reaching for one is a choice.
+ *
+ * ```ts
+ * // database/config.ts
+ * import { defineConfig } from 'migrane';
+ * import { pgDriver } from 'migrane/drivers/pg';
+ *
+ * export default defineConfig({
+ *   dirs: ['./migrations'],
+ *   seeds: './seeders',
+ *   driver: () => pgDriver(process.env.DATABASE_URL!),
+ * });
+ * ```
+ */
+export { entryFor, type EntryOptions } from './bundle.js';
+export { defineConfig, findConfig, loadConfig, type Resolved, } from './config.js';
+export { reachable, withDriver } from './connect.js';
+export { discover } from './discover.js';
+export { compose, fromManifest, loadAll, type Bundled, type Shipped, } from './load.js';
+export { withLock } from './lock.js';
+export { reset, resetPlanFrom, type ResetPlan } from './reset.js';
+export { run } from './cli.js';
+export { consoleReporter, down, planFrom, status, up, type Plan, type Reporter, type Status, } from './runner.js';
+export { refuse } from './safety.js';
+export { seed, seedPlanFrom, seedStatus, unitsIn, unseed, type SeedPlan, type Seeded, } from './seeds.js';
+export { applied, ChangedError, ensure, forget, record, type Applied, } from './storage.js';
+export type { Config, Context, Discovered, Driver, Fragment, Hook, Migration, Module, Part, Policy, Queryable, Row, Session, Sql, Transacted, } from './types.js';

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * A migration runner that knows nothing about your application.
+ *
+ * Handed a {@link Driver} and a list of directories, and that is all it knows:
+ * no ORM, no container, no module registry, no dependency it makes you adopt.
+ * Drivers live behind their own import path, so reaching for one is a choice.
+ *
+ * ```ts
+ * // database/config.ts
+ * import { defineConfig } from 'migrane';
+ * import { pgDriver } from 'migrane/drivers/pg';
+ *
+ * export default defineConfig({
+ *   dirs: ['./migrations'],
+ *   seeds: './seeders',
+ *   driver: () => pgDriver(process.env.DATABASE_URL!),
+ * });
+ * ```
+ */
+export { entryFor } from './bundle.js';
+export { defineConfig, findConfig, loadConfig, } from './config.js';
+export { reachable, withDriver } from './connect.js';
+export { discover } from './discover.js';
+export { compose, fromManifest, loadAll, } from './load.js';
+export { withLock } from './lock.js';
+export { reset, resetPlanFrom } from './reset.js';
+export { run } from './cli.js';
+export { consoleReporter, down, planFrom, status, up, } from './runner.js';
+export { refuse } from './safety.js';
+export { seed, seedPlanFrom, seedStatus, unitsIn, unseed, } from './seeds.js';
+export { applied, ChangedError, ensure, forget, record, } from './storage.js';

package/dist/load.d.ts

@@ -0,0 +1,53 @@
+import type { Discovered, Migration, Module } from './types.js';
+/**
+ * A `.sql` migration: two sections, marked by comments.
+ *
+ * The whole section is sent as one statement with no bind parameters, so
+ * PostgreSQL's simple query protocol runs every statement in it. Splitting on
+ * `;` ourselves would be wrong the first time a function body or a quoted
+ * string contained one.
+ */
+export declare const parseSql: (text: string, label: string) => Module;
+/**
+ * Runs parts in declaration order and reverses them for `down`.
+ *
+ * The transaction opt-out is taken by the whole migration if any single part
+ * asks for it. A part needing `CREATE INDEX CONCURRENTLY` cannot be wrapped,
+ * and wrapping the others while leaving that one bare would mean a failure
+ * rolling back some of a migration and not the rest — worse than being honest
+ * that this one is not atomic.
+ */
+export declare const compose: (parts: readonly Module[]) => Module;
+/**
+ * Loads one discovered migration, composing its parts if it has several.
+ *
+ * `run` rather than `files`: a directory with an `index.ts` runs that one file,
+ * and the rest are its imports. They still count towards the checksum, which is
+ * discovery's business rather than this one's.
+ */
+export declare const load: (entry: Discovered) => Promise<Migration>;
+export declare const loadAll: (entries: readonly Discovered[]) => Promise<Migration[]>;
+/**
+ * One part of a shipped unit: a module the manifest imported, or SQL text it
+ * carried inline because an image has no file to read.
+ */
+export type Shipped = Module | {
+    sql: string;
+};
+/** One migration or seed unit, as the generated manifest names it. */
+export interface Bundled {
+    name: string;
+    sequence: number;
+    checksum: string;
+    parts: readonly Shipped[];
+}
+/**
+ * Turns a manifest's arrays into units the runner takes — {@link loadAll} for a
+ * machine with no source tree.
+ *
+ * The same composition rule applies, because it is the same rule: one part runs
+ * as itself, several compose in order with `down` reversed. Parsing the inline
+ * SQL happens here rather than in the generated file, which is what lets that
+ * file import nothing from this package.
+ */
+export declare const fromManifest: (entries: readonly Bundled[]) => Migration[];

package/dist/load.js

@@ -0,0 +1,119 @@
+import { readFileSync } from 'node:fs';
+import { extname, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Turning what discovery found into something runnable.
+ *
+ * A directory migration's parts are composed here rather than by an `index.ts`
+ * the author writes: `up` in path order, `down` in reverse, so foreign keys
+ * hold in both directions. That is the whole reason the numbers on the files
+ * are load-bearing — they are the dependency order, and there is no second
+ * place stating it.
+ */
+/** `-- migrate:up`, optionally `-- migrate:up transaction:false`. */
+const SECTION = /^\s*--\s*migrate:(up|down)\b(.*)$/;
+/**
+ * A `.sql` migration: two sections, marked by comments.
+ *
+ * The whole section is sent as one statement with no bind parameters, so
+ * PostgreSQL's simple query protocol runs every statement in it. Splitting on
+ * `;` ourselves would be wrong the first time a function body or a quoted
+ * string contained one.
+ */
+export const parseSql = (text, label) => {
+    const sections = {};
+    let current;
+    let transacted = true;
+    for (const line of text.split('\n')) {
+        const marker = SECTION.exec(line);
+        if (marker) {
+            if (/\btransaction:\s*false\b/.test(marker[2] ?? ''))
+                transacted = false;
+            current = sections[marker[1]] ??= [];
+            continue;
+        }
+        current?.push(line);
+    }
+    if (!sections.up) {
+        throw new Error(`${label} has no "-- migrate:up" section, so there is nothing to run.`);
+    }
+    const body = (key) => sections[key]?.join('\n').trim();
+    const up = body('up');
+    const down = body('down');
+    return {
+        transaction: transacted,
+        up: async ({ db }) => {
+            if (up)
+                await db.query(up);
+        },
+        down: down ? async ({ db }) => void (await db.query(down)) : undefined,
+    };
+};
+const loadFile = async (file, root) => {
+    const label = relative(root, file) || file;
+    if (extname(file) === '.sql') {
+        return parseSql(readFileSync(file, 'utf8'), label);
+    }
+    // A file URL rather than the path: on Windows a bare absolute path is not a
+    // valid specifier, and this is the one place the package touches the loader.
+    const module = (await import(pathToFileURL(file).href));
+    if (typeof module.up !== 'function') {
+        throw new Error(`${label} does not export an "up" function.`);
+    }
+    return module;
+};
+/**
+ * Runs parts in declaration order and reverses them for `down`.
+ *
+ * The transaction opt-out is taken by the whole migration if any single part
+ * asks for it. A part needing `CREATE INDEX CONCURRENTLY` cannot be wrapped,
+ * and wrapping the others while leaving that one bare would mean a failure
+ * rolling back some of a migration and not the rest — worse than being honest
+ * that this one is not atomic.
+ */
+export const compose = (parts) => ({
+    transaction: parts.every((part) => part.transaction !== false),
+    up: async (context) => {
+        for (const part of parts)
+            await part.up(context);
+    },
+    down: parts.some((part) => part.down)
+        ? async (context) => {
+            for (const part of [...parts].reverse())
+                await part.down?.(context);
+        }
+        : undefined,
+});
+/**
+ * Loads one discovered migration, composing its parts if it has several.
+ *
+ * `run` rather than `files`: a directory with an `index.ts` runs that one file,
+ * and the rest are its imports. They still count towards the checksum, which is
+ * discovery's business rather than this one's.
+ */
+export const load = async (entry) => {
+    const parts = await Promise.all(entry.run.map((file) => loadFile(file, entry.path)));
+    return {
+        name: entry.name,
+        sequence: entry.sequence,
+        checksum: entry.checksum,
+        module: parts.length === 1 ? parts[0] : compose(parts),
+    };
+};
+export const loadAll = (entries) => Promise.all(entries.map(load));
+const moduleOf = (part, label) => 'sql' in part ? parseSql(part.sql, label) : part;
+/**
+ * Turns a manifest's arrays into units the runner takes — {@link loadAll} for a
+ * machine with no source tree.
+ *
+ * The same composition rule applies, because it is the same rule: one part runs
+ * as itself, several compose in order with `down` reversed. Parsing the inline
+ * SQL happens here rather than in the generated file, which is what lets that
+ * file import nothing from this package.
+ */
+export const fromManifest = (entries) => entries.map(({ parts, ...rest }) => ({
+    ...rest,
+    module: parts.length === 1
+        ? moduleOf(parts[0], rest.name)
+        : compose(parts.map((part) => moduleOf(part, rest.name))),
+}));

package/dist/lock.d.ts

@@ -0,0 +1,30 @@
+import type { Session } from './types.js';
+/**
+ * A session-level advisory lock held for the length of a run.
+ *
+ * Two containers starting at once is the ordinary case, not the exotic one.
+ * Without this both read the same empty bookkeeping table and both run the same
+ * `CREATE TABLE`, and the loser fails a deploy over a schema that was in fact
+ * applied correctly.
+ *
+ * Session-level rather than transaction-level because each migration commits in
+ * a transaction of its own, and a lock scoped to one would be released between
+ * migrations — exactly when the other process slips in.
+ */
+/**
+ * A stable key from the table name, so two applications sharing a database
+ * usually do not block each other.
+ *
+ * *Usually*: two names can collide into one key, and thirty-two bits makes that
+ * unlikely rather than impossible. A collision costs waiting, never
+ * correctness, so a wider key would buy a guarantee against a harmless outcome.
+ *
+ * Kept inside a signed 32-bit range because PostgreSQL wants a bigint and any
+ * int is one, well clear of what a JS number could no longer represent exactly.
+ */
+export declare const lockKey: (table: string) => number;
+/**
+ * Choosing the key is this file's business; knowing how a lock is spelled is
+ * the driver's, in a package whose opening line says it names no database.
+ */
+export declare const withLock: <T>(session: Session, table: string, run: () => Promise<T>) => Promise<T>;

package/dist/lock.js

@@ -0,0 +1,35 @@
+/**
+ * A session-level advisory lock held for the length of a run.
+ *
+ * Two containers starting at once is the ordinary case, not the exotic one.
+ * Without this both read the same empty bookkeeping table and both run the same
+ * `CREATE TABLE`, and the loser fails a deploy over a schema that was in fact
+ * applied correctly.
+ *
+ * Session-level rather than transaction-level because each migration commits in
+ * a transaction of its own, and a lock scoped to one would be released between
+ * migrations — exactly when the other process slips in.
+ */
+/**
+ * A stable key from the table name, so two applications sharing a database
+ * usually do not block each other.
+ *
+ * *Usually*: two names can collide into one key, and thirty-two bits makes that
+ * unlikely rather than impossible. A collision costs waiting, never
+ * correctness, so a wider key would buy a guarantee against a harmless outcome.
+ *
+ * Kept inside a signed 32-bit range because PostgreSQL wants a bigint and any
+ * int is one, well clear of what a JS number could no longer represent exactly.
+ */
+export const lockKey = (table) => {
+    let hash = 5381;
+    for (const character of table) {
+        hash = (Math.imul(hash, 33) ^ character.charCodeAt(0)) | 0;
+    }
+    return hash;
+};
+/**
+ * Choosing the key is this file's business; knowing how a lock is spelled is
+ * the driver's, in a package whose opening line says it names no database.
+ */
+export const withLock = (session, table, run) => session.lock(lockKey(table), run);

package/dist/reset.d.ts

@@ -0,0 +1,23 @@
+import { type Reporter } from './runner.js';
+import type { Config, Driver, Policy } from './types.js';
+/**
+ * Drops every object in a schema.
+ *
+ * This exists so new DDL can be folded back into an unreleased migration
+ * instead of accumulating one-line migrations nobody has run — which is the
+ * normal way to work before a first release, and impossible without it, since
+ * an applied migration cannot be edited.
+ *
+ * It is also the only command that leaves a database with *nothing* in it:
+ * `up` runs the `before` hooks, so `fresh` always ends with whatever they
+ * install, and this does not.
+ */
+export interface ResetPlan {
+    schema: string;
+    /** Consulted before anything is dropped. Defaults to `refuse`. */
+    guard?: Policy;
+}
+/** A reset plan from a config, defaulting the schema from the same constant. */
+export declare const resetPlanFrom: (config: Config) => ResetPlan;
+/** The guard runs before the schema name is even quoted. See `safety.ts`. */
+export declare const reset: (driver: Driver, plan: ResetPlan, reporter?: Reporter) => Promise<void>;

package/dist/reset.js

@@ -0,0 +1,16 @@
+import { DEFAULTS } from './defaults.js';
+import { consoleReporter } from './runner.js';
+import { refuse } from './safety.js';
+import { quoteIdent } from './sql.js';
+/** A reset plan from a config, defaulting the schema from the same constant. */
+export const resetPlanFrom = (config) => ({
+    schema: config.schema ?? DEFAULTS.schema,
+    guard: config.guard,
+});
+/** The guard runs before the schema name is even quoted. See `safety.ts`. */
+export const reset = async (driver, plan, reporter = consoleReporter) => {
+    await (plan.guard ?? refuse)(driver, 'reset drops every table');
+    await driver.query(`DROP SCHEMA IF EXISTS ${quoteIdent(plan.schema)} CASCADE`);
+    await driver.query(`CREATE SCHEMA ${quoteIdent(plan.schema)}`);
+    reporter.line('schema dropped');
+};

package/dist/runner.d.ts

@@ -0,0 +1,61 @@
+import type { Config, Driver, Hook, Migration, Policy } from './types.js';
+/**
+ * Applying and reverting — the same way on a developer machine and in a
+ * container, which is what makes a migration's result reproducible.
+ */
+/** Where output goes. Injected so a test can read it back. */
+export interface Reporter {
+    line: (text: string) => void;
+}
+export declare const consoleReporter: Reporter;
+export interface Plan {
+    migrations: readonly Migration[];
+    table: string;
+    before?: readonly Hook[];
+    /** Consulted by `down`, the one destructive verb here. Defaults to `refuse`. */
+    guard?: Policy;
+}
+/**
+ * A plan from a config and migrations already loaded — the shape an entrypoint
+ * built from a manifest is in, where there is nothing to read off a disk.
+ *
+ * The table default is settled here from the same constant `loadConfig` uses,
+ * deliberately: two spellings of one default is how an image ends up recording
+ * migrations in a table the CLI does not look in.
+ */
+export declare const planFrom: (config: Config, migrations: readonly Migration[]) => Plan;
+/**
+ * Each migration commits in a transaction of its own together with the row that
+ * records it, so a failure can never leave the DDL applied and the bookkeeping
+ * unwritten.
+ */
+export declare const up: (driver: Driver, plan: Plan, reporter?: Reporter) => Promise<Migration[]>;
+/**
+ * Revert the most recently applied migration.
+ *
+ * Only one, and only the last: reverting is a decision taken a step at a time,
+ * and a command unwinding an unbounded number of them empties a database by
+ * typo.
+ *
+ * Guarded like `reset`. "No `down` against production" has to sit on the
+ * function to mean anything — a verb withheld from one entrypoint's command
+ * table says nothing about the same function imported directly.
+ */
+export declare const down: (driver: Driver, plan: Plan, reporter?: Reporter) => Promise<Migration | undefined>;
+export interface Status {
+    name: string;
+    applied: boolean;
+    /** Applied, and the file has changed since — what `up` will refuse on. */
+    changed: boolean;
+}
+/**
+ * What is applied and what is pending, in the order they would run.
+ *
+ * Writes nothing beyond the `CREATE TABLE IF NOT EXISTS` that reading requires:
+ * asking a database what it holds should not change what it holds.
+ *
+ * **And it never refuses.** An edited migration is the likeliest reason someone
+ * is running this, so it reports `changed` and finishes the report rather than
+ * answering with a stack trace and no lines. `up` and `down` still refuse.
+ */
+export declare const status: (driver: Driver, plan: Plan, reporter?: Reporter) => Promise<Status[]>;

package/dist/runner.js

@@ -0,0 +1,150 @@
+import { DEFAULTS } from './defaults.js';
+import { withLock } from './lock.js';
+import { refuse } from './safety.js';
+import { sqlOver } from './sql.js';
+import { applied, forget, record, verify } from './storage.js';
+export const consoleReporter = { line: (text) => console.log(text) };
+/**
+ * A plan from a config and migrations already loaded — the shape an entrypoint
+ * built from a manifest is in, where there is nothing to read off a disk.
+ *
+ * The table default is settled here from the same constant `loadConfig` uses,
+ * deliberately: two spellings of one default is how an image ends up recording
+ * migrations in a table the CLI does not look in.
+ */
+export const planFrom = (config, migrations) => ({
+    migrations,
+    table: config.table ?? DEFAULTS.table,
+    before: config.before,
+    guard: config.guard,
+});
+const contextOver = (db) => ({ sql: sqlOver(db), db });
+/**
+ * Everything a run needs held at once: one pinned connection, the advisory
+ * lock on it, and the bookkeeping read inside that lock.
+ *
+ * Reading `applied` *inside* the lock is the point. Read it outside and two
+ * processes can both see the same empty table before either takes the lock,
+ * which is the race the lock exists to close.
+ */
+const inRun = async (driver, plan, run) => driver.session((session) => withLock(session, plan.table, async () => {
+    const rows = await applied(session, plan.table);
+    verify(rows, plan.migrations);
+    return run(session, new Set(rows.map((row) => row.name)));
+}));
+/**
+ * Each migration commits in a transaction of its own together with the row that
+ * records it, so a failure can never leave the DDL applied and the bookkeeping
+ * unwritten.
+ */
+export const up = async (driver, plan, reporter = consoleReporter) => inRun(driver, plan, async (session, done) => {
+    // Before the pending check, not after: a hook syncs things a migration may
+    // reference, and whether it needs syncing has nothing to do with whether a
+    // *new* migration was added. Registering something that contributes a type
+    // has to take effect on the next `migrate`, with no migration written.
+    for (const hook of plan.before ?? [])
+        await hook(contextOver(session));
+    const pending = plan.migrations.filter(({ name }) => !done.has(name));
+    if (!pending.length) {
+        reporter.line('nothing to do');
+        return [];
+    }
+    for (const migration of pending) {
+        const { name, checksum, module } = migration;
+        reporter.line(`  migrating  ${name}`);
+        const started = performance.now();
+        const apply = async (db) => {
+            await module.up(contextOver(db));
+            await record(db, plan.table, {
+                name,
+                checksum,
+                duration: Math.round(performance.now() - started),
+            });
+        };
+        // The opt-out is not a detail to hide: an untransacted migration that
+        // fails half way leaves the schema changed and unrecorded, and the
+        // operator needs to know which one that was.
+        if (module.transaction === false) {
+            reporter.line(`  (untransacted)`);
+            await apply(session);
+        }
+        else {
+            await session.transaction(apply);
+        }
+        reporter.line(`  migrated   ${name}  ${Math.round(performance.now() - started)}ms`);
+    }
+    reporter.line(`applied ${pending.length}`);
+    return pending;
+});
+/**
+ * Revert the most recently applied migration.
+ *
+ * Only one, and only the last: reverting is a decision taken a step at a time,
+ * and a command unwinding an unbounded number of them empties a database by
+ * typo.
+ *
+ * Guarded like `reset`. "No `down` against production" has to sit on the
+ * function to mean anything — a verb withheld from one entrypoint's command
+ * table says nothing about the same function imported directly.
+ */
+export const down = async (driver, plan, reporter = consoleReporter) => {
+    await (plan.guard ?? refuse)(driver, 'down reverts a migration');
+    return inRun(driver, plan, async (session, done) => {
+        const last = [...plan.migrations]
+            .reverse()
+            .find(({ name }) => done.has(name));
+        if (!last) {
+            reporter.line('nothing to do');
+            return undefined;
+        }
+        if (!last.module.down) {
+            throw new Error(`"${last.name}" has no "down", so it cannot be reverted.`);
+        }
+        reporter.line(`  reverting  ${last.name}`);
+        const started = performance.now();
+        const revert = async (db) => {
+            await last.module.down?.(contextOver(db));
+            await forget(db, plan.table, last.name);
+        };
+        if (last.module.transaction === false)
+            await revert(session);
+        else
+            await session.transaction(revert);
+        reporter.line(`  reverted   ${last.name}  ${Math.round(performance.now() - started)}ms`);
+        return last;
+    });
+};
+/**
+ * What is applied and what is pending, in the order they would run.
+ *
+ * Writes nothing beyond the `CREATE TABLE IF NOT EXISTS` that reading requires:
+ * asking a database what it holds should not change what it holds.
+ *
+ * **And it never refuses.** An edited migration is the likeliest reason someone
+ * is running this, so it reports `changed` and finishes the report rather than
+ * answering with a stack trace and no lines. `up` and `down` still refuse.
+ */
+export const status = async (driver, plan, reporter = consoleReporter) => {
+    const rows = await applied(driver, plan.table);
+    const done = new Map(rows.map((row) => [row.name, row.checksum]));
+    const lines = plan.migrations.map(({ name, checksum }) => ({
+        name,
+        applied: done.has(name),
+        changed: done.has(name) && done.get(name) !== checksum,
+    }));
+    for (const { name, applied: isApplied, changed } of lines) {
+        reporter.line(changed
+            ? `  changed  ${name}  (edited after it was applied)`
+            : `  ${isApplied ? 'up     ' : 'pending'}  ${name}`);
+    }
+    if (!lines.length)
+        reporter.line('  no migrations');
+    // A name in the table with no file behind it is what a squash looks like from
+    // the database's side, and saying so is more useful than staying quiet.
+    for (const row of rows) {
+        if (!plan.migrations.some(({ name }) => name === row.name)) {
+            reporter.line(`  orphan   ${row.name}  (recorded, not on disk)`);
+        }
+    }
+    return lines;
+};

package/dist/safety.d.ts

@@ -0,0 +1,7 @@
+import type { Driver } from './types.js';
+/**
+ * @param what what the command does, as a clause — `reset drops every table`.
+ * It opens both messages, so the refusal reads as a sentence about the command
+ * rather than about the guard.
+ */
+export declare const refuse: (driver: Driver, what: string) => void;

package/dist/safety.js

@@ -0,0 +1,45 @@
+/**
+ * The refusal every destructive command runs through **by default**.
+ *
+ * Default, not mechanism: a consumer who declares {@link Config.guard} replaces
+ * both rules below. Declaring nothing is what keeps them absolute.
+ *
+ * Two rules, because there are two different mistakes. `NODE_ENV=production`
+ * catches a command run *inside* a deployed environment, and nothing here gets
+ * past it. The host catches the commoner one the first cannot see — a laptop
+ * holding a `.env` that points somewhere real — and is overridable, because a
+ * remote database you own and mean to rebuild is legitimate. The override must
+ * *name* the host, so a stale export cannot answer for a database it was never
+ * about.
+ *
+ * The host comes off the driver rather than the environment, which is why
+ * {@link Driver.host} exists: a guard reading a variable that merely resembles
+ * the connection is not guarding the connection.
+ */
+/** Set to the exact host you mean, and only for as long as you mean it. */
+const OVERRIDE = 'DB_ALLOW_REMOTE';
+/**
+ * A unix socket (`''`) counts, because a socket cannot leave the host. A
+ * compose service name like `postgres` deliberately does not: on a droplet that
+ * is exactly what production is called.
+ */
+const isLocal = (host) => host === '' ||
+    host === 'localhost' ||
+    host === '::1' ||
+    /^127\./.test(host) ||
+    host.endsWith('.localhost');
+/**
+ * @param what what the command does, as a clause — `reset drops every table`.
+ * It opens both messages, so the refusal reads as a sentence about the command
+ * rather than about the guard.
+ */
+export const refuse = (driver, what) => {
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`${what} and will not run with NODE_ENV=production.`);
+    }
+    const { host } = driver;
+    if (isLocal(host) || process.env[OVERRIDE] === host)
+        return;
+    throw new Error(`${what}, and ${host} is not this machine.\n` +
+        `  If you mean that database, name it: ${OVERRIDE}=${host} <the same command>`);
+};

package/dist/seeds.d.ts

@@ -0,0 +1,60 @@
+import { type Reporter } from './runner.js';
+import type { Config, Discovered, Driver, Migration, Policy, Row } from './types.js';
+/**
+ * Seed units — fixtures, and the deliberate opposite of a migration.
+ *
+ * Units are **alternatives, not increments**: one directory is one dataset and
+ * you run exactly one against a fresh database. So a unit is recorded but never
+ * refused — editing a fixture set and running it again is how one is used.
+ *
+ * The row answers a different question from a migration's: *which fixtures is
+ * this database holding, and do they still match the units in hand.*
+ *
+ * Split the way migrations are: {@link unitsIn} reads a directory, everything
+ * below it takes units already loaded. A seed that loads itself cannot ship,
+ * and an image has no `seeders/` directory to load from.
+ */
+export interface Seeded extends Row {
+    name: string;
+    checksum: string;
+    run_at: string;
+}
+/**
+ * Every directory under the seeds root holding something runnable — the seed
+ * half of `discover()`, and the only part of this file that touches a disk.
+ *
+ * A unit composes exactly like a directory migration, `index.ts` rule included.
+ * `discover()` cannot find it because that enforces a `<number>-<slug>` name,
+ * and a unit has no number: you pick it by name, so `sequence` is `0` for all
+ * of them. A directory holding nothing runnable is skipped, as `discover` does.
+ */
+export declare const unitsIn: (dir: string) => Discovered[];
+export interface SeedPlan {
+    /**
+     * The units, already loaded — `loadAll(unitsIn(dir))` on a developer machine,
+     * and a generated array in an image. Paths are deliberately absent: where a
+     * unit came from was discovery's problem, and the code that runs it is the
+     * same code in both places.
+     */
+    units: readonly Migration[];
+    table: string;
+    /** Consulted by `seed` and `unseed`. Defaults to `refuse`. */
+    guard?: Policy;
+}
+/**
+ * A seed plan from a config and units already loaded — `planFrom`'s twin, and
+ * defaulting its table from the same constant for the same reason.
+ */
+export declare const seedPlanFrom: (config: Config, units: readonly Migration[]) => SeedPlan;
+export declare const seed: (driver: Driver, plan: SeedPlan, unit: string, reporter?: Reporter) => Promise<void>;
+export declare const unseed: (driver: Driver, plan: SeedPlan, unit: string, reporter?: Reporter) => Promise<void>;
+/**
+ * What this database was seeded with, and whether that unit still matches disk.
+ *
+ * Read from the database rather than inferred from a checkout, which is the
+ * point: the plan tells you which units exist, only the row tells you which one
+ * you are looking at. A unit the plan no longer carries still reports — it is
+ * how a database seeded from a deleted branch explains itself, and how an image
+ * explains fixtures that were dropped from a later build.
+ */
+export declare const seedStatus: (driver: Driver, plan: SeedPlan, reporter?: Reporter) => Promise<Seeded[]>;