@starci/hfs 4.11.22 → 4.12.0

package/runtime/scripts/hfs/db-errors.d.mts

@@ -0,0 +1,2 @@
+export declare class DbVerbError extends Error {
+}

package/runtime/scripts/hfs/db-errors.mjs

@@ -1,2 +1,3 @@
 // The refusal every `starci app db` verb module throws; dbFailure (db-baseline-verb.mjs) prints its message, any other error is withheld.
-export class DbVerbError extends Error {}
+export class DbVerbError extends Error {
+}

package/runtime/scripts/hfs/db-plan-verb.d.mts

@@ -0,0 +1,33 @@
+import { type DbMainIo } from './db-baseline-verb.mjs';
+/** The inventories a plan compares. */
+export type Kind = 'migrations' | 'cron' | 'queues';
+/** One row of a database inventory, read back as JSON. */
+export type Row = Record<string, unknown>;
+/** How one inventory differs between the repository and the database. */
+export interface Summary {
+    expected: number;
+    remote: number;
+    missing: number;
+    unexpected: number;
+    changed: number;
+}
+/** Reads one read-only inventory query as rows (the clean-plan check of baseline: psql through the ports; db migrate's dry run: the verb context's psql). */
+export type InventoryQuery = (sql: string) => Row[];
+/** The inventories of the active migrations against those of the database: the counts of each kind and whether any differs. */
+export interface PlanInventory {
+    summaries: Record<Kind, Summary>;
+    drift: boolean;
+}
+/** The one line of a summary, as the clean-plan check of `db baseline` and the dry run of `db migrate` print it. */
+export declare const summaryLine: (kind: Kind, item: Summary) => string;
+/** True when a summary names a missing, unexpected or changed entry. */
+export declare const summaryDrifts: (item: Summary) => boolean;
+/** Compares what the active migrations of `root` declare (history, cron jobs, queues) with what `query` reads from the database; read-only. A DbVerbError is a refusal. */
+export declare function planInventory(root: string, query: InventoryQuery): PlanInventory;
+/**
+ * The options of the read-only plan that `db baseline` demands to be clean before it dumps (the dry run of `db migrate` prints the
+ * same inventory through planInventory).
+ */
+export declare const PLAN_OPTIONS: readonly string[];
+/** Numeric exit codes: 0 equal, 1 drift, 2 invalid/failed (an --execute too: a plan never mutates history, queues or jobs); all IO and CLI calls are injectable. */
+export declare function dbPlanMain(argv: string[], { cwd, stdout, stderr, ...ports }?: DbMainIo): number;

package/runtime/scripts/hfs/db-plan-verb.mjs

@@ -1,4 +1,5 @@
-// app db plan: compare migration-owned state (history, pg_cron jobs, pgmq queues) without fetching commands.
+// The read-only database plan: compare migration-owned state (history, pg_cron jobs, pgmq queues) without fetching commands.
+// planInventory is what the dry run of `db migrate` prints after its own plan; dbPlanMain is the clean-plan precondition of `db baseline`.
 import fs from 'node:fs';
 import path from 'node:path';
 import { sha256 } from '../../engine/digest.mjs';
@@ -6,171 +7,216 @@ import pg from 'libpg-query';
 import { invocationDir } from '../lib/roots.mjs';
 import { sqlStringParts, walkSqlAst as walk, sqlParser, sqlCallArgument as argument, sqlStringLiteral as literal } from '../lib/sql-ast.mjs';
 import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbPostgres, dbFailure, offendersError } from './db-baseline-verb.mjs';
-
 await pg.loadModule();
-
 // Each inventory is one read-only psql query whose rows come back as JSON (db-baseline-verb.mjs runDbPostgres).
 const PRESENCE_SQL = `select
   pg_catalog.to_regclass('supabase_migrations.schema_migrations') is not null as migrations,
   pg_catalog.to_regclass('cron.job') is not null as cron,
   pg_catalog.to_regclass('pgmq.meta') is not null as queues;`;
 const INVENTORIES = {
-  migrations: 'select version from supabase_migrations.schema_migrations order by version;',
-  cron: 'select jobname as name, schedule, pg_catalog.encode(pg_catalog.sha256(pg_catalog.convert_to(command, \'UTF8\')), \'hex\') as "commandHash", active from cron.job order by jobid;',
-  queues: 'select queue_name as name from pgmq.meta order by queue_name;',
+    migrations: 'select version from supabase_migrations.schema_migrations order by version;',
+    cron: 'select jobname as name, schedule, pg_catalog.encode(pg_catalog.sha256(pg_catalog.convert_to(command, \'UTF8\')), \'hex\') as "commandHash", active from cron.job order by jobid;',
+    queues: 'select queue_name as name from pgmq.meta order by queue_name;',
 };
 const names = (nodes) => sqlStringParts(nodes).join('.');
 const OWNERSHIP_CALLS = new Set(['pgmq.create', 'pgmq.drop_queue', 'cron.schedule', 'cron.unschedule', 'cron.schedule_in_database', 'cron.alter_job']);
