ultimabase 0.0.0-stage → 0.1.0

package/dist/cascade.js

@@ -0,0 +1,209 @@
+import { PublicError } from './errors.js';
+import { hasHook, redirectOf } from './hooks.js';
+import { updated } from './write-plan.js';
+/** The stored `one` relations to `target`, each with its `onDelete`. */
+function referencesTo(models, target) {
+    const references = [];
+    for (const model of models.values()) {
+        for (const field of model.fields.values()) {
+            if (field.kind !== 'one' || !field.stored || field.target !== target) {
+                continue;
+            }
+            references.push({ model, field: field.name, onDelete: field.onDelete });
+        }
+    }
+    return references;
+}
+const keyOf = (model, id) => `${model.name}:${id}`;
+/**
+ * Loads every row deleting `deleting` reaches, level by level, as stored: no
+ * `beforeFind`, no access rules (D-54, D-90). Fails with
+ * `RELATION_RESTRICTED` when a row the delete leaves references a deleted one.
+ * A redirected row stays: it cascades nothing (D-89, D-90).
+ */
+export async function cascadeOf(models, model, deleting, store, except) {
+    const redirected = redirectOf(model) !== undefined;
+    const roots = deleting.map((row) => ({ model, row, redirected }));
+    if (redirected)
+        return { deleted: roots, nulled: [] };
+    const deleted = new Map();
+    for (const root of roots)
+        deleted.set(keyOf(model, root.row.id), root);
+    const restricted = [];
+    const nulled = new Map();
+    let level = roots;
+    while (level.length > 0) {
+        const next = [];
+        const ids = new Map();
+        for (const doomed of level) {
+            ids.set(doomed.model, [...(ids.get(doomed.model) ?? []), doomed.row.id]);
+        }
+        for (const [target, targets] of ids) {
+            for (const reference of referencesTo(models, target.name)) {
+                const { model: from, field, onDelete } = reference;
+                const rows = await store.find({
+                    model: from.name,
+                    where: { [field]: { is: { id: { in: targets } } } },
+                    lock: true,
+                });
+                for (const found of rows) {
+                    const left = except?.model === from.name &&
+                        except.field === field &&
+                        except.id === found.id;
+                    if (left)
+                        continue;
+                    if (onDelete === 'restrict') {
+                        restricted.push({
+                            model: from,
+                            field,
+                            id: found.id,
+                            to: target.name,
+                        });
+                    }
+                    else if (onDelete === 'setNull') {
+                        const key = `${from.name}.${field}`;
+                        const group = nulled.get(key) ?? { model: from, field, rows: [] };
+                        // A key holds one target, deleted once: no row comes twice.
+                        group.rows.push(found);
+                        nulled.set(key, group);
+                    }
+                    else if (!deleted.has(keyOf(from, found.id))) {
+                        // Not redirected: a row that stayed would keep a key to a
+                        // deleted one (D-90).
+                        const doomed = { model: from, row: found, redirected: false };
+                        deleted.set(keyOf(from, found.id), doomed);
+                        next.push(doomed);
+                    }
+                }
+            }
+        }
+        level = next;
+    }
+    // A row the cascade removes no longer references anything.
+    const stays = (from, id) => !deleted.has(keyOf(from, id));
+    for (const { model: from, field, id, to } of restricted) {
+        if (!stays(from, id))
+            continue;
+        throw new PublicError('RELATION_RESTRICTED', `${from.name}.${field} references a ${to} the delete removes.`, { details: { model: from.name, field } });
+    }
+    return {
+        // The roots last, in the order they were read.
+        deleted: [...deleted.values()]
+            .slice(roots.length)
+            .toReversed()
+            .concat(roots),
+        nulled: [...nulled.values()].map((group) => ({
+            ...group,
+            rows: group.rows.filter((found) => stays(group.model, found.id)),
+        })),
+    };
+}
+/** Whether deleting a row of `model` runs code of its own. */
+const deleteRuns = (model) => redirectOf(model) !== undefined ||
+    hasHook(model, 'beforeDelete') ||
+    hasHook(model, 'afterDelete') ||
+    hasHook(model, 'afterDeleteCommit');
+const anyOf = (filters) => filters.length === 1 && filters[0] !== undefined
+    ? filters[0]
+    : { OR: filters };
+/**
+ * The changes and checks of a delete whose reach runs no code, so no row is
+ * loaded (D-102): the root goes by `where`, each level by the rows the level
+ * above removed, and `setNull` empties the keys naming them. `undefined` when
+ * a reached model has delete hooks or a redirect, a `setNull` one update
+ * hooks, a cascade comes back to a model it left, or a model is both deleted
+ * and emptied, or emptied twice.
+ */
+export function cascadeWhere(models, model, where) {
+    const deleted = new Map();
+    /** The rows each `setNull` or `restrict` relation reaches, by relation. */
+    const reached = new Map();
+    const reach = (reference, filter) => {
+        const key = `${reference.model.name}.${reference.field}`;
+        const group = reached.get(key) ?? { ...reference, filters: [] };
+        group.filters.push(filter);
+        reached.set(key, group);
+    };
+    const visit = (at, filter, path, parent) => {
+        if (deleteRuns(at))
+            return false;
+        const entry = deleted.get(at.name) ?? {
+            filters: [],
+            depth: 0,
+            parents: new Map(),
+        };
+        entry.filters.push(filter);
+        entry.depth = Math.max(entry.depth, path.length);
+        if (parent !== undefined) {
+            entry.parents.set(`${parent.model.name}.${parent.field}`, parent);
+        }
+        deleted.set(at.name, entry);
+        const below = [...path, at.name];
+        for (const { model: from, field, onDelete } of referencesTo(models, at.name)) {
+            const child = { [field]: { is: filter } };
+            if (onDelete === 'cascade') {
+                const edge = { model: at, field };
+                if (below.includes(from.name) || !visit(from, child, below, edge)) {
+                    return false;
+                }
+            }
+            else if (onDelete === 'setNull' && updated(from)) {
+                return false;
+            }
+            else {
+                const restricts = onDelete === 'restrict';
+                reach({ model: from, field, to: at.name, restricts }, child);
+            }
+        }
+        return true;
+    };
+    if (!visit(model, where, []))
+        return undefined;
+    const groups = [...reached.values()];
+    const nulls = groups.filter((group) => !group.restricts);
+    const emptied = new Set(nulls.map((group) => group.model.name));
+    // PostgreSQL gives two changes of the same rows in one statement no order.
+    const twice = emptied.size < nulls.length ||
+        [...emptied].some((name) => deleted.has(name));
+    if (twice)
+        return undefined;
+    // A row the cascade removes is not refusing.
+    const left = (from, filters) => {
+        const gone = deleted.get(from.name);
+        return gone === undefined
+            ? anyOf(filters)
+            : { AND: [anyOf(filters), { NOT: [anyOf(gone.filters)] }] };
+    };
+    const checks = groups
+        .filter((group) => group.restricts)
+        .map((group) => ({
+        check: {
+            model: group.model.name,
+            where: left(group.model, group.filters),
+            count: 0,
+        },
+        message: `${group.model.name}.${group.field} references a ${group.to} the delete removes.`,
+        restricted: { model: group.model.name, field: group.field },
+    }));
+    // A level after the levels above it: its parents have a lower depth.
+    const levels = [...deleted].toSorted(([, a], [, b]) => a.depth - b.depth);
+    const removedBy = (field, name) => ({
+        [field]: { removedBy: levels.findIndex(([each]) => each === name) },
+    });
+    const changes = [
+        ...levels.map(([name, { parents }]) => ({
+            kind: 'delete',
+            model: name,
+            where: parents.size === 0
+                ? where
+                : anyOf([...parents.values()].map((edge) => removedBy(edge.field, edge.model.name))),
+        })),
+        ...nulls.map((group) => ({
+            kind: 'update',
+            model: group.model.name,
+            where: removedBy(group.field, group.to),
+            set: { [group.field]: null, updatedAt: new Date(Date.now()) },
+        })),
+    ];
+    return { changes, checks };
+}

