@starci/hfs 4.11.21 → 4.12.0

package/db/post-cutover.mjs

@@ -3,130 +3,137 @@
 //   1. a READ-ONLY pg_proc preflight (also in the dry run): every function of the declared families (database.postCutover.functionPrefixes and
 //      functionNames in database.postCutover.schema) that exists on the database must be covered by the DROP FUNCTION statements of the held-back
 //      migration (or database.postCutover.functions); a function nobody drops is a function something may still need, so nothing is applied;
-//   2. a time gate: --green-at <ISO> at least minAgeHours (48) ago, or --owner-confirms-old-app-gone;
+//   2. a time gate: --green-at <ISO> at least minAgeHours (48) ago, or else --owner-confirms-old-app-gone (never both);
 //   3. STARCI_DB_ARMED=1.
 // Idempotent: when every held-back version is already on the remote it prints `nothing to do`. The pg_proc query goes through `options.query(sql)`
-// (specs inject one) or, by default, psql against the database --url-env names (default DATABASE_URL).
+// (specs inject one) or, by default, psql against the database --db-url-env names (default DATABASE_URL).
 import fs from 'node:fs';
 import path from 'node:path';
 import { failure, refusal } from '../stack/errors.mjs';
 import { runVerb } from '../release/index.mjs';
 import { applyVersions, buildModel, listRemote, loadDatabase, requireArmed, resolveTarget } from './migrate.mjs';
 import { queryRows as psqlRows } from './postgres.mjs';
-
 const DROP_FUNCTION = /^drop\s+function\s+/iu;
 const IF_EXISTS = /^if\s+exists\s+/iu;
 const MS_PER_HOUR = 3.6e6;
 const DEFAULT_MIN_AGE_HOURS = 48;
-
 /** Makes a DROP signature comparable with pg_proc's regprocedure text. */
 function normalizeSignature(signature, schema) {
-  const lowered = signature.trim().toLowerCase();
-  const bare = lowered.startsWith(`${schema}.`) ? lowered.slice(schema.length + 1) : lowered;
-  const words = bare
-    .replace(/\bint\b/gu, 'integer')
-    .replace(/\btimestamptz\b/gu, 'timestamp with time zone')
-    .replace(/\s+/gu, ' ');
-  return [...'(),'].reduce((out, mark) => out.replaceAll(` ${mark}`, mark).replaceAll(`${mark} `, mark), words);
+    const lowered = signature.trim().toLowerCase();
+    const bare = lowered.startsWith(`${schema}.`) ? lowered.slice(schema.length + 1) : lowered;
+    const words = bare
+        .replace(/\bint\b/gu, 'integer')
+        .replace(/\btimestamptz\b/gu, 'timestamp with time zone')
+        .replace(/\s+/gu, ' ');
+    return [...'(),'].reduce((out, mark) => out.replaceAll(` ${mark}`, mark).replaceAll(`${mark} `, mark), words);
 }
-
 /** The signature a `DROP FUNCTION [IF EXISTS] <signature>` statement drops, or null for any other statement. */
 function droppedSignature(statement) {
-  const head = DROP_FUNCTION.exec(statement);
-  return head ? statement.slice(head[0].length).replace(IF_EXISTS, '') : null;
+    const head = DROP_FUNCTION.exec(statement);
+    return head ? statement.slice(head[0].length).replace(IF_EXISTS, '') : null;
 }
-
 /** The signatures a migration drops: every `DROP FUNCTION [IF EXISTS] <signature>;` statement. */
 function dropSignatures(sql, schema) {
-  return sql.replace(/--[^\n]*/gu, '').split(';').flatMap((statement) => {
-    const signature = droppedSignature(statement.trim());
-    return signature === null ? [] : [normalizeSignature(signature, schema)];
-  });
+    return sql.replace(/--[^\n]*/gu, '').split(';').flatMap((statement) => {
+        const signature = droppedSignature(statement.trim());
+        return signature === null ? [] : [normalizeSignature(signature, schema)];
+    });
 }
-
 const settingsOf = (post) => ({
-  schema: post.schema ?? 'public', prefixes: post.functionPrefixes ?? [], names: post.functionNames ?? [], extra: post.functions ?? [],
+    schema: post.schema ?? 'public', prefixes: post.functionPrefixes ?? [], names: post.functionNames ?? [], extra: post.functions ?? [],
 });
