@starci/hfs 4.4.1 → 4.5.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.5.1 - 2026-10-18
+- Fixed: managed CI base refs, public build values, caching and timeouts; optional quality service handling, README formatting and Supabase migration-history parsing.
+
+## 4.5.0 - 2026-10-17
+- Added: consumer-class CI declarations, `app ci` custody verbs and R296-R298; manifest-driven quality files and split cached CI with immutable action pins.
+- Added: release audit/local Sonar and main-CI protection; encrypted outside-repository DB dump and armed linked reset with backup/auth/storage validation.
+- Fixed: DB types refuse stale migration history.
+
 ## 4.4.1 - 2026-10-17
 - Changed: the bundled runtime copies follow the runtime of 1.0.0-alpha.19 (owner ruling no-runtime-specs, 2026-10-17): the failure codes, the slot manifest (`exampleNa`) and the rule catalog (`specNa`, `exampleNa`) carry the removal of the runtime's own specs; package behavior is unchanged. The managed codecov.yml, the CI coverage upload and the hfs sync render stay (Codecov is kept for apps and examples); internal exports that only the deleted runtime specs read are no longer exported.
 

package/ci/cli.mjs

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { readCiDeclaration, sealedKeyNames } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { github, refuse } from './github.mjs';
+import { setSecret } from './secret.mjs';
+import { setVariable, syncVariables } from './vars.mjs';
+import { verifyCi } from './verify.mjs';
+
+const COMMANDS = {
+  'secret set': ['env', 'dependabot', 'repo'],
+  'var set': ['env', 'value', 'repo'],
+  'var sync': ['execute', 'repo'],
+  verify: ['json', 'repo'],
+};
+const BOOLEAN = new Set(['dependabot', 'execute', 'json']);
+
+/** Invalid options never echo argv, because an extra argument may itself contain a secret. */
+function parse(argv) {
+  const command = argv[0] === 'verify' ? 'verify' : argv.slice(0, 2).join(' ');
+  const allowed = COMMANDS[command];
+  if (!allowed) throw refuse('CI_USAGE', 'use secret set, var set, var sync or verify');
+  const positional = [], options = {};
+  for (let i = command === 'verify' ? 1 : 2; i < argv.length; i += 1) {
+    const arg = argv[i], match = /^--([^=]+)(?:=(.*))?$/s.exec(arg);
+    if (!match && !arg.startsWith('-')) { positional.push(arg); continue; }
+    const key = match?.[1];
+    if (!allowed.includes(key) || Object.hasOwn(options, key)) throw refuse(command === 'secret set' ? 'CI_VALUE_ARGV' : 'CI_USAGE', 'unsupported or repeated option');
+    if (BOOLEAN.has(key)) {
+      if (match[2] !== undefined) throw refuse('CI_USAGE', 'boolean flags take no value');
+      options[key] = true;
+    } else {
+      const value = match[2] ?? argv[++i];
+      if (value === undefined || value.startsWith('--') || (key !== 'value' && !value.length)) throw refuse('CI_USAGE', 'an option value is required');
+      options[key] = value;
+    }
+  }
+  const named = command.endsWith(' set');
+  if (positional.length !== (named ? 1 : 0)) throw refuse(command === 'secret set' && positional.length > 1 ? 'CI_VALUE_ARGV' : 'CI_USAGE', 'provide the declared name only for set');
+  if (named && (!/^[A-Z][A-Z0-9_]*$/.test(positional[0]) || positional[0].startsWith('GITHUB_'))) throw refuse('CI_NAME_UNDECLARED', 'a declared uppercase CI name is required');
+  if (options.dependabot && options.env) throw refuse('CI_SCOPE_MISMATCH', 'Dependabot secrets have repository scope');
+  return { command, options, name: positional[0] };
+}
+
+/** Manifest and sealed key reads remain offline; only github.mjs may invoke the GitHub CLI. */
+export async function ciMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), stdin, env = process.env, tools = {} } = {}) {
+  try {
+    const parsed = parse(argv);
+    let declaration, sealed;
+    try {
+      declaration = readCiDeclaration(parseYaml(fs.readFileSync(path.join(cwd, '.starcistacks/application-stacks.yaml'), 'utf8')));
+      sealed = sealedKeyNames(cwd, { fs });
+    } catch { throw refuse('CI_DECLARATION_INVALID', 'the manifest or sealed key names could not be read'); }
+    if (declaration.problems.length) throw refuse('CI_DECLARATION_INVALID', 'correct the CI declaration before using GitHub');
+    const context = { ...parsed, declaration, sealed, gh: github({ cwd, env, spawn: tools.spawn }), stdin, stdout };
+    if (parsed.command === 'secret set') return await setSecret(context);
+    if (parsed.command === 'var set') return setVariable(context);
+    if (parsed.command === 'var sync') return syncVariables(context);
+    return verifyCi(context);
+  } catch (error) {
+    stderr(`${error.code ? error.message : 'CI_USAGE: CI command could not complete'}\n`);
+    return 2;
+  }
+}