package/dist/cli-config.d.ts

@@ -0,0 +1,6 @@
+import type { Internals } from './app-internals.ts';
+/** The config file `--config` names, or the first one in `cwd`. */
+export declare function configPath(cwd: string, given: string | undefined): string;
+/** The application the config file default-exports. */
+export declare function load(path: string): Promise<Internals>;
+//# sourceMappingURL=cli-config.d.ts.map

package/dist/cli-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-config.d.ts","sourceRoot":"","sources":["../src/cli-config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAWnD,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAazE;AAED,uDAAuD;AACvD,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAY3D"}

package/dist/cli-config.js

@@ -0,0 +1,45 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// `ultimabase.config.ts` (D-105): where the commands find the application.
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { internalsOf } from './app-internals.js';
+import { Refused } from './errors.js';
+const names = [
+    'ultimabase.config.ts',
+    'ultimabase.config.mts',
+    'ultimabase.config.js',
+    'ultimabase.config.mjs',
+];
+/** The config file `--config` names, or the first one in `cwd`. */
+export function configPath(cwd, given) {
+    if (given !== undefined) {
+        const path = resolve(cwd, given);
+        if (!existsSync(path))
+            throw new Refused(`There is no ${path}.`);
+        return path;
+    }
+    const found = names.map((name) => join(cwd, name)).find(existsSync);
+    if (found === undefined) {
+        throw new Refused(`There is no ultimabase.config.ts in ${cwd}: write one that default-exports defineApp(...), or pass --config <path>.`);
+    }
+    return found;
+}
+/** The application the config file default-exports. */
+export async function load(path) {
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(path).href));
+    const app = typeof module === 'object' && module !== null
+        ? internalsOf(Reflect.get(module, 'default'))
+        : undefined;
+    if (app === undefined) {
+        throw new Refused(`${basename(path)} does not default-export defineApp(...).`);
+    }
+    return app;
+}