-
 /** The read-only pg_proc query of the declared function families (identifiers are validated, so nothing free-form reaches the SQL). */
 function preflightSql({ schema, prefixes, names }) {
-  const escaped = (prefix) => prefix.replaceAll('_', String.raw`\_`);
-  const clauses = [...names.map((name) => `proname = '${name}'`), ...prefixes.map((prefix) => `proname like '${escaped(prefix)}%'`)];
-  return `select oid::regprocedure::text as signature from pg_proc where pronamespace = '${schema}'::regnamespace and (${clauses.join(' or ')})`;
+    const escaped = (prefix) => prefix.replaceAll('_', String.raw `\_`);
+    const clauses = [...names.map((name) => `proname = '${name}'`), ...prefixes.map((prefix) => `proname like '${escaped(prefix)}%'`)];
+    return `select oid::regprocedure::text as signature from pg_proc where pronamespace = '${schema}'::regnamespace and (${clauses.join(' or ')})`;
 }
-
 const cliQuery = (session) => (sql) => psqlRows(session.ctx, session.target, sql, { withhold: true });
-
 async function queryRows(session, sql, options) {
-  try {
-    const rows = await (options.query ?? cliQuery(session))(sql);
-    if (Array.isArray(rows) && rows.every((row) => typeof row?.signature === 'string')) return rows;
-  } catch { /* the cause may hold a connection detail: it is withheld */ }
-  throw failure('DB_PREFLIGHT_UNREADABLE', 'the read-only function preflight could not query the database; nothing applied');
+    try {
+        const rows = await (options.query ?? cliQuery(session))(sql);
+        if (Array.isArray(rows) && rows.every((row) => typeof row?.signature === 'string'))
+            return rows;
+    }
+    catch { /* the cause may hold a connection detail: it is withheld */ }
+    throw failure('DB_PREFLIGHT_UNREADABLE', 'the read-only function preflight could not query the database; nothing applied');
 }
-
 /** The pg_proc preflight: refuses when a function of the declared families is not dropped by the held-back migration(s). */
 async function functionPreflight(session, options) {
-  const { model, decl } = session;
-  const settings = settingsOf(decl.postCutover);
-  if (settings.prefixes.length + settings.names.length === 0) return { count: 0, line: 'function preflight: no function family declared; nothing to check' };
-  const dropped = model.held.flatMap((file) => dropSignatures(fs.readFileSync(path.join(model.root, decl.migrationsDir, file), 'utf8'), settings.schema));
-  const allowed = new Set([...dropped, ...settings.extra.map((item) => normalizeSignature(item, settings.schema))]);
-  const rows = await queryRows(session, preflightSql(settings), options);
-  const uncovered = rows.map((row) => normalizeSignature(row.signature, settings.schema)).filter((item) => !allowed.has(item));
-  if (uncovered.length > 0) throw refusal('DB_PREFLIGHT_UNCOVERED', `function signatures not covered by the held-back migration:\n${uncovered.join('\n')}`);
-  return { count: rows.length, line: `read-only function preflight: ${rows.length} signature(s), all covered by the held-back migration` };
+    const { model } = session;
+    const decl = session.decl;
+    const settings = settingsOf(decl.postCutover);
+    if (settings.prefixes.length + settings.names.length === 0)
+        return { count: 0, line: 'function preflight: no function family declared; nothing to check' };
+    const dropped = model.held.flatMap((file) => dropSignatures(fs.readFileSync(path.join(model.root, decl.migrationsDir, file), 'utf8'), settings.schema));
+    const allowed = new Set([...dropped, ...settings.extra.map((item) => normalizeSignature(item, settings.schema))]);
+    const rows = await queryRows(session, preflightSql(settings), options);
+    const uncovered = rows.map((row) => normalizeSignature(row.signature, settings.schema)).filter((item) => !allowed.has(item));
+    if (uncovered.length > 0)
+        throw refusal('DB_PREFLIGHT_UNCOVERED', `function signatures not covered by the held-back migration:\n${uncovered.join('\n')}`);
+    return { count: rows.length, line: `read-only function preflight: ${rows.length} signature(s), all covered by the held-back migration` };
 }
