@starci/hfs 4.2.17 → 4.4.0

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

@@ -0,0 +1,70 @@
+// starci app check --coverage-from <lcov>: the optional, read-only coverage proof and its declared boundary (R273).
+import path from 'node:path';
+import { invocationDir } from '../lib/roots.mjs';
+import { isMain } from '../lib/is-main.mjs';
+import { gitOutputOf } from '../lib/git.mjs';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import { loadSlotManifest, readRepoDeclaration } from './slots.mjs';
+import { coverageBelowReport } from './rules/coverage-below.mjs';
+
+/** Report for the coordinator's dispatcher; supply its findings as checkRepository's extraFindings. */
+export function coverageFrom({ repoRoot = invocationDir(), coverageFrom: reportPath, files, repo, manifest = loadSlotManifest(), lcov } = {}) {
+  const declaration = repo ?? readRepoDeclaration(manifest, repoRoot);
+  if (!['app', 'be'].includes(declaration.profile)) throw new Error('coverage proof requires an app root or its be side');
+  const tracked = files ?? gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files').split('\0').filter(Boolean);
+  return coverageBelowReport({ repoRoot, files: tracked, repo: declaration, manifest, coverageFrom: reportPath, lcov });
+}
+
+function setValueOption(opts, flag, value) {
+  const key = flag === '--cwd' ? 'cwd' : 'coverageFrom';
+  if (value === undefined || !value || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+  if (Object.hasOwn(opts, key)) throw new Error(`${flag} may be given only once`);
+  opts[key] = value;
+}
+
+function parse(argv) {
+  const opts = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const [flag, inline] = argv[index].split(/=(.*)/su);
+    if (flag === '--json' && inline === undefined) opts.json = true;
+    else if (['--coverage-from', '--cwd'].includes(flag)) {
+      const value = inline ?? argv[++index];
+      setValueOption(opts, flag, value);
+    } else throw new Error(`unknown argument ${argv[index]}`);
+  }
+  if (!opts.coverageFrom) throw new Error('usage: starci app check --coverage-from <lcov> [--cwd <app>] [--json]');
+  return opts;
+}
+
+/** Human-readable measured scope, excluded scope and every unmeasured source file; suitable for normal check output. */
+export function formatCoverageReport(report) {
+  const roles = report.scope?.roles ?? [];
+  const rolePattern = roles.length === 1 ? roles[0] : '{' + roles.join(',') + '}';
+  const lines = [
+    `coverage: ${report.ok ? 'passed' : 'refused'} (${report.measured.length} measured logic files; lines/functions/branches at 100% per file)`,
+    'statement coverage is enforced by the unit runner; lcov does not carry statement counts',
+    'measured scope:',
+    ...(report.scope?.roots ?? []).map((root) => `  ${report.prefix ?? ''}${root}**/*.${rolePattern}.ts`),
+    'unmeasured scope:',
+    ...report.unmeasuredScopes.map((entry) => `  ${entry}${entry.endsWith('/') ? '**' : ''}`),
+    'unmeasured source files:',
+    ...(report.unmeasured.length ? report.unmeasured.map((file) => `  ${file}`) : ['  (none)']),
+    ...report.findings.map((finding) => `${finding.code} ${finding.path}: ${finding.message}`),
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
+export function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
+  try {
+    const opts = parse(argv);
+    const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });
+    stdout(opts.json ? `${JSON.stringify(report, null, 2)}\n` : formatCoverageReport(report));
+    return report.ok ? 0 : 2;
+  } catch (error) {
+    stderr(`starci app check --coverage-from: ${String(error.code ?? error.message).split('\n')[0]}\n`);
+    return 2;
+  }
+}
+
+if (isMain(import.meta.url)) process.exitCode = coverageFromMain(process.argv.slice(2));

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