package/dist/cli-deploy.d.ts

@@ -0,0 +1,14 @@
+import type { Internals } from './app-internals.ts';
+/** Applies the pending migrations, then stores the models' snapshot. */
+export declare function migrateDeploy({ options }: Internals, dir: string): Promise<readonly string[]>;
+/** What a deploy would do or refuse; `ok` when it has nothing to do. */
+export declare function migrateStatus({ options }: Internals, dir: string): Promise<{
+    readonly lines: readonly string[];
+    readonly ok: boolean;
+}>;
+/**
+ * Drops a development database's tables, then applies every migration; one
+ * on another machine only with `force`.
+ */
+export declare function reset({ options }: Internals, dir: string, force: boolean): Promise<readonly string[]>;
+//# sourceMappingURL=cli-deploy.d.ts.map

package/dist/cli-deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-deploy.d.ts","sourceRoot":"","sources":["../src/cli-deploy.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAmGnD,wEAAwE;AACxE,wBAAsB,aAAa,CAClC,EAAE,OAAO,EAAE,EAAE,SAAS,EACtB,GAAG,EAAE,MAAM,GACT,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAwB5B;AAED,wEAAwE;AACxE,wBAAsB,aAAa,CAClC,EAAE,OAAO,EAAE,EAAE,SAAS,EACtB,GAAG,EAAE,MAAM,GACT,OAAO,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAC,CA8BtE;AAmBD;;;GAGG;AACH,wBAAsB,KAAK,CAC1B,EAAE,OAAO,EAAE,EAAE,SAAS,EACtB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GACZ,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAwC5B"}

package/dist/cli-deploy.js