-
 /** The time gate: { open, line }. Dry run only reports it; --execute refuses while it is closed. */
 function timeGate(ctx, post, options) {
-  if (options.ownerConfirms === true) return { open: true, line: 'gate: the owner confirms the old app is gone: OPEN' };
-  if (options.greenAt === undefined) return { open: false, line: 'gate: CLOSED (needs --green-at <ISO> old enough, or --owner-confirms-old-app-gone)' };
-  const at = Date.parse(options.greenAt);
-  if (Number.isNaN(at)) throw refusal('DB_USAGE', '--green-at must be an ISO time');
-  const hours = (ctx.now() - at) / MS_PER_HOUR;
-  const need = post.minAgeHours ?? DEFAULT_MIN_AGE_HOURS;
-  return { open: hours >= need, line: `gate: last green ${options.greenAt} (${hours.toFixed(1)} h ago, ${need} h needed): ${hours >= need ? 'OPEN' : 'CLOSED'}` };
+    if (options.ownerConfirms === true)
+        return { open: true, line: 'gate: the owner confirms the old app is gone: OPEN' };
+    if (options.greenAt === undefined)
+        return { open: false, line: 'gate: CLOSED (needs --green-at <ISO> old enough, or --owner-confirms-old-app-gone)' };
+    const at = Date.parse(options.greenAt);
+    if (Number.isNaN(at))
+        throw refusal('DB_USAGE', '--green-at must be an ISO time');
+    const hours = (ctx.now() - at) / MS_PER_HOUR;
+    const need = post.minAgeHours ?? DEFAULT_MIN_AGE_HOURS;
+    return { open: hours >= need, line: `gate: last green ${options.greenAt} (${hours.toFixed(1)} h ago, ${need} h needed): ${hours >= need ? 'OPEN' : 'CLOSED'}` };
 }
-
 function applyHeld(session, remote) {
-  const { model } = session;
-  const lacking = [...model.pushVersions].filter((version) => !remote.has(version));
-  if (lacking.length > 0) throw refusal('DB_BASELINE_NOT_APPLIED', `the history lacks ${lacking.join(', ')}: run starci app db migrate first`);
-  return applyVersions(session, model.heldVersions.filter((version) => !remote.has(version)));
+    const { model } = session;
+    const lacking = [...model.pushVersions].filter((version) => !remote.has(version));
+    if (lacking.length > 0)
+        throw refusal('DB_BASELINE_NOT_APPLIED', `the history lacks ${lacking.join(', ')}: run starci app db migrate --execute first`);
+    return applyVersions(session, model.heldVersions.filter((version) => !remote.has(version)));
 }
-
 /**
  * `starci app db post-cutover`. options: { execute, urlEnv, greenAt, ownerConfirms, query }. Dry run: history read plus the read-only preflight.
  * --execute: gate open and STARCI_DB_ARMED=1, then exactly the held-back versions, each with its history row in one transaction.
  */
 async function postCutoverDatabase(ctx, decl, options = {}) {
-  const model = buildModel(ctx.cwd, decl);
-  if (model.held.length === 0) return { ok: true, lines: ['no held-back migration in the repository. Nothing to do.'], data: { held: [], done: true, executed: false } };
-  if (decl.postCutover === null) throw refusal('DB_POSTCUTOVER_UNDECLARED', 'database.postCutover is not declared: the function preflight needs it (an empty mapping declares no family)');
-  const session = { ctx, decl, model, target: resolveTarget(ctx, options) };
-  const remote = listRemote(session);
-  const data = { held: model.heldVersions, done: false, executed: false };
-  if (model.heldVersions.every((version) => remote.has(version))) return { ok: true, lines: [`held-back migrations ${model.held.join(', ')} are already applied. Nothing to do.`], data: { ...data, done: true } };
-  const gate = timeGate(ctx, decl.postCutover, options);
-  const preflight = await functionPreflight(session, options);
-  const lines = [`held-back migrations: ${model.held.join(', ')}`, preflight.line, gate.line, 'WARNING: after this step a rollback to the old app needs a database restore.'];
-  if (options.execute !== true) return { ok: true, lines: [...lines, 'dry run: only read-only calls were made; nothing applied.'], data: { ...data, gateOpen: gate.open, signatures: preflight.count } };
-  if (!gate.open) throw refusal('DB_POSTCUTOVER_GATE_CLOSED', 'the time gate is closed; nothing applied');
-  requireArmed(ctx);
-  const pending = applyHeld(session, remote);
-  if (!model.heldVersions.every((version) => listRemote(session).has(version))) throw failure('DB_HELD_MISSING', 'a held-back migration is still missing from the remote history');
-  return { ok: true, lines: [...lines, pending.length > 0 ? `applied: ${pending.join(', ')}` : 'nothing pending: already applied.'], data: { ...data, done: true, executed: true, pushed: pending, signatures: preflight.count } };
+    const model = buildModel(ctx.cwd, decl);
+    if (model.held.length === 0)
+        return { ok: true, lines: ['no held-back migration in the repository. Nothing to do.'], data: { held: [], done: true, executed: false } };
+    if (decl.postCutover === null)
+        throw refusal('DB_POSTCUTOVER_UNDECLARED', 'database.postCutover is not declared: the function preflight needs it (an empty mapping declares no family)');
+    const session = { ctx, decl, model, target: resolveTarget(ctx, options) };
+    const remote = listRemote(session);
+    const data = { held: model.heldVersions, done: false, executed: false };
+    if (model.heldVersions.every((version) => remote.has(version)))
+        return { ok: true, lines: [`held-back migrations ${model.held.join(', ')} are already applied. Nothing to do.`], data: { ...data, done: true } };
+    const gate = timeGate(ctx, decl.postCutover, options);
+    const preflight = await functionPreflight(session, options);
+    const lines = [`held-back migrations: ${model.held.join(', ')}`, preflight.line, gate.line, 'WARNING: after this step a rollback to the old app needs a database restore.'];
+    if (options.execute !== true)
+        return { ok: true, lines: [...lines, 'dry run: only read-only calls were made; nothing applied.'], data: { ...data, gateOpen: gate.open, signatures: preflight.count } };
+    if (!gate.open)
+        throw refusal('DB_POSTCUTOVER_GATE_CLOSED', 'the time gate is closed; nothing applied');
+    requireArmed(ctx);
+    const pending = applyHeld(session, remote);
+    if (!model.heldVersions.every((version) => listRemote(session).has(version)))
+        throw failure('DB_HELD_MISSING', 'a held-back migration is still missing from the remote history');
+    return { ok: true, lines: [...lines, pending.length > 0 ? `applied: ${pending.join(', ')}` : 'nothing pending: already applied.'], data: { ...data, done: true, executed: true, pushed: pending, signatures: preflight.count } };
 }
