@everystack/cli 0.4.43 → 0.4.45

package/src/cli/model-render.ts

@@ -81,6 +81,10 @@ export interface RenderOptions {
   /** The rendered derived layer (B5) — rides the barrel: block after the models,
    *  sequences/derived arrays on the module wrapper, symbols on the import header. */
   derived?: DerivedRenderResult;
+  /** The `--derived-out` case: the layer lives in its own file, so the barrel imports and
+   *  wires it instead of embedding it. Mutually exclusive with `derived` in practice —
+   *  passing neither is what silently produced `defineModule({ models })`. */
+  externalDerived?: ExternalDerived;
 }
 
 /**
@@ -209,8 +213,25 @@ function bareName(table: string): string {
   return table.replace(/^[^.]+\./, '');
 }
 
-/** Migration infrastructure a pull must never render as a model, whatever schema it landed in. */
-const INFRASTRUCTURE_TABLES = new Set(['__drizzle_migrations']);
+/**
+ * Migration infrastructure a pull must never render as a model, whatever schema it landed in.
+ *
+ * A brownfield pull adopts a database another migration tool still owns, and that tool's
+ * bookkeeping is not the app's data. Rendering it as a model makes everystack GOVERN it: the
+ * compiled contract declares an admin policy, and the adopter's first plan carries a
+ * `CREATE POLICY` on a table nobody asked us to manage. The journal belongs to whoever writes
+ * it — drizzle-kit's `__drizzle_migrations`, Rails' `schema_migrations` +
+ * `ar_internal_metadata`.
+ *
+ * Deliberately a SHORT list of names that are unambiguously a migration tool's own state. It
+ * is not a heuristic and must not become one: a real app table wrongly matched here silently
+ * loses its declared authorization.
+ */
+const INFRASTRUCTURE_TABLES = new Set([
+  '__drizzle_migrations', // drizzle-kit
+  'schema_migrations', // Rails / ActiveRecord
+  'ar_internal_metadata', // Rails / ActiveRecord
+]);
 
 /**
  * The tables a pull renders: the requested schema, minus migration infrastructure.
@@ -505,22 +526,42 @@ function importHeader(body: string, extra: string[] = []): string {
   return imports.join('\n');
 }
 
-/** The barrel's module wrapper: models always; sequences/derived when the pull found any (B5). */
-function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multiline = false): string {
+/**
+ * The barrel's module wrapper: models always; sequences/derived when the pull found any (B5).
+ *
+ * `external` is the `--derived-out` case — the descriptors live in their own file, so the
+ * barrel IMPORTS the arrays rather than re-declaring them. Before this the barrel simply
+ * omitted them, which meant the same pull that wrote 120 descriptors emitted a
+ * `defineModule({ models })` that excluded every one, and `db:plan` then compared against a
+ * fraction of the database while reporting a confident statement count. A plan scoped to
+ * something narrower than the reader assumes is the same false-completeness failure as a
+ * classification that defaults to safe.
+ */
+function moduleFooter(
+  modelNames: string[],
+  derived?: DerivedRenderResult,
+  multiline = false,
+  external?: ExternalDerived,
+): string {
   // A materialized table (--matviews-as-tables) is a MODEL — its block rides the derived
   // render (topo-ordered with the objects around it) but its name belongs in `models`.
-  const allModels = [...modelNames, ...(derived?.materializedTableNames ?? [])];
-  const models = multiline
-    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n];`
-    : `export const models = [${allModels.join(', ')}];`;
-  const parts = [models];
+  const hasMaterialized = external ? external.materializedTables : Boolean(derived?.materializedTableNames.length);
+  const inlineNames = external ? [] : (derived?.materializedTableNames ?? []);
+  const allModels = [...modelNames, ...inlineNames];
+  const rendered = multiline
+    ? `export const models = [\n${allModels.map((n) => `  ${n},`).join('\n')}\n${external && hasMaterialized ? '  ...materializedTables,\n' : ''}];`
+    : `export const models = [${[...allModels, ...(external && hasMaterialized ? ['...materializedTables'] : [])].join(', ')}];`;
+  const parts = [rendered];
   const keys = ['models'];
-  if (derived?.sequenceNames.length) {
-    parts.push(`export const sequences = [${derived.sequenceNames.join(', ')}];`);
+
+  const hasSequences = external ? external.sequences : Boolean(derived?.sequenceNames.length);
+  const hasDerived = external ? external.derived : Boolean(derived?.names.length);
+  if (hasSequences) {
+    if (!external) parts.push(`export const sequences = [${derived!.sequenceNames.join(', ')}];`);
     keys.push('sequences');
   }
-  if (derived?.names.length) {
-    parts.push(`export const derived = [${derived.names.join(', ')}];`);
+  if (hasDerived) {
+    if (!external) parts.push(`export const derived = [${derived!.names.join(', ')}];`);
     keys.push('derived');
   }
   parts.push(`export const appModule = defineModule({ ${keys.join(', ')} });`);
@@ -528,6 +569,24 @@ function moduleFooter(modelNames: string[], derived?: DerivedRenderResult, multi
   return parts.join('\n\n');
 }
 
+/** What an external (`--derived-out`) derived file exports, so the barrel can wire it. */
+export interface ExternalDerived {
+  /** Import specifier as written in the barrel, e.g. `'./derived'`. */
+  specifier: string;
+  sequences: boolean;
+  materializedTables: boolean;
+  derived: boolean;
+}
+
+/** The named exports to pull out of an external derived file, in a stable order. */
+function externalDerivedNames(e: ExternalDerived): string[] {
+  const names: string[] = [];
+  if (e.derived) names.push('derived');
+  if (e.materializedTables) names.push('materializedTables');
+  if (e.sequences) names.push('sequences');
+  return names;
+}
+
 /**
  * Render a whole snapshot as a single Models module: the import, one block per table (scoped
  * to `opts.schema`), and the `models` array the rest of the framework consumes. The tables
@@ -610,14 +669,21 @@ export function renderModelFiles(snapshot: SchemaSnapshot, opts: RenderOptions =
   // their own model.
   const names = tables.map((t) => modelVarName(t.table));
   const modelSymbols = ['defineModule', ...(opts.derived?.imports ?? [])];
+  const ext = opts.externalDerived;
+  const extNames = ext ? externalDerivedNames(ext) : [];
   const index = [
     [
       `import { ${modelSymbols.join(', ')} } from '@everystack/model';`,
+      // The --derived-out layer, imported rather than re-declared — the barrel must WIRE it
+      // or db:plan silently compares against models only.
+      ...(extNames.length ? [`import { ${extNames.join(', ')} } from '${ext!.specifier}';`] : []),
       ...names.map((n, i) => `import { ${n} } from './${bareName(tables[i].table).replace(/_/g, '-')}';`),
     ].join('\n'),
     `export {\n${names.map((n) => `  ${n},`).join('\n')}\n};`,
+    // Re-exported so the barrel remains the one place that describes the database.
+    ...(extNames.length ? [`export { ${extNames.join(', ')} };`] : []),
     ...(opts.derived?.block ? [opts.derived.block] : []),
-    moduleFooter(names, opts.derived, true),
+    moduleFooter(names, opts.derived, true, ext),
   ].join('\n\n');
   files.push({ file: 'index.ts', source: index + '\n' });
 

package/src/cli/output.ts

@@ -11,11 +11,11 @@ export function step(msg: string): void {
 }
 
 export function success(msg: string): void {
-  console.log(`  \u2713 ${msg}`);
+  say(`  \u2713 ${msg}`);
 }
 
 export function warn(msg: string): void {
-  console.log(`  ! ${msg}`);
+  say(`  ! ${msg}`);
 }
 
 export function fail(msg: string): void {
@@ -23,5 +23,27 @@ export function fail(msg: string): void {
 }
 
 export function info(msg: string): void {
-  console.log(`  ${msg}`);
+  say(`  ${msg}`);
+}
+
+/**
+ * When a command makes stdout the DATA channel (`db:plan --out -`), every human-readable
+ * line has to move to stderr \u2014 otherwise the report is interleaved with the artifact and
+ * the stdout form cannot be piped to anything. `step` and `fail` already write to stderr
+ * on that principle; this extends it to the rest, on demand.
+ *
+ * Off by default, so no command's output moves unless it asks. One-way and process-wide:
+ * a CLI process runs exactly one command, and the choice is made once, before it prints.
+ */
+let stdoutReserved = false;
+
+/** Declare stdout the data channel: human-readable output moves to stderr from here on. */
+export function reserveStdoutForData(): void {
+  stdoutReserved = true;
+}
+
+/** Human-readable output \u2014 stdout normally, stderr once stdout is reserved for data. */
+function say(line: string): void {
+  if (stdoutReserved) console.error(line);
+  else console.log(line);
 }

package/src/cli/parse-flags.ts

@@ -0,0 +1,39 @@
+/**
+ * The CLI's flag parser.
+ *
+ * `--key value` / `-k value`, with a value-less flag defaulting to the string `'true'`.
+ * Extracted from the entry point so it can be tested without executing the CLI.
+ *
+ * The subtlety is what counts as "the next argument is a VALUE, not the next flag".
+ * Two legitimate values look like flags, or like nothing, to a naive check:
+ *
+ *   - A bare `-` is the conventional stdout sentinel. `db:plan --out -` documents itself
+ *     as "print to stdout"; read as a value-less flag it became `out=true` and the
+ *     command wrote a file literally named `true`.
+ *   - The EMPTY string is a value. `db:approvers --set ''` is the documented way to
+ *     declare an empty approver set and DISABLE destructive applies on a stage; read as
+ *     value-less it became `set=true`, and the command refused with "--set needs a
+ *     value" — so the documented way to turn the gate off could not be typed.
+ *
+ * Both are the same mistake: treating an unusual-looking value as an absent one. A flag
+ * is an argument that starts with `-` AND is longer than one character; everything else,
+ * including `''`, is a value.
+ */
+
+/** Is this argument a flag (as opposed to a value)? A bare `-` is a value. */
+function isFlag(arg: string): boolean {
+  return arg.startsWith('-') && arg.length > 1;
+}
+
+/** Parse `--key value` / `-k value` pairs; a flag with no value becomes `'true'`. */
+export function parseFlags(args: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!isFlag(arg)) continue;
+    const key = arg.startsWith('--') ? arg.slice(2) : arg.slice(1);
+    const next = args[i + 1];
+    flags[key] = next !== undefined && !isFlag(next) ? args[++i] : 'true';
+  }
+  return flags;
+}

package/src/cli/schema-fingerprint.ts

@@ -46,6 +46,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { canonicalAuthz } from './authz-canonical.js';
 import type { ModelDescriptor, SequenceDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect.js';
 import type { AuthzContract, TableContract } from './authz-contract.js';
@@ -62,7 +63,17 @@ import { normalizeDefault, normalizeCheck } from './schema-diff.js';
 // STANDALONE SEQUENCES enter the canonical form (declared via defineSequence,
 // introspected from pg_sequence minus serial-owned) — a coverage expansion; the
 // `sequences` key appears only when any exist, so sequence-free states hash unchanged.
-export const FINGERPRINT_VERSION = 3;
+// v4: the AUTHZ canonical form became the reconciler's equivalence relation instead of a
+// name-keyed transcript of the catalog. Policy NAMES leave the hash (a brownfield database
+// names its policies whatever its previous migration tool named them, so hashing the name made
+// a policy carrying the declared authorization read as a different state); policies expand
+// across their roles as a MULTISET (so one policy TO a,b hashes equal to two identical ones TO
+// a and TO b, and duplicates never collapse); PUBLIC stays a single sentinel and is never
+// enumerated; and grants are filtered to the GOVERNED grantees, because the reconciler leaves
+// an ungoverned migrator/ETL role alone and a hash that counts it can never converge.
+// Together these restore the identity the format exists for: fingerprints match exactly when
+// db:generate is a no-op.
+export const FINGERPRINT_VERSION = 4;
 
 // ---------------------------------------------------------------------------
 // Canonical form.
@@ -115,40 +126,18 @@ function canonicalTable(table: TableSchema): Record<string, unknown> {
   };
 }
 
-function canonicalAuthzTable(contract: TableContract): Record<string, unknown> {
-  return {
-    table: contract.table,
-    rls: { enabled: contract.rls.enabled, forced: contract.rls.forced },
-    grants: Object.fromEntries(
-      Object.entries(contract.grants)
-        .map(([role, privs]) => [role, [...privs].sort()] as const)
-        .sort(([a], [b]) => (a < b ? -1 : 1)),
-    ),
-    ...(contract.columnGrants && Object.keys(contract.columnGrants).length > 0
-      ? {
-          columnGrants: Object.fromEntries(
-            Object.entries(contract.columnGrants)
-              .map(([role, byPriv]) => [
-                role,
-                Object.fromEntries(
-                  Object.entries(byPriv)
-                    .map(([priv, cols]) => [priv, [...cols].sort()] as const)
-                    .sort(([a], [b]) => (a < b ? -1 : 1)),
-                ),
-              ] as const)
-              .sort(([a], [b]) => (a < b ? -1 : 1)),
-          ),
-        }
-      : {}),
-    policies: byKey(
-      contract.policies.map((p) => ({
-        name: p.name, command: p.command, roles: [...p.roles].sort(),
-        permissive: p.permissive, using: p.using, check: p.check,
-      })),
-      (p) => p.name,
-    ),
-    // The handler-side columns exposure block is NOT a database fact — excluded.
-  };
+/**
+ * The authorization slice of the canonical form.
+ *
+ * Delegates to `authz-canonical`, which the reconciler and the differ read too. Keeping a
+ * private copy here is what let the fingerprint drift out of step with the reconciler and
+ * report permanent drift on a database that had nothing to reconcile.
+ */
+function canonicalAuthzTable(
+  contract: TableContract,
+  governed?: ReadonlySet<string>,
+): Record<string, unknown> {
+  return canonicalAuthz(contract, governed);
 }
 
 export interface CanonicalState {
@@ -171,6 +160,17 @@ export interface CanonicalizeOptions {
   /** Restrict the state to these schemas — the content address of ONE schema (e.g. a
    *  schema-scoped artifact) instead of the whole database. Omitted = every schema. */
   schemas?: string[];
+  /**
+   * The grantees the models govern. PASS THIS WHENEVER HASHING A LIVE CONTRACT.
+   *
+   * The reconciler leaves an ungoverned grantee alone by design, so a live grant to a
+   * migrator or ETL role is never reconciled. A hash that counts it describes a state the
+   * models can never reach: the operator gets "nothing to do" from the plan and "you have
+   * drifted" from the gate, with no action in between that resolves it. Omitted means "hash
+   * every grantee", which is correct only for a contract compiled FROM the models, where
+   * every grantee is governed by construction.
+   */
+  governedRoles?: ReadonlySet<string>;
 }
 
 export function canonicalizeState(
@@ -208,7 +208,10 @@ export function canonicalizeState(
         .map((e) => ({ name: e.name, values: e.values })),
       (e) => e.name,
     ),
-    authz: byKey(authzTables.filter((t) => keepTable(t.table)).map(canonicalAuthzTable), (t) => String(t.table)),
+    authz: byKey(
+      authzTables.filter((t) => keepTable(t.table)).map((t) => canonicalAuthzTable(t, opts.governedRoles)),
+      (t) => String(t.table),
+    ),
     ...(sequences.length ? { sequences } : {}),
   };
 }
@@ -305,3 +308,52 @@ export interface UnfingerprintedObject {
 export function mapUnfingerprintedRows(rows: Array<{ kind: unknown; identity: unknown }>): UnfingerprintedObject[] {
   return rows.map((r) => ({ kind: String(r.kind), identity: String(r.identity) }));
 }
+
+
+// ---------------------------------------------------------------------------
+// Comparing a STORED fingerprint against live reality.
+// ---------------------------------------------------------------------------
+
+/**
+ * A fingerprint as recorded in an artifact — a plan, a baseline, an export stamp.
+ *
+ * `v` is the format it was computed under. It must be stored ALONGSIDE the hash, not merely
+ * mixed into it: a hash alone cannot say why it differs, and the difference between "you have
+ * drifted" and "the format changed" is the difference between an operator hunting a phantom
+ * change and an operator running one re-baseline.
+ */
+export interface StoredFingerprint {
+  hash: string;
+  /** The FINGERPRINT_VERSION in force when the hash was computed. Absent = pre-v4 artifact. */
+  v?: number;
+}
+
+export type FingerprintComparison =
+  | { kind: 'match' }
+  | { kind: 'drift' }
+  | { kind: 'format-changed'; stored: number | 'unstamped'; current: number };
+
+/**
+ * Compare a stored fingerprint to one computed now.
+ *
+ * A raw hash compare across formats reports DRIFT, which is a lie — the state may be
+ * untouched while the way we describe it changed. Every hash comparison that spans an artifact
+ * boundary must come through here so a format change reads as a format change.
+ */
+export function compareStoredFingerprint(
+  stored: StoredFingerprint,
+  currentHash: string,
+  currentVersion: number = FINGERPRINT_VERSION,
+): FingerprintComparison {
+  if (stored.v !== currentVersion) {
+    return { kind: 'format-changed', stored: stored.v ?? 'unstamped', current: currentVersion };
+  }
+  return stored.hash === currentHash ? { kind: 'match' } : { kind: 'drift' };
+}
+
+/** The operator-facing sentence for a format change. Names the fix, never the phantom drift. */
+export function formatChangedMessage(c: Extract<FingerprintComparison, { kind: 'format-changed' }>): string {
+  return `fingerprint format changed (recorded v${c.stored}, current v${c.current}) — this is NOT drift. `
+    + 'The artifact predates the current canonical form, so its hash cannot be compared. '
+    + 'Re-mint the plan (db:plan) or re-baseline the stage (db:reconcile --rebaseline); no DDL is involved.';
+}