package/ci/github.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+
+/** Refusals carry only fixed public diagnostics, never child output or secret input. */
+export function refuse(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+/** All GitHub access uses argument arrays and captured output; secret bodies travel only on stdin. */
+export function github({ cwd, spawn = spawnSync, env = process.env }) {
+  function run(args, input) {
+    let result;
+    try { result = spawn('gh', args, { cwd, env, encoding: 'utf8', shell: false, stdio: ['pipe', 'pipe', 'pipe'], ...(input === undefined ? {} : { input }) }); }
+    catch { throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI could not run; check installation and authentication'); }
+    if (result.error || result.status !== 0) throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI failed; check authentication and repository access');
+    return result.stdout;
+  }
+  function json(args) {
+    try { return JSON.parse(run(args)); }
+    catch (error) {
+      if (error.code) throw error;
+      throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI returned invalid JSON');
+    }
+  }
+  function repository(explicit) {
+    const repo = explicit ?? json(['repo', 'view', '--json', 'nameWithOwner'])?.nameWithOwner;
+    if (typeof repo !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw refuse('CI_GITHUB_UNREADABLE', 'a repository owner/name is required');
+    return repo;
+  }
+  return { run, json, repository };
+}
+
+/** Repository, environment and Dependabot stores are distinct even when their names coincide. */
+export function scopeArgs(options) {
+  return options.dependabot ? ['--app', 'dependabot'] : options.env ? ['--env', options.env] : [];
+}
+
+export function scopeName(options) {
+  return options.dependabot ? 'dependabot' : options.env ? `environment:${options.env}` : 'repository';
+}

package/ci/secret.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+
+/** A declared name must belong to the requested store before a secret body is read. */
+export function declaredEntry(entries, name, options) {
+  const entry = entries.find((item) => item.name === name);
+  if (!entry) throw refuse('CI_NAME_UNDECLARED', 'the name is not declared for this CI class');
+  const environment = entry.scope === 'environment' ? entry.environment : undefined;
+  if (environment !== options.env || (options.dependabot && options.env)) throw refuse('CI_SCOPE_MISMATCH', 'the requested scope differs from the declaration');
+  return entry;
+}
+
+/** Secret input is read once, stripped of one trailing newline, and passed only to the child stdin. */
+export async function setSecret({ declaration, sealed, gh, options, name, stdin, stdout }) {
+  if (sealed.some((item) => item.key === name)) throw refuse('CI_SECRET_SEALED', 'the name belongs to a sealed app secret');
+  declaredEntry(options.dependabot ? declaration.dependabotSecrets : declaration.secrets, name, options);
+  let value;
+  if (stdin === undefined) {
+    if (process.stdin.isTTY) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+    value = fs.readFileSync(0, 'utf8');
+  } else value = typeof stdin === 'function' ? await stdin() : stdin;
+  value = String(value ?? '').replace(/\r?\n$/, '');
+  if (!value.length) throw refuse('CI_VALUE_EMPTY', 'a secret value is required on stdin');
+  const repo = gh.repository(options.repo);
+  gh.run(['secret', 'set', name, ...scopeArgs(options), '--repo', repo], value);
+  stdout(`set secret ${name} (${scopeName(options)})\n`);
+  return 0;
+}

package/ci/vars.mjs

@@ -0,0 +1,33 @@
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+import { declaredEntry } from './secret.mjs';
+
+/** Public CI values may come from argv or the manifest, but two supplied values must agree. */
+function valueOf(entry, supplied) {
+  const declared = entry.value === undefined ? undefined : String(entry.value);
+  if (supplied !== undefined && declared !== undefined && supplied !== declared) throw refuse('CI_VAR_DRIFT', 'the supplied value differs from the manifest');
+  const value = supplied ?? declared;
+  if (value === undefined) throw refuse('CI_VALUE_EMPTY', 'a public variable value is required');
+  return value;
+}
+
+function writeVariable(gh, repo, entry, value, options, stdout) {
+  gh.run(['variable', 'set', entry.name, '--body', value, ...scopeArgs(options), '--repo', repo]);
+  stdout(`set variable ${entry.name} (${scopeName(options)})\n`);
+}
+
+export function setVariable({ declaration, gh, options, name, stdout }) {
+  const entry = declaredEntry(declaration.vars, name, options), value = valueOf(entry, options.value);
+  writeVariable(gh, gh.repository(options.repo), entry, value, options, stdout);
+  return 0;
+}
+
+/** Sync validates the whole plan first and performs no GitHub access until execution is requested. */
+export function syncVariables({ declaration, gh, options, stdout }) {
+  const plan = declaration.vars.map((entry) => ({ entry, value: valueOf(entry), options: { env: entry.scope === 'environment' ? entry.environment : undefined } }));
+  const repo = options.execute && plan.length ? gh.repository(options.repo) : undefined;
+  for (const item of plan) {
+    if (options.execute) writeVariable(gh, repo, item.entry, item.value, item.options, stdout);
+    else stdout(`would set variable ${item.entry.name} (${scopeName(item.options)})\n`);
+  }
+  return 0;
+}

package/ci/verify.mjs

@@ -0,0 +1,36 @@
+import { refuse, scopeArgs, scopeName } from './github.mjs';
+
+/** Verification reports names and scopes only; values are compared in memory and excluded from findings. */
+export function verifyCi({ declaration, sealed, gh, options, stdout }) {
+  const repo = gh.repository(options.repo), stores = [];
+  const environments = [...new Set([...declaration.secrets, ...declaration.vars].filter((item) => item.scope === 'environment').map((item) => item.environment))].sort();
+  for (const scope of [{}, ...environments.map((env) => ({ env })), { dependabot: true }]) {
+    for (const kind of scope.dependabot ? ['secret'] : ['secret', 'variable']) {
+      const rows = gh.json([kind, 'list', '--json', kind === 'secret' ? 'name' : 'name,value', ...scopeArgs(scope), '--repo', repo]);
+      if (!Array.isArray(rows) || rows.some((row) => typeof row?.name !== 'string' || (kind === 'variable' && typeof row.value !== 'string'))) throw refuse('CI_GITHUB_UNREADABLE', 'GitHub CLI returned an invalid name list');
+      stores.push({ scope, kind, rows });
+    }
+  }
+  const findings = [], sealedNames = new Set(sealed.map((item) => item.key));
+  const declarations = (store) => store.scope.dependabot ? declaration.dependabotSecrets : store.kind === 'secret' ? declaration.secrets : declaration.vars;
+  const matches = (entry, scope) => (entry.scope === 'environment' ? entry.environment : undefined) === scope.env;
+  const add = (code, name, scope) => findings.push({ code, name, scope: scopeName(scope) });
+  for (const store of stores) {
+    const entries = declarations(store), actual = new Map(store.rows.map((row) => [row.name, row]));
+    for (const entry of entries.filter((item) => matches(item, store.scope))) {
+      const row = actual.get(entry.name);
+      if (!row && !(store.kind === 'secret' && entry.optional)) add(store.kind === 'secret' ? 'CI_SECRET_MISSING' : 'CI_VAR_MISSING', entry.name, store.scope);
+      else if (row && store.kind === 'variable' && entry.value !== undefined && row.value !== String(entry.value)) add('CI_VAR_DRIFT', entry.name, store.scope);
+    }
+    for (const row of store.rows) {
+      if (store.kind === 'secret' && sealedNames.has(row.name)) add('APP_SECRET_IN_CI', row.name, store.scope);
+      if (entries.some((entry) => entry.name === row.name && matches(entry, store.scope))) continue;
+      const sameKind = store.kind === 'secret' ? [...declaration.secrets, ...declaration.dependabotSecrets] : declaration.vars;
+      add(sameKind.some((entry) => entry.name === row.name) ? 'CI_SCOPE_MISMATCH' : store.kind === 'secret' ? 'CI_SECRET_UNDECLARED' : 'CI_VAR_UNDECLARED', row.name, store.scope);
+    }
+  }
+  if (options.json) stdout(`${JSON.stringify({ ok: findings.length === 0, findings }, null, 2)}\n`);
+  else if (!findings.length) stdout('CI verification passed\n');
+  else for (const finding of findings) stdout(`${finding.code}: ${finding.name} (${finding.scope})\n`);
+  return findings.length ? 1 : 0;
+}

package/db/backup-receipt.mjs

@@ -0,0 +1,129 @@
+// backup-receipt.mjs - encrypted database backup custody, shared by dump and reset; tool output never enters diagnostics.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { readDeclaration } from '../release/index.mjs';
+import { resolveTarget, runCli as migrationCli, targetArgs } from './migrate.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+
+export const RECEIPT_SCHEMA = 'starci/db-backup@1';
+export function sha256(file) {
+  const hash = createHash('sha256');
+  const fd = fs.openSync(file, 'r');
+  const chunk = Buffer.alloc(1024 * 1024);
+  try {
+    let bytes;
+    while ((bytes = fs.readSync(fd, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytes));
+  } finally { fs.closeSync(fd); }
+  return hash.digest('hex');
+}
+const inside = (root, file) => { const rel = path.relative(root, file); return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel)); };
+
+/** Backup/restore SQL can hold row values, so even the migration runner's scrubbed stderr must be withheld. */
+export function runCli(session, args) {
+  try { return migrationCli(session, args); }
+  catch { throw failure('DB_BACKUP_CLI_FAILED', `supabase ${args.slice(0, 2).join(' ')} failed; output withheld`); }
+}
+
+/** Resolves existing ancestors before checking containment, including symlinked output directories and Git worktree marker files. */
+export function outsideRepository(root, output) {
+  let ancestor = path.resolve(output);
+  const tail = [];
+  while (!fs.existsSync(ancestor)) { tail.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
+  const resolved = path.join(fs.realpathSync(ancestor), ...tail);
+  if (inside(fs.realpathSync(root), resolved)) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside the app repository and every Git worktree');
+  for (let dir = resolved; ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git'))) throw refusal('DB_DUMP_INSIDE_REPO', '--out must be outside every Git worktree');
+    if (dir === path.dirname(dir)) break;
+  }
+  return resolved;
+}
+
+/** Uses migrate's linked/password/URL resolution; local is explicitly selected and never silently defaults to linked. */
+export function backupSession(ctx, options) {
+  const database = readDeclaration(ctx.cwd).database ?? {};
+  const selections = [options.linked === true, options.local === true, options.urlEnv !== undefined].filter(Boolean).length;
+  if (selections !== 1) throw refusal('DB_USAGE', 'select exactly one of --linked, --local or --url-env');
+  const target = options.local ? { kind: 'local', ref: null, env: {}, secrets: [], how: 'local database' }
+    : resolveTarget(ctx, { projectRef: null, password: null, ...database }, options);
+  if (target.kind === 'linked' && !/^[a-z0-9]{10,40}$/u.test(target.ref)) throw refusal('DB_NOT_LINKED', 'linked project ref is invalid');
+  const project = path.basename(ctx.cwd).replace(/[^A-Za-z0-9_-]/gu, '-') || 'database';
+  return { ctx, target, database, project };
+}
+
+export const backupArgs = (session) => session.target.kind === 'local' ? ['--local', '--workdir', session.ctx.cwd] : targetArgs(session.target, session.ctx.cwd);
+
+/** Queries via the same injected Supabase runner; malformed output is withheld. */
+export function queryRows(session, sql) {
+  let rows;
+  try { rows = JSON.parse(runCli(session, ['db', 'query', sql, '--output', 'json', '--agent', 'no', ...backupArgs(session)]).stdout); }
+  catch { throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory query failed; output withheld'); }
+  if (!Array.isArray(rows) || rows.some((row) => !row || typeof row !== 'object' || Array.isArray(row))) throw failure('DB_BACKUP_QUERY_FAILED', 'database inventory is not a rows array');
+  return rows;
+}
+
+/** Executes local tar/age through ctx.spawn, the same seam used by the stack's age installer; never relays tool errors containing data. */
+export function backupTool(ctx, command, args, options = {}) {
+  const result = ctx.spawn(command, args, { cwd: ctx.cwd, env: ctx.env, ...options });
+  if (result.error || result.status !== 0) throw failure('DB_BACKUP_TOOL_FAILED', `${command} failed; output withheld`);
+  return result;
+}
+
+/** Reads public recipients only from creation_rules age fields, including nested SOPS key_groups. */
+export function backupRecipients(root) {
+  let rules;
+  try { rules = parseYaml(fs.readFileSync(path.join(root, '.sops.yaml'), 'utf8')).creation_rules; } catch { rules = []; }
+  const found = [];
+  const visit = (value) => {
+    if (!value || typeof value !== 'object') return;
+    for (const [key, item] of Object.entries(value)) {
+      if (key === 'age') found.push(...(JSON.stringify(item).match(/age1[0-9a-z]{50,}/gu) ?? []));
+      else if (typeof item === 'object') visit(item);
+    }
+  };
+  visit(rules);
+  if (!found.length) throw refusal('DB_BACKUP_NO_RECIPIENT', 'no age recipient in .sops.yaml creation_rules');
+  return [...new Set(found)];
+}
+
+/** Header and size checks prove an age envelope exists; proving decryption requires the owner's identity separately. */
+function checkArchive(file) {
+  const size = fs.statSync(file).size;
+  const fd = fs.openSync(file, 'r');
+  const header = Buffer.alloc(22);
+  try { fs.readSync(fd, header, 0, header.length, 0); } finally { fs.closeSync(fd); }
+  if (size < 100 || !header.toString('ascii').startsWith('age-encryption.org/v1\n')) throw failure('DB_BACKUP_ARCHIVE_INVALID', 'encrypted archive has no valid age header or payload');
+  return size;
+}
+
+export function encryptFile(ctx, input, output, recipients) {
+  backupTool(ctx, 'age', [...recipients.flatMap((recipient) => ['-r', recipient]), '-o', output, input]);
+  return checkArchive(output);
+}
+
+/** Validates a complete, recent, full-data receipt and its encrypted bytes before any destructive reset call. */
+export function validateReceipt(session, receiptPath) {
+  if (!receiptPath) throw refusal('DB_RESET_BACKUP_MISSING', '--backup must name an encrypted backup receipt');
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8')); } catch { throw refusal('DB_RESET_BACKUP_INVALID', 'backup receipt is missing or invalid JSON'); }
+  const valid = receipt && receipt.schema === RECEIPT_SCHEMA && receipt.target === 'linked' && receipt.schemaOnly === false
+    && typeof receipt.project === 'string' && typeof receipt.ref === 'string' && typeof receipt.file === 'string'
+    && path.basename(receipt.file) === receipt.file && receipt.file.endsWith('.age') && Number.isSafeInteger(receipt.bytes) && receipt.bytes >= 100
+    && /^[a-f0-9]{64}$/u.test(receipt.sha256 ?? '') && Array.isArray(receipt.parts)
+    && ['roles.sql', 'schema.sql', 'auth-storage-schema.sql', 'data.sql', 'auth-storage-data.sql', 'rowcounts.json'].every((part) => receipt.parts.includes(part))
+    && Number.isSafeInteger(receipt.rowcounts?.tables) && receipt.rowcounts.tables >= 0 && /^\d+$/u.test(receipt.rowcounts?.rows ?? '')
+    && typeof receipt.at === 'string' && Number.isFinite(Date.parse(receipt.at));
+  if (!valid) throw refusal('DB_RESET_BACKUP_INVALID', 'backup receipt is not a full starci/db-backup@1 linked backup');
+  if (receipt.ref !== session.target.ref) throw refusal('DB_RESET_BACKUP_PROJECT', 'backup targets a different project ref');
+  const maxAge = session.database.reset?.backupMaxAgeHours ?? 24;
+  if (!Number.isFinite(maxAge) || maxAge <= 0) throw refusal('DB_CONFIG_INVALID', 'database.reset.backupMaxAgeHours must be positive');
+  const age = session.ctx.now() - Date.parse(receipt.at);
+  if (age < 0 || age > maxAge * 3600000) throw refusal('DB_RESET_BACKUP_STALE', 'backup is future-dated or older than the allowed backup age');
+  const file = path.resolve(path.dirname(receiptPath), receipt.file);
+  if (!fs.existsSync(file)) throw refusal('DB_RESET_BACKUP_ARCHIVE_MISSING', 'backup archive is absent');
+  try {
+    if (checkArchive(file) !== receipt.bytes || sha256(file) !== receipt.sha256) throw new Error('mismatch');
+  } catch { throw refusal('DB_RESET_BACKUP_HASH', 'backup archive size, header or sha256 differs from the receipt'); }
+  return receipt;
+}

package/db/dump.mjs

@@ -0,0 +1,66 @@
+// dump.mjs - full Supabase backup, encrypted outside Git; every plaintext part is removed even when a tool fails.
+import fs from 'node:fs';
+import path from 'node:path';
+import { runVerb } from '../release/index.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+import { RECEIPT_SCHEMA, outsideRepository, backupSession, backupArgs, backupRecipients, backupTool, encryptFile, queryRows, sha256, runCli } from './backup-receipt.mjs';
+
+/** Counts every ordinary table with quoted identifiers in a read-only transaction, including auth and storage. */
+export function rowcounts(session) {
+  const tables = queryRows(session, "select schemaname, tablename from pg_catalog.pg_tables where schemaname not in ('pg_catalog', 'information_schema') order by schemaname, tablename;");
+  const quote = (name) => `"${String(name).replaceAll('"', '""')}"`;
+  return tables.map((table) => {
+    if (typeof table.schemaname !== 'string' || typeof table.tablename !== 'string') throw failure('DB_BACKUP_QUERY_FAILED', 'invalid table inventory');
+    const rows = queryRows(session, `begin read only; select count(*)::text as count from ${quote(table.schemaname)}.${quote(table.tablename)}; commit;`);
+    if (rows.length !== 1 || !/^\d+$/u.test(String(rows[0].count))) throw failure('DB_BACKUP_QUERY_FAILED', 'invalid rowcount');
+    return { schema: table.schemaname, table: table.tablename, count: String(rows[0].count) };
+  });
+}
+
+/** Writes only ciphertext and its receipt permanently; a receipt is published only after header, size and hash checks. */
+function dumpDatabase(ctx, options = {}) {
+  if (!options.out) throw refusal('DB_USAGE', '--out is required');
+  const out = outsideRepository(ctx.cwd, path.resolve(ctx.cwd, options.out));
+  const session = backupSession(ctx, options);
+  const recipients = backupRecipients(ctx.cwd);
+  fs.mkdirSync(out, { recursive: true, mode: 0o700 });
+  const at = new Date(ctx.now()).toISOString();
+  const stamp = at.replace(/[-:.]/gu, '');
+  const name = `${session.project}-${stamp}`;
+  const dir = path.join(out, name);
+  fs.mkdirSync(dir, { mode: 0o700 });
+  const scratch = path.join(dir, '.plaintext');
+  const archive = path.join(dir, `${name}.tar.age`);
+  const receiptPath = path.join(dir, `${name}.receipt.json`);
+  let complete = false;
+  try {
+    fs.mkdirSync(scratch, { mode: 0o700 });
+    const jobs = [['roles.sql', ['--role-only']], ['schema.sql', []], ['auth-storage-schema.sql', ['--schema', 'auth,storage']]];
+    if (!options.schemaOnly) jobs.push(['data.sql', ['--data-only']], ['auth-storage-data.sql', ['--data-only', '--schema', 'auth,storage']]);
+    for (const [file, flags] of jobs) runCli(session, ['db', 'dump', ...flags, '--file', path.join(scratch, file), ...backupArgs(session)]);
+    const counts = rowcounts(session);
+    fs.writeFileSync(path.join(scratch, 'rowcounts.json'), `${JSON.stringify(counts, null, 2)}\n`, { mode: 0o600 });
+    const parts = [...jobs.map(([file]) => file), 'rowcounts.json'];
+    const tar = path.join(scratch, 'backup.tar');
+    backupTool(ctx, 'tar', ['-cf', tar, '-C', scratch, ...parts]);
+    const bytes = encryptFile(ctx, tar, archive, recipients);
+    const receipt = { schema: RECEIPT_SCHEMA, project: session.project, target: session.target.kind, ref: session.target.ref ?? null,
+      at, file: path.basename(archive), bytes, sha256: sha256(archive), parts,
+      rowcounts: { tables: counts.length, rows: counts.reduce((sum, row) => sum + BigInt(row.count), 0n).toString(), tablesByName: counts }, schemaOnly: options.schemaOnly === true };
+    fs.writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
+    complete = true;
+    return { ok: true, lines: [JSON.stringify(receipt, null, 2), `receipt: ${receiptPath}`, 'age header, size and sha256 verified; decryption requires the owner identity'], data: { receipt, receiptPath } };
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    if (!complete) { fs.rmSync(archive, { force: true }); fs.rmSync(receiptPath, { force: true }); }
+  }
+}
+
+export function dbDumpMain(argv, io = {}) {
+  return runVerb({ label: 'starci app db dump', name: 'db dump', code: 'DB_USAGE', io, argv,
+    spec: { boolean: ['--linked', '--local', '--schema-only', '--json'], value: ['--url-env', '--out'] },
+    run: (ctx, flags, positional) => {
+      if (positional.length) throw refusal('DB_USAGE', 'dump takes flags only');
+      return dumpDatabase(ctx, { linked: flags.linked, local: flags.local, urlEnv: flags['url-env'], out: flags.out, schemaOnly: flags['schema-only'] });
+    } });
+}

package/db/migrate.mjs

@@ -43,6 +43,8 @@ const POST_CHECKS = {
 };
 const postOk = (value) => plain(value) && Object.keys(value).every((key) => POST_FIELDS.includes(key) && POST_CHECKS[key](value[key]));
 
+const resetOk = (value) => plain(value) && Object.keys(value).every((key) => key === 'backupMaxAgeHours' && Number.isFinite(value[key]) && value[key] > 0);
+
 const CHECKS = {
   migrationsDir: [dirOk, 'must be a relative directory inside the app'],
   archiveDir: [dirOk, 'must be a relative directory inside the app'],
@@ -53,6 +55,7 @@ const CHECKS = {
   restamp: [listOf(pairOk), 'must be a list of { from, to } fourteen-digit stamps'],
   password: [passwordOk, 'must be { env, member, key } naming a sealed value'],
   postCutover: [postOk, `must use only ${POST_FIELDS.join(', ')} with valid values`],
+  reset: [resetOk, 'must be a mapping with only optional finite positive backupMaxAgeHours'],
 };
 
 /** Judges the `database:` block. Returns { config } or { problems }; `baseline` is the one required field. */
@@ -66,7 +69,7 @@ function normalizeDatabase(block) {
   if (block.baseline === undefined) problems.push('database.baseline: is required');
   if (problems.length > 0) return { problems };
   const config = {
-    migrationsDir: 'supabase/migrations', archiveDir: null, standard: null, heldBack: [], projectRef: null, restamp: [], password: null, postCutover: null, ...block,
+    migrationsDir: 'supabase/migrations', archiveDir: null, standard: null, heldBack: [], projectRef: null, restamp: [], password: null, postCutover: null, reset: null, ...block,
   };
   return { config };
 }

package/db/reset.mjs

@@ -0,0 +1,125 @@
+// 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 });
+    } });
+}