@@ -0,0 +1,276 @@
+// app db baseline: schema-only dump, explicit cutover and repair commands; preview writes nothing.
+import fs from 'node:fs';
+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 { migrationStamp, isMigrationName, databaseSqlTokens, databaseExecutableTokens } from './rules/database-migrations.mjs';
+import { baselineMarkers, baselineSourceFindings } from './rules/database-baseline.mjs';
+import { databaseQueueDeclarations } from './rules/database-queues.mjs';
+import { MIGRATIONS_DIR, MIGRATIONS_ARCHIVE_DIR } from './rules/database-constants.mjs';
+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) {
+  const opts = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    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 (inline !== undefined && !['true', 'false'].includes(inline)) throw new DbVerbError(`${flag} expects true or false`);
+      opts[name] = inline !== 'false';
+    } else {
+      const value = inline ?? argv[++index];
+      if (!value || value.startsWith('--')) throw new DbVerbError(`${flag} requires a value`);
+      opts[name] = value;
+    }
+  }
+  return opts;
+}
+
+export function dbAppRoot(cwd, opts) {
+  const root = path.resolve(cwd, opts.cwd ?? '.');
+  let declaration;
+  try { declaration = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8')); } catch { throw new DbVerbError('run at an app root containing hfs.json'); }
+  if (declaration.kind !== 'app' || !['lite', 'full'].includes(declaration.edition ?? 'full')) throw new DbVerbError('database verbs require a lite or full app');
+  return root;
+}
+
+/** Immediate SQL files only, never secrets or Supabase's temporary credential files. */
+export function dbSqlFiles(root, directory = MIGRATIONS_DIR) {
+  const dir = path.join(root, directory);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith('.sql')).map((entry) => {
+    const match = /^(\d{14})_/.exec(entry.name);
+    if (!isMigrationName(entry.name) || !match || migrationStamp(match[1]) === null) throw new DbVerbError('migration filenames must carry valid UTC stamps');
+    return { file: `${directory}/${entry.name}`, name: entry.name, stamp: match[1] };
+  }).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 };
+
+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);
+}
+
+export function runDbSupabase(root, args, ports = {}) {
+  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');
+  return String(result.stdout ?? '');
+}
+
+export const repairArgs = (stamp, status, local) => ['migration', 'repair', stamp, '--status', status, local ? '--local' : '--linked'];
+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) {
+  const active = dbSqlFiles(root);
+  if (!active.length) throw new DbVerbError('baseline requires an existing active migration chain');
+  const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
+  const oldStamps = [...active, ...archived].map((entry) => entry.stamp);
+  const last = oldStamps.sort((left, right) => left.localeCompare(right)).at(-1);
+  const stamp = opts.stamp ?? now().toISOString().replace(/\D/g, '').slice(0, 14);
+  if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= last) throw new DbVerbError('--stamp must be a valid UTC version after the archive boundary');
+  const file = `${MIGRATIONS_DIR}/${stamp}_baseline.sql`;
+  if (fs.existsSync(path.join(root, file)) || active.some((entry) => fs.existsSync(path.join(root, MIGRATIONS_ARCHIVE_DIR, entry.name)))) throw new DbVerbError('baseline would overwrite an existing migration');
+  return { active, last, stamp, file };
+}
+
+const EXCLUDED_SCHEMAS = new Set(['information_schema', '_analytics', '_realtime', '_supavisor', 'auth', 'etl', 'extensions', 'pgbouncer', 'realtime', 'storage', 'supabase_functions', 'supabase_migrations', 'cron', 'dbdev', 'graphql', 'graphql_public', 'net', 'pgmq', 'pgmq_public', 'pgsodium', 'pgsodium_masks', 'pgtle', 'repack', 'tiger', 'tiger_data', 'topology', 'vault']);
+const ROLE_OPTIONS = new Set(['canlogin', 'inherit', 'superuser', 'createdb', 'createrole', 'isreplication', 'bypassrls', 'connectionlimit']);
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+const excludedSchema = (name) => EXCLUDED_SCHEMAS.has(name) || /^(?:pg_|timescaledb_|_timescaledb_)/.test(name ?? '');
+
+/** Inventory source paths only; no credential, generated or vendor tree is traversed. */
+function baselineFiles(root) {
+  const files = [];
+  const visit = (directory) => {
+    const full = path.join(root, directory);
+    if (!fs.existsSync(full)) return;
+    for (const entry of fs.readdirSync(full, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const file = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) visit(file);
+      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);
+  return files;
+}
+
+const parsed = sqlParser(pg, () => { throw new DbVerbError('migration SQL could not be prepared safely for a baseline'); });
+
+function statementSql(text, entry) {
+  const bytes = Buffer.from(text);
+  const start = entry.stmt_location ?? 0;
+  const statement = bytes.subarray(start, entry.stmt_len ? start + entry.stmt_len : bytes.length).toString('utf8');
+  return `${statement.slice(databaseSqlTokens(statement)[0]?.index ?? 0).trim().replace(/;\s*$/, '')};\n`;
+}
+
+function ownedSchemas(node) {
+  const schemas = [node.relation?.schemaname, node.table?.schemaname, node.schemaname, node.newschema];
+  for (const field of ['funcname', 'typeName', 'typename', 'type', 'object', 'domainname', 'collname', 'opfamilyname', 'opclassname']) {
+    const parts = names(Array.isArray(node[field]) ? node[field] : node[field]?.names ?? node[field]?.List?.items);
+    if (parts.length > 1) schemas.push(parts[0]);
+  }
+  for (const object of node.objects ?? []) {
+    const parts = names(object.List?.items ?? object.ObjectWithArgs?.objname);
+    schemas.push(object.RangeVar?.schemaname);
+    if (parts.length > 1 || /^OBJECT_SCHEMA$/.test(node.objtype ?? node.removeType ?? '')) schemas.push(parts[0]);
+  }
+  return schemas;
+}
+
+function excludedOwnership(stmt) {
+  if (ownedSchemas(stmt).some(excludedSchema)) return true;
+  let unsupported = false;
+  walk(stmt, (node) => {
+    if (node.DefElem?.defname === 'schemas' && names(node.DefElem.arg?.List?.items).some(excludedSchema)) unsupported = true;
+    if (node.FuncCall && names(node.FuncCall.funcname)[0] === 'vault') unsupported = true;
+  });
+  if (stmt.name === 'search_path') unsupported ||= (stmt.args ?? []).some((node) => excludedSchema(node.A_Const?.sval?.sval));
+  return unsupported;
+}
+
+function dataMutation(stmt) {
+  if (stmt.CreateFunctionStmt || stmt.CreateTrigStmt || stmt.CreatePolicyStmt || stmt.AlterPolicyStmt || stmt.CreateStmt || stmt.ViewStmt) return false;
+  let mutation = false;
+  walk(stmt, (node) => { if (['InsertStmt', 'UpdateStmt', 'DeleteStmt', 'MergeStmt', 'CopyStmt', 'TruncateStmt', 'IntoClause'].some((key) => node[key])) mutation = true; });
+  return mutation;
+}
+
+function unsupportedCall(call) {
+  const name = names(call.funcname).join('.');
+  const args = (call.args ?? []).map((arg) => arg.NamedArgExpr?.arg ?? arg);
+  if (name === 'pgmq.create' || name === 'pgmq.drop_queue') return args.length !== 1 || !args[0]?.A_Const?.sval;
+  if (name === 'cron.schedule' || name === 'cron.unschedule') return false;
+  if (name === 'pg_catalog.set_config') return args[0]?.A_Const?.sval?.sval !== 'search_path' || args[1]?.A_Const?.sval?.sval !== '';
+  return true;
+}
+
+function sourceExecution(stmt) {
+  if (stmt.CallStmt) return true;
+  if (!stmt.SelectStmt) return false;
+  let unsupported = false;
+  walk(stmt, (node) => { if (node.FuncCall && unsupportedCall(node.FuncCall)) unsupported = true; });
+  return unsupported;
+}
+
+function unsupportedDo(node) {
+  const body = (node.args ?? []).find((item) => item.DefElem?.defname === 'as')?.DefElem?.arg?.String?.sval ?? '';
+  const tokens = databaseExecutableTokens(body);
+  const unsupported = tokens.some((token, index) => {
+    const next = tokens[index + 1]?.v;
+    return (token.t === 'word' && ['execute', 'role', 'user', 'extension', 'insert', 'update', 'delete', 'merge', 'copy', 'truncate'].includes(token.v))
+      || (excludedSchema(token.v) && next === '.' && !['pgmq', 'cron'].includes(token.v));
+  });
+  if (unsupported) return true;
+  let tree;
+  try { tree = pg.parsePlPgSQLSync(`do ${literal(body)};`); } catch { return true; }
+  let effects = false;
+  walk(tree, (item) => {
+    if (item.PLpgSQL_expr?.parseMode !== 0) return;
+    const sql = parsed(item.PLpgSQL_expr.query);
+    if ((sql.stmts ?? []).some((entry) => dataMutation(entry.stmt) || sourceExecution(entry.stmt))) effects = true;
+  });
+  return effects;
+}
+
+function roleDeclaration(stmt, sql, roles) {
+  const create = stmt.CreateRoleStmt;
+  const alter = stmt.AlterRoleStmt;
+  const setting = stmt.AlterRoleSetStmt;
+  const declaration = create ?? alter ?? setting;
+  if (!declaration) return false;
+  const name = create?.role ?? declaration.role?.rolename;
+  if (!name || name.startsWith('pg_') || (declaration.options ?? []).some((option) => !ROLE_OPTIONS.has(option.DefElem?.defname))) throw new DbVerbError('baseline role declarations require static non-secret role attributes');
+  if (setting && setting.setstmt?.name !== 'search_path') throw new DbVerbError('baseline supports only non-secret search_path role settings');
+  if (create) roles.set(name, [sql]);
+  else {
+    if (!roles.has(name)) throw new DbVerbError('baseline cannot reconstruct alterations to a role it does not declare');
+    roles.get(name).push(sql);
+  }
+  return true;
+}
+
+function extensionDeclaration(stmt, sql, extensions) {
+  if (stmt.CreateExtensionStmt) {
+    extensions.set(stmt.CreateExtensionStmt.extname, sql.replace(/\bcreate\s+extension\s+(?!if\s+not\s+exists\b)/i, 'create extension if not exists '));
+    return true;
+  }
+  if (!/^OBJECT_EXTENSION$/.test(stmt.DropStmt?.removeType ?? '')) return false;
+  for (const object of stmt.DropStmt.objects ?? []) extensions.delete(names(object.List?.items)[0]);
+  return true;
+}
+
+function baselineStatement(state, stmt, sql) {
+  if (roleDeclaration(stmt, sql, state.roles) || extensionDeclaration(stmt, sql, state.extensions)) return;
+  if (stmt.DropRoleStmt) { for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename); return; }
+  if (stmt.GrantRoleStmt || stmt.AlterExtensionStmt || stmt.AlterExtensionContentsStmt || /^OBJECT_ROLE$/.test(stmt.RenameStmt?.renameType ?? '')) throw new DbVerbError('baseline cannot reconstruct role membership, role renames or extension alterations');
+  if (dataMutation(stmt) || sourceExecution(stmt)) throw new DbVerbError('baseline cannot reconstruct migration-owned data changes or custom execution from a schema-only dump');
+  const node = Object.values(stmt)[0];
+  const queueGrant = stmt.GrantStmt && (node.objects ?? []).every((object) => object.RangeVar?.schemaname === 'pgmq');
+  if ((excludedOwnership(node) && !queueGrant) || (stmt.DoStmt && unsupportedDo(node))) throw new DbVerbError('baseline cannot reconstruct application changes to excluded managed schemas or dynamic operational declarations');
+}
+
+function baselineMetadata(root, plan, files) {
+  const queues = databaseQueueDeclarations({ repoRoot: root, files, all: files });
+  if (queues.findings.length) throw new DbVerbError('baseline requires valid migration-owned queues, grants and cron declarations');
+  const state = { roles: new Map(), extensions: new Map() };
+  for (const migration of plan.active) {
+    const text = fs.readFileSync(path.join(root, migration.file), 'utf8');
+    for (const entry of parsed(text).stmts ?? []) baselineStatement(state, entry.stmt, statementSql(text, entry));
+  }
+  return { ...queues, roles: [...state.roles.values()].flat().join(''), extensions: [...state.extensions.values()].join('') };
+}
+
+function metadataSql(metadata) {
+  const queueSql = metadata.queues.map((queue) => `select pgmq.create(${literal(queue)});\n`).join('');
+  const grants = (metadata.grants ?? []).map((grant) => `grant ${grant.privileges.join(', ')} on table ${grant.tables.map((table) => table.split('.').map(identifier).join('.')).join(', ')} to ${grant.roles.map(identifier).join(', ')}${grant.grantOption ? ' with grant option' : ''};\n`).join('');
+  const cron = metadata.cron.map((job) => `select cron.schedule(${literal(job.name)}, ${literal(job.schedule)}, ${literal(job.command)});\n`).join('');
+  return `${queueSql}${grants}${cron}`;
+}
+
+/** 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 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 (!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)];
+    stdout(`${opts.apply ? 'apply' : 'preview'} baseline ${plan.file}; archive ${plan.active.length} migrations\n`);
+    for (const args of repairs) stdout(`supabase ${args.join(' ')}\n`);
+    if (!opts.apply) return 0;
+    for (const args of repairs) runDbSupabase(root, args, ports);
+    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));
+    return 0;
+  } catch (error) { return dbFailure('baseline', error, stderr); }
+}

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

@@ -0,0 +1,254 @@
+// app db plan: compare migration-owned state without fetching commands or Vault values.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+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';
+
+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.
+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;`;
+const INVENTORIES = {
+  migrations: 'select version from supabase_migrations.schema_migrations order by version;',
+  cron: 'select jobname as name, schedule, pg_catalog.md5(command) 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 hash = (command) => createHash('md5').update(command).digest('hex');
+const OWNERSHIP_CALLS = new Set(['pgmq.create', 'pgmq.drop_queue', 'cron.schedule', 'cron.unschedule', 'cron.schedule_in_database', 'cron.alter_job']);
+
+const parseSql = sqlParser(pg, () => { throw new DbVerbError('migration SQL could not be inventoried safely'); });
+
+function requiredLiteral(call, index, aliases) {
+  const value = literal(argument(call, index, aliases));
+  if (value === null || value.length === 0) throw new DbVerbError('queue and cron ownership requires literal migration declarations');
+  return value;
+}
+
+function inventoryCall(state, call) {
+  const name = names(call.funcname);
+  if (name === 'pgmq.create') {
+    state.queues.set(requiredLiteral(call, 0, ['queue_name']), null);
+  } else if (name === 'pgmq.drop_queue') {
+    state.queues.delete(requiredLiteral(call, 0, ['queue_name']));
+  } else if (name === 'cron.schedule') {
+    const job = requiredLiteral(call, 0, ['job_name']);
+    const schedule = requiredLiteral(call, 1, ['schedule']);
+    const command = requiredLiteral(call, 2, ['command']);
+    state.cron.set(job, { schedule, commandHash: hash(command), active: true });
+  } else if (name === 'cron.unschedule') {
+    state.cron.delete(requiredLiteral(call, 0, ['job_name']));
+  } else if (name === 'cron.schedule_in_database' || name === 'cron.alter_job') {
+    throw new DbVerbError('database plan requires cron.schedule and named cron.unschedule ownership');
+  }
+}
+
+function ownershipCalls(tree) {
+  const calls = [];
+  walk(tree, (node) => { if (node.FuncCall && OWNERSHIP_CALLS.has(names(node.FuncCall.funcname))) calls.push(node.FuncCall); });
+  return calls;
+}
+
+function flatDeclaration(tree, call) {
+  const node = tree.SelectStmt ?? (tree.stmts?.length === 1 && tree.stmts[0].stmt.SelectStmt);
+  const constrained = ['fromClause', 'withClause', 'whereClause', 'intoClause', 'limitCount', 'limitOffset', 'groupClause', 'havingClause', 'distinctClause', 'windowClause'];
+  return node && /^SETOP_NONE$/.test(node.op) && node.targetList?.length === 1
+    && !constrained.some((key) => node[key]) && node.targetList[0].ResTarget?.val?.FuncCall === call;
+}
+
+function inventoryTree(state, tree) {
+  const calls = ownershipCalls(tree);
+  if (!calls.length) return;
+  if (calls.length !== 1 || !flatDeclaration(tree, calls[0])) throw new DbVerbError('database ownership requires one unconditional migration SELECT per declaration');
+  inventoryCall(state, calls[0]);
+}
+
+function conditionalBlock(item) {
+  if (item.PLpgSQL_stmt_block?.exceptions) return true;
+  return Object.keys(item).some((key) => key.startsWith('PLpgSQL_stmt_')
+    && !['PLpgSQL_stmt_block', 'PLpgSQL_stmt_perform', 'PLpgSQL_stmt_execsql'].includes(key)
+    && !(key === 'PLpgSQL_stmt_return' && item[key].lineno === undefined));
+}
+
+function inventoryDo(state, node) {
+  const option = (key) => (node.args ?? []).find((item) => item.DefElem?.defname === key)?.DefElem?.arg?.String?.sval;
+  if (option('language') && option('language') !== 'plpgsql') throw new DbVerbError('database plan requires statically readable migration blocks');
+  const body = option('as') ?? '';
+  let delimiter = '$starci_plan$';
+  while (body.includes(delimiter)) delimiter = `${delimiter.slice(0, -1)}_$`;
+  let tree;
+  try { tree = pg.parsePlPgSQLSync(`create function starci_plan_probe() returns void language plpgsql as ${delimiter}${body}${delimiter};`); }
+  catch { throw new DbVerbError('migration block could not be inventoried safely'); }
+  const statements = [];
+  let conditional = false;
+  walk(tree, (item) => {
+    conditional ||= conditionalBlock(item);
+    if (item.PLpgSQL_stmt_dynexecute) throw new DbVerbError('dynamic migration blocks cannot prove database inventory');
+    if (item.PLpgSQL_expr?.parseMode === 0) statements.push(parseSql(item.PLpgSQL_expr.query));
+  });
+  if (conditional && statements.some((statement) => ownershipCalls(statement).length)) throw new DbVerbError('conditional migration blocks cannot prove database inventory');
+  for (const statement of statements) inventoryTree(state, statement);
+}
+
+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) };
+  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'));
+    for (const statement of tree.stmts ?? []) {
+      // Creating a function does not execute its body. Inert SQL strings never declare remote state.
+      if (statement.stmt.CreateFunctionStmt) continue;
+      if (statement.stmt.DoStmt) inventoryDo(state, statement.stmt.DoStmt);
+      else inventoryTree(state, statement.stmt);
+    }
+  }
+  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);
+  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');
+  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');
+  const state = {};
+  for (const [key, sql] of Object.entries(INVENTORIES)) state[key] = rows[0][key] ? queryRows(root, sql, local, ports) : [];
+  return state;
+}
+
+function compare(expected, actual, kind) {
+  const unmatched = new Set(expected.keys());
+  let unexpected = 0;
+  let changed = 0;
+  for (const row of actual) {
+    const key = kind === 'migrations' ? row.version : row.name;
+    if (key !== null && (typeof key !== 'string' || key.length === 0)) throw new DbVerbError('Supabase returned an invalid inventory identifier');
+    if (kind === 'cron' && (typeof row.schedule !== 'string' || !/^[a-f0-9]{32}$/.test(row.commandHash ?? '') || typeof row.active !== 'boolean')) throw new DbVerbError('Supabase returned invalid cron metadata');
+    if (!unmatched.delete(key)) unexpected += 1;
+    else if (kind === 'cron') {
+      const desired = expected.get(key);
+      if (desired.schedule !== row.schedule || desired.commandHash !== row.commandHash || desired.active !== row.active) changed += 1;
+    }
+  }
+  return { expected: expected.size, remote: actual.length, missing: unmatched.size, unexpected, changed };
+}
+
+/** 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 root = dbAppRoot(cwd, opts);
+    const expected = repositoryState(root);
+    const actual = remoteState(root, opts.local, 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.
+    if (opts.json) stdout(`${JSON.stringify({ readOnly: true, drift, ...summaries })}\n`);
+    else {
+      stdout(`read-only database plan: ${drift ? 'drift detected' : 'repo and database agree'}\n`);
+      for (const [kind, item] of Object.entries(summaries)) stdout(`${kind}: repo ${item.expected}, remote ${item.remote}, missing ${item.missing}, unexpected ${item.unexpected}, changed ${item.changed}\n`);
+    }
+    return drift ? 1 : 0;
+  } catch (error) { return dbFailure('plan', error, stderr); }
+}