-
 const parseSql = sqlParser(pg, () => { throw new DbVerbError('migration SQL could not be inventoried safely'); });
-
 function requiredLiteral(call, index, aliases) {
-  const value = literal(argument(call, index, aliases));
-  if (value === null || value.length === 0) throw new DbVerbError('queue and cron ownership requires literal migration declarations');
-  return value;
+    const value = literal(argument(call, index, aliases));
+    if (value === null || value.length === 0)
+        throw new DbVerbError('queue and cron ownership requires literal migration declarations');
+    return value;
 }
-
 function inventoryCall(state, call) {
-  const name = names(call.funcname);
-  if (name === 'pgmq.create') {
-    state.queues.set(requiredLiteral(call, 0, ['queue_name']), null);
-  } else if (name === 'pgmq.drop_queue') {
-    state.queues.delete(requiredLiteral(call, 0, ['queue_name']));
-  } else if (name === 'cron.schedule') {
-    const job = requiredLiteral(call, 0, ['job_name']);
-    const schedule = requiredLiteral(call, 1, ['schedule']);
-    const command = requiredLiteral(call, 2, ['command']);
-    state.cron.set(job, { schedule, commandHash: sha256(command), active: true });
-  } else if (name === 'cron.unschedule') {
-    state.cron.delete(requiredLiteral(call, 0, ['job_name']));
-  } else if (name === 'cron.schedule_in_database' || name === 'cron.alter_job') {
-    throw new DbVerbError('database plan requires cron.schedule and named cron.unschedule ownership');
-  }
+    const name = names(call.funcname);
+    if (name === 'pgmq.create') {
+        state.queues.set(requiredLiteral(call, 0, ['queue_name']), null);
+    }
+    else if (name === 'pgmq.drop_queue') {
+        state.queues.delete(requiredLiteral(call, 0, ['queue_name']));
+    }
+    else if (name === 'cron.schedule') {
+        const job = requiredLiteral(call, 0, ['job_name']);
+        const schedule = requiredLiteral(call, 1, ['schedule']);
+        const command = requiredLiteral(call, 2, ['command']);
+        state.cron.set(job, { schedule, commandHash: sha256(command), active: true });
+    }
+    else if (name === 'cron.unschedule') {
+        state.cron.delete(requiredLiteral(call, 0, ['job_name']));
+    }
+    else if (name === 'cron.schedule_in_database' || name === 'cron.alter_job') {
+        throw new DbVerbError('database plan requires cron.schedule and named cron.unschedule ownership');
+    }
 }
-
 function ownershipCalls(tree) {
-  const calls = [];
-  walk(tree, (node) => { if (node.FuncCall && OWNERSHIP_CALLS.has(names(node.FuncCall.funcname))) calls.push(node.FuncCall); });
-  return calls;
+    const calls = [];
+    walk(tree, (node) => { if (node.FuncCall && OWNERSHIP_CALLS.has(names(node.FuncCall.funcname)))
+        calls.push(node.FuncCall); });
+    return calls;
 }
-
 function flatDeclaration(tree, call) {
-  const node = tree.SelectStmt ?? (tree.stmts?.length === 1 && tree.stmts[0].stmt.SelectStmt);
-  const constrained = ['fromClause', 'withClause', 'whereClause', 'intoClause', 'limitCount', 'limitOffset', 'groupClause', 'havingClause', 'distinctClause', 'windowClause'];
-  return node && /^SETOP_NONE$/.test(node.op) && node.targetList?.length === 1
-    && !constrained.some((key) => node[key]) && node.targetList[0].ResTarget?.val?.FuncCall === call;
+    const node = tree.SelectStmt ?? (tree.stmts?.length === 1 && tree.stmts[0].stmt.SelectStmt);
+    const constrained = ['fromClause', 'withClause', 'whereClause', 'intoClause', 'limitCount', 'limitOffset', 'groupClause', 'havingClause', 'distinctClause', 'windowClause'];
+    return node && /^SETOP_NONE$/.test(node.op) && node.targetList?.length === 1
+        && !constrained.some((key) => node[key]) && node.targetList[0].ResTarget?.val?.FuncCall === call;
 }
-
 function inventoryTree(state, tree) {
-  const calls = ownershipCalls(tree);
-  if (!calls.length) return;
-  if (calls.length !== 1 || !flatDeclaration(tree, calls[0])) throw new DbVerbError('database ownership requires one unconditional migration SELECT per declaration');
-  inventoryCall(state, calls[0]);
+    const calls = ownershipCalls(tree);
+    if (!calls.length)
+        return;
+    if (calls.length !== 1 || !flatDeclaration(tree, calls[0]))
+        throw new DbVerbError('database ownership requires one unconditional migration SELECT per declaration');
+    inventoryCall(state, calls[0]);
 }