@@ -0,0 +1,193 @@
+import { MigrationFailed } from './adapter.js';
+import { create, read } from './cli-migrate.js';
+import { kernelLogger, schemaOf } from './lifecycle.js';
+import { Refused } from './errors.js';
+import { ahead, hashOf, held, migrationsOf } from './migrate.js';
+const upToDate = 'The database is up to date.';
+const production = () => process.env['NODE_ENV'] === 'production';
+/** How a development database gets back to what the files build. */
+const rebuild = () => production()
+    ? []
+    : [
+        'Restore the dump you test on, or rebuild this database from the migrations with `npx ultimabase reset`.',
+    ];
+const refused = (...lines) => new Refused([...lines, ...rebuild()].join('\n'));
+/**
+ * The files the database has not applied, and the files it applied after
+ * the last one, which newer code wrote; refuses a file edited or removed.
+ */
+function planOf(stored, files) {
+    const applied = stored?.applied ?? [];
+    const last = files.at(-1)?.name ?? '';
+    const later = [];
+    for (const { name, checksum } of applied) {
+        const file = files.find((given) => given.name === name);
+        if (file === undefined && name > last) {
+            later.push(name);
+        }
+        else if (file === undefined) {
+            throw refused(`${name} was applied to the database, and migrations/ no longer holds it: restore it from version control.`);
+        }
+        else if (file.checksum !== checksum) {
+            throw refused(`${name} was edited after it was applied to the database: restore it, and write the change with ${create}.`);
+        }
+    }
+    const pending = files.filter((file) => !applied.some((given) => given.name === file.name));
+    const [first] = pending;
+    if (first !== undefined && later.length > 0) {
+        throw refused(`${first.name} is pending, and the database applied ${later.join(', ')} after it, which migrations/ does not hold: deploy the code that holds them.`);
+    }
+    return { pending, later };
+}
+/** Why the files do not lead to the models whose hash is `hash`, if so. */
+function behind(files, hash) {
+    const last = files.at(-1);
+    if (last === undefined) {
+        return `migrations/ holds no migration: run ${create} first.`;
+    }
+    if (last.schema === hash)
+        return undefined;
+    return `The models changed after ${last.name} was written: run ${create}, then deploy again.`;
+}
+const syncedSince = () => refused('Development sync changed this database since its last deploy: deploy applies migrations only to a database they built.');
+/** Applies `files`; a refused one names those applied before it. */
+async function deployed(migrations, files, to, again) {
+    const lines = files.map((file) => `Applied ${file.name}.`);
+    try {
+        await migrations.apply({ kind: 'deploy', files, to });
+    }
+    catch (error) {
+        if (!(error instanceof MigrationFailed))
+            throw error;
+        const done = files.findIndex((file) => file.name === error.at);
+        throw new Refused([
+            ...lines.slice(0, done),
+            `${error.at} was not applied: ${error.reason}`,
+            files[done]?.transaction === false
+                ? `It ran without a transaction, so nothing was rolled back: undo what it left, such as an invalid index, then ${again}.`
+                : `The database rolled it back: fix it, then ${again}.`,
+        ].join('\n'));
+    }
+    return lines;
+}
+/** Applies the pending migrations, then stores the models' snapshot. */
+export async function migrateDeploy({ options }, dir) {
+    const { database } = options;
+    const migrations = migrationsOf(database);
+    const schema = schemaOf(options);
+    const to = migrations.snapshot(schema);
+    const hash = hashOf(to);
+    const { files } = await read(dir);
+    const late = behind(files, hash);
+    if (late !== undefined)
+        throw new Refused(late);
+    await database.start(schema, kernelLogger(options));
+    try {
+        const stored = await migrations.stored();
+        if (stored?.by === 'sync')
+            throw syncedSince();
+        const { pending, later } = planOf(stored, files);
+        // The code was rolled back: its migrations are applied, and more.
+        if (later.length > 0)
+            return [ahead(later)];
+        const current = stored?.snapshot !== undefined && hashOf(stored.snapshot) === hash;
+        if (pending.length === 0 && current)
+            return [upToDate];
+        const lines = await deployed(migrations, pending, to, 'deploy again');
+        return lines.length === 0 ? [upToDate] : lines;
+    }
+    finally {
+        await database.stop();
+    }
+}
+/** What a deploy would do or refuse; `ok` when it has nothing to do. */
+export async function migrateStatus({ options }, dir) {
+    const { database } = options;
+    const migrations = migrationsOf(database);
+    const schema = schemaOf(options);
+    const hash = hashOf(migrations.snapshot(schema));
+    const { files } = await read(dir);
+    await database.start(schema, kernelLogger(options));
+    try {
+        const stored = await migrations.stored();
+        const late = behind(files, hash);
+        const { pending, later } = planOf(stored, files);
+        const lines = [
+            ...(late === undefined ? [] : [late]),
+            ...(stored?.by === 'sync' ? [syncedSince().message] : []),
+            ...pending.map((file) => `${file.name} is pending.`),
+        ];
+        if (lines.length > 0)
+            return { lines, ok: false };
+        if (later.length > 0)
+            return { lines: [ahead(later)], ok: true };
+        if (stored?.snapshot !== undefined && hashOf(stored.snapshot) === hash) {
+            return { lines: [upToDate], ok: true };
+        }
+        return {
+            lines: [
+                "The database's snapshot is not the models': run `npx ultimabase migrate deploy`.",
+            ],
+            ok: false,
+        };
+    }
+    finally {
+        await database.stop();
+    }
+}
+/** Drops every table; one another session holds stops the reset. */
+async function dropAll(migrations) {
+    try {
+        return await migrations.reset();
+    }
+    catch (error) {
+        if (!(error instanceof MigrationFailed && error.locked))
+            throw error;
+        throw new Refused([
+            'UltimaBase did not reset the database: another session held a table.',
+            `  ${error.at};`,
+            `  -- ${error.reason}`,
+            held,
+        ].join('\n'));
+    }
+}
+/**
+ * Drops a development database's tables, then applies every migration; one
+ * on another machine only with `force`.
+ */
+export async function reset({ options }, dir, force) {
+    if (production()) {
+        throw new Refused('reset rebuilds only a development database: it is refused in production.');
+    }
+    const { database } = options;
+    const migrations = migrationsOf(database);
+    if (migrations.remote !== undefined && !force) {
+        throw new Refused(`reset drops every table, and ${migrations.remote} is not this machine: pass --force if it holds a development database.`);
+    }
+    const schema = schemaOf(options);
+    const { files, snapshot } = await read(dir);
+    await database.start(schema, kernelLogger(options));
+    try {
+        const dropped = await dropAll(migrations);
+        const lines = [
+            dropped.length === 0
+                ? 'The database held no table.'
+                : `Dropped ${dropped.join(', ')}.`,
+        ];
+        const last = files.at(-1);
+        if (last === undefined) {
+            return [
+                ...lines,
+                'migrations/ holds no migration: the next start builds the tables.',
+            ];
+        }
+        lines.push(...(await deployed(migrations, files, snapshot, 'reset again')));
+        if (behind(files, hashOf(migrations.snapshot(schema))) !== undefined) {
+            lines.push(`The models changed after ${last.name} was written: the next start syncs them.`);
+        }
+        return lines;
+    }
+    finally {
+        await database.stop();
+    }
+}

