@everystack/cli 0.4.23 → 0.4.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.23",
+  "version": "0.4.24",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

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

@@ -411,6 +411,24 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     info(`${declared.objects.length} declared derived object(s) from the models barrel.`);
   }
 
+  // --only <a,b>: restrict the reconcile to the named identities (surgical). With --rebuild it is
+  // the recovery path for a self-consistent-but-wrong provenance row (a mistaken --rebaseline).
+  const only = flags.only ? flags.only.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+  // An empty/whitespace --only would silently degrade to a FULL reconcile — refuse it, since the
+  // operator clearly meant to scope the run.
+  if (flags.only !== undefined && !only?.length) {
+    fail('--only was given but names no identities — pass full schema.name objects (e.g. --only stats_view.my_mv), or drop the flag for a full reconcile.');
+    process.exit(1);
+  }
+  if (only?.length) {
+    const declaredIds = new Set((declared?.objects ?? []).map((o) => o.identity));
+    const unknown = only.filter((id) => !declaredIds.has(id));
+    if (unknown.length) {
+      warn(`--only names ${unknown.length} identity(ies) not in the declared derived layer: ${unknown.join(', ')} — a full schema.name is expected (e.g. stats_view.college_player_epa_context). They will match nothing.`);
+    }
+    info(`--only: restricting the reconcile to ${only.join(', ')}${flags.rebuild === 'true' ? ' (forced rebuild from source)' : ''}.`);
+  }
+
   const reconcileOptions = {
     apply,
     declared: declared?.objects,
@@ -419,6 +437,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     rebaseline: flags.rebaseline === 'true',
     rebuild: flags.rebuild === 'true',
     overwriteDrift: flags['overwrite-drift'] === 'true',
+    only,
     actor: process.env.USER ?? null,
     gitRef: currentGitRef(),
   };

package/src/cli/derived-plan.ts

