@starci/hfs 4.9.11 → 4.10.0

package/runtime/scripts/hfs/coverage-scope.mjs

@@ -52,7 +52,7 @@ export function nested(inner, outer) {
 const variantsOf = (slot) => braceVariants(slot.path).map(star);
 
 /**
- * The tracked slots of the be profile, in manifest order. A slot gated by a connection provider (be.integrations.supabase) holds files only in an
+ * The tracked slots of the be profile, in manifest order. A slot gated by a connection provider holds files only in an
  * app whose connection declares that provider (`providers`), so it takes no part in the scope of any other app.
  */
 const beSlots = (manifest, providers) => manifest.slots.filter((slot) => slot.profiles.includes('be') && slot.tracked === 'tracked' && (slot.provider === undefined || providers.includes(slot.provider)));

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

@@ -4,9 +4,7 @@ import path from 'node:path';
 import pg from 'libpg-query';
 import { invocationDir } from '../lib/roots.mjs';
 import { sqlStringParts as names, walkSqlAst as walk, sqlParser } from '../lib/sql-ast.mjs';
-import { databaseDump } from '../api/supabase/database-dump.mjs';
-import { databaseQuery } from '../api/supabase/database-query.mjs';
-import { migrationRepair } from '../api/supabase/migration-repair.mjs';
+import { spawnSync } from 'node:child_process';
 import { migrationStamp, isMigrationName, databaseSqlTokens, databaseExecutableTokens } from './rules/database-migrations.mjs';
 import { baselineMarkers, baselineSourceFindings } from './rules/database-baseline.mjs';
 import { databaseQueueDeclarations } from './rules/database-queues.mjs';
@@ -16,10 +14,6 @@ import { dbPlanMain } from './db-plan-verb.mjs';
 await pg.loadModule();
 
 export class DbVerbError extends Error {}
-const LINKED_PASSWORD_ENV = 'SUPABASE_DB_PASSWORD';
-const TELEMETRY_DISABLED_ENV = 'SUPABASE_TELEMETRY_DISABLED';
-const TELEMETRY_DEBUG_ENV = 'SUPABASE_TELEMETRY_DEBUG';
-const CLI_DEBUG_ENV = 'SUPABASE_DEBUG';
 
 /** Strict shared options; unknown flags never reach the database CLI. */
 export function dbOptions(argv, allowed) {
@@ -28,7 +22,7 @@ export function dbOptions(argv, allowed) {
     const [flag, inline] = argv[index].split(/=(.*)/s);
     const name = flag.slice(2);
     if (!flag.startsWith('--') || !allowed.includes(name) || Object.hasOwn(opts, name)) throw new DbVerbError('unknown or duplicate database option');
-    if (['apply', 'local', 'json'].includes(name)) {
+    if (['apply', 'json'].includes(name)) {
       if (inline !== undefined && !['true', 'false'].includes(inline)) throw new DbVerbError(`${flag} expects true or false`);
       opts[name] = inline !== 'false';
     } else {
@@ -48,7 +42,7 @@ export function dbAppRoot(cwd, opts) {
   return root;
 }
 
-/** Immediate SQL files only, never secrets or Supabase's temporary credential files. */
+/** Immediate SQL files only, never secrets or credential files. */
 export function dbSqlFiles(root, directory = MIGRATIONS_DIR) {
   const dir = path.join(root, directory);
   if (!fs.existsSync(dir)) return [];
@@ -59,27 +53,50 @@ export function dbSqlFiles(root, directory = MIGRATIONS_DIR) {
   }).sort((left, right) => left.name < right.name ? -1 : Number(left.name > right.name));
 }
 
-/** Supabase adapter uses supabaseSpawn's (repoRoot, args, options) contract; raw failures are private. */
-const DB_CALLS = { 'db dump': databaseDump, 'db query': databaseQuery, 'migration repair': migrationRepair };
+/** The database of `--url-env` (default DATABASE_URL): the URL without its password and the password for PGPASSWORD. */
+function connectionOf(env, urlEnv) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(urlEnv)) throw new DbVerbError('--url-env must name an UPPER_CASE environment variable');
+  let url;
+  try { url = new URL(String(env[urlEnv] ?? '')); } catch { throw new DbVerbError(`${urlEnv} must hold a postgres connection URL`); }
+  if (!/^postgres(?:ql)?:$/.test(url.protocol)) throw new DbVerbError(`${urlEnv} must hold a postgres connection URL`);
+  const password = decodeURIComponent(url.password);
+  url.password = '';
+  return { url: url.toString(), env: { ...env, ...(password ? { PGPASSWORD: password } : {}) } };
+}
+
+const HISTORY = 'supabase_migrations.schema_migrations';
+const sqlLiteral = (value) => `'${String(value).replaceAll("'", "''")}'`;
 
-function runDatabaseCommand(root, args, options) {
-  const call = DB_CALLS[args.slice(0, 2).join(' ')];
-  if (!call) throw new DbVerbError('unsupported database command');
-  return call(root, args.slice(2), options);
+/** The psql and pg_dump invocation of one operation: a JSON rows query, a schema-only dump, or one history row applied or reverted. */
+function commandOf(op, url) {
+  const psql = ['-X', '-q', '-v', 'ON_ERROR_STOP=1', '-d', url];
+  if (op.kind === 'query') return ['psql', [...psql, '-A', '-t', '-c', `select coalesce(json_agg(row_to_json(q)), '[]'::json) from (${op.sql.replace(/;\s*$/, '')}) q`]];
+  if (op.kind === 'dump') return ['pg_dump', ['--schema-only', '--schema', 'public', '--dbname', url]];
+  if (op.kind === 'repair') {
+    const change = op.status === 'applied'
+      ? `insert into ${HISTORY} (version, name) values (${sqlLiteral(op.stamp)}, ${sqlLiteral(op.name ?? 'baseline')}) on conflict (version) do nothing`
+      : `delete from ${HISTORY} where version = ${sqlLiteral(op.stamp)}`;
+    return ['psql', [...psql, '-1', '-c', `create schema if not exists supabase_migrations; create table if not exists ${HISTORY} (version text primary key, statements text[], name text)`, '-c', change]];
+  }
+  throw new DbVerbError('unsupported database command');
 }
 
-export function runDbSupabase(root, args, ports = {}) {
+/** Runs one database operation through psql or pg_dump (ports.runPostgres in specs); raw failures and output are private. */
+export function runDbPostgres(root, op, ports = {}, urlEnv = 'DATABASE_URL') {
   const env = ports.env ?? process.env;
-  // The linked CLI can mint a temporary remote login when no existing password is supplied.
-  // Check custody presence only; the value stays within the CLI environment.
-  if (args.includes('--linked') && !ports.runSupabase && !ports.run && (typeof env[LINKED_PASSWORD_ENV] !== 'string' || env[LINKED_PASSWORD_ENV].length === 0)) throw new DbVerbError('linked database operations require an existing SUPABASE_DB_PASSWORD in the CLI environment');
-  const cliEnv = { ...env, [TELEMETRY_DISABLED_ENV]: '1', [TELEMETRY_DEBUG_ENV]: '0', [CLI_DEBUG_ENV]: '0' };
-  const result = (ports.runSupabase ?? runDatabaseCommand)(root, args, { env: cliEnv, ...(ports.run ? { run: ports.run } : {}) });
-  if (result?.error || !(result?.ok === true || result?.status === 0)) throw new DbVerbError('Supabase command failed; inspect the CLI privately');
+  const result = ports.runPostgres ? ports.runPostgres(root, op) : (() => {
+    const connection = connectionOf(env, urlEnv);
+    const [command, args] = commandOf(op, connection.url);
+    return spawnSync(command, args, { cwd: root, encoding: 'utf8', env: connection.env, timeout: 120_000, windowsHide: true });
+  })();
+  if (result?.error || !(result?.ok === true || result?.status === 0)) throw new DbVerbError('database command failed; inspect psql privately');
   return String(result.stdout ?? '');
 }
 
-export const repairArgs = (stamp, status, local) => ['migration', 'repair', stamp, '--status', status, local ? '--local' : '--linked'];
+/** A history change: `stamp` recorded as applied (named `name`) or reverted. */
+export const repairOp = (stamp, status, name) => ({ kind: 'repair', stamp, status, ...(name ? { name } : {}) });
+/** The printed form of a history change. */
+export const repairLine = (op) => `history ${op.status} ${op.stamp}${op.name ? ` ${op.name}` : ''}`;
 export const dbFailure = (verb, error, stderr) => { stderr(`starci app db ${verb}: ${error instanceof DbVerbError ? error.message : 'operation failed; database output was withheld'}\n`); return 2; };
 
 function baselinePlan(root, opts, now) {
@@ -114,7 +131,7 @@ function baselineFiles(root) {
       else if (entry.isFile() && /\.(?:sql|[cm]?[jt]sx?)$/.test(entry.name)) files.push(file);
     }
   };
-  for (const directory of ['supabase', 'be/src', 'be/apps', 'src', 'apps']) visit(directory);
+  for (const directory of ['db', 'be/src', 'be/apps', 'src', 'apps']) visit(directory);
   return files;
 }
 
@@ -257,20 +274,21 @@ function metadataSql(metadata) {
 /** Numeric CLI exit code, injectable IO/clock/CLI; neither files nor history change without --apply. */
 export function dbBaselineMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), now = () => new Date(), ...ports } = {}) {
   try {
-    const opts = dbOptions(argv, ['cwd', 'stamp', 'apply', 'local']);
+    const opts = dbOptions(argv, ['cwd', 'stamp', 'apply', 'url-env']);
+    const urlEnv = opts['url-env'] ?? 'DATABASE_URL';
     const root = dbAppRoot(cwd, opts);
     const plan = baselinePlan(root, opts, now);
     const files = baselineFiles(root);
     if (baselineSourceFindings({ repoRoot: root, files, all: files, git: ports.git }).length) throw new DbVerbError('baseline sources and archives must match committed migration history');
     const metadata = baselineMetadata(root, plan, files);
-    if (dbPlanMain(['--json', ...(opts.local ? ['--local'] : [])], { ...ports, cwd: root, stdout: () => {}, stderr: () => {} }) !== 0) throw new DbVerbError('baseline requires a clean database plan with all local migrations already applied');
-    const schema = runDbSupabase(root, ['db', 'dump', opts.local ? '--local' : '--linked'], ports);
+    if (dbPlanMain(['--json', '--url-env', urlEnv], { ...ports, cwd: root, stdout: () => {}, stderr: () => {} }) !== 0) throw new DbVerbError('baseline requires a clean database plan with every migration already applied');
+    const schema = runDbPostgres(root, { kind: 'dump' }, ports, urlEnv);
     if (!schema.trim() || baselineMarkers(schema).length || /\bvault\.(?:create_secret|update_secret)\s*\(|\bpassword\s+'[^']+'/i.test(schema)) throw new DbVerbError('schema dump is empty or contains unsupported secret/baseline statements');
-    const repairs = [...plan.active.map((entry) => repairArgs(entry.stamp, 'reverted', opts.local)), repairArgs(plan.stamp, 'applied', opts.local)];
+    const repairs = [...plan.active.map((entry) => repairOp(entry.stamp, 'reverted')), repairOp(plan.stamp, 'applied', 'baseline')];
     stdout(`${opts.apply ? 'apply' : 'preview'} baseline ${plan.file}; archive ${plan.active.length} migrations\n`);
-    for (const args of repairs) stdout(`supabase ${args.join(' ')}\n`);
+    for (const op of repairs) stdout(`${repairLine(op)}\n`);
     if (!opts.apply) return 0;
-    for (const args of repairs) runDbSupabase(root, args, ports);
+    for (const op of repairs) runDbPostgres(root, op, ports, urlEnv);
     fs.mkdirSync(path.join(root, MIGRATIONS_ARCHIVE_DIR), { recursive: true });
     fs.writeFileSync(path.join(root, plan.file), `-- starci:baseline ${plan.last}\n${metadata.extensions}${metadata.roles}${schema.replace(/^\s+/, '')}\n${metadataSql(metadata)}`, { flag: 'wx' });
     for (const entry of plan.active) fs.renameSync(path.join(root, entry.file), path.join(root, MIGRATIONS_ARCHIVE_DIR, entry.name));

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

@@ -1,27 +1,23 @@
-// app db plan: compare migration-owned state without fetching commands or Vault values.
+// app db plan: compare migration-owned state (history, pg_cron jobs, pgmq queues) without fetching commands.
 import fs from 'node:fs';
 import path from 'node:path';
 import { sha256 } from '../../engine/digest.mjs';
 import pg from 'libpg-query';
-import { parse as parseToml } from 'smol-toml';
 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, runDbSupabase, dbFailure } from './db-baseline-verb.mjs';
+import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbPostgres, dbFailure } from './db-baseline-verb.mjs';
 
 await pg.loadModule();
 
-// The pinned Supabase CLI uses positional SQL, --output json and --agent no for a plain rows array.
-// Contract: supabase/cli apps/cli/src/commands/db/query/{query.command,query.handler}.ts at the pinned CLI tag.
+// 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,
-  pg_catalog.to_regclass('vault.secrets') is not null as vault;`;
+  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;',
-  vault: 'select name from vault.secrets order by 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']);
@@ -99,91 +95,9 @@ function inventoryDo(state, node) {
   for (const statement of statements) inventoryTree(state, statement);
 }
 
-function quotedEnd(text, start) {
-  const quote = text[start];
-  const delimiter = text.startsWith(quote.repeat(3), start) ? quote.repeat(3) : quote;
-  let cursor = start + delimiter.length;
-  while (cursor < text.length) {
-    if (quote === '"' && text[cursor] === '\\') { cursor += 2; continue; }
-    if (text.startsWith(delimiter, cursor)) {
-      let end = cursor + delimiter.length;
-      if (delimiter.length === 3) while (text[end] === quote) end += 1;
-      return end;
-    }
-    cursor += 1;
-  }
-  throw new DbVerbError('Supabase config contains an unterminated string');
-}
-
-// Advance over an assignment value without collecting, decoding or resolving its content.
-function valueEnd(text, start) {
-  let cursor = start;
-  let depth = 0;
-  while (cursor < text.length) {
-    const character = text[cursor];
-    if (character === '"' || character === "'") { cursor = quotedEnd(text, cursor); continue; }
-    if (character === '#') {
-      cursor = text.indexOf('\n', cursor);
-      if (cursor < 0) return text.length;
-      if (depth === 0) return cursor + 1;
-    } else if (character === '[' || character === '{') depth += 1;
-    else if (character === ']' || character === '}') depth -= 1;
-    else if (character === '\n' && depth === 0) return cursor + 1;
-    cursor += 1;
-  }
-  return cursor;
-}
-
-function assignmentEnd(text, start) {
-  let cursor = start;
-  while (cursor < text.length && !['=', '\n', '#'].includes(text[cursor])) {
-    if (text[cursor] === '"' || text[cursor] === "'") cursor = quotedEnd(text, cursor);
-    else cursor += 1;
-  }
-  return cursor;
-}
-
-function vaultKeys(table, key) {
-  // The TOML parser sees only the table/key syntax and an invented empty value.
-  let metadata;
-  try { metadata = parseToml(`${table}\n${key} = ""`); }
-  catch { throw new DbVerbError('Supabase config keys could not be inventoried safely'); }
-  const vault = metadata.db?.vault ?? {};
-  if (typeof vault !== 'object' || Object.values(vault).some((value) => typeof value !== 'string')) throw new DbVerbError('Vault config requires individual named keys');
-  return Object.keys(vault);
-}
-
-function configToken(text, cursor, table) {
-  if (/\s/.test(text[cursor])) return { cursor: cursor + 1, table, keys: [] };
-  if (text[cursor] === '#' || text[cursor] === '[') {
-    const end = text.indexOf('\n', cursor);
-    const line = text.slice(cursor, end < 0 ? undefined : end);
-    return { cursor: end < 0 ? text.length : end + 1, table: text[cursor] === '[' ? line : table, keys: [] };
-  }
-  const end = assignmentEnd(text, cursor);
-  if (text[end] !== '=') throw new DbVerbError('Supabase config keys could not be inventoried safely');
-  return { cursor: valueEnd(text, end + 1), table, keys: vaultKeys(table, text.slice(cursor, end)) };
-}
-
-function configVaultNames(root) {
-  const file = path.join(root, 'supabase/config.toml');
-  if (!fs.existsSync(file)) return new Map();
-  const text = fs.readFileSync(file, 'utf8');
-  const configured = new Map();
-  let token = { cursor: 0, table: '' };
-  while (token.cursor < text.length) {
-    token = configToken(text, token.cursor, token.table);
-    for (const name of token.keys) {
-      if (configured.has(name)) throw new DbVerbError('Vault config names must be unique');
-      configured.set(name, null);
-    }
-  }
-  return configured;
-}
-
 function repositoryState(root) {
   const migrations = dbSqlFiles(root);
-  const state = { migrations: new Map(migrations.map((entry) => [entry.stamp, null])), cron: new Map(), queues: new Map(), vault: configVaultNames(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');
   for (const entry of migrations) {
     const tree = parseSql(fs.readFileSync(path.join(root, entry.file), 'utf8'));
@@ -197,22 +111,19 @@ function repositoryState(root) {
   return state;
 }
 
-function queryRows(root, sql, local, ports) {
-  // The pinned CLI otherwise creates this cache in its linked-query finalizer.
-  // Existing metadata is sufficient; never inspect the cache or credential files.
-  if (!local && !ports.runSupabase && !ports.run && !fs.existsSync(path.join(root, 'supabase/.temp/linked-project.json'))) throw new DbVerbError('link the existing project before running a read-only database plan');
-  const output = runDbSupabase(root, ['db', 'query', sql, local ? '--local' : '--linked', '--output', 'json', '--agent', 'no'], ports);
+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('Supabase returned unreadable inventory; database output was withheld'); }
-  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw new DbVerbError('Supabase returned an invalid inventory; database output was withheld');
+  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;
 }
 
-function remoteState(root, local, ports) {
-  const rows = queryRows(root, PRESENCE_SQL, local, ports);
-  if (rows.length !== 1 || Object.keys(INVENTORIES).some((key) => typeof rows[0][key] !== 'boolean')) throw new DbVerbError('Supabase returned invalid inventory availability');
+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, local, ports) : [];
+  for (const [key, sql] of Object.entries(INVENTORIES)) state[key] = rows[0][key] ? queryRows(root, sql, urlEnv, ports) : [];
   return state;
 }
 
@@ -222,8 +133,8 @@ function compare(expected, actual, kind) {
   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('Supabase 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('Supabase returned invalid cron metadata');
+    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);
@@ -236,10 +147,10 @@ function compare(expected, actual, kind) {
 /** 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', 'local', 'json', 'apply']);
+    const opts = dbOptions(argv, ['cwd', 'url-env', 'json', 'apply']);
     const root = dbAppRoot(cwd, opts);
     const expected = repositoryState(root);
-    const actual = remoteState(root, opts.local, ports);
+    const actual = remoteState(root, opts['url-env'] ?? 'DATABASE_URL', ports);
     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.

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

@@ -5,7 +5,7 @@ import { parseYaml } from '../../engine/yaml.mjs';
 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, runDbSupabase, repairArgs, dbFailure } from './db-baseline-verb.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) {
@@ -39,16 +39,16 @@ function sourceOf(entry, active) {
  * 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, local, ports) {
+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(runDbSupabase(root, ['db', 'query', `select name from supabase_migrations.schema_migrations where version = '${old}'`, local ? '--local' : '--linked', '--output', 'json', '--agent', 'no'], ports)); } catch { throw unreadable; }
+  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, { local = false, ports = {} } = {}) {
+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')); }
@@ -67,7 +67,7 @@ function restampPlan(root, mapFile, { local = false, ports = {} } = {}) {
     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, local, ports) : true);
+    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]));
@@ -79,16 +79,17 @@ function restampPlan(root, mapFile, { local = false, ports = {} } = {}) {
 /** The complete map is validated before any repair or file mutation. */
 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', 'local']);
+    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, { local: opts.local, ports });
-    const repairs = steps.filter((step) => step.applied).flatMap((step) => [repairArgs(step.old, 'reverted', opts.local), repairArgs(step.next, 'applied', opts.local)]);
+    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 args of repairs) stdout(`supabase ${args.join(' ')}\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 args of repairs) runDbSupabase(root, args, ports);
+    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/, '');

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -2,27 +2,23 @@
 // against a loaded manifest remain in slots.mjs; this module mirrors modules/schemas/hfs-repo.schema.yaml only.
 import { isPlainObject } from '../../engine/plain-object.mjs';
 import { APP_KIND, connectionShapeProblems, NAME, PACKAGE_NAME, RUNTIME_KIND, SLOT_ID } from './manifest-shape.mjs';
+import { dbFunctionsOk } from './rule-params-shape.mjs';
 import { kindShapeProblems, patternShapeProblems } from './declaration-slots.mjs';
 import { byCodeUnit } from '../lib/list.mjs';
 
-/** Shape problems of the optional hfs.json `supabase` block whose auth posture DB_CONFIG_POLICY checks. */
-const isSupabaseStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
+/** Shape problems of the optional hfs.json `db` block of a lite app: the environment variable naming its database, its image, forced RLS and its application role. */
+const isStringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.trim());
 
-function supabaseValueProblems(block) {
-  const bad = [];
-  if (block.enableSignup !== undefined && typeof block.enableSignup !== 'boolean') bad.push('supabase.enableSignup must be true or false');
-  if (block.jwtExpiry !== undefined && !(Number.isInteger(block.jwtExpiry) && block.jwtExpiry > 0 && block.jwtExpiry <= 3600)) bad.push('supabase.jwtExpiry must be an integer of seconds, 3600 at most');
-  if (block.siteUrl !== undefined && (typeof block.siteUrl !== 'string' || !block.siteUrl.trim())) bad.push('supabase.siteUrl must be a URL string');
-  for (const key of ['redirectUrls', 'forceRls']) if (block[key] !== undefined && !isSupabaseStringList(block[key])) bad.push(`supabase.${key} must be a list of strings`);
-  return bad;
-}
-
-function supabaseBlockProblems(block) {
+function dbBlockProblems(block) {
   if (block === undefined) return [];
-  if (!isPlainObject(block)) return ['supabase must be an object'];
+  if (!isPlainObject(block)) return ['db must be an object'];
   const bad = [];
-  for (const key of Object.keys(block)) if (!['enableSignup', 'jwtExpiry', 'siteUrl', 'redirectUrls', 'forceRls'].includes(key)) bad.push(`supabase has unknown key ${key}`);
-  bad.push(...supabaseValueProblems(block));
+  for (const key of Object.keys(block)) if (!['urlEnv', 'image', 'forceRls', 'forceRlsExemptions', 'appRole'].includes(key)) bad.push(`db has unknown key ${key}`);
+  if (block.urlEnv !== undefined && (typeof block.urlEnv !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(block.urlEnv))) bad.push('db.urlEnv must name an UPPER_CASE environment variable');
+  if (block.image !== undefined && (typeof block.image !== 'string' || !/@sha256:[0-9a-f]{64}$/.test(block.image))) bad.push('db.image must be a digest-pinned image reference');
+  if (block.forceRls !== undefined && !isStringList(block.forceRls)) bad.push('db.forceRls must be a list of strings');
+  if (block.appRole !== undefined && (typeof block.appRole !== 'string' || !/^[a-z][a-z0-9_]*$/.test(block.appRole))) bad.push('db.appRole must name a role');
+  if (block.forceRlsExemptions !== undefined && !Array.isArray(block.forceRlsExemptions)) bad.push('db.forceRlsExemptions must be a list of { table, reason }');
   return bad;
 }
 
@@ -95,7 +91,8 @@ function declarationSideProblems(side, value, names) {
   const bad = [];
   const at = `sides.${side}`;
   if (!isPlainObject(value)) return [`${at} must be an object`];
-  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'queueOutbox'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing', 'queueOutbox', 'dbFunctions'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  if (value.dbFunctions !== undefined && (side !== 'be' || !dbFunctionsOk(value.dbFunctions))) bad.push(`${at}.dbFunctions belongs to the be side and lists {name, reason} database functions with unique names`);
   bad.push(...appShapeProblems(value.apps, at, side, names));
   if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
   if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
@@ -127,13 +124,13 @@ function observeBlockProblems(observe) {
   return bad;
 }
 
-const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'supabase', 'sides', 'browser', 'lexicon', 'observe']);
+const DECLARATION_KEYS = new Set(['hfs', 'kind', 'project', 'edition', 'db', 'sides', 'browser', 'lexicon', 'observe']);
 const RUNTIME_DECLARATION_KEYS = new Set(['hfs', 'kind', 'project']);
 
 function productDeclarationProblems(declaration, profiles) {
   const bad = [];
   for (const key of Object.keys(declaration)) if (!DECLARATION_KEYS.has(key)) bad.push(`unknown key ${key}`);
-  bad.push(...supabaseBlockProblems(declaration.supabase), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
+  bad.push(...dbBlockProblems(declaration.db), ...lexiconBlockProblems(declaration.lexicon), ...observeBlockProblems(declaration.observe));
   if (declaration.browser !== undefined && declaration.browser !== true) bad.push('browser is `true` when the app has a browser journey (slot app.browser), and is left out otherwise');
   if (declaration.kind !== APP_KIND) bad.push(`kind must be ${APP_KIND} (a product is one app repository with a be and an fe side) or ${RUNTIME_KIND} (the StarCi runtime repository)`);
   if (!isPlainObject(declaration.sides) || Object.keys(declaration.sides).sort(byCodeUnit).join() !== profiles.join()) { bad.push('sides must declare exactly be and fe'); return bad; }

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -15,12 +15,12 @@ const ENV_PREFIX =/^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/;
 const CONTEXT_ISOLATIONS = Object.freeze(["database", "schema"]);
 /** The app kinds that may own a context: the services, never the migrate or cli apps that only run migrations. */
 const CONTEXT_OWNER_KINDS = Object.freeze(["api", "worker"]);
-/** The database engines a connection may run on: a self-described Postgres, or the Postgres of a Supabase project. */
-const CONNECTION_PROVIDERS = Object.freeze(["postgres", "supabase"]);
+/** The database engine a connection runs on. */
+const CONNECTION_PROVIDERS = Object.freeze(["postgres"]);
 /** The editions an app repository may declare in hfs.json (`full` when absent): the filter slots.mjs applies. */
 export const EDITIONS = Object.freeze(["full", "lite"]);
-/** What decides where schema changes live (ruleParams.<side>.schemaAuthority): TypeORM migrations under persistence/, or the Supabase migration tree. */
-export const SCHEMA_AUTHORITIES = Object.freeze(["typeorm", "supabase"]);
+/** What decides where schema changes live (ruleParams.<side>.schemaAuthority): TypeORM migrations under persistence/, or the SQL migration tree db/migrations. */
+export const SCHEMA_AUTHORITIES = Object.freeze(["typeorm", "sql"]);
 /**
  * The shape problems of the `connections` of one side: a list of {name, envPrefix, owner, isolation}, the owner an api or worker app
  * of the same side (a connection is a bounded context and one service owns it), isolation `database` or `schema`.

package/runtime/scripts/hfs/rule-params-shape.mjs

@@ -62,6 +62,9 @@ function beSpecificProblems(be, manifest) {
   return bad;
 }
 
+/** True for an absent list or a list of {name, reason} database functions, names unique. */
+export const dbFunctionsOk = (list) => list === undefined || (Array.isArray(list) && list.every((entry) => isPlainObject(entry) && Object.keys(entry).sort().join() === 'name,reason' && /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/.test(entry.name) && typeof entry.reason === 'string' && entry.reason.trim().length > 0) && new Set(list.map((entry) => entry.name)).size === list.length);
+
 /** The shape problems of `m.ruleParams`. */
 export function ruleParamsProblems(m) {
   const bad = [];
@@ -71,7 +74,7 @@ export function ruleParamsProblems(m) {
     // common holds the parameters both sides share; a side may restate one of them (a valid value) as an override, nothing else.
     // Edition lite: a side's optional `lite` map overrides keys of the same side (never `lite` itself) when the app declares edition lite.
     if (!sideOk(rp.common, []) || !fileLinesOk(rp.common.fileLines) || !blockOk(rp.common.duplicateBlock)) bad.push('ruleParams.common needs fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}; optional functionLines and featureFiles must be positive integers');
-    if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !liteOk(rp.be.lite, [...BE_OWN, ...SHARED_KEYS, 'schemaAuthority'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns, addKinds and backing (shared parameters live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + ') and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
+    if (!sideOk(rp.be, BE_OWN, ['schemaAuthority', 'lite', 'dbFunctions']) || (rp.be.schemaAuthority !== undefined && !SCHEMA_AUTHORITIES.includes(rp.be.schemaAuthority)) || !dbFunctionsOk(rp.be.dbFunctions) || !liteOk(rp.be.lite, [...BE_OWN, ...SHARED_KEYS, 'schemaAuthority', 'dbFunctions'])) bad.push('ruleParams.be needs infraOwners, eventBus, specDoubles, paramNames, suffixes, bannedSuffixes, contractShape {helper}, unitRoles, logicRoles, thinRoles, patternScenarios, kindPatterns, addKinds and backing (shared parameters live in ruleParams.common, a side may override them); optional: schemaAuthority (' + SCHEMA_AUTHORITIES.join(' | ') + '), dbFunctions ([{name, reason}]) and lite (overrides of the same keys)'); else bad.push(...unitRolesProblems(rp.be), ...roleListProblems(rp.be));
     bad.push(...beSpecificProblems(rp.be, m));
     if (rp.fe !== undefined && (!sideOk(rp.fe, [], ['lite']) || !liteOk(rp.fe.lite, SHARED_KEYS))) bad.push('ruleParams.fe may only restate the shared parameters of ruleParams.common, and carry a lite override of them');
     if (!dbParamsOk(rp.db)) bad.push('ruleParams.db may contain only extensions (a list of unique non-empty extension names) and queueOutbox ({table: <schema>.<table>, columns: [unique column names including queue]})');

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -48,7 +48,7 @@ export const A15_CODES = [
   'HFS_WORKFLOW_CONTEXT',
   'CI_STANDARD',
   'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
-  'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_API_EXPOSED', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_SERVICE_ROLE_SCOPE', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
+  'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BOOT_PROOF_TIMEOUT', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_REDIS_PERSISTENCE', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
   // codes-end
 ];
 

package/runtime/scripts/hfs/rules/cli.mjs

@@ -26,7 +26,7 @@ export function cliFindings({ files, repo, resolver }) {
   const commandFiles = onBe.filter((file) => beResolver.classifyPath(file).slot === CLI_FEATURE_SLOT);
   const findings = [];
   const cliApps = be.apps.filter((app) => app.kind === CLI_KIND);
-  // Where the cli app is only optional (litePresence: schema migration is the Supabase CLI's job) a connection no longer forces it; a tracked command still does.
+  // Where the cli app is only optional (litePresence: schema migration is `starci app db migrate`'s job) a connection no longer forces it; a tracked command still does.
   const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
   const needs = migrates || commandFiles.length > 0;
   let why = 'it tracks commands under be/src/features/cli/';