package/dist/cli-main.d.ts

@@ -0,0 +1,16 @@
+export type Io = {
+    readonly cwd: string;
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+    readonly now: () => Date;
+    /** Runs Node with `args` until it exits, and returns its exit code. */
+    readonly node: (args: readonly string[]) => Promise<number>;
+};
+/** The file `dev` runs under `node --watch`. */
+export declare const serveFile: string;
+export declare const processIo: Io;
+/** Runs the command `args` name, and returns its exit code. */
+export declare function main(args: readonly string[], io?: Io): Promise<number>;
+/** Starts the application of `path`, for `dev` (D-105). */
+export declare function serve(path: string | undefined, io?: Io): Promise<number>;
+//# sourceMappingURL=cli-main.d.ts.map

package/dist/cli-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-main.d.ts","sourceRoot":"","sources":["../src/cli-main.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,EAAE,GAAG;IAChB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAA;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC3D,CAAA;AAED,gDAAgD;AAChD,eAAO,MAAM,SAAS,EAAE,MAGvB,CAAA;AAeD,eAAO,MAAM,SAAS,EAAE,EAMvB,CAAA;AAiFD,+DAA+D;AAC/D,wBAAsB,IAAI,CACzB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,EAAc,GAChB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,2DAA2D;AAC3D,wBAAsB,KAAK,CAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,EAAE,GAAE,EAAc,GAChB,OAAO,CAAC,MAAM,CAAC,CAQjB"}

