@everystack/cli 0.4.78 → 0.4.80

package/src/cli/commands/db-adopt.ts

@@ -1,243 +0,0 @@
-/**
- * `everystack db:adopt` — first-time adoption of a pre-Models database, by PROOF.
- *
- *   db:adopt [--stage <name> | --database-url <url>] [--schema public] [--out db/models]
- *            [--govern-roles r1,r2]
- *
- * The problem it solves: a production database that never went through Models has no committed
- * ancestor declaring it. db:adopt is the deliberate, auditable on-ramp for taking it AS IT IS: it renders
- * Models from the live database (the same renderers db:pull uses), compiles them back, and PROVES
- * the compiled Models declare the live state EXACTLY — predicted == governed live, the same
- * declares-test descent and db:check use. Only then does it write the model files and print the
- * `chore(db): adopt live baseline <fp>` commit: that commit legitimately declares the live state,
- * so a later db:apply descends for real instead of hitting the drift refusal.
- *
- * The doctrine (Fable-ruled 2026-09-05): PROVE, not attest. There is NO bypass flag. When the
- * round-trip is not exact, adoption REFUSES, names the surfaces that diverged, and prints the
- * edge — because a baseline that papered over a difference is the bypass under another name. It
- * writes NOTHING on refusal; --out is left untouched. That refusal is the HARDENING case (the
- * vocabulary cannot declare something live), and it needs no adoption commit: commit the intended
- * Models, db:plan, db:apply — descent proves no commit declares the database and treats the
- * reviewed plan as the origin (git-descent.ts, proven drift, 2026-09-07).
- *
- * The pure proof core is adopt.ts (proveAdoption); the shared render is live-models.ts
- * (renderLiveModelFiles). This shell is the IO: connect, render into a sandbox to compile, prove,
- * and either finalize or refuse.
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
-import { introspectContract, type AuthzContract, type QueryRunner } from '../authz-contract';
-import { introspectDerived } from '../derived-introspect';
-import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
-import { renderLiveModelFiles } from '../live-models';
-import { proveAdoption, type AdoptionProof } from '../adopt';
-import { generateMigrationSql } from '../migration-generate';
-import { loadModels } from './db-generate';
-import type { ModelDescriptor } from '@everystack/model';
-import type { RenderedModelFile } from '../model-render';
-import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source';
-import type { SessionRunner } from '../session';
-import { resolveConfig, opsFunction } from '../config';
-import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
-import { step, success, fail, info, warn } from '../output';
-import { opsAdviceLines } from '../ops-advice';
-
-const DEFAULT_OUT = 'db/models';
-
-export interface AdoptResult {
-  /** The proof: clean means the compiled Models declare the live state exactly. */
-  proof: AdoptionProof;
-  /** The rendered model files (directory shape) — written to --out only when the proof is clean. */
-  files: RenderedModelFile[];
-  /** The live schema, as introspected. */
-  snapshot: SchemaSnapshot;
-  /** The live authorization contract, as introspected. */
-  contract: AuthzContract;
-  /** `chore(db): adopt live baseline <fp>` when clean; null on refusal. */
-  commitMessage: string | null;
-  /** On refusal, the db:generate edge (what the Models and the live database still differ by). */
-  refusalDiff: string[];
-}
-
-/**
- * The adopt CORE: introspect the live database, render Models with the shared renderer, compile
- * them in `sandboxDir`, and prove they declare the live state. Pure of policy — it does not decide
- * to write --out or to exit; the caller does that from the verdict. The sandbox is where the
- * rendered barrel is written so it can be dynamically imported (the compile the proof needs);
- * --out is written by the shell only after the proof is clean.
- */
-export async function adoptFromLive(opts: {
-  session: SessionRunner;
-  runner: QueryRunner;
-  schema?: string | string[];
-  governRoles?: string[];
-  sandboxDir: string;
-  /** How to compile the rendered barrel back to descriptors. Defaults to loadModels (the barrel
-   *  loader db:generate uses). Injectable so a test runner that cannot dynamic-import a `.ts` via
-   *  a file:// URL (jest) can supply its own transforming import. */
-  loadBarrel?: (indexPath: string) => Promise<ModelDescriptor[]>;
-}): Promise<AdoptResult> {
-  const { session, sandboxDir } = opts;
-  const schema = opts.schema ?? 'public';
-  const load = opts.loadBarrel ?? loadModels;
-
-  const snapshot = await introspectSchema(session);
-  const contract = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
-  const derivedCatalog = await introspectDerived(session);
-
-  const rendered = renderLiveModelFiles(snapshot, contract, derivedCatalog, { schema, governRoles: opts.governRoles });
-
-  // Compile the rendered barrel: proveAdoption needs the loaded ModelDescriptors, and loading is a
-  // dynamic import, so the files must exist on disk under a tree where @everystack/model resolves.
-  await fs.mkdir(sandboxDir, { recursive: true });
-  for (const f of rendered.files) await fs.writeFile(path.join(sandboxDir, f.file), f.source, 'utf8');
-  const models = await load(path.join(sandboxDir, 'index.ts'));
-
-  const proof = proveAdoption(models, snapshot, contract, { schema: typeof schema === 'string' ? schema : undefined });
-  const commitMessage = proof.clean ? `chore(db): adopt live baseline ${proof.fingerprint}` : null;
-  // On refusal, show WHAT still differs — the same edge db:generate would mint against the live DB.
-  const refusalDiff = proof.clean ? [] : generateMigrationSql(models, snapshot, { liveAuthz: contract });
-
-  return { proof, files: rendered.files, snapshot, contract, commitMessage, refusalDiff };
-}
-
-/**
- * Turn the adopt verdict into action — the SECURITY BOUNDARY, isolated so it is testable without a
- * database. This is where "PROVE not attest, no bypass" is actually enforced: on refusal it writes
- * NOTHING to --out and reports; on a clean proof it writes the baseline and prints the commit/push
- * runbook. It never calls process.exit (the caller maps the returned code) — so a test can assert,
- * against a synthetic verdict, that a dirty result leaves --out untouched and a clean one finalizes.
- * A future edit that let the refusal path fall through to the write is caught by that test, red.
- */
-export async function applyAdoptVerdict(result: AdoptResult, outDir: string): Promise<{ exitCode: 0 | 1; wrote: boolean }> {
-  if (!result.proof.clean) {
-    // REFUSAL — the round trip is not exact. Name what diverged and show the edge; write NOTHING.
-    console.log('');
-    fail('db:adopt refused — the rendered Models do NOT declare the live database exactly.');
-    warn('A baseline that papered over this difference would be a bypass. Nothing was written to --out.');
-    info('Surfaces that diverge:');
-    for (const s of result.proof.divergentSurfaces) info(`  • ${s}`);
-    if (result.refusalDiff.length) {
-      console.log('');
-      info(`What still differs (the db:generate edge, ${result.refusalDiff.length} statement(s)):`);
-      for (const stmt of result.refusalDiff) console.log(stmt.endsWith(';') ? stmt : `${stmt};`);
-    }
-    console.log('');
-    info('The Models vocabulary cannot declare the surfaces above as they are live (a sequence grant with no INSERT behind it, for example), so no render can round-trip this database. That is the HARDENING case, and it needs no adoption commit: commit the Models you intend, then');
-    info('  everystack db:plan --stage <name>                       # mints the edge above as a reviewable plan');
-    info('  everystack db:apply --plan <file.plan.json> --stage <name>   # credential-free; no commit declares this database yet, so the reviewed plan is the ORIGIN and is recorded as such');
-    info('Every later db:apply descends from that recorded origin.');
-    return { exitCode: 1, wrote: false };
-  }
-
-  // CLEAN — finalize. Write the rendered barrel to --out, then print the runbook.
-  try {
-    await fs.mkdir(outDir, { recursive: true });
-    const written = new Set(result.files.map((f) => f.file));
-    const existing = (await fs.readdir(outDir)).filter((f) => f.endsWith('.ts') && !written.has(f));
-    for (const f of result.files) await fs.writeFile(path.join(outDir, f.file), f.source, 'utf8');
-    if (existing.length) {
-      warn(`${existing.length} existing .ts file(s) in ${path.relative(process.cwd(), outDir)} were not part of this adoption and were left untouched: ${existing.join(', ')}`);
-    }
-  } catch (err: any) {
-    fail(`Could not write ${outDir}: ${err.message}`);
-    return { exitCode: 1, wrote: false };
-  }
-
-  console.log('');
-  success(`db:adopt — the rendered Models declare the live database exactly (${result.files.length - 1} model(s)).`);
-  info(`Wrote ${path.relative(process.cwd(), outDir)} — the adopted baseline.`);
-  console.log('');
-  info('Finalize the baseline — commit, then PUSH before you apply:');
-  info(`  git add ${path.relative(process.cwd(), outDir)}`);
-  info(`  git commit -m "${result.commitMessage}"`);
-  info('  git push        # an unpushed baseline is an unknown commit to teammates and the ops Lambda');
-  info('  everystack db:plan --stage <name>   # empty — the live database is now declared');
-  return { exitCode: 0, wrote: true };
-}
-
-export async function dbAdoptCommand(
-  flags: Record<string, string>,
-  opts: {
-    /** Injected barrel loader (jest cannot file:// import a .ts). Default: adoptFromLive's loadModels. */
-    loadBarrel?: (indexPath: string) => Promise<ModelDescriptor[]>;
-    /** Injected sandbox dir, so a test can assert it is cleaned up. Default: a fresh mkdtemp. */
-    sandboxDir?: string;
-  } = {},
-): Promise<void> {
-  const schemas = (flags.schema || 'public').split(',').map((s) => s.trim()).filter(Boolean);
-  if (schemas.length === 0) fail('--schema needs at least one schema name.');
-  const schema = schemas.length === 1 ? schemas[0] : schemas;
-  const outDir = path.resolve(flags.out || DEFAULT_OUT);
-
-  // --govern-roles: the operator's EXPLICIT decision to transcribe foreign roles' grants as
-  // privileges (so a fresh build recreates them). Same vocabulary guard as db:pull.
-  const governRoles = (flags['govern-roles'] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
-  for (const r of governRoles) {
-    if (['anon', 'authenticated', 'admin', 'PUBLIC', 'public'].includes(r)) {
-      fail(`--govern-roles ${r}: the vocabulary roles and PUBLIC are always governed — name only foreign roles (an ops/connection role the migrations granted to).`);
-      process.exit(1);
-    }
-  }
-
-  let dbSource: DbSource;
-  try {
-    dbSource = resolveDbSource(flags);
-  } catch (err: any) {
-    fail(err.message);
-    process.exit(1);
-  }
-
-  // The proof-compile sandbox MUST live inside the project, never the OS temp dir. The rendered
-  // barrel imports `@everystack/model`, and Node resolves a bare specifier by walking UP from the
-  // importing file looking for node_modules. pnpm hoists workspace packages to the repo root (an
-  // app dir has no local copy), so a dir under $TMPDIR cannot reach them and the compile crashes
-  // with "Cannot find module '@everystack/model'". cwd is inside the project, so a sandbox under it
-  // resolves exactly as the real db/models barrel will. (Reported by a consumer on 0.4.74; the
-  // scratch-sweep harness documents the same rule: $TMPDIR → MODULE_NOT_FOUND, project dir resolves.)
-  const sandboxDir = opts.sandboxDir ?? await fs.mkdtemp(path.join(process.cwd(), '.everystack-adopt-'));
-  let exitCode: 0 | 1 = 1;
-  let end: (() => Promise<void>) | undefined;
-  try {
-    let runner: QueryRunner;
-    let session: SessionRunner;
-    if (dbSource.kind === 'url') {
-      step(connectingVia(dbSource));
-      ({ runner, session, end } = await createUrlRunner(dbSource.url));
-    } else {
-      step('Resolving deployed config...');
-      const config = await resolveConfig(flags.stage);
-      info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
-      runner = lambdaQueryRunner(config.region, opsFunction(config));
-      session = lambdaSessionRunner(config.region, opsFunction(config));
-    }
-    step(`Introspecting live database (schema: ${schemas.join(', ')})...`);
-    const result = await adoptFromLive({ session, runner, schema, governRoles, sandboxDir, loadBarrel: opts.loadBarrel });
-    // Only after a proof do we act. A throw before here (connect, introspect, render, compile)
-    // never reaches applyAdoptVerdict, so --out is untouched — a bad baseline is impossible.
-    ({ exitCode } = await applyAdoptVerdict(result, outDir));
-  } catch (err: any) {
-    fail(err.message);
-    // A failure to load the rendered barrel is a COMPILE error, not a connection or IAM problem —
-    // don't send the operator to check their credentials for it.
-    if (/Could not load models|Cannot find module/i.test(err.message ?? '')) {
-      info('This is the proof-compile step, not the database. The rendered Models could not be loaded —');
-      info('run db:adopt from inside your project (where @everystack/model resolves), and check the models compile.');
-    } else if (dbSource.kind === 'url') {
-      info('Check the connection string and that the database is accepting connections.');
-    } else {
-      for (const line of opsAdviceLines(err, [
-        'Ensure your IAM user/role has lambda:InvokeFunction and the stage is deployed.',
-        'Adopting a local database instead? Pass --database-url or set DATABASE_URL.',
-      ])) info(line);
-    }
-    exitCode = 1;
-  } finally {
-    // The sandbox is the compile scratch, never the baseline — remove it on EVERY exit path.
-    await end?.();
-    await fs.rm(sandboxDir, { recursive: true, force: true });
-  }
-  process.exit(exitCode);
-}

package/src/cli/live-models.ts

@@ -1,65 +0,0 @@
-/**
- * renderLiveModelFiles — the render db:pull and db:adopt SHARE.
- *
- * Both commands turn a live database into `field()` Models with the same posture: derive each
- * model's authz from the grants and policies already there (`abilities: 'live'`), render the
- * derived layer from the live catalog, and write the directory shape (one file per model + an
- * index barrel). Factoring it here is not only DRY — it is the round-trip's correctness. db:adopt
- * PROVES the rendered Models declare the live state; if adopt rendered even slightly differently
- * from pull, the proof could refuse on a cosmetic difference pull produces fine. One renderer,
- * one result.
- *
- * Pure: introspection results in, rendered files out. The command shells do the IO.
- */
-
-import type { SchemaSnapshot } from './schema-introspect';
-import type { AuthzContract } from './authz-contract';
-import type { DerivedCatalog } from './derived-introspect';
-import { renderModelFiles, pullableTables, modelVarName, type RenderedModelFile } from './model-render';
-import { renderDerivedSource } from './derived-render';
-import { fingerprintLive } from './schema-fingerprint';
-import { ungovernedGrants, ALWAYS_GOVERNED, type GrantExemption } from './authz-reconcile';
-import { deriveAbilities } from './authz-derive';
-
-export interface LiveModelRender {
-  /** The directory shape: one file per model + `index.ts` (the barrel that exports `models`). */
-  files: RenderedModelFile[];
-  /** The RAW live fingerprint — the baseline id db:adopt names the commit by. */
-  fingerprint: string;
-  /** Foreign grantees present at pull, exempt from revocation (the adoption baseline observation). */
-  exemptions: GrantExemption[];
-}
-
-/**
- * Render `field()` Models from a live database in the live-abilities, directory shape. The
- * `--govern-roles` complete-or-refuse gate runs here (pure re-derivation on the pulled tables),
- * before any file is written, so a listed role holding a column-scoped grant throws instead of
- * leaving a half-written tree.
- */
-export function renderLiveModelFiles(
-  snapshot: SchemaSnapshot,
-  contract: AuthzContract,
-  derivedCatalog: DerivedCatalog,
-  opts: { schema?: string | string[]; governRoles?: string[] } = {},
-): LiveModelRender {
-  const schema = opts.schema ?? 'public';
-  const governRoles = opts.governRoles ?? [];
-  const pulled = pullableTables(snapshot, schema);
-  const knownTables = new Map(pulled.map((t) => [t.table, modelVarName(t.table)]));
-  const derived = renderDerivedSource(derivedCatalog, { knownTables, sequences: snapshot.sequences });
-  const liveAuthz = new Map(contract.tables.map((t) => [t.table, t]));
-
-  // The --govern-roles gate, BEFORE any file is written: a governed role holding a column-scoped
-  // grant fails the render (deriveAbilities throws) rather than producing a half-owned barrel.
-  if (governRoles.length) {
-    const pulledNames = new Set(pulled.map((t) => t.table));
-    const govern = new Set(governRoles);
-    for (const [name, c] of liveAuthz) if (pulledNames.has(name)) deriveAbilities(c, { governRoles: govern });
-  }
-
-  const files = renderModelFiles(snapshot, { schema, abilities: 'live', liveAuthz, governRoles, derived });
-  // A governed role's grants are DECLARED (transcribed as privileges), so they are not also
-  // recorded as exemptions — that would double-book them, declared and exempted at once.
-  const exemptions = ungovernedGrants(contract, new Set([...ALWAYS_GOVERNED, ...governRoles]));
-  return { files, fingerprint: fingerprintLive(snapshot, contract).hash, exemptions };
-}