-
 function conditionalBlock(item) {
-  if (item.PLpgSQL_stmt_block?.exceptions) return true;
-  return Object.keys(item).some((key) => key.startsWith('PLpgSQL_stmt_')
-    && !['PLpgSQL_stmt_block', 'PLpgSQL_stmt_perform', 'PLpgSQL_stmt_execsql'].includes(key)
-    && !(key === 'PLpgSQL_stmt_return' && item[key].lineno === undefined));
+    if (item.PLpgSQL_stmt_block?.exceptions)
+        return true;
+    return Object.keys(item).some((key) => key.startsWith('PLpgSQL_stmt_')
+        && !['PLpgSQL_stmt_block', 'PLpgSQL_stmt_perform', 'PLpgSQL_stmt_execsql'].includes(key)
+        && !(key === 'PLpgSQL_stmt_return' && item[key].lineno === undefined));
 }
-
 /** Inventories one DO block; returns the body-relative line of each EXECUTE, whose SQL is built at run time and so never inventoried. */
 function inventoryDo(state, node) {
-  const option = (key) => (node.args ?? []).find((item) => item.DefElem?.defname === key)?.DefElem?.arg?.String?.sval;
-  if (option('language') && option('language') !== 'plpgsql') throw new DbVerbError('database plan requires statically readable migration blocks');
-  const body = option('as') ?? '';
-  let delimiter = '$starci_plan$';
-  while (body.includes(delimiter)) delimiter = `${delimiter.slice(0, -1)}_$`;
-  let tree;
-  try { tree = pg.parsePlPgSQLSync(`create function starci_plan_probe() returns void language plpgsql as ${delimiter}${body}${delimiter};`); }
-  catch { throw new DbVerbError('migration block could not be inventoried safely'); }
-  const statements = [];
-  const dynamic = [];
-  let conditional = false;
-  walk(tree, (item) => {
-    conditional ||= conditionalBlock(item);
-    if (item.PLpgSQL_stmt_dynexecute) dynamic.push(item.PLpgSQL_stmt_dynexecute.lineno);
-    if (item.PLpgSQL_expr?.parseMode === 0) statements.push(parseSql(item.PLpgSQL_expr.query));
-  });
-  if (conditional && statements.some((statement) => ownershipCalls(statement).length)) throw new DbVerbError('conditional migration blocks cannot prove database inventory');
-  for (const statement of statements) inventoryTree(state, statement);
-  return dynamic;
+    const option = (key) => (node.args ?? []).find((item) => item.DefElem?.defname === key)?.DefElem?.arg?.String?.sval;
+    if (option('language') && option('language') !== 'plpgsql')
+        throw new DbVerbError('database plan requires statically readable migration blocks');
+    const body = option('as') ?? '';
+    let delimiter = '$starci_plan$';
+    while (body.includes(delimiter))
+        delimiter = `${delimiter.slice(0, -1)}_$`;
+    let tree;
+    try {
+        tree = pg.parsePlPgSQLSync(`create function starci_plan_probe() returns void language plpgsql as ${delimiter}${body}${delimiter};`);
+    }
+    catch {
+        throw new DbVerbError('migration block could not be inventoried safely');
+    }
+    const statements = [];
+    const dynamic = [];
+    let conditional = false;
+    walk(tree, (item) => {
+        conditional ||= conditionalBlock(item);
+        if (item.PLpgSQL_stmt_dynexecute)
+            dynamic.push(item.PLpgSQL_stmt_dynexecute.lineno);
+        if (item.PLpgSQL_expr?.parseMode === 0)
+            statements.push(parseSql(item.PLpgSQL_expr.query));
+    });
+    if (conditional && statements.some((statement) => ownershipCalls(statement).length))
+        throw new DbVerbError('conditional migration blocks cannot prove database inventory');
+    for (const statement of statements)
+        inventoryTree(state, statement);
+    return dynamic;
 }
-
 /** The 1-based line of `text` at libpg_query's byte offset `location`. */
 const lineAt = (text, location) => Buffer.from(text).subarray(0, location).toString().split('\n').length;