package/dist/cli-main.js

@@ -0,0 +1,151 @@
+// The `ultimabase` command (D-105): `dev`, `start`, `sync`, `reset` and
+// `migrate`.
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { configPath, load } from './cli-config.js';
+import { migrateDeploy, migrateStatus, reset } from './cli-deploy.js';
+import { migrateCreate, sync } from './cli-migrate.js';
+import { Refused } from './errors.js';
+const usage = `Usage: ultimabase <command> [--config <path>]
+
+  dev                    Start the application, sync its development
+                         database, and restart it when a file changes.
+  start                  Start the application in production.
+  sync [--force]         Sync the development database to the models.
+  reset [--force]        Rebuild the development database from the
+                         migrations: every table is dropped. --force
+                         allows a database on another machine.
+  migrate create <name>  Write the models' changes as a migration, or an
+                         empty one for your SQL.
+  migrate deploy         Apply the pending migrations.
+  migrate status         Say what a deploy would do; exit 1 if anything.`;
+/** The file `dev` runs under `node --watch`. */
+export const serveFile = join(dirname(fileURLToPath(import.meta.url)), 'serve.ts');
+function runNode(args) {
+    return new Promise((done, fail) => {
+        const child = spawn(process.execPath, args, { stdio: 'inherit' });
+        const forward = () => child.kill('SIGTERM');
+        process.on('SIGTERM', forward);
+        child.on('error', fail);
+        child.on('exit', (code) => {
+            process.off('SIGTERM', forward);
+            done(code ?? 1);
+        });
+    });
+}
+export const processIo = {
+    cwd: process.cwd(),
+    out: (text) => process.stdout.write(`${text}\n`),
+    err: (text) => process.stderr.write(`${text}\n`),
+    now: () => new Date(),
+    node: runNode,
+};
+/**
+ * An expected failure, a refusal or an error with a `code` (from Node,
+ * PostgreSQL or the kernel), prints its message; any other, a bug, its
+ * stack (D-105).
+ */
+function report(error, io) {
+    if (!(error instanceof Error))
+        io.err(String(error));
+    else if (error.name === 'Refused' ||
+        typeof Reflect.get(error, 'code') === 'string')
+        io.err(error.message);
+    else
+        io.err(error.stack ?? error.message);
+    return 1;
+}
+/** Reads `args`, refusing an option it does not know with its first sentence. */
+function read(args) {
+    try {
+        return parseArgs({
+            args: [...args],
+            allowPositionals: true,
+            options: {
+                config: { type: 'string' },
+                force: { type: 'boolean', default: false },
+                help: { type: 'boolean', default: false },
+            },
+        });
+    }
+    catch (error) {
+        const message = Reflect.get(Object(error), 'message');
+        const first = String(message).replace(/\.( .*)?$/s, '');
+        throw new Refused(`${first}. Run \`npx ultimabase --help\`.`);
+    }
+}
+async function run(args, io) {
+    const { values, positionals } = read(args);
+    const [command, sub, name, ...rest] = positionals;
+    const known = rest.length === 0 &&
+        (command === 'migrate'
+            ? (sub === 'create' && name !== undefined) ||
+                (['deploy', 'status'].includes(sub ?? '') && name === undefined)
+            : ['dev', 'start', 'sync', 'reset'].includes(command ?? '') &&
+                sub === undefined);
+    if (values.help) {
+        io.out(usage);
+        return 0;
+    }
+    if (!known) {
+        if (command !== undefined)
+            io.err(`Unknown command '${positionals.join(' ')}'.`);
+        io.err(usage);
+        return 1;
+    }
+    const path = configPath(io.cwd, values.config);
+    if (command === 'dev') {
+        process.env['NODE_ENV'] ??= 'development';
+        return io.node(['--watch', serveFile, path]);
+    }
+    if (command === 'start')
+        process.env['NODE_ENV'] ??= 'production';
+    const app = await load(path);
+    const dir = join(dirname(path), 'migrations');
+    if (command === 'start')
+        await app.app.start();
+    else if (command === 'sync') {
+        const said = await sync(app, values.force);
+        if (said !== undefined)
+            io.out(said);
+    }
+    else if (command === 'reset') {
+        for (const line of await reset(app, dir, values.force))
+            io.out(line);
+    }
+    else if (sub === 'deploy') {
+        for (const line of await migrateDeploy(app, dir))
+            io.out(line);
+    }
+    else if (sub === 'status') {
+        const { lines, ok } = await migrateStatus(app, dir);
+        for (const line of lines)
+            io.out(line);
+        return ok ? 0 : 1;
+    }
+    else
+        io.out(await migrateCreate(app, dir, name ?? '', io.now()));
+    return 0;
+}
+/** Runs the command `args` name, and returns its exit code. */
+export async function main(args, io = processIo) {
+    try {
+        return await run(args, io);
+    }
+    catch (error) {
+        return report(error, io);
+    }
+}
+/** Starts the application of `path`, for `dev` (D-105). */
+export async function serve(path, io = processIo) {
+    try {
+        const { app } = await load(configPath(io.cwd, path));
+        await app.start();
+        return 0;
+    }
+    catch (error) {
+        return report(error, io);
+    }
+}