@@ -126,6 +126,19 @@ export interface ReconcileOptions {
    * their provenance identity migrates with them.
    */
   renamedTables?: Record<string, string>;
+  /**
+   * Restrict the reconcile to these identities (full `schema.name`) — a surgical run that
+   * considers ONLY the named objects for create/replace/rebuild/drop/prune. Everything else is
+   * left untouched. The dependency cascade still applies: rebuilding a named relation pulls its
+   * live dependents in (they must rebuild with it) or blocks if one has no source.
+   *
+   * Combined with `rebuild`, this is the RECOVERY path for a self-consistent-but-WRONG
+   * provenance row — the state a mistaken `--rebaseline` leaves, where the source hash was
+   * re-recorded against a stale live def so both `srcChanged` and `liveChanged` read false and
+   * every normal verb no-ops. `--rebuild --only <id>` forces that object to rebuild from source
+   * regardless of the hash bookkeeping, then re-records honest provenance from the fresh object.
+   */
+  only?: string[];
 }
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
@@ -156,6 +169,12 @@ export function planReconcile(
   // Every provenance consumer below reads the POST-MIGRATION view.
   const provRows = [...provById.values()];
 
+  // --only: restrict every primary decision (create/replace/rebuild/drop/prune) to these
+  // identities. The catalog/source/provenance maps above stay FULL so the dependency cascade
+  // can still pull a named relation's dependents in — the restriction is on what the operator
+  // TARGETS, not on what the graph is allowed to see.
+  const only = options.only && options.only.length ? new Set(options.only) : null;
+
   const skipped: string[] = [];
   const drift: DriftFinding[] = [];
   const needsBaseline: string[] = [];
@@ -184,6 +203,10 @@ export function planReconcile(
   const extraWarnings: string[] = [];
 
   for (const src of source.objects) {
+    // --only restricts the primary decisions to the named identities; the rest are left
+    // untouched (they are not skips — they were never in scope, so they get no plan entry).
+    if (only && !only.has(src.identity)) continue;
+
     const liveObj = liveById.get(src.identity);
     const prov = provById.get(src.identity);
 
@@ -193,6 +216,10 @@ export function planReconcile(
     if (src.kind === 'sql') {
       if (!prov) {
         create.set(src.identity, 'new in source (provenance-tracked kind — invisible to the catalog)');
+      } else if (options.rebuild && only) {
+        // Forced recovery: rebuild through the recorded drop even when the source hash matches.
+        sqlDrops.set(src.identity, { dropSql: prov.dropSql ?? src.drop ?? '', reason: 'forced rebuild from source (--rebuild --only)' });
+        create.set(src.identity, 'forced rebuild from source (--rebuild --only, through the recorded drop)');
       } else if (src.hash !== prov.srcHash) {
         sqlDrops.set(src.identity, { dropSql: prov.dropSql ?? src.drop ?? '', reason: 'source changed' });
         create.set(src.identity, 'source changed (rebuilt through the recorded drop)');
@@ -224,6 +251,27 @@ export function planReconcile(
       continue;
     }
 
+    // Forced recovery (--rebuild --only): rebuild this provenanced object from source even when
+    // the hashes show no diff. This is the clean exit from a self-consistent-but-WRONG provenance
+    // row — a mistaken --rebaseline re-records the source hash against the stale live def, so both
+    // srcChanged and liveChanged read false below and every normal verb no-ops. The dependency
+    // cascade recreates any live dependents; the post-batch introspection re-records honest
+    // provenance. Gated on `only` so a bare --rebuild never becomes an implicit rebuild-the-world.
+    if (options.rebuild && only) {
+      // If the live object was genuinely hand-edited (drift), record it before overwriting — the
+      // same audit the --overwrite-drift path keeps, so a forced rebuild never silently erases
+      // what it clobbered.
+      if (liveObj.defHash !== prov.defHash) {
+        drift.push({
+          identity: src.identity,
+          detail: 'live definition differs from what the reconciler applied — rebuilt from source (--rebuild --only overwrote it)',
+        });
+      }
+      if (isRelation(src.kind)) rebuild.set(src.identity, 'forced rebuild from source (--rebuild --only)');
+      else fnReplace.set(src.identity, 'forced replace from source (--rebuild --only)');
+      continue;
+    }
+
     const srcChanged = src.hash !== prov.srcHash;
     const liveChanged = liveObj.defHash !== prov.defHash;
 
@@ -253,12 +301,14 @@ export function planReconcile(
   }
 
   for (const liveObj of live.objects) {
+    if (only && !only.has(liveObj.identity)) continue;
     if (srcById.has(liveObj.identity)) continue;
     if (provById.has(liveObj.identity)) drop.set(liveObj.identity, 'removed from source');
     else unmanaged.push(liveObj.identity);
   }
 
   for (const prov of provRows) {
+    if (only && !only.has(prov.identity)) continue;
     if (srcById.has(prov.identity) || liveById.has(prov.identity)) continue;
     // A removed 'sql' object is invisible to the catalog — pruning would silently orphan
     // it in the database. The recorded drop_sql removes it (the C1 closure); only a

package/src/cli/index.ts

@@ -371,7 +371,7 @@ Usage:
   everystack db:pull           [--stage <name> | --database-url <url>] [--schema public] [--out <dir | file.ts>] [--derived-out <file.ts>] [--abilities public-read]  Introspect the live DB → render field() Models (the brownfield on-ramp). --out <dir> writes one file per model + index.ts (the default shape); --out <file.ts> writes a single module; stdout otherwise. --derived-out <file.ts> extracts the derived layer (descriptors + sequences) as its own self-contained module — alone it leaves the models untouched (the hand-maintained-barrel splice); with --out the models render omits the now-external derived layer. Every model scaffolds its authz decision as comments (db:check fails until authored); --abilities public-read stamps the common stanza (public read, admin write) uncommented — explicit generated code, never a runtime default. --matviews-as-tables renders every matview as defineMaterializedTable with INTROSPECTED fields (the canonical-sync flip: a pipeline-owned table everystack migrates but never refreshes) — names land in an exported materializedTables array to spread into your models; fields come back nullable/unkeyed (matviews carry no PK/NOT NULL) — tighten on review; add --suggest-keys to probe the LIVE rows for functionally-unique columns (one scan per matview) and surface each as a commented .primaryKey() suggestion. docs/derived-objects.md#flipping-a-matview-to-a-materialized-table---matviews-as-tables
                                Both introspect via the deployed ops Lambda by default; --database-url (or an inherited DATABASE_URL) connects directly — for a schema that exists only on a local Postgres.
   everystack db:fingerprint    [--stage <name> | --database-url <url>] [--models <barrel>] [--json]  Content-address the live base schema (tables+constraints+authz) and compare against the models — MATCH/MISMATCH (exit 1), plus the unfingerprinted-objects report
-  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive.
+  everystack db:reconcile      [--stage <name> | --database-url <url>] [--apply] [--check] [--baseline] [--rebuild] [--overwrite-drift] [--only a,b] [--json]  Reconcile the derived layer (functions/views/matviews/triggers) against the DECLARED descriptors (defineView/defineMaterializedView/defineFunction/defineSql/trigger() on models, from the barrel) — the single home (db/sql is retired; leftover .sql files fail with the migration path): plan with rebuild-cost estimates by default; --check is the CI gate; --apply executes (atomic — DDL + provenance in one transaction) and records provenance + schema_log; --apply --stage runs credential-free in the ops Lambda (no admin URL on the deployer, the db:apply twin), --apply --database-url runs direct. Hand-edits are drift (never overwritten silently). First contact with existing objects: --baseline TRUSTS live == source (records provenance, verifies nothing), --rebuild GUARANTEES it (drop+create from source). They are mutually exclusive. --only <schema.name,…> restricts the run to the named objects (surgical); with --rebuild it FORCES those to rebuild from source even when the hashes show no diff — the recovery exit when a mistaken --rebaseline left a self-consistent-but-wrong provenance row (the dependency cascade rebuilds their live dependents).
   everystack db:refresh        [--stage <name> | --database-url <url> | --direct] [--only a,b] [--list]  Refresh the declared materialized views in dependency order, credential-free. --stage runs the whole refresh in the ops Lambda on the operator connection (no URL on the operator's machine — the data-lane twin of the reconcile lane); --database-url/--direct refresh over a direct connection (dev); --only refreshes a named subset (full identity or bare name); --list previews the order without connecting. Plain REFRESH (ACCESS EXCLUSIVE); fail-fast, idempotent to re-run.
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)