-
 function repositoryState(root) {
-  const migrations = dbSqlFiles(root);
-  const state = { migrations: new Map(migrations.map((entry) => [entry.stamp, null])), cron: new Map(), queues: new Map() };
-  if (state.migrations.size !== migrations.length) throw new DbVerbError('active migrations must have unique versions');
-  // Every EXECUTE of every active migration is named (file:line) before the refusal.
-  const dynamic = [];
-  for (const entry of migrations) {
-    const text = fs.readFileSync(path.join(root, entry.file), 'utf8');
-    const tree = parseSql(text);
-    for (const statement of tree.stmts ?? []) {
-      // Creating a function does not execute its body. Inert SQL strings never declare remote state.
-      if (statement.stmt.CreateFunctionStmt) continue;
-      if (!statement.stmt.DoStmt) { inventoryTree(state, statement.stmt); continue; }
-      // The body opens on the line of its quote (the `as` DefElem), so a body line maps to that line plus its offset.
-      const opening = lineAt(text, statement.stmt.DoStmt.args?.find((item) => item.DefElem?.defname === 'as')?.DefElem?.location ?? statement.stmt_location ?? 0);
-      for (const line of inventoryDo(state, statement.stmt.DoStmt)) dynamic.push(`${entry.file}:${opening + line - 1}: EXECUTE builds its SQL at run time`);
+    const migrations = dbSqlFiles(root);
+    const state = { migrations: new Map(migrations.map((entry) => [entry.stamp, null])), cron: new Map(), queues: new Map() };
+    if (state.migrations.size !== migrations.length)
+        throw new DbVerbError('active migrations must have unique versions');
+    // Every EXECUTE of every active migration is named (file:line) before the refusal.
+    const dynamic = [];
+    for (const entry of migrations) {
+        const text = fs.readFileSync(path.join(root, entry.file), 'utf8');
+        const tree = parseSql(text);
+        for (const statement of tree.stmts ?? []) {
+            // Creating a function does not execute its body. Inert SQL strings never declare remote state.
+            if (statement.stmt.CreateFunctionStmt)
+                continue;
+            if (!statement.stmt.DoStmt) {
+                inventoryTree(state, statement.stmt);
+                continue;
+            }
+            // The body opens on the line of its quote (the `as` DefElem), so a body line maps to that line plus its offset.
+            const opening = lineAt(text, statement.stmt.DoStmt.args?.find((item) => item.DefElem?.defname === 'as')?.DefElem?.location ?? statement.stmt_location ?? 0);
+            for (const line of inventoryDo(state, statement.stmt.DoStmt))
+                dynamic.push(`${entry.file}:${opening + line - 1}: EXECUTE builds its SQL at run time`);
+        }
     }
-  }
-  if (dynamic.length) throw offendersError('dynamic migration blocks cannot prove database inventory', dynamic);
-  return state;
+    if (dynamic.length)
+        throw offendersError('dynamic migration blocks cannot prove database inventory', dynamic);
+    return state;
 }
-
 function queryRows(root, sql, urlEnv, ports) {
-  const output = runDbPostgres(root, { kind: 'query', sql }, ports, urlEnv);
-  let rows;
-  try { rows = JSON.parse(output); } catch { throw new DbVerbError('the database returned unreadable inventory; database output was withheld'); }
-  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw new DbVerbError('the database returned an invalid inventory; database output was withheld');
-  return rows;
+    const output = runDbPostgres(root, { kind: 'query', sql }, ports, urlEnv);
+    let rows;
+    try {
+        rows = JSON.parse(output);
+    }
+    catch {
+        throw new DbVerbError('the database returned unreadable inventory; database output was withheld');
+    }
+    return rows;
 }
-
-function remoteState(root, urlEnv, ports) {
-  const rows = queryRows(root, PRESENCE_SQL, urlEnv, ports);
-  if (rows.length !== 1 || Object.keys(INVENTORIES).some((key) => typeof rows[0][key] !== 'boolean')) throw new DbVerbError('the database returned invalid inventory availability');
-  const state = {};
-  for (const [key, sql] of Object.entries(INVENTORIES)) state[key] = rows[0][key] ? queryRows(root, sql, urlEnv, ports) : [];
-  return state;
+function remoteState(query) {
+    const asRows = (sql) => {
+        const rows = query(sql);
+        if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row)))
+            throw new DbVerbError('the database returned an invalid inventory; database output was withheld');
+        return rows;
+    };
+    const rows = asRows(PRESENCE_SQL);
+    if (rows.length !== 1 || Object.keys(INVENTORIES).some((key) => typeof rows[0][key] !== 'boolean'))
+        throw new DbVerbError('the database returned invalid inventory availability');
+    // reason: every key of INVENTORIES is assigned by the loop below before the state is returned.
+    const state = {};
+    for (const [key, sql] of Object.entries(INVENTORIES))
+        state[key] = rows[0][key] ? asRows(sql) : [];
+    return state;
 }