package/dist/cli-migrate.d.ts

@@ -0,0 +1,20 @@
+import type { Migration } from './adapter.ts';
+import type { Internals } from './app-internals.ts';
+export declare const header = "-- ultimabase schema ";
+/** For a statement a transaction refuses: `create index concurrently`. */
+export declare const noTransaction = "-- ultimabase no transaction";
+export declare const create = "`npx ultimabase migrate create <name>`";
+export type Folder = {
+    readonly files: readonly Migration[];
+    readonly snapshot: unknown;
+};
+/** The `.sql` files of `dir` in name order, and its `schema.json`. */
+export declare function read(dir: string): Promise<Folder>;
+/**
+ * Writes the migration from `schema.json` to the models; with no model
+ * changed, a file for the developer's SQL, as a data migration.
+ */
+export declare function migrateCreate({ options }: Internals, dir: string, name: string, now: Date): Promise<string>;
+/** Syncs a development database, losing data only with `force`. */
+export declare function sync({ options }: Internals, force: boolean): Promise<string | undefined>;
+//# sourceMappingURL=cli-migrate.d.ts.map

package/dist/cli-migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-migrate.d.ts","sourceRoot":"","sources":["../src/cli-migrate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAKnD,eAAO,MAAM,MAAM,0BAA0B,CAAA;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,aAAa,iCAAiC,CAAA;AAC3D,eAAO,MAAM,MAAM,2CAA2C,CAAA;AAE9D,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC1B,CAAA;AAED,sEAAsE;AACtE,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCvD;AAuBD;;;GAGG;AACH,wBAAsB,aAAa,CAClC,EAAE,OAAO,EAAE,EAAE,SAAS,EACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,IAAI,GACP,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED,mEAAmE;AACnE,wBAAsB,IAAI,CACzB,EAAE,OAAO,EAAE,EAAE,SAAS,EACtB,KAAK,EAAE,OAAO,GACZ,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B"}