-
-const SPEC = { boolean: ['--execute', '--json', '--owner-confirms-old-app-gone'], value: ['--url-env', '--green-at'] };
-
-/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--url-env NAME] [--json]`. */
+/** The flags of `starci app db post-cutover`; the parser refuses every other. */
+export const SPEC = { boolean: ['--execute', '--json', '--owner-confirms-old-app-gone'], value: ['--db-url-env', '--green-at'] };
+/** Entry of the verb: `starci app db post-cutover [--execute] [--green-at <ISO> | --owner-confirms-old-app-gone] [--db-url-env NAME] [--json]`. */
 export function dbPostCutoverMain(argv, io = {}) {
-  return runVerb({
-    label: 'starci app db post-cutover', name: 'db post-cutover', code: 'DB_USAGE', io, argv, spec: SPEC,
-    run: (ctx, flags) => postCutoverDatabase(ctx, loadDatabase(ctx.cwd), {
-      execute: flags.execute === true, urlEnv: flags['url-env'], greenAt: flags['green-at'], ownerConfirms: flags['owner-confirms-old-app-gone'] === true,
-    }),
-  });
+    return runVerb({
+        label: 'starci app db post-cutover', name: 'db post-cutover', code: 'DB_USAGE', io, argv, spec: SPEC,
+        run: (ctx, flags) => {
+            // The two openings of the time gate are alternatives: the owner's word skips the age check, so a --green-at beside it would be ignored.
+            if (flags['green-at'] !== undefined && flags['owner-confirms-old-app-gone'] === true)
+                throw refusal('DB_USAGE', '--green-at and --owner-confirms-old-app-gone are alternative openings of the time gate: give one');
+            return postCutoverDatabase(ctx, loadDatabase(ctx.cwd), {
+                execute: flags.execute === true, urlEnv: flags['db-url-env'], greenAt: flags['green-at'], ownerConfirms: flags['owner-confirms-old-app-gone'] === true,
+            });
+        },
+    });
 }

package/db/postgres.d.mts

@@ -0,0 +1,71 @@
+import type { VerbContext } from '../release/index.mjs';
+/** The default environment variable that names the app's database. */
+export declare const DEFAULT_DB_URL_ENV = "DATABASE_URL";
+/** The history table `starci app db migrate` records applied migrations in (Supabase's layout, so a history restored from a hosted Supabase carries over; migrate creates it on an empty database). */
+export declare const HISTORY_TABLE = "supabase_migrations.schema_migrations";
+/** A database a verb reaches: its connection URL (password removed), the environment that carries the password, and the secrets to scrub from any text. */
+export interface DbTarget {
+    kind?: 'url';
+    how: string;
+    urlEnv?: string;
+    url: string;
+    env: Record<string, string>;
+    secrets: string[];
+    container?: string;
+}
+/** { url, password } of a postgres connection URL with the password removed, or null when `value` is not one. */
+export declare function parseConnection(value: string): {
+    url: string;
+    password: string;
+} | null;
+/** The database `name` (an UPPER_CASE environment variable, default DATABASE_URL) names: { how, url, env, secrets }. */
+export declare function dbTarget(ctx: VerbContext, name?: string): DbTarget & {
+    kind: 'url';
+    urlEnv: string;
+};
+/**
+ * `target` reached inside the running container `container` (`docker exec` through this invocation's daemon), for a database only the stack's
+ * network reaches (the first start of a self-hosted database, `stack deploy --urgent --first-start`): the image's own client tools run there
+ * against the URL's database on 127.0.0.1, a `-f` file is copied in first, and the password travels on the exec's stdin, never in argv, a file
+ * or an environment of this machine.
+ */
+export declare function inContainer(target: DbTarget, container: string): DbTarget & {
+    container: string;
+};
+/** Runs a PostgreSQL client tool against `target`; a failure names the first stderr line with every secret scrubbed (or withholds it). */
+export declare function pgTool(ctx: VerbContext, target: DbTarget, command: string, args: readonly string[], { withhold, code }?: {
+    withhold?: boolean;
+    code?: string;
+}): {
+    stdout: string;
+    text: string;
+};
+/** Runs SQL statements (`-c`) and files (`-f`) in ONE transaction: each step is { sql } or { file }. */
+export declare function psqlTransaction(ctx: VerbContext, target: DbTarget, steps: readonly ({
+    sql: string;
+    file?: undefined;
+} | {
+    file: string;
+    sql?: undefined;
+})[], options?: {
+    withhold?: boolean;
+    code?: string;
+}): {
+    stdout: string;
+    text: string;
+};
+/** The rows of one read-only query as plain objects (json_agg on the server, so no psql formatting is parsed). */
+export declare function queryRows(ctx: VerbContext, target: DbTarget, sql: string, options?: {
+    withhold?: boolean;
+    code?: string;
+}): Record<string, any>[];
+/** A SQL string literal of `value`. */
+export declare const literal: (value: unknown) => string;
+/** The versions the history table records; an absent table is an empty history (a database `migrate` has never touched). */
+export declare function historyVersions(ctx: VerbContext, target: DbTarget): Set<string>;
+/** The statement that creates the history table when it is absent (same columns as the image's own: version, statements, name). */
+export declare const HISTORY_DDL = "create schema if not exists supabase_migrations; create table if not exists supabase_migrations.schema_migrations (version text primary key, statements text[], name text)";
+/** Records `version` (named `name`) as applied. */
+export declare const markApplied: (version: string, name: string) => string;
+/** Removes `version` from the history. */
+export declare const markReverted: (version: string) => string;

package/db/postgres.mjs

@@ -1,46 +1,46 @@
 // postgres.mjs - the one door of the `starci app db` verbs to a self-hosted PostgreSQL: psql and pg_dump through ctx.spawn (never a
-// shell). The database is named by an environment variable holding a postgres connection URL (`--url-env <NAME>`, default
+// shell). The database is named by an environment variable holding a postgres connection URL (`--db-url-env <NAME>`, default
 // DATABASE_URL); the password travels only in the child's PGPASSWORD, never in argv, a file, a line or an error. An in-container target
 // (`inContainer`) runs the same tools inside the database's own container through docker exec, the password on stdin.
 import path from 'node:path';
 import { failure, refusal } from '../stack/errors.mjs';
 import { firstLine, tool } from '../stack/context.mjs';
-
 /** The default environment variable that names the app's database. */
 export const DEFAULT_DB_URL_ENV = 'DATABASE_URL';
 /** The history table `starci app db migrate` records applied migrations in (Supabase's layout, so a history restored from a hosted Supabase carries over; migrate creates it on an empty database). */
 export const HISTORY_TABLE = 'supabase_migrations.schema_migrations';
-
 const KEY = /^[A-Z][A-Z0-9_]*$/u;
-
 const scrub = (text, secrets) => secrets.reduce((out, secret) => out.replaceAll(secret, '[value]'), String(text));
-
 /** { url, password } of a postgres connection URL with the password removed, or null when `value` is not one. */
 export function parseConnection(value) {
-  try {
-    const url = new URL(value);
-    if (!/^postgres(?:ql)?:$/u.test(url.protocol)) return null;
-    const password = decodeURIComponent(url.password);
-    url.password = '';
-    return { url: url.toString(), password };
-  } catch { return null; }
+    try {
+        const url = new URL(value);
+        if (!/^postgres(?:ql)?:$/u.test(url.protocol))
+            return null;
+        const password = decodeURIComponent(url.password);
+        url.password = '';
+        return { url: url.toString(), password };
+    }
+    catch {
+        return null;
+    }
 }
-
 /** The database `name` (an UPPER_CASE environment variable, default DATABASE_URL) names: { how, url, env, secrets }. */
 export function dbTarget(ctx, name = DEFAULT_DB_URL_ENV) {
-  if (!KEY.test(name)) throw refusal('DB_USAGE', '--url-env must name an UPPER_CASE environment variable');
-  const value = ctx.env[name];
-  if (typeof value !== 'string' || value === '') throw refusal('DB_URL_ENV_MISSING', `${name} is not set`);
-  const parsed = parseConnection(value);
-  if (!parsed) throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
-  return { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
+    if (!KEY.test(name))
+        throw refusal('DB_USAGE', '--db-url-env must name an UPPER_CASE environment variable');
+    const value = ctx.env[name];
+    if (typeof value !== 'string' || value === '')
+        throw refusal('DB_URL_ENV_MISSING', `${name} is not set`);
+    const parsed = parseConnection(value);
+    if (!parsed)
+        throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
+    return { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
 }
-
 /** Where a `-f` file of an in-container target is copied before the client reads it. */
 const CONTAINER_DIR = '/tmp/starci-db';
 /** The shell an in-container client runs under: the password comes in on stdin into PGPASSWORD, then the tool runs with its arguments. */
 const STDIN_PASSWORD = 'IFS= read -r PGPASSWORD; export PGPASSWORD; exec "$@"';
-
 /**
  * `target` reached inside the running container `container` (`docker exec` through this invocation's daemon), for a database only the stack's
  * network reaches (the first start of a self-hosted database, `stack deploy --urgent --first-start`): the image's own client tools run there
@@ -48,68 +48,69 @@ const STDIN_PASSWORD = 'IFS= read -r PGPASSWORD; export PGPASSWORD; exec "$@"';
  * or an environment of this machine.
  */
 export function inContainer(target, container) {
-  const url = new URL(target.url);
-  url.hostname = '127.0.0.1';
-  return { ...target, how: `${target.how}, inside container ${container.slice(0, 12)}`, url: url.toString(), container };
+    const url = new URL(target.url);
+    url.hostname = '127.0.0.1';
+    return { ...target, how: `${target.how}, inside container ${container.slice(0, 12)}`, url: url.toString(), container };
 }
-
 /** Runs `command` of an in-container target: copies each `-f` file in, then execs the tool through the stdin-password shell. */
 function containerRun(ctx, target, command, args) {
-  const short = target.container.slice(0, 12);
-  const step = (what, run) => {
-    if (run.error || run.status !== 0) throw failure('DB_CLI_FAILED', `${what} in container ${short} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
-  };
-  step('mkdir', tool(ctx, 'docker', ['exec', target.container, 'mkdir', '-p', CONTAINER_DIR]));
-  const inside = args.map((arg, index) => {
-    if (args[index - 1] !== '-f') return arg;
-    const copied = `${CONTAINER_DIR}/${index}-${path.basename(arg)}`;
-    step(`docker cp of ${path.basename(arg)}`, tool(ctx, 'docker', ['cp', arg, `${target.container}:${copied}`]));
-    return copied;
-  });
-  return tool(ctx, 'docker', ['exec', '-i', target.container, 'sh', '-c', STDIN_PASSWORD, 'sh', command, ...inside], { input: `${target.env.PGPASSWORD ?? ''}\n` });
+    const short = target.container.slice(0, 12);
+    const step = (what, run) => {
+        if (run.error || run.status !== 0)
+            throw failure('DB_CLI_FAILED', `${what} in container ${short} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
+    };
+    step('mkdir', tool(ctx, 'docker', ['exec', target.container, 'mkdir', '-p', CONTAINER_DIR]));
+    const inside = args.map((arg, index) => {
+        if (args[index - 1] !== '-f')
+            return arg;
+        const copied = `${CONTAINER_DIR}/${index}-${path.basename(arg)}`;
+        step(`docker cp of ${path.basename(arg)}`, tool(ctx, 'docker', ['cp', arg, `${target.container}:${copied}`]));
+        return copied;
+    });
+    return tool(ctx, 'docker', ['exec', '-i', target.container, 'sh', '-c', STDIN_PASSWORD, 'sh', command, ...inside], { input: `${target.env.PGPASSWORD ?? ''}\n` });
 }
-
 /** Runs a PostgreSQL client tool against `target`; a failure names the first stderr line with every secret scrubbed (or withholds it). */
 export function pgTool(ctx, target, command, args, { withhold = false, code = 'DB_CLI_FAILED' } = {}) {
-  const run = target.container ? containerRun(ctx, target, command, args) : tool(ctx, command, args, { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
-  if (run.error) throw failure('DB_CLI_MISSING', target.container ? `cannot run docker exec ${command} in container ${target.container.slice(0, 12)}` : `cannot run ${command}; install the PostgreSQL client tools (psql, pg_dump)`);
-  if (run.status !== 0) throw failure(code, withhold ? `${command} failed; output withheld` : `${command} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
-  return { stdout: run.stdout ?? '', text: `${run.stdout ?? ''}${run.stderr ?? ''}` };
+    const run = target.container ? containerRun(ctx, target, command, args) : tool(ctx, command, args, { cwd: ctx.cwd, env: { ...ctx.env, ...target.env } });
+    if (run.error)
+        throw failure('DB_CLI_MISSING', target.container ? `cannot run docker exec ${command} in container ${target.container.slice(0, 12)}` : `cannot run ${command}; install the PostgreSQL client tools (psql, pg_dump)`);
+    if (run.status !== 0)
+        throw failure(code, withhold ? `${command} failed; output withheld` : `${command} failed: ${scrub(firstLine(run.stderr), target.secrets)}`);
+    return { stdout: run.stdout ?? '', text: `${run.stdout ?? ''}${run.stderr ?? ''}` };
 }
-
 const PSQL = ['-X', '-q', '-v', 'ON_ERROR_STOP=1'];
-
 /** Runs SQL statements (`-c`) and files (`-f`) in ONE transaction: each step is { sql } or { file }. */
 export function psqlTransaction(ctx, target, steps, options = {}) {
-  const args = [...PSQL, '-1', '-d', target.url, ...steps.flatMap((step) => (step.file !== undefined ? ['-f', step.file] : ['-c', step.sql]))];
-  return pgTool(ctx, target, 'psql', args, options);
+    const args = [...PSQL, '-1', '-d', target.url, ...steps.flatMap((step) => (step.file !== undefined ? ['-f', step.file] : ['-c', step.sql]))];
+    return pgTool(ctx, target, 'psql', args, options);
 }
-
 /** The rows of one read-only query as plain objects (json_agg on the server, so no psql formatting is parsed). */
 export function queryRows(ctx, target, sql, options = {}) {
-  const wrapped = `select coalesce(json_agg(row_to_json(q)), '[]'::json) from (${sql.replace(/;\s*$/u, '')}) q`;
-  const { stdout } = pgTool(ctx, target, 'psql', [...PSQL, '-A', '-t', '-d', target.url, '-c', wrapped], options);
-  let rows;
-  try { rows = JSON.parse(stdout.trim() || '[]'); } catch { throw failure('DB_QUERY_UNREADABLE', 'the database answered rows psql could not print as JSON; output withheld'); }
-  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw failure('DB_QUERY_UNREADABLE', 'the database answer is not a rows array');
-  return rows;
+    const wrapped = `select coalesce(json_agg(row_to_json(q)), '[]'::json) from (${sql.replace(/;\s*$/u, '')}) q`;
+    const { stdout } = pgTool(ctx, target, 'psql', [...PSQL, '-A', '-t', '-d', target.url, '-c', wrapped], options);
+    let rows; // reason: JSON parsed from psql output, validated as an array of plain objects below
+    try {
+        rows = JSON.parse(stdout.trim() || '[]');
+    }
+    catch {
+        throw failure('DB_QUERY_UNREADABLE', 'the database answered rows psql could not print as JSON; output withheld');
+    }
+    if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row)))
+        throw failure('DB_QUERY_UNREADABLE', 'the database answer is not a rows array');
+    return rows;
 }
