@starci/hfs 4.9.9 → 4.10.0

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/client.ts

@@ -1,18 +1,50 @@
-import { createClient } from "@supabase/supabase-js"
-import type { Session, SupabaseClient } from "@supabase/supabase-js"
-import { supabaseAnonKey, supabaseUrl } from "@/modules/config"
+import { callAuthDoor } from "./auth-door"
+import type { DoorAnswer } from "./auth-door"
 import type { AuthClient, AuthFailure, AuthSession } from "./contracts"
+import { heldSession, heldToken, hold, listen } from "./token-store"
 
-let authentication: SupabaseClient["auth"] | undefined
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> => typeof value === "object" && value !== null
 
-/**
- * The one Supabase client of the front end, used for Supabase Auth only (the PKCE flow runs in the browser: a returning
- * redirect's code is exchanged by `detectSessionInUrl`, no route handler). It never calls `.from()`, `.rpc()` or storage:
- * data goes through modules/api to the back end, which verifies the access token.
- */
-const authOf = (): SupabaseClient["auth"] =>
-    (authentication ??= createClient(supabaseUrl(), supabaseAnonKey(), {
-        auth: { flowType: "pkce", detectSessionInUrl: true, persistSession: true, autoRefreshToken: true },
-    }).auth)
+/** The token and session an auth door issued, narrowed from its unread body; undefined when the body is not one. */
+const issuedOf = (body: unknown): { readonly token: string; readonly session: AuthSession } | undefined => {
+    if (!isRecord(body) || typeof body.accessToken !== "string" || !isRecord(body.user) || typeof body.user.id !== "string") return undefined
+    const email = typeof body.user.email === "string" ? body.user.email : undefined
+    return { token: body.accessToken, session: { userId: body.user.id, ...(email === undefined ? {} : { email }) } }
+}
 
-// {{> fe/auth/supabase-client.ts.tpl}}
+/** The failure kind of a door's status: refused credentials, rejected input, or the API unavailable. */
+const kindOf = (status: number): string => {
+    if (status === 400 || status === 401 || status === 403) return "refused"
+    return status === 422 ? "invalid" : "unavailable"
+}
+
+const failureOf = (answer: DoorAnswer): AuthFailure => ({ code: `AUTH_${String(answer.status)}`, kind: kindOf(answer.status), message: "" })
+
+const ok = (answer: DoorAnswer): boolean => answer.status >= 200 && answer.status < 300
+
+/** Rotates the refresh cookie and holds the new access token; signs out when the API refuses the cookie. */
+const refresh = async (): Promise<string | undefined> => {
+    const answer = await callAuthDoor("refresh")
+    hold(ok(answer) ? issuedOf(answer.body) : undefined)
+    return heldToken()
+}
+
+/** The lite session issuer's client: the app's own auth doors through `auth-door.ts`, the token in `token-store.ts`. */
+export const authClient: AuthClient = {
+    session: async () => heldSession() ?? ((await refresh()) === undefined ? undefined : heldSession()),
+    accessToken: async () => heldToken() ?? refresh(),
+    refreshAccessToken: refresh,
+    signInWithPassword: async (email, password) => {
+        const answer = await callAuthDoor("sign-in", { email, password })
+        const issued = ok(answer) ? issuedOf(answer.body) : undefined
+        if (issued === undefined) return failureOf(answer)
+        hold(issued)
+        return undefined
+    },
+    signOut: async () => {
+        const answer = await callAuthDoor("sign-out")
+        hold(undefined)
+        return ok(answer) ? undefined : failureOf(answer)
+    },
+    onChange: listen,
+}

package/templates/fe/skeleton-lite/apps/__app__/src/modules/auth/token-store.ts

@@ -0,0 +1,31 @@
+import type { AuthSession } from "./contracts"
+
+/** The signed-in reader and the access token, in memory only; the refresh token never reaches the browser's script. */
+interface Held {
+    readonly token: string
+    readonly session: AuthSession
+}
+
+let held: Held | undefined
+const listeners = new Set<(session: AuthSession | undefined) => void>()
+
+/** The held access token, or undefined when signed out. */
+export const heldToken = (): string | undefined => held?.token
+
+/** The held session, or undefined when signed out. */
+export const heldSession = (): AuthSession | undefined => held?.session
+
+/** Replaces the held token and session (undefined signs out) and tells every listener. */
+export const hold = (next: Held | undefined): void => {
+    held = next
+    for (const listener of listeners) listener(held?.session)
+}
+
+/** Subscribes to session changes; the listener hears the current session first. */
+export const listen = (listener: (session: AuthSession | undefined) => void): (() => void) => {
+    listeners.add(listener)
+    listener(held?.session)
+    return () => {
+        listeners.delete(listener)
+    }
+}

package/templates/fe/skeleton-lite/apps/web/src/modules/config/index.ts

@@ -6,8 +6,5 @@ const required = (name: string, value: string | undefined): string => {
 
 /** The public origin used for metadata. */
 export const siteUrl = (): string => required("NEXT_PUBLIC_SITE_URL", process.env.NEXT_PUBLIC_SITE_URL)
-/** The public Supabase project origin, read by modules/auth only. */
-export const supabaseUrl = (): string => required("NEXT_PUBLIC_SUPABASE_URL", process.env.NEXT_PUBLIC_SUPABASE_URL)
-/** The public anonymous key of Supabase Auth; the back end verifies every access token it is sent. */
-export const supabaseAnonKey = (): string =>
-    required("NEXT_PUBLIC_SUPABASE_ANON_KEY", process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY)
+/** The public origin of the API whose auth doors modules/auth calls; the browser holds no credential of its own. */
+export const apiUrl = (): string => required("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL)

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 });
-    } });
-}