-
 function compare(expected, actual, kind) {
-  const unmatched = new Set(expected.keys());
-  let unexpected = 0;
-  let changed = 0;
-  for (const row of actual) {
-    const key = kind === 'migrations' ? row.version : row.name;
-    if (key !== null && (typeof key !== 'string' || key.length === 0)) throw new DbVerbError('the database returned an invalid inventory identifier');
-    if (kind === 'cron' && (typeof row.schedule !== 'string' || !/^[a-f0-9]{64}$/.test(row.commandHash ?? '') || typeof row.active !== 'boolean')) throw new DbVerbError('the database returned invalid cron metadata');
-    if (!unmatched.delete(key)) unexpected += 1;
-    else if (kind === 'cron') {
-      const desired = expected.get(key);
-      if (desired.schedule !== row.schedule || desired.commandHash !== row.commandHash || desired.active !== row.active) changed += 1;
+    const unmatched = new Set(expected.keys());
+    let unexpected = 0;
+    let changed = 0;
+    for (const row of actual) {
+        const key = kind === 'migrations' ? row.version : row.name;
+        if (key !== null && (typeof key !== 'string' || key.length === 0))
+            throw new DbVerbError('the database returned an invalid inventory identifier');
+        if (kind === 'cron' && (typeof row.schedule !== 'string' || !/^[a-f0-9]{64}$/.test((row.commandHash ?? '')) || typeof row.active !== 'boolean'))
+            throw new DbVerbError('the database returned invalid cron metadata');
+        if (!unmatched.delete(key))
+            unexpected += 1;
+        else if (kind === 'cron') {
+            const desired = expected.get(key);
+            if (desired.schedule !== row.schedule || desired.commandHash !== row.commandHash || desired.active !== row.active)
+                changed += 1;
+        }
     }
-  }
-  return { expected: expected.size, remote: actual.length, missing: unmatched.size, unexpected, changed };
+    return { expected: expected.size, remote: actual.length, missing: unmatched.size, unexpected, changed };
 }
-
-/** Numeric exit codes: 0 equal, 1 drift, 2 invalid/failed; all IO and CLI calls are injectable. */
-export function dbPlanMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), ...ports } = {}) {
-  try {
-    const opts = dbOptions(argv, ['cwd', 'url-env', 'json', 'apply']);
-    const root = dbAppRoot(cwd, opts);
+/** The one line of a summary, as the clean-plan check of `db baseline` and the dry run of `db migrate` print it. */
+export const summaryLine = (kind, item) => `${kind}: repo ${item.expected}, remote ${item.remote}, missing ${item.missing}, unexpected ${item.unexpected}, changed ${item.changed}`;
+/** True when a summary names a missing, unexpected or changed entry. */
+export const summaryDrifts = (item) => item.missing > 0 || item.unexpected > 0 || item.changed > 0;
+/** Compares what the active migrations of `root` declare (history, cron jobs, queues) with what `query` reads from the database; read-only. A DbVerbError is a refusal. */
+export function planInventory(root, query) {
     const expected = repositoryState(root);
-    const actual = remoteState(root, opts['url-env'] ?? 'DATABASE_URL', ports);
+    const actual = remoteState(query);
     const summaries = Object.fromEntries(Object.keys(INVENTORIES).map((kind) => [kind, compare(expected[kind], actual[kind], kind)]));
-    const drift = Object.values(summaries).some((item) => item.missing || item.unexpected || item.changed);
-    // --apply is accepted for shared verb ergonomics; a plan never mutates history, queues or jobs.
-    if (opts.json) stdout(`${JSON.stringify({ readOnly: true, drift, ...summaries })}\n`);
-    else {
-      stdout(`read-only database plan: ${drift ? 'drift detected' : 'repo and database agree'}\n`);
-      for (const [kind, item] of Object.entries(summaries)) stdout(`${kind}: repo ${item.expected}, remote ${item.remote}, missing ${item.missing}, unexpected ${item.unexpected}, changed ${item.changed}\n`);
+    return { summaries, drift: Object.values(summaries).some(summaryDrifts) };
+}
+/**
+ * The options of the read-only plan that `db baseline` demands to be clean before it dumps (the dry run of `db migrate` prints the
+ * same inventory through planInventory).
+ */
+export const PLAN_OPTIONS = Object.freeze(['cwd', 'db-url-env', 'json']);
+/** Numeric exit codes: 0 equal, 1 drift, 2 invalid/failed (an --execute too: a plan never mutates history, queues or jobs); all IO and CLI calls are injectable. */
+export function dbPlanMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), ...ports } = {}) {
+    try {
+        const opts = dbOptions(argv, PLAN_OPTIONS);
+        const root = dbAppRoot(cwd, opts);
+        const urlEnv = opts['db-url-env'] ?? 'DATABASE_URL';
+        const { summaries, drift } = planInventory(root, (sql) => queryRows(root, sql, urlEnv, ports));
+        if (opts.json)
+            stdout(`${JSON.stringify({ readOnly: true, drift, ...summaries })}\n`);
+        else {
+            stdout(`read-only database plan: ${drift ? 'drift detected' : 'repo and database agree'}\n`);
+            for (const [kind, item] of Object.entries(summaries))
+                stdout(`${summaryLine(kind, item)}\n`);
+        }
+        return drift ? 1 : 0;
+    }
+    catch (error) {
+        return dbFailure('migrate', error, stderr);
     }
-    return drift ? 1 : 0;
-  } catch (error) { return dbFailure('plan', error, stderr); }
 }