-
 /** A SQL string literal of `value`. */
 export const literal = (value) => `'${String(value).replaceAll("'", "''")}'`;
-
 /** The versions the history table records; an absent table is an empty history (a database `migrate` has never touched). */
 export function historyVersions(ctx, target) {
-  const [presence] = queryRows(ctx, target, `select pg_catalog.to_regclass(${literal(HISTORY_TABLE)}) is not null as present`);
-  if (presence?.present !== true) return new Set();
-  return new Set(queryRows(ctx, target, `select version from ${HISTORY_TABLE} order by version`).map((row) => String(row.version)));
+    const [presence] = queryRows(ctx, target, `select pg_catalog.to_regclass(${literal(HISTORY_TABLE)}) is not null as present`);
+    if (presence?.present !== true)
+        return new Set();
+    return new Set(queryRows(ctx, target, `select version from ${HISTORY_TABLE} order by version`).map((row) => String(row.version)));
 }
-
 /** The statement that creates the history table when it is absent (same columns as the image's own: version, statements, name). */
 export const HISTORY_DDL = `create schema if not exists supabase_migrations; create table if not exists ${HISTORY_TABLE} (version text primary key, statements text[], name text)`;
-
 /** Records `version` (named `name`) as applied. */
 export const markApplied = (version, name) => `insert into ${HISTORY_TABLE} (version, name) values (${literal(version)}, ${literal(name)}) on conflict (version) do update set name = excluded.name`;
-
 /** Removes `version` from the history. */
 export const markReverted = (version) => `delete from ${HISTORY_TABLE} where version = ${literal(version)}`;

package/emit/compiler.d.mts

@@ -0,0 +1,3 @@
+import type TypeScript from 'typescript';
+/** Answers the compiler options of the repository at `repoRoot`. */
+export declare function compilerOptionsOf(ts: typeof TypeScript, repoRoot: string, note?: (message: string) => unknown): TypeScript.CompilerOptions;

package/emit/compiler.mjs

@@ -4,32 +4,30 @@
  * a Nest project compiles with, and each problem is handed to `note` so the caller can report it like a stand-in.
  */
 import path from 'node:path';
-
 /** Answers the compiler options of the repository at `repoRoot`. */
-export function compilerOptionsOf(ts, repoRoot, note = () => {}) {
-  const parsed = ts.getParsedCommandLineOfConfigFile(
-    path.join(repoRoot, 'tsconfig.json'),
-    {},
-    { ...ts.sys, onUnRecoverableConfigFileDiagnostic: (diagnostic) => { throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')); } },
-  );
-  for (const error of parsed.errors) note(`tsconfig.json (${ts.flattenDiagnosticMessageText(error.messageText, ' ')}): compiler options fall back to the Nest defaults`);
-  return {
-    target: ts.ScriptTarget.ES2022,
-    module: ts.ModuleKind.CommonJS,
-    esModuleInterop: true,
-    ...parsed.options,
-    experimentalDecorators: true,
-    emitDecoratorMetadata: true,
-    declaration: false,
-    declarationMap: false,
-    sourceMap: false,
-    inlineSourceMap: false,
-    incremental: false,
-    composite: false,
-    tsBuildInfoFile: undefined,
-    noEmit: false,
-    noEmitOnError: false,
-    outDir: undefined,
-    rootDir: undefined,
-  };
+export function compilerOptionsOf(ts, repoRoot, note = () => { }) {
+    const parsed = ts.getParsedCommandLineOfConfigFile(path.join(repoRoot, 'tsconfig.json'), {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: (diagnostic) => { throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')); } }); // an unreadable configuration never returns: the host callback above throws first
+    for (const error of parsed.errors)
+        note(`tsconfig.json (${ts.flattenDiagnosticMessageText(error.messageText, ' ')}): compiler options fall back to the Nest defaults`);
+    const options = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.CommonJS,
+        esModuleInterop: true,
+        ...parsed.options,
+        experimentalDecorators: true,
+        emitDecoratorMetadata: true,
+        declaration: false,
+        declarationMap: false,
+        sourceMap: false,
+        inlineSourceMap: false,
+        incremental: false,
+        composite: false,
+        noEmit: false,
+        noEmitOnError: false,
+    };
+    // The repository configuration may set these three; the emit workers never write build info or redirect the output.
+    delete options.tsBuildInfoFile;
+    delete options.outDir;
+    delete options.rootDir;
+    return options;
 }

package/emit/contracts.d.mts

@@ -0,0 +1,35 @@
+/** The parts of the parsed hfs.json this module reads. */
+export interface HfsDeclaration {
+    readonly apps?: ReadonlyArray<{
+        readonly name: string;
+        readonly kind: string;
+    }>;
+}
+/** The repository-relative path of an app's root module. */
+export declare const appModulePath: (app: string) => string;
+/** A tsconfig `paths` alias: its prefix and the absolute bases it maps to. */
+export interface PathAlias {
+    readonly prefix: string;
+    readonly targets: readonly string[];
+}
+/** The `paths` aliases of a tsconfig as [{ prefix, targets }], `@modules/*` giving prefix `@modules/`. Pure. */
+export declare function aliasesOf(paths: Readonly<Record<string, readonly string[]>> | undefined, baseDir: string): PathAlias[];
+/** The absolute base a specifier resolves to through the aliases, or null when it is not aliased. Pure. */
+export declare function aliasTarget(aliases: readonly PathAlias[], specifier: string): string | null;
+/** The text written to a snapshot file: the printed schema and one final newline. Pure. */
+export declare const snapshotText: (printed: string) => string;
+/**
+ * Writes the snapshots of every api app: `contracts/<app>/schema.graphql` when it serves GraphQL and `contracts/<app>/openapi.json`
+ * when it has an operation table. Answers `{ written: [paths], skipped: [apps], standIns: { app: [lines] } }`, `skipped`
+ * being the apps with neither. `declaration` is the parsed hfs.json. `outDir` (absolute) redirects the snapshots to another
+ * root, keeping their relative paths.
+ */
+export declare function emitContracts({ repoRoot, declaration, outDir }: {
+    repoRoot: string;
+    declaration: HfsDeclaration;
+    outDir?: string;
+}): {
+    written: string[];
+    skipped: string[];
+    standIns: Record<string, string[]>;
+};