@starci/hfs 4.9.11 → 4.10.0

package/db/local-migrate.mjs

@@ -1,194 +0,0 @@
-// Explicit-local migration applies only the app's active SQL chain through the Supabase API owner.
-// Supabase CLI v2.119.0: db/push, migration-pending, migration-list and db-config.toml-read (read 2026-10-18).
-import fs from 'node:fs';
-import path from 'node:path';
-import { createHash } from 'node:crypto';
-import { parseEnv } from 'node:util';
-import { parse as parseToml } from 'smol-toml';
-import { databasePush } from '../runtime/scripts/api/supabase/database-push.mjs';
-import { isMigrationName, migrationStamp } from '../runtime/scripts/hfs/rules/database-migrations.mjs';
-import { CONFIG_FILE, MIGRATIONS_DIR } from '../runtime/scripts/hfs/rules/database-constants.mjs';
-import { failure, refusal } from '../stack/errors.mjs';
-import { assertLocalDatabase, boundSupabaseLauncher, nativeDatabaseEnvironment } from '../stack/target-binding.mjs';
-
-const configError = (reason) => refusal('DB_CONFIG_INVALID', reason);
-const encrypted = (value) => typeof value === 'string' && value.includes('encrypted:');
-const byteOrder = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
-
-/** Never quote a parser/tool diagnostic: config, env and child streams can contain credentials. */
-function readFile(file, optional = false) {
-  try {
-    const stat = fs.lstatSync(file);
-    if (!stat.isFile() || stat.isSymbolicLink()) throw configError('local migration inputs must be regular files');
-    return fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    if (optional && error.code === 'ENOENT') return null;
-    throw configError('local migration inputs must be readable regular files');
-  }
-}
-
-function requireDirectory(directory) {
-  try {
-    const stat = fs.lstatSync(directory);
-    if (stat.isDirectory() && !stat.isSymbolicLink()) return;
-  } catch { /* The refusal below withholds filesystem diagnostics. */ }
-  throw configError('local migration requires the existing app directories, without links');
-}
-
-function requirePlainConfig(value) {
-  if (encrypted(value)) throw configError('local migration does not decrypt encrypted configuration');
-  if (value && typeof value === 'object') for (const item of Object.values(value)) requirePlainConfig(item);
-}
-
-/** The pinned CLI searches these exact files; interpolation/escapes are held rather than partially interpreted. */
-function projectEnvironment(root, ambient) {
-  const selected = ambient.SUPABASE_ENV || 'development';
-  if (!/^[A-Za-z0-9_-]+$/.test(selected)) throw configError('local migration requires an unambiguous Supabase environment selector');
-  const names = [`.env.${selected}.local`, ...(selected === 'test' ? [] : ['.env.local']), `.env.${selected}`, '.env'];
-  const values = {};
-  const files = [];
-  for (const dir of [path.join(root, 'supabase'), root]) {
-    for (const name of names) {
-      const file = path.join(dir, name);
-      const text = readFile(file, true);
-      files.push([file, text]);
-      if (text === null) continue;
-      // Pinned godotenv expansion and double-quote unescaping can synthesize the encryption prefix.
-      if (encrypted(text) || /[$\\]/.test(text)) throw configError('local migration requires literal unencrypted dotenv inputs');
-      // Keep only the common literal assignment grammar shared by Node and the pinned CLI.
-      for (const line of text.split(/\r?\n/)) {
-        if (/^\s*(?:#.*)?$/.test(line)) continue;
-        if (!/^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^'"#\r\n]*)(?:\s+#.*)?\s*$/.test(line)) {
-          throw configError('local migration requires literal single-line dotenv assignments');
-        }
-      }
-      let parsed;
-      try { parsed = parseEnv(text); } catch { throw configError('local migration dotenv inputs are not readable assignments'); }
-      for (const [key, value] of Object.entries(parsed)) {
-        if (!Object.hasOwn(ambient, key) && !Object.hasOwn(values, key)) values[key] = value;
-      }
-    }
-  }
-  return { values: { ...values, ...ambient }, files };
-}
-
-function expanded(value, env) {
-  if (typeof value !== 'string') return value;
-  const reference = /^env\(([A-Za-z_][A-Za-z0-9_]*)\)$/.exec(value);
-  const result = reference ? env[reference[1]] : value;
-  if (typeof result !== 'string' || result.startsWith('env(')) throw configError('local migration configuration has an unresolved environment reference');
-  return result;
-}
-
-const overridden = (name, value, env) => expanded(typeof env[name] === 'string' && env[name] !== '' ? env[name] : value, env);
-
-function targetIdentity(config, env) {
-  const project = overridden('SUPABASE_PROJECT_ID', config.project_id, env);
-  const portValue = overridden('SUPABASE_DB_PORT', config.db?.port, env);
-  const port = typeof portValue === 'string' && /^\d+$/.test(portValue) ? Number(portValue) : portValue;
-  const enabled = overridden('SUPABASE_DB_MIGRATIONS_ENABLED', config.db?.migrations?.enabled ?? true, env);
-  if (typeof project !== 'string' || !/^[A-Za-z0-9_-]+$/.test(project) || !Number.isInteger(port) || port < 1 || port > 65535) {
-    throw configError('local migration requires an explicit local project identity and database port');
-  }
-  if (enabled !== true && !(typeof enabled === 'string' && /^(?:1|t|T|true|TRUE|True)$/.test(enabled))) {
-    throw configError('local migration requires migrations to be explicitly enabled by the effective configuration');
-  }
-  return { project, port };
-}
-
-/** Snapshot only in memory; no plaintext configuration, values or hashes reach the result. */
-function inputs(ctx, nativeTarget = null) {
-  const root = path.resolve(ctx.cwd);
-  requireDirectory(root);
-  requireDirectory(path.join(root, 'supabase'));
-  requireDirectory(path.join(root, MIGRATIONS_DIR));
-  const appText = readFile(path.join(root, 'hfs.json'));
-  let app;
-  try { app = JSON.parse(appText); } catch { throw configError('local migration requires a readable app declaration'); }
-  if (app?.kind !== 'app' || !['full', 'lite'].includes(app.edition ?? 'full')) throw configError('local migration requires a lite or full app');
-  const configText = readFile(path.join(root, CONFIG_FILE));
-  let config;
-  try { config = parseToml(configText); } catch { throw configError('local migration requires valid Supabase TOML'); }
-  requirePlainConfig(config);
-  for (const value of Object.values(ctx.env)) if (encrypted(value)) throw configError('local migration does not decrypt encrypted environment values');
-  const { values: env, files: envFiles } = projectEnvironment(root, ctx.env);
-  if (nativeTarget && (config.experimental?.stack === true
-    || env.SUPABASE_EXPERIMENTAL_STACK && !/^(?:0|false)$/i.test(env.SUPABASE_EXPERIMENTAL_STACK)
-    || env.SUPABASE_CLI_BINARY_OVERRIDE)) throw configError('the bound local target requires the declared legacy Supabase backend and installed launcher');
-  const launcher = nativeTarget ? boundSupabaseLauncher(root) : null;
-  const target = targetIdentity(config, env);
-  let names;
-  try { names = fs.readdirSync(path.join(root, MIGRATIONS_DIR)).sort(byteOrder); } catch { throw configError('local migrations are not readable'); }
-  // Match the pinned CLI's unanchored first-entry legacy-init skip, including nested names.
-  const legacy = /([0-9]{14})_init\.sql/.exec(names[0] ?? '');
-  if (legacy && Number(legacy[1]) < 20211209000000) throw refusal('DB_STAMP_ORDER', 'the local chain contains a legacy init migration the installed CLI skips');
-  const migrations = [];
-  const stamps = new Set();
-  for (const name of names.filter((entry) => entry.endsWith('.sql'))) {
-    const stamp = name.slice(0, name.indexOf('_'));
-    if (!isMigrationName(name) || migrationStamp(stamp) === null) throw refusal('DB_MIGRATION_NAME', 'local migrations require valid UTC-stamped filenames');
-    if (stamps.has(stamp)) throw refusal('DB_STAMP_COLLISION', 'local migrations contain a duplicate timestamp');
-    stamps.add(stamp);
-    migrations.push([name, readFile(path.join(root, MIGRATIONS_DIR, name))]);
-  }
-  const digest = createHash('sha256').update(JSON.stringify({ root, appText, configText, envFiles, env, target, migrations })).digest('hex');
-  return { root, target, names: migrations.map(([name]) => name), digest, nativeTarget, launcher };
-}
-
-function unchanged(ctx, snapshot) {
-  const current = inputs(ctx, snapshot.nativeTarget);
-  if (current.digest !== snapshot.digest) throw failure('DB_FINAL_MISMATCH', 'local migration inputs changed during the operation');
-  return current;
-}
-
-/** Only the specific Supabase owner can spawn; failures and malformed JSON never expose child output. */
-function push(ctx, snapshot, dryRun) {
-  const env = snapshot.nativeTarget ? nativeDatabaseEnvironment(ctx.env, snapshot.nativeTarget,
-    { 'SUPABASE_SERVICES_HOSTNAME': '127.0.0.1', 'SUPABASE_EXPERIMENTAL_STACK': '0' }) : ctx.env;
-  const run = snapshot.nativeTarget ? (file, args, options) => {
-    if (file !== process.execPath || args[0] !== snapshot.launcher) throw failure('DB_CLI_MISSING', 'the bound database launcher cannot fall back to a global tool');
-    return ctx.spawn(file, args, options);
-  } : ctx.spawn;
-  const result = databasePush(snapshot.root, ['--local', '--skip-vault', '--workdir', snapshot.root, '--output-format', 'json',
-    ...(snapshot.nativeTarget ? ['--profile', 'supabase'] : []), ...(dryRun ? ['--dry-run'] : ['--yes'])], { env, run });
-  if (result?.error || result?.signal || result?.status !== 0) throw failure('DB_CLI_FAILED', 'the local Supabase migration command failed; database output was withheld');
-  let payload;
-  try { payload = JSON.parse(result.stdout); } catch { throw failure('DB_CLI_FAILED', 'the local migration command returned unreadable JSON'); }
-  if (!payload || typeof payload !== 'object' || Array.isArray(payload) || Object.hasOwn(payload, 'error') || payload._tag === 'Error' || payload.dryRun !== dryRun || typeof payload.upToDate !== 'boolean'
-    || !Array.isArray(payload.migrations) || !payload.migrations.every((name) => typeof name === 'string')
-    || !Array.isArray(payload.seeds) || payload.seeds.length !== 0 || !Array.isArray(payload.roles) || payload.roles.length !== 0) {
-    throw failure('DB_PUSH_STRAY', 'the local migration command returned an unexpected result');
-  }
-  const pending = payload.migrations;
-  const expected = snapshot.names.slice(snapshot.names.length - pending.length);
-  if (pending.length > snapshot.names.length || pending.some((name, index) => name !== expected[index]) || payload.upToDate !== (pending.length === 0)) {
-    throw failure('DB_PUSH_STRAY', 'the local migration result is not an ordered suffix of the authored chain');
-  }
-  return pending;
-}
-
-/** Preview by default; the caller admits execute only after the existing database arming check. No history repair, reset or linked fallback. */
-export function migrateLocalDatabase(ctx, { execute = false, nativeTarget = null } = {}) {
-  const snapshot = inputs(ctx, nativeTarget);
-  assertLocalDatabase(nativeTarget, snapshot.target);
-  const pending = push(ctx, snapshot, true);
-  unchanged(ctx, snapshot);
-  let applied = [];
-  if (execute && pending.length > 0) {
-    const fresh = push(ctx, snapshot, true);
-    unchanged(ctx, snapshot);
-    if (fresh.some((name, index) => name !== pending[index]) || fresh.length !== pending.length) throw failure('DB_FINAL_MISMATCH', 'the local migration plan changed before apply');
-    applied = push(ctx, snapshot, false);
-    unchanged(ctx, snapshot);
-    if (applied.length !== fresh.length || applied.some((name, index) => name !== fresh[index])) {
-      throw failure('DB_FINAL_MISMATCH', 'the applied local migrations differ from the reviewed pending plan');
-    }
-    if (push(ctx, snapshot, true).length !== 0) throw failure('DB_FINAL_MISMATCH', 'the local migration version history is not fully applied');
-    unchanged(ctx, snapshot);
-  }
-  return {
-    ok: true,
-    lines: [`target         local project ${snapshot.target.project}`, `pending SQL    ${pending.join(', ') || 'none'}`, execute && applied.length ? `applied         ${applied.length} migration(s); local version history is current` : 'nothing applied'],
-    data: { target: 'local', pending, pushed: applied, executed: execute && applied.length > 0, done: pending.length === 0 || execute },
-  };
-}

package/db/reset.mjs

@@ -1,125 +0,0 @@
-// reset.mjs - linked reset requires explicit custody choices, a recent verified encrypted backup and the migration arming rule.
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { runVerb } from '../release/index.mjs';
-import { requireArmed } from './migrate.mjs';
-import { failure, refusal } from '../stack/errors.mjs';
-import { backupSession, backupArgs, backupRecipients, backupTool, encryptFile, queryRows, validateReceipt, runCli } from './backup-receipt.mjs';
-
-/** Metadata fingerprints allow verification without printing or retaining rows, object keys or auth identities in the result. */
-function inventory(session, schema) {
-  const tables = queryRows(session, `select tablename from pg_catalog.pg_tables where schemaname = '${schema}' and tablename not in ('schema_migrations', 'migrations') order by tablename;`);
-  return tables.map(({ tablename }) => {
-    if (typeof tablename !== 'string' || !/^[a-z_][a-z0-9_]*$/u.test(tablename)) throw failure('DB_RESET_VERIFY_FAILED', 'invalid preservation table inventory');
-    const rows = queryRows(session, `begin read only; select count(*)::text as count, md5(coalesce(string_agg(md5(row_to_json(t)::text), '' order by md5(row_to_json(t)::text)), '')) as hash from "${schema}"."${tablename}" t; commit;`);
-    if (rows.length !== 1 || !/^\d+$/u.test(String(rows[0].count)) || !/^[a-f0-9]{32}$/u.test(rows[0].hash ?? '')) throw failure('DB_RESET_VERIFY_FAILED', 'invalid preservation fingerprint');
-    return { table: tablename, count: String(rows[0].count), hash: rows[0].hash };
-  });
-}
-
-/** age reads identity bytes on stdin or the configured identity file; neither identity nor SQL is placed in argv or diagnostics. */
-function decryptPart(ctx, encrypted, plaintext) {
-  const key = ctx.env.SOPS_AGE_KEY;
-  const identity = key ? '-' : ctx.env.SOPS_AGE_KEY_FILE;
-  if (!identity) throw refusal('DB_RESET_IDENTITY_MISSING', '--auth/--storage keep needs SOPS_AGE_KEY or SOPS_AGE_KEY_FILE to restore the temporary encrypted part');
-  backupTool(ctx, 'age', ['--decrypt', '--identity', identity, '-o', plaintext, encrypted], key ? { input: `${key}\n` } : {});
-}
-
-function preservePart(session, scratch, schema, recipients) {
-  const before = inventory(session, schema);
-  const plain = path.join(scratch, `${schema}.sql`);
-  const encrypted = `${plain}.age`;
-  runCli(session, ['db', 'dump', '--data-only', '--schema', schema, '--exclude', `${schema}.schema_migrations,${schema}.migrations`, '--file', plain, ...backupArgs(session)]);
-  encryptFile(session.ctx, plain, encrypted, recipients);
-  fs.rmSync(plain, { force: true });
-  // Prove the selected identity can restore this exact part before the destructive call.
-  decryptPart(session.ctx, encrypted, plain);
-  fs.rmSync(plain, { force: true });
-  return { schema, before, encrypted, plain };
-}
-
-function restorePart(session, part) {
-  // Supabase retains some managed tables. Replace their data to avoid duplicate users, buckets or migration-independent metadata.
-  decryptPart(session.ctx, part.encrypted, part.plain);
-  const tables = part.before.map((row) => `"${part.schema}"."${row.table}"`);
-  const source = fs.readFileSync(part.plain, 'utf8');
-  fs.writeFileSync(part.plain, `begin;\nset constraints all deferred;\n${tables.length ? `truncate ${tables.join(', ')} cascade;\n` : ''}${source}\ncommit;\n`, { mode: 0o600 });
-  try { runCli(session, ['db', 'query', '--file', part.plain, '--output', 'json', '--agent', 'no', ...backupArgs(session)]); }
-  finally { fs.rmSync(part.plain, { force: true }); }
-  if (JSON.stringify(inventory(session, part.schema)) !== JSON.stringify(part.before)) throw failure('DB_RESET_VERIFY_FAILED', `${part.schema} data differs after restore; use the full backup receipt for recovery`);
-}
-
-function expectedHead(session) {
-  const dir = path.join(session.ctx.cwd, session.database.migrationsDir ?? 'supabase/migrations');
-  let expected;
-  try { expected = fs.readdirSync(dir).filter((name) => /^\d{14}_[A-Za-z0-9_-]+\.sql$/u.test(name)).map((name) => name.slice(0, 14)).sort(); }
-  catch { throw refusal('DB_MIGRATIONS_MISSING', 'migration directory is not readable'); }
-  if (!expected.length || new Set(expected).size !== expected.length) throw refusal('DB_MIGRATIONS_MISSING', 'migration versions must be present and unique');
-  return expected;
-}
-
-function verifyHead(session) {
-  const expected = expectedHead(session);
-  const actual = queryRows(session, 'select version from supabase_migrations.schema_migrations order by version;').map((row) => row.version);
-  if (JSON.stringify(expected) !== JSON.stringify(actual)) throw failure('DB_RESET_HEAD_MISMATCH', 'reset migration history differs from repository migration versions');
-  return expected;
-}
-
-/** Dry run validates custody and prints a plan; execute preserves chosen managed data, resets, restores and verifies the exact migration head. */
-function resetDatabase(ctx, options = {}) {
-  if (options.linked !== true || options.local || options.urlEnv !== undefined) throw refusal('DB_RESET_LINKED_REQUIRED', 'reset requires --linked; use npm run db:reset for a local database');
-  if (!['keep', 'drop'].includes(options.auth) || !['keep', 'drop'].includes(options.storage)) throw refusal('DB_RESET_CHOICE_MISSING', 'explicit --auth keep|drop and --storage keep|drop are required');
-  const session = backupSession(ctx, options);
-  const receipt = validateReceipt(session, options.backup ? path.resolve(ctx.cwd, options.backup) : undefined);
-  const lines = [`target: linked project ${session.target.ref}`, `backup: verified encrypted receipt from ${receipt.at}`,
-    options.auth === 'keep' ? 'auth: encrypt all auth data tables before reset, restore in a transaction and verify' : 'auth: users and identities are deleted',
-    options.storage === 'keep' ? 'storage: preserve and verify buckets and objects metadata' : 'storage: empty storage.objects metadata; files in the storage backend are not deleted by SQL',
-    'reset: supabase db reset --linked; verify migration versions against repository'];
-  if (!options.execute) return { ok: true, lines: [...lines, 'dry run: nothing changed'], data: { executed: false, auth: options.auth, storage: options.storage, ref: session.target.ref } };
-  requireArmed(ctx);
-  // Refuse unsupported CLI file execution before resetting: SQL containing identity data must never travel in argv.
-  if (options.auth === 'keep' || options.storage === 'keep') {
-    const help = runCli(session, ['db', 'query', '--help']).text;
-    if (!help.includes('--file')) throw refusal('DB_RESET_QUERY_FILE_UNSUPPORTED', 'the Supabase CLI must support db query --file for transactional restore');
-  }
-  expectedHead(session);
-  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-db-reset-'));
-  const parts = [];
-  let resetStarted = false;
-  let complete = false;
-  try {
-    const keep = ['auth', 'storage'].filter((schema) => options[schema] === 'keep');
-    const recipients = keep.length ? backupRecipients(ctx.cwd) : [];
-    for (const schema of keep) parts.push(preservePart(session, scratch, schema, recipients));
-    resetStarted = true;
-    runCli(session, ['db', 'reset', '--yes', ...backupArgs(session)]);
-    for (const part of parts) restorePart(session, part);
-    if (options.auth === 'drop') {
-      const rows = queryRows(session, 'select (select count(*) from auth.users)::text as users, (select count(*) from auth.identities)::text as identities;');
-      if (rows.length !== 1 || String(rows[0].users) !== '0' || String(rows[0].identities) !== '0') throw failure('DB_RESET_VERIFY_FAILED', 'auth users or identities remain after reset');
-    }
-    if (options.storage === 'drop') {
-      runCli(session, ['db', 'query', 'begin; delete from storage.objects; commit;', '--output', 'json', '--agent', 'no', ...backupArgs(session)]);
-      const rows = queryRows(session, 'select count(*)::text as count from storage.objects;');
-      if (rows.length !== 1 || String(rows[0].count) !== '0') throw failure('DB_RESET_VERIFY_FAILED', 'storage.objects metadata was not emptied');
-    }
-    const versions = verifyHead(session);
-    complete = true;
-    return { ok: true, lines: [...lines, 'reset completed; managed data choices and migration head verified'], data: { executed: true, auth: options.auth, storage: options.storage, ref: session.target.ref, versions } };
-  } finally {
-    // Preserve encrypted recovery parts after a reset/restore failure; remove every plaintext file on every exit.
-    for (const name of fs.readdirSync(scratch)) if (!name.endsWith('.age')) fs.rmSync(path.join(scratch, name), { force: true });
-    if (complete || !resetStarted) fs.rmSync(scratch, { recursive: true, force: true });
-    else ctx.stderr(`DB_RESET_RECOVERY_PARTS: encrypted recovery parts retained at ${scratch}\n`);
-  }
-}
-
-export function dbResetMain(argv, io = {}) {
-  return runVerb({ label: 'starci app db reset', name: 'db reset', code: 'DB_USAGE', io, argv,
-    spec: { boolean: ['--linked', '--execute', '--json', '--local'], value: ['--auth', '--storage', '--backup', '--url-env'] },
-    run: (ctx, flags, positional) => {
-      if (positional.length) throw refusal('DB_USAGE', 'reset takes flags only');
-      return resetDatabase(ctx, { linked: flags.linked, local: flags.local, urlEnv: flags['url-env'], execute: flags.execute, auth: flags.auth, storage: flags.storage, backup: flags.backup });
-    } });
-}

package/emit/db-types.mjs

@@ -1,271 +0,0 @@
-/**
- * `supabase/types/database.types.ts` (slot `app.supabase.types`): the Database types the Supabase CLI generates from an app's
- * local stack, written by `npm run contract:emit` (`starci app emit`) beside the be contract snapshots and judged for drift
- * by DB_TYPES_DRIFT (L09, scripts/hfs/rules/database.mjs) - the rule compares the committed file with the text `emitTypes()`
- * produces, and `dbTypesEmitter` below is that callback.
- *
- * The text is `supabase gen types typescript --local` run at the app root against the running local stack, narrowed to the
- * schemas `supabase/config.toml` declares under [api]; the CLI reaches Docker, so nothing here runs inside a check that has
- * no stack. `run` is the command runner - `(file, args, {cwd})` answering the spawnSync result `{status, stdout, stderr}` -
- * the default spawns the `supabase` binary with an argument array, never a shell string and never printing env; a spec's fake
- * keeps Docker out of the suite. Before generation, `migration list --local` must prove that the database's applied versions
- * equal the migration filename stamps (HFS_EMIT_DB_TYPES_STALE otherwise). Unreadable history or failed generation throws HFS_EMIT_DB_TYPES_FAILED.
- */
-import { createHash } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-import { parse as parseToml } from 'smol-toml';
-import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
-
-/** The repository-relative path of the generated types (the path of slot `app.supabase.types`). */
-export const dbTypesPath = 'supabase/types/database.types.ts';
-
-/** The folder of the app's migrations, and the first line of the committed types: the digest of the migrations they were generated from. */
-const MIGRATIONS_DIR = 'supabase/migrations';
-const TYPES_STAMP = '// migrations-sha256: ';
-
-/**
- * The sha256 of the app's migrations, hex: every `supabase/migrations/*.sql` by name, each as name, NUL, its text with LF line ends,
- * NUL. The offline codegen hook of a lite app (templates/app/codegen-lite) computes the same digest and refuses types stamped with another.
- */
-function migrationsDigest(root) {
-  const dir = path.join(root, MIGRATIONS_DIR);
-  const hash = createHash('sha256');
-  for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql')).sort()) {
-    hash.update(`${name}\0${fs.readFileSync(path.join(dir, name), 'utf8').replace(/\r\n/g, '\n')}\0`);
-  }
-  return hash.digest('hex');
-}
-
-/** The slot that owns the generated types; enabled by a connection declaring provider supabase. */
-const DB_TYPES_SLOT = 'app.supabase.types';
-
-/** The config file whose [api] schemas narrow the generation. */
-const CONFIG_FILE = 'supabase/config.toml';
-const SUPABASE_CLI = 'supabase';
-
-/** A types emit refuses unreadable history or failed generation with HFS_EMIT_DB_TYPES_FAILED, and unequal applied versions with HFS_EMIT_DB_TYPES_STALE. */
-class DbTypesError extends Error {
-  constructor(message, details = {}, code = 'HFS_EMIT_DB_TYPES_FAILED') {
-    super(`${code}: ${message}`);
-    this.name = 'DbTypesError';
-    this.code = code;
-    this.details = details;
-  }
-}
-
-const spawn = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024, ...options });
-
-/**
- * The one spawn: an argument array, a hidden window, a bound buffer, never a shell. Specs inject a fake of the same shape. The
- * `supabase` binary is the one on PATH; a machine without it runs the CLI at the canon pin through npx (the pin of knowledge/hfs/canon-pins.yaml).
- */
-const withNpxFallback = (run, platform) => (file, args, options = {}) => {
-  const first = run(file, args, options);
-  if (file !== SUPABASE_CLI || first.error?.code !== 'ENOENT') return first;
-  const version = bundledPins()[SUPABASE_CLI]?.version;
-  if (!version) return first;
-  return platform === 'win32'
-    ? run('cmd.exe', ['/d', '/s', '/c', 'npx', '--yes', `${SUPABASE_CLI}@${version}`, ...args], options)
-    : run('npx', ['--yes', `${SUPABASE_CLI}@${version}`, ...args], options);
-};
-
-/** The first meaningful line of a failure output, for the error a human acts on. */
-const firstLine = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
-
-const START_TAIL_LINES = 12;
-const START_LINE_CHARS = 300;
-/** The last lines (bounded) of a failed `supabase start`: its cause (42501 permission denied to alter role) sits after the first progress lines, so the first line alone hid it. */
-const startDetail = (started) => {
-  const text = [started?.stderr, started?.stdout, started?.error?.message ?? started?.error].map((part) => String(part ?? '')).find((part) => part.trim()) ?? '';
-  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => (line.length > START_LINE_CHARS ? `${line.slice(0, START_LINE_CHARS)}...` : line));
-  return lines.length ? lines.slice(-START_TAIL_LINES).join(' | ') : 'no output';
-};
-
-/**
- * The schemas `supabase/config.toml` exposes under [api] (`[]` when the file or the list is absent - the CLI then reads its
- * own defaults). A config that does not parse is a refusal: L08 reads the same file and the emit must not guess.
- */
-function apiSchemas(root) {
-  const file = path.join(root, CONFIG_FILE);
-  if (!fs.existsSync(file)) return [];
-  let toml;
-  try { toml = parseToml(fs.readFileSync(file, 'utf8')); } catch (error) {
-    throw new DbTypesError(`${CONFIG_FILE} is not readable valid TOML (${firstLine(error?.message ?? error) ?? 'unreadable'}); the types scope comes from its [api] schemas`, { file: CONFIG_FILE });
-  }
-  return (toml?.api?.schemas ?? []).filter((schema) => typeof schema === 'string');
-}
-
-/** CLI JSON and table rows use the remote field for the database history even with --local; local only describes files. */
-function historyVersion(value) {
-  if (value == null || value === '') return null;
-  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
-    throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
-  }
-  return value;
-}
-
-/** JSON must explicitly carry a migrations array; an empty array proves an empty database history. */
-function jsonAppliedVersions(text) {
-  let history;
-  try { history = JSON.parse(text); } catch {
-    throw new DbTypesError('the local migration history contains unreadable JSON', { file: dbTypesPath });
-  }
-  if (!Array.isArray(history?.migrations)) {
-    throw new DbTypesError('the local migration history has no migrations array', { file: dbTypesPath });
-  }
-  const versions = new Set();
-  for (const row of history.migrations) {
-    if (!row || !Object.hasOwn(row, 'local') || !Object.hasOwn(row, 'remote')) {
-      throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
-    }
-    historyVersion(row.local);
-    const applied = historyVersion(row.remote);
-    if (applied) versions.add(applied);
-  }
-  return versions;
-}
-
-/** Optional outer borders do not add columns; pretty output may wrap each table cell in Markdown backticks. */
-const historyCells = (line, bordered) => {
-  const row = bordered ? line.trim().replace(/^\|/, '').replace(/\|$/, '') : line;
-  return row.split('|').map((cell) => cell.trim().replace(/^`(.*)`$/, '$1'));
-};
-
-/** A recognized header, including a header without rows, proves a table history; malformed rows still refuse. */
-function tableAppliedVersions(lines, header) {
-  const versions = new Set();
-  const bordered = /^\s*\|/.test(lines[header]);
-  const width = historyCells(lines[header], bordered).length;
-  for (const line of lines.slice(header + 1)) {
-    if (/^[\s|+-]+$/.test(line)) continue;
-    if (!line.includes('|')) continue;
-    const cells = historyCells(line, bordered);
-    if (cells.length !== width) {
-      throw new DbTypesError('the local migration history contains an unreadable row', { file: dbTypesPath });
-    }
-    historyVersion(cells[0]);
-    const applied = historyVersion(cells[1]);
-    if (applied) versions.add(applied);
-  }
-  return versions;
-}
-
-/** Read either CLI stream, stripping terminal colors, and require an explicit JSON history or Local | Remote [| Time] header. */
-function appliedVersions(result) {
-  for (const output of [result.stdout, result.stderr]) {
-    const text = String(output ?? '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replaceAll('\u2502', '|').trim();
-    const lines = text.split(/\r?\n/);
-    const json = lines.findIndex((line) => line.trimStart().startsWith('{'));
-    if (json >= 0) return jsonAppliedVersions(lines.slice(json).join('\n'));
-    const header = lines.findIndex((line) => /^\s*\|?\s*Local\s*\|\s*Remote\s*(?:\|\s*Time(?:\s*\(UTC\))?\s*)?\|?\s*$/i.test(line));
-    if (header >= 0) return tableAppliedVersions(lines, header);
-  }
-  throw new DbTypesError('the local migration history is unreadable; expected migrations JSON or the Local | Remote migration list', { file: dbTypesPath });
-}
-
-/** Every applied local version must equal a migration filename stamp, including gaps and extra versions even when the heads match. */
-function requireCurrentDatabase(root, run) {
-  const dir = path.join(root, MIGRATIONS_DIR);
-  const expected = new Set();
-  for (const name of (fs.existsSync(dir) ? fs.readdirSync(dir) : []).filter((file) => file.endsWith('.sql'))) {
-    const stamp = /^(\d+)(?:_|\.sql$)/.exec(name)?.[1];
-    if (!stamp) throw new DbTypesError(`${MIGRATIONS_DIR} contains a SQL file without a migration version`, { file: dbTypesPath });
-    expected.add(stamp);
-  }
-  let result;
-  try { result = run(SUPABASE_CLI, ['migration', 'list', '--local'], { cwd: root }); } catch {
-    throw new DbTypesError('supabase migration list --local could not run; the local migration history must be readable before emitting types', { file: dbTypesPath });
-  }
-  if (result?.error || result?.signal || result?.status !== 0) {
-    throw new DbTypesError('supabase migration list --local failed; the local migration history must be readable before emitting types', { file: dbTypesPath });
-  }
-  const applied = appliedVersions(result);
-  if (applied.size !== expected.size || [...expected].some((version) => !applied.has(version))) {
-    const head = (versions) => [...versions].sort().at(-1) ?? 'none';
-    throw new DbTypesError(`the local database is at ${head(applied)}, the migrations folder at ${head(expected)}; inspect "starci app db plan --local", preview "starci app db migrate --local", apply the reviewed local plan with --execute and STARCI_DB_ARMED=1, then run "starci app emit"`, { file: dbTypesPath }, 'HFS_EMIT_DB_TYPES_STALE');
-  }
-}
-
-/**
- * The freshly generated text of `dbTypesPath` for the app at `root`: `supabase gen types typescript --local` (the running
- * local stack), narrowed to the [api] schemas of supabase/config.toml. A failing CLI, a spawn error and an empty answer all
- * raise DbTypesError; the first stderr line names the cause.
- */
-function emitDbTypesWithRunner({ root, run }) {
-  const schemas = apiSchemas(root);
-  requireCurrentDatabase(root, run);
-  const args = ['gen', 'types', 'typescript', '--local', ...(schemas.length ? ['--schema', schemas.join(',')] : [])];
-  const command = `${SUPABASE_CLI} ${args.join(' ')}`;
-  let result;
-  try {
-    result = run(SUPABASE_CLI, args, { cwd: root });
-  } catch (error) {
-    throw new DbTypesError(`\`${command}\` could not run: ${firstLine(error?.message ?? error) ?? 'unknown failure'}; the local Supabase stack must be up (supabase start)`, { file: dbTypesPath });
-  }
-  const stdout = String(result?.stdout ?? '');
-  const stderr = String(result?.stderr ?? '');
-  if (result?.error || result?.status !== 0 || !stdout.trim()) {
-    const cause = firstLine(stderr) ?? firstLine(result?.error?.message ?? result?.error) ?? 'no output';
-    throw new DbTypesError(`\`${command}\` failed${result?.status !== undefined && result?.status !== null ? ` (exit ${result.status})` : ''}: ${cause}; the local Supabase stack must be up (supabase start)`, { file: dbTypesPath, stderr });
-  }
-  // The CLI pads blank lines with spaces; the committed file carries none (git diff --check refuses trailing whitespace).
-  return `${TYPES_STAMP}${migrationsDigest(root)}\n${stdout.replace(/[ \t]+$/gm, '')}`;
-}
-
-export function emitDbTypes({ root, run = spawn, platform = process.platform } = {}) {
-  return emitDbTypesWithRunner({ root, run: withNpxFallback(run, platform) });
-}
-
-/**
- * The types of an app that has no stack yet (a fresh scaffold): start the app's own local stack (its project id and ports from
- * supabase/config.toml; every migration of supabase/migrations is applied on start), emit the types, and stop the stack again when
- * this call started it. The slow, Docker-reaching path `starci app scaffold --edition lite` takes; `emitDbTypes` alone is the fast one for a stack that is up.
- */
-export function generateDbTypes({ root, run = spawn, platform = process.platform } = {}) {
-  const execute = withNpxFallback(run, platform);
-  const started = execute(SUPABASE_CLI, ['start', '-x', 'studio,mailpit,logflare,vector,edge-runtime,imgproxy,supavisor'], { cwd: root });
-  const already = /already (?:running|started)/i.test(`${started?.stderr ?? ''}${started?.stdout ?? ''}`);
-  if (started?.error || (started?.status !== 0 && !already)) {
-    throw new DbTypesError(`\`${SUPABASE_CLI} start\` failed${started?.status != null ? ` (exit ${started.status})` : ''}: ${startDetail(started)} (the last ${START_TAIL_LINES} output lines at most; with no cause among them, Docker must be running)`, { file: dbTypesPath });
-  }
-  try {
-    return emitDbTypesWithRunner({ root, run: execute });
-  } finally {
-    if (!already) execute(SUPABASE_CLI, ['stop', '--no-backup'], { cwd: root });
-  }
-}
-
-/**
- * Writes `emitDbTypes` to `<root>/<dbTypesPath>`, creating `supabase/types/` when needed. Answers `{ path, changed }`:
- * `changed` is false when the committed text already equals the generated one, so a re-run is a no-op on disk.
- */
-export function writeDbTypes({ root, run } = {}) {
-  const text = emitDbTypes({ root, run });
-  const target = path.join(root, dbTypesPath);
-  const committed = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
-  const changed = committed !== text;
-  if (changed) {
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, text);
-  }
-  return { path: dbTypesPath, changed };
-}
-
-/**
- * Whether the slot `app.supabase.types` is enabled for the app `resolver` views (a connection of the app declares
- * provider: supabase). Read through the slot view, never through a path check: a side-scope resolver holds no app slots
- * and answers false, exactly like an app without a supabase connection.
- */
-export function appHasDbTypes(resolver) {
-  const slot = typeof resolver?.slot === 'function' ? resolver.slot(DB_TYPES_SLOT) : null;
-  return slot != null && typeof resolver?.slotEnabled === 'function' && resolver.slotEnabled(slot) === true;
-}
-
-/**
- * The `emitTypes` callback checkDatabase (L09 DB_TYPES_DRIFT) expects: `({repoRoot, declaration}) -> text`, `repoRoot`
- * being the app root under check; the bound `root` is the fallback for a caller that already knows it. The declared
- * `supabase` block plays no part: the schemas come from supabase/config.toml on disk.
- */
-export const dbTypesEmitter = ({ root = null, run } = {}) => async ({ repoRoot } = {}) => emitDbTypes({ root: repoRoot ?? root, run });

package/runtime/scripts/api/supabase/database-dump.mjs

@@ -1,5 +0,0 @@
-// database-dump.mjs - schema dump for an app's local or linked Supabase database.
-import { supabaseCall } from './lib.mjs';
-
-/** The spawn result of supabase db dump; arguments and runner options remain with the caller. */
-export function databaseDump(...args) { return supabaseCall(['db', 'dump'], ...args); }

package/runtime/scripts/api/supabase/database-push.mjs

@@ -1,5 +0,0 @@
-// database-push.mjs - pending SQL migration push for an app's selected Supabase database.
-import { supabaseCall } from './lib.mjs';
-
-/** The spawn result of supabase db push; target, preview and runner options remain with the owning caller. */
-export function databasePush(...args) { return supabaseCall(['db', 'push'], ...args); }

package/runtime/scripts/api/supabase/database-query.mjs

@@ -1,5 +0,0 @@
-// database-query.mjs - database query for an app's local or linked Supabase database.
-import { supabaseCall } from './lib.mjs';
-
-/** The spawn result of supabase db query; arguments and runner options remain with the caller. */
-export function databaseQuery(...args) { return supabaseCall(['db', 'query'], ...args); }