package/runtime/scripts/hfs/db-restamp-verb.d.mts

@@ -0,0 +1,5 @@
+import { type DbMainIo } from './db-baseline-verb.mjs';
+/** The complete map is validated before any repair or file mutation. */
+/** The options of `starci app db restamp` (dbOptions refuses every other). */
+export declare const RESTAMP_OPTIONS: readonly string[];
+export declare function dbRestampMain(argv: string[], { cwd, stdout, stderr, ...ports }?: DbMainIo): number;

package/runtime/scripts/hfs/db-restamp-verb.mjs

@@ -6,96 +6,120 @@ import { invocationDir } from '../lib/roots.mjs';
 import { migrationStamp } from './rules/database-migrations.mjs';
 import { MIGRATIONS_DIR } from './rules/database-constants.mjs';
 import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbPostgres, repairOp, repairLine, dbFailure } from './db-baseline-verb.mjs';
-
 /** The map value of one old version: a new version, or { file, to, applied } for the colliding-versions case. */
 function mapEntry(old, raw) {
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { old, file: null, to: String(raw), applied: undefined };
-  const known = Object.keys(raw).every((key) => ['file', 'to', 'applied'].includes(key));
-  if (!known || (raw.applied !== undefined && typeof raw.applied !== 'boolean') || (raw.file !== undefined && typeof raw.file !== 'string')) throw new DbVerbError('a restamp entry is a new version or { file, to, applied } with a string file and a boolean applied');
-  return { old, file: raw.file ?? null, to: raw.to === undefined ? null : String(raw.to), applied: raw.applied };
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return { old, file: null, to: String(raw), applied: undefined };
+    const entry = raw;
+    const known = Object.keys(raw).every((key) => ['file', 'to', 'applied'].includes(key));
+    if (!known || (entry.applied !== undefined && typeof entry.applied !== 'boolean') || (entry.file !== undefined && typeof entry.file !== 'string'))
+        throw new DbVerbError('a restamp entry is a new version or { file, to, applied } with a string file and a boolean applied');
+    return { old, file: entry.file ?? null, to: entry.to === undefined ? null : String(entry.to), applied: entry.applied };
 }
-
 /** The first unoccupied version after `old`, one second at a time. */
 function nextFreeVersion(old, occupied) {
-  let moment = migrationStamp(old);
-  for (;;) {
-    moment += 1000;
-    const candidate = new Date(moment).toISOString().replace(/\D/g, '').slice(0, 14);
-    if (!occupied.has(candidate)) return candidate;
-  }
+    let moment = migrationStamp(old) ?? 0; // null + 1000 === 0 + 1000
+    for (;;) {
+        moment += 1000;
+        const candidate = new Date(moment).toISOString().replace(/\D/g, '').slice(0, 14);
+        if (!occupied.has(candidate))
+            return candidate;
+    }
 }
-
 /** The active migration that moves: the only file of its version, or the one an entry names among files that share it. */
 function sourceOf(entry, active) {
-  const sharing = active.filter((file) => file.stamp === entry.old);
-  const named = entry.file === null ? sharing : sharing.filter((file) => [file.name, file.name.slice(15), file.name.slice(15).replace(/\.sql$/, '')].includes(entry.file));
-  if (named.length === 1 && (sharing.length === 1 || entry.file !== null)) return named[0];
-  if (sharing.length > 1) throw new DbVerbError(`version ${entry.old} is shared by ${sharing.map((file) => file.name).join(', ')}; name the file to move: "${entry.old}": { file: <name> }`);
-  throw new DbVerbError('each restamp source must identify exactly one active migration; archives never change');
+    const sharing = active.filter((file) => file.stamp === entry.old);
+    const named = entry.file === null ? sharing : sharing.filter((file) => [file.name, file.name.slice(15), file.name.slice(15).replace(/\.sql$/, '')].includes(entry.file));
+    if (named.length === 1 && (sharing.length === 1 || entry.file !== null))
+        return named[0];
+    if (sharing.length > 1)
+        throw new DbVerbError(`version ${entry.old} is shared by ${sharing.map((file) => file.name).join(', ')}; name the file to move: "${entry.old}": { file: <name> }`);
+    throw new DbVerbError('each restamp source must identify exactly one active migration; archives never change');
 }
-
 /**
  * Whether the history records the file that moves under the shared version `old` (SELECT only: supabase_migrations.schema_migrations keeps the name
  * of the file that ran). No row means nothing ran; a row named for the other file means the one that stays ran. A history that cannot be read is
  * not guessed: the entry has to say `applied`.
  */
 function recordedAsApplied(root, source, old, urlEnv, ports) {
-  const unreadable = new DbVerbError(`version ${old} is shared by several migrations and the history could not be read; say which one ran with "${old}": { file: <name>, applied: true|false }`);
-  let rows;
-  try { rows = JSON.parse(runDbPostgres(root, { kind: 'query', sql: `select name from supabase_migrations.schema_migrations where version = '${old}'` }, ports, urlEnv)); } catch { throw unreadable; }
-  if (!Array.isArray(rows) || (rows.length > 0 && typeof rows[0]?.name !== 'string')) throw unreadable;
-  return rows.length > 0 && rows[0].name === source.name.slice(15).replace(/\.sql$/, '');
+    const unreadable = new DbVerbError(`version ${old} is shared by several migrations and the history could not be read; say which one ran with "${old}": { file: <name>, applied: true|false }`);
+    let rows;
+    try {
+        rows = JSON.parse(runDbPostgres(root, { kind: 'query', sql: `select name from supabase_migrations.schema_migrations where version = '${old}'` }, ports, urlEnv));
+    }
+    catch {
+        throw unreadable;
+    }
+    if (!Array.isArray(rows) || (rows.length > 0 && typeof rows[0]?.name !== 'string'))
+        throw unreadable;
+    return rows.length > 0 && rows[0].name === source.name.slice(15).replace(/\.sql$/, '');
 }
-
 /** YAML maps use quoted UTC stamps as keys and a new version, or { file, to?, applied? }, as values (or a versions: mapping). */
 function restampPlan(root, mapFile, { urlEnv = 'DATABASE_URL', ports = {} } = {}) {
-  if (!mapFile) throw new DbVerbError('restamp requires --map <restamp.yaml>');
-  let document;
-  try { document = parseYaml(fs.readFileSync(path.resolve(root, mapFile), 'utf8')); }
-  catch { throw new DbVerbError('restamp map must be readable YAML with unique version keys'); }
-  const mapping = document?.versions ?? document;
-  if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || !Object.keys(mapping).length) throw new DbVerbError('restamp map must contain old-to-new version pairs');
-  const active = dbSqlFiles(root);
-  const occupied = new Set(active.map((entry) => entry.stamp));
-  const targets = new Set();
-  const steps = Object.entries(mapping).map(([old, raw]) => {
-    const entry = mapEntry(old, raw);
-    const source = sourceOf(entry, active);
-    const shared = active.filter((file) => file.stamp === old).length > 1;
-    const next = entry.to ?? nextFreeVersion(old, new Set([...occupied, ...targets]));
-    if (![old, next].every((stamp) => /^\d{14}$/.test(stamp) && migrationStamp(stamp) !== null) || old === next) throw new DbVerbError('restamp pairs require distinct valid UTC versions');
-    if (occupied.has(next) || targets.has(next)) throw new DbVerbError('restamp targets must be unique unoccupied versions');
-    targets.add(next);
-    // a version two files share ran for at most one of them: the history says which, unless the entry does
-    const applied = entry.applied ?? (shared ? recordedAsApplied(root, source, old, urlEnv, ports) : true);
-    return { old, next, source: source.file, target: `${MIGRATIONS_DIR}/${source.name.replace(old, next)}`, applied };
-  });
-  const moved = new Map(steps.map((step) => [step.source, step.next]));
-  const resulting = active.map((entry) => moved.get(entry.file) ?? entry.stamp);
-  if (resulting.some((stamp, index) => index > 0 && stamp <= resulting[index - 1])) throw new DbVerbError('the map must cover every version needed to preserve migration order');
-  return steps.sort((left, right) => left.old < right.old ? -1 : 1);
+    if (!mapFile)
+        throw new DbVerbError('restamp requires --map <restamp.yaml>');
+    let document;
+    try {
+        document = parseYaml(fs.readFileSync(path.resolve(root, mapFile), 'utf8'));
+    }
+    catch {
+        throw new DbVerbError('restamp map must be readable YAML with unique version keys');
+    }
+    const mapping = document?.versions ?? document;
+    if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || !Object.keys(mapping).length)
+        throw new DbVerbError('restamp map must contain old-to-new version pairs');
+    const active = dbSqlFiles(root);
+    const occupied = new Set(active.map((entry) => entry.stamp));
+    const targets = new Set();
+    const steps = Object.entries(mapping).map(([old, raw]) => {
+        const entry = mapEntry(old, raw);
+        const source = sourceOf(entry, active);
+        const shared = active.filter((file) => file.stamp === old).length > 1;
+        const next = entry.to ?? nextFreeVersion(old, new Set([...occupied, ...targets]));
+        if (![old, next].every((stamp) => /^\d{14}$/.test(stamp) && migrationStamp(stamp) !== null) || old === next)
+            throw new DbVerbError('restamp pairs require distinct valid UTC versions');
+        if (occupied.has(next) || targets.has(next))
+            throw new DbVerbError('restamp targets must be unique unoccupied versions');
+        targets.add(next);
+        // a version two files share ran for at most one of them: the history says which, unless the entry does
+        const applied = entry.applied ?? (shared ? recordedAsApplied(root, source, old, urlEnv, ports) : true);
+        return { old, next, source: source.file, target: `${MIGRATIONS_DIR}/${source.name.replace(old, next)}`, applied };
+    });
+    const moved = new Map(steps.map((step) => [step.source, step.next]));
+    const resulting = active.map((entry) => moved.get(entry.file) ?? entry.stamp);
+    if (resulting.some((stamp, index) => index > 0 && stamp <= resulting[index - 1]))
+        throw new DbVerbError('the map must cover every version needed to preserve migration order');
+    return steps.sort((left, right) => left.old < right.old ? -1 : 1);
 }
-
 /** The complete map is validated before any repair or file mutation. */
+/** The options of `starci app db restamp` (dbOptions refuses every other). */
+export const RESTAMP_OPTIONS = Object.freeze(['cwd', 'map', 'execute', 'db-url-env']);
 export function dbRestampMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), ...ports } = {}) {
-  try {
-    const opts = dbOptions(argv, ['cwd', 'map', 'apply', 'url-env']);
-    const urlEnv = opts['url-env'] ?? 'DATABASE_URL';
-    const root = dbAppRoot(cwd, opts);
-    const steps = restampPlan(root, opts.map, { urlEnv, ports });
-    const repairs = steps.filter((step) => step.applied).flatMap((step) => [repairOp(step.old, 'reverted'), repairOp(step.next, 'applied', step.target.split('/').at(-1).slice(15).replace(/\.sql$/, ''))]);
-    stdout(`${opts.apply ? 'apply' : 'preview'} restamp ${steps.length} migrations\n`);
-    for (const step of steps) stdout(`${step.source} -> ${step.target}\n`);
-    for (const op of repairs) stdout(`${repairLine(op)}\n`);
-    if (!opts.apply) return 0;
-    // CLI failures never echo credentials and leave the local files intact for an explicit retry.
-    for (const op of repairs) runDbPostgres(root, op, ports, urlEnv);
-    for (const step of steps) {
-      const source = path.join(root, step.source);
-      const text = fs.readFileSync(source, 'utf8').replace(/^\s*--\s*starci:restamp\s+\d{14}\s+\d{14}\s*\r?\n/, '');
-      fs.writeFileSync(path.join(root, step.target), `-- starci:restamp ${step.old} ${step.next}\n${text}`, { flag: 'wx' });
-      fs.unlinkSync(source);
+    try {
+        const opts = dbOptions(argv, RESTAMP_OPTIONS);
+        const urlEnv = opts['db-url-env'] ?? 'DATABASE_URL';
+        const root = dbAppRoot(cwd, opts);
+        const steps = restampPlan(root, opts.map, { urlEnv, ports });
+        const repairs = steps.filter((step) => step.applied).flatMap((step) => [repairOp(step.old, 'reverted'), repairOp(step.next, 'applied', step.target.split('/').at(-1).slice(15).replace(/\.sql$/, ''))]);
+        stdout(`${opts.execute ? 'apply' : 'preview'} restamp ${steps.length} migrations\n`);
+        for (const step of steps)
+            stdout(`${step.source} -> ${step.target}\n`);
+        for (const op of repairs)
+            stdout(`${repairLine(op)}\n`);
+        if (!opts.execute)
+            return 0;
+        // CLI failures never echo credentials and leave the local files intact for an explicit retry.
+        for (const op of repairs)
+            runDbPostgres(root, op, ports, urlEnv);
+        for (const step of steps) {
+            const source = path.join(root, step.source);
+            const text = fs.readFileSync(source, 'utf8').replace(/^\s*--\s*starci:restamp\s+\d{14}\s+\d{14}\s*\r?\n/, '');
+            fs.writeFileSync(path.join(root, step.target), `-- starci:restamp ${step.old} ${step.next}\n${text}`, { flag: 'wx' });
+            fs.unlinkSync(source);
+        }
+        return 0;
+    }
+    catch (error) {
+        return dbFailure('restamp', error, stderr);
     }
-    return 0;
-  } catch (error) { return dbFailure('restamp', error, stderr); }
 }