@everystack/cli 0.4.19 → 0.4.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.19",
+  "version": "0.4.22",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -37,6 +37,10 @@
       "types": "./src/cli/apply-execute.ts",
       "default": "./src/cli/apply-execute.ts"
     },
+    "./reconcile": {
+      "types": "./src/reconcile.ts",
+      "default": "./src/reconcile.ts"
+    },
     "./audit/source": {
       "types": "./src/cli/audit-source-api.ts",
       "default": "./src/cli/audit-source-api.ts"

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

@@ -23,10 +23,10 @@
  * explicit trust that live == source, recorded). A source RE-RENDER over an
  * untouched live object — the db/sql-era → descriptor migration — needs
  * `--rebaseline` once: live is verified (defHash match), the new source hash
- * is re-recorded, nothing rebuilds. `--apply` needs a direct
- * connection (`--database-url` / DATABASE_URL): the ops Lambda `db:query`
- * path is read-only by design, so plan/check work anywhere but writes go
- * through a credentialed connection you chose to hold.
+ * is re-recorded, nothing rebuilds. `--apply --stage` runs the whole reconcile
+ * credential-free in the ops Lambda on the operator connection (the `db:reconcile`
+ * action, the db:apply twin) — the deployer holds no URL. `--apply --database-url`
+ * runs it direct. A stage DRY-RUN (no `--apply`) reads through the `db:query` path.
  */
 
 import type { QueryRunner } from '../authz-contract.js';
@@ -380,11 +380,6 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
-  if (apply && dbSource.kind !== 'url') {
-    fail('--apply needs a direct connection (--database-url or DATABASE_URL) — the ops Lambda query path is read-only by design.');
-    process.exit(1);
-  }
-
   // --baseline only writes under --apply (executeReconcile returns the plan and executes nothing
   // when apply=false). Passing it alone used to print "recording provenance…" and exit 0 while
   // persisting nothing — a silent no-op. Fail loudly instead; the plan already lists needsBaseline.
@@ -416,29 +411,51 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     info(`${declared.objects.length} declared derived object(s) from the models barrel.`);
   }
 
-  let runner: QueryRunner;
-  let end: (() => Promise<void>) | undefined;
-  if (dbSource.kind === 'url') {
-    step(connectingVia(dbSource));
-    ({ runner, end } = await createUrlRunner(dbSource.url));
-  } else {
-    step('Resolving deployed config...');
-    const config = await resolveConfig(flags.stage);
-    runner = lambdaRunner(config.region, opsFunction(config));
-  }
+  const reconcileOptions = {
+    apply,
+    declared: declared?.objects,
+    renamedTables: declared?.renamedTables,
+    baseline: flags.baseline === 'true',
+    rebaseline: flags.rebaseline === 'true',
+    rebuild: flags.rebuild === 'true',
+    overwriteDrift: flags['overwrite-drift'] === 'true',
+    actor: process.env.USER ?? null,
+    gitRef: currentGitRef(),
+  };
 
+  // Resolve the run from one of two venues:
+  //  - --apply on a deployed stage runs the WHOLE reconcile in the ops Lambda on the operator
+  //    connection (the db:reconcile action) — a least-privileged operator needs no raw admin URL,
+  //    the derived-edge twin of db:apply.
+  //  - otherwise executeReconcile runs locally over a direct URL, or over the read-only db:query
+  //    path for a stage DRY-RUN (planning only reads).
+  let end: (() => Promise<void>) | undefined;
   try {
-    const run = await executeReconcile(runner, {
-      apply,
-      declared: declared?.objects,
-      renamedTables: declared?.renamedTables,
-      baseline: flags.baseline === 'true',
-      rebaseline: flags.rebaseline === 'true',
-      rebuild: flags.rebuild === 'true',
-      overwriteDrift: flags['overwrite-drift'] === 'true',
-      actor: process.env.USER ?? null,
-      gitRef: currentGitRef(),
-    });
+    let run: ReconcileRun;
+    if (apply && dbSource.kind !== 'url') {
+      step('Resolving deployed config...');
+      const config = await resolveConfig(flags.stage);
+      const result: any = await invokeAction(config.region, opsFunction(config), 'db:reconcile', reconcileOptions);
+      if (result?.error) {
+        fail(`db:reconcile failed: ${result.error}`);
+        if (/Unknown action/i.test(String(result.error))) {
+          info('The deployed handler predates the db:reconcile ops action (needs @everystack/server >= 0.4.8). Upgrade the server, or apply direct: db:reconcile --apply --database-url <url>.');
+        }
+        process.exit(1);
+      }
+      run = { plan: result.plan, applied: result.applied, statements: result.statements ?? [], refusal: result.refusal ?? undefined };
+    } else {
+      let runner: QueryRunner;
+      if (dbSource.kind === 'url') {
+        step(connectingVia(dbSource));
+        ({ runner, end } = await createUrlRunner(dbSource.url));
+      } else {
+        step('Resolving deployed config...');
+        const config = await resolveConfig(flags.stage);
+        runner = lambdaRunner(config.region, opsFunction(config));
+      }
+      run = await executeReconcile(runner, reconcileOptions);
+    }
 
     if (flags.json === 'true') {
       console.log(JSON.stringify({ ...run.plan, applied: run.applied, refusal: run.refusal ?? null }, null, 2));

package/src/cli/commands/db.ts

@@ -207,9 +207,103 @@ export function buildProvisionSecretPlan(args: {
   return { updates, notes, warnings };
 }
 
+/** The provisioning core's shape (mirrors @everystack/server/provision — no compile-time dep,
+ *  same seam as pipeline-loader). */
+export interface ServerProvision {
+  runProvision(
+    payload: { authPassword?: string; adminPassword?: string },
+    deps: {
+      execute: (sql: string) => Promise<unknown>;
+      connection?: { host: string; port?: number | string; database: string } | null;
+      connectProbe?: (url: string) => Promise<void>;
+    },
+  ): Promise<any>;
+}
+
+/**
+ * Lazily load the provisioning core from the @everystack/server peer (runtime only —
+ * the CLI keeps no compile-time dependency on the server package). A missing peer gets
+ * the install remedy, not a raw ERR_MODULE_NOT_FOUND.
+ */
+export async function loadServerProvision(importer?: () => Promise<unknown>): Promise<ServerProvision> {
+  const spec = '@everystack/server/provision';
+  try {
+    return (await (importer ? importer() : import(spec))) as ServerProvision;
+  } catch (err: unknown) {
+    const code = (err as { code?: string })?.code;
+    const message = String((err as { message?: string })?.message ?? err);
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND' || /Cannot find (package|module)/.test(message)) {
+      throw new Error(
+        'db:provision --database-url needs @everystack/server (>= 0.4.6) installed in this app — '
+        + 'it carries the provisioning logic:\n  pnpm add @everystack/server',
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Resolve the DIRECT-venue privileged URL, keeping the master password OFF argv (shell
+ * history / ps / CI logs are all leak surfaces, and the whole point of provision is to STOP
+ * using master). An explicit --database-url wins; `--direct` reads the stage's already-stored
+ * ADMIN_DATABASE_URL secret; no flag returns null (the ops-Lambda venue). A consumer report:
+ * "any workflow that requires a human to re-handle the master DB password is both friction and
+ * a secret-leak point."
+ */
+export function resolveProvisionDirectUrl(args: {
+  flagUrl?: string;
+  direct?: boolean;
+  secrets: Record<string, string>;
+}): { url: string; source: 'flag' | 'secret' } | null {
+  if (args.flagUrl) return { url: args.flagUrl, source: 'flag' };
+  if (args.direct) {
+    const url = args.secrets.ADMIN_DATABASE_URL ?? args.secrets.AdminDatabaseUrl;
+    if (!url) {
+      throw new Error(
+        '--direct needs the stage\'s ADMIN_DATABASE_URL secret (the privileged URL) — set it with '
+        + '`everystack secrets set ADMIN_DATABASE_URL <url> --stage <stage>`, or pass --database-url <url> once.',
+      );
+    }
+    return { url, source: 'secret' };
+  }
+  return null;
+}
+
+/** The declared non-public schemas (sorted, public trailing) — the API connection's search_path.
+ *  Empty for an all-public app, so its URL is left byte-identical. */
+export function declaredSearchPath(schemas: string[]): string[] {
+  const nonPublic = [...new Set(schemas)].filter((s) => s && s !== 'public').sort();
+  return nonPublic.length ? [...nonPublic, 'public'] : [];
+}
+
+/**
+ * Bake the declared schemas into a postgres URL as `?search_path=…`. A multi-schema app's role
+ * defaults to `"$user",public`, so every bare-ref query 404s until a hand ALTER ROLE pin
+ * (recorded nowhere, repeated every stage) — writing it into the minted DATABASE_URL is
+ * declarative and survives redeploys. postgres.js forwards unknown URL params as connection
+ * startup params (GridironDB proved search_path this way). No-op for an all-public app.
+ */
+export function withSearchPath(url: string, schemas: string[]): string {
+  const path = declaredSearchPath(schemas);
+  if (!path.length) return url;
+  const u = new URL(url);
+  u.searchParams.set('search_path', path.join(','));
+  return u.toString();
+}
+
+/** host/port/database from a postgres URL — the direct venue's connection info. */
+export function parseUrlConnection(url: string): { host: string; port: string; database: string } {
+  const u = new URL(url);
+  return {
+    host: u.hostname,
+    port: u.port || '5432',
+    database: u.pathname.replace(/^\//, ''),
+  };
+}
+
 export async function dbProvisionCommand(flags: Record<string, string>): Promise<void> {
   if (!flags.stage) {
-    fail('--stage is required for db:provision (it writes the DATABASE_URL secret for that stage)');
+    fail('--stage is required for db:provision (it writes the stage\'s DATABASE_URL secret — the new credentials are never displayed, so they must land in the secret store)');
     process.exit(1);
   }
 
@@ -222,7 +316,37 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
     process.exit(1);
   }
 
-  info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  // Load the stage secrets once — the direct venue reads the privileged URL from here (never
+  // from argv), and the writer below reuses them.
+  const { loadSstSecrets, putSstSecrets } = await import('../utils/secrets.js');
+  const { parseAppName } = await import('../discover.js');
+  const secretsCtx = { appName: await parseAppName(), stage: flags.stage, region: config.region };
+  let stageSecrets: Record<string, string> = {};
+  try {
+    stageSecrets = await loadSstSecrets(secretsCtx);
+  } catch {
+    // Secrets unreadable (e.g. store not bootstrapped) — direct-from-secret is simply unavailable;
+    // an explicit --database-url still works, and the writer below surfaces any real failure.
+  }
+
+  // Venue: DIRECT connection (bring-your-own-RDS / no Ops Lambda) vs the ops-Lambda invoke.
+  // --database-url is explicit; --direct reads the ADMIN_DATABASE_URL secret so master never
+  // lands on argv. No flag = ops-Lambda venue, with an auto-fallback to the secret-backed
+  // direct connection when the deployed handler has no dbPlugin. --stage always names the
+  // secret store the new credentials are written to.
+  let venue: { url: string; source: 'flag' | 'secret' } | null;
+  try {
+    venue = resolveProvisionDirectUrl({ flagUrl: flags['database-url'], direct: !!flags.direct, secrets: stageSecrets });
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  let directUrl = venue?.url;
+  if (directUrl) {
+    info(`Region: ${config.region}, venue: direct connection (${venue!.source === 'secret' ? 'ADMIN_DATABASE_URL secret' : 'bring-your-own database'})`);
+  } else {
+    info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
+  }
   info('Creating the least-privilege role chain on your EXISTING database (no database is created).');
   step('Provisioning roles...');
 
@@ -232,13 +356,71 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   const authPassword = randomBytes(24).toString('hex');
   const adminPassword = randomBytes(24).toString('hex');
 
+  // Run the role chain over a direct connection to `url` — shared by the explicit direct venue
+  // and the auto-fallback below.
+  const provisionDirect = async (url: string): Promise<any> => {
+    const { runProvision } = await loadServerProvision();
+    const { createUrlRunner } = await import('../db-source.js');
+    const { runner, end } = await createUrlRunner(url);
+    try {
+      return await runProvision({ authPassword, adminPassword }, {
+        execute: async (statement) => runner(statement),
+        connection: parseUrlConnection(url),
+        // Same probe as the ops-Lambda venue: a real login as the new role, DDL-capable.
+        connectProbe: async (probeUrl) => {
+          const { default: postgres } = await import('postgres');
+          const probe = postgres(probeUrl, { max: 1, connect_timeout: 5, ssl: 'prefer' });
+          try {
+            await probe`SELECT 1`;
+            await probe.unsafe('CREATE TEMP TABLE _everystack_provision_probe (x int)');
+            await probe.unsafe('DROP TABLE _everystack_provision_probe');
+          } finally {
+            await probe.end({ timeout: 1 });
+          }
+        },
+      });
+    } finally {
+      await end?.();
+    }
+  };
+
   let result: any;
-  try {
-    result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword, adminPassword });
-  } catch (err: any) {
-    fail(`db:provision failed: ${err.message}`);
-    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
-    process.exit(1);
+  let conn: any;
+  if (directUrl) {
+    try {
+      result = await provisionDirect(directUrl);
+    } catch (err: any) {
+      fail(`db:provision failed: ${err.message}`);
+      process.exit(1);
+    }
+    conn = parseUrlConnection(directUrl);
+  } else {
+    try {
+      result = await invokeAction(config.region, opsFunction(config), 'db:provision', { authPassword, adminPassword });
+    } catch (err: any) {
+      // Auto-fallback: no Ops Lambda (Unknown action), but an ADMIN_DATABASE_URL secret exists —
+      // provision directly over it. Master never crosses the CLI; the operator sets nothing new.
+      const secretUrl = stageSecrets.ADMIN_DATABASE_URL ?? stageSecrets.AdminDatabaseUrl;
+      if (/Unknown action/i.test(String(err.message)) && secretUrl) {
+        info('No Ops Lambda (the deployed handler has no dbPlugin) — provisioning directly over the ADMIN_DATABASE_URL secret.');
+        try {
+          result = await provisionDirect(secretUrl);
+          directUrl = secretUrl;
+          conn = parseUrlConnection(secretUrl);
+        } catch (err2: any) {
+          fail(`db:provision failed: ${err2.message}`);
+          process.exit(1);
+        }
+      } else {
+        fail(`db:provision failed: ${err.message}`);
+        if (/Unknown action/i.test(String(err.message))) {
+          info('The deployed handler has no dbPlugin (no Ops Lambda), and no ADMIN_DATABASE_URL secret is set.');
+          info('Provision directly: everystack db:provision --stage <stage> --database-url <master-url> (once), or set the ADMIN_DATABASE_URL secret and use --direct.');
+        }
+        for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
+        process.exit(1);
+      }
+    }
   }
   if (result?.error) {
     // Includes the admin-verification refusal: the action set NO authenticator password,
@@ -252,35 +434,60 @@ export async function dbProvisionCommand(flags: Record<string, string>): Promise
   }
 
   // Resolve host/port/db (not secret) to build the connection strings in memory.
-  let conn: any;
-  try {
-    conn = await invokeAction(config.region, opsFunction(config), 'db:psql', {});
-  } catch {
-    /* handled below */
+  // Direct venue already knows them from the URL itself.
+  if (!directUrl) {
+    try {
+      conn = await invokeAction(config.region, opsFunction(config), 'db:psql', {});
+    } catch {
+      /* handled below */
+    }
   }
   if (!conn?.host) {
     fail('Could not resolve the database host to build DATABASE_URL.');
     info('Provide a db:psql connectionInfo callback, or set the DATABASE_URL secret yourself.');
     process.exit(1);
   }
-  const authUrl = `postgresql://${result.loginRole}:${authPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`;
+  // Echo the NON-SECRET target so the operator can confirm which database the secrets landed on,
+  // WITHOUT psql'ing the master in to check the prompt (a consumer burned time on a phantom
+  // wrong-database scare, and that check meant re-handling the master credential).
+  success(`Target database: ${conn.database} @ ${conn.host}:${conn.port ?? 5432} — secrets for stage "${flags.stage}" will point here.`);
+
+  // Bake the app's declared schemas into the minted URLs, so a multi-schema API connects with
+  // the right search_path instead of going dark on bare refs (best-effort: a modelless app or
+  // an all-public one changes nothing).
+  let declaredSchemas: string[] = [];
+  try {
+    const { resolveModelsPath } = await import('../models-path.js');
+    const { loadModels } = await import('./db-generate.js');
+    const models = await loadModels(resolveModelsPath(flags.models));
+    declaredSchemas = models.map((m: any) => m.schema ?? 'public');
+  } catch {
+    // No models resolvable here — leave the URLs schema-agnostic.
+  }
+  const searchPath = declaredSearchPath(declaredSchemas);
+  if (searchPath.length) info(`  search_path baked into DATABASE_URL: ${searchPath.join(', ')}`);
+
+  const authUrl = withSearchPath(
+    `postgresql://${result.loginRole}:${authPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`,
+    declaredSchemas,
+  );
   const adminUrl = result.adminRole
-    ? `postgresql://${result.adminRole}:${adminPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`
+    ? withSearchPath(
+        `postgresql://${result.adminRole}:${adminPassword}@${conn.host}:${conn.port ?? 5432}/${conn.database}`,
+        declaredSchemas,
+      )
     : undefined;
 
   // Write the secrets directly to the SST secret store — never display them. One blob
   // write updates every key together, so there is no window where the API side is the
-  // authenticator but the operator side is still unset.
+  // authenticator but the operator side is still unset. Reuse the secrets loaded up front.
   step('Writing the database secrets (not displayed)...');
   let plan: ProvisionSecretPlan;
   try {
-    const { loadSstSecrets, putSstSecrets } = await import('../utils/secrets.js');
-    const { parseAppName } = await import('../discover.js');
-    const ctx = { appName: await parseAppName(), stage: flags.stage, region: config.region };
-    const secrets = await loadSstSecrets(ctx);
+    const secrets = { ...stageSecrets };
     plan = buildProvisionSecretPlan({ result, authUrl, adminUrl, existing: secrets });
     Object.assign(secrets, plan.updates);
-    await putSstSecrets(ctx, secrets);
+    await putSstSecrets(secretsCtx, secrets);
   } catch (err: any) {
     fail(`Failed to write the database secrets: ${err.message}`);
     info('Ensure your IAM role can write the SST secret store (s3:PutObject, kms:Encrypt).');
@@ -321,17 +528,26 @@ export async function dbDoctorCommand(flags: Record<string, string>): Promise<vo
   info(`Region: ${config.region}, Function: ${opsFunction(config)}`);
   step('Probing database connections (api + operator)...');
 
+  const noOpsHint = () => {
+    // Name the cause, not the internal dispatch: a bring-your-own-DB app has no Ops Lambda, so
+    // db:doctor's action can't be dispatched. It has no direct venue yet — say so plainly.
+    info('This deployed handler has no dbPlugin (no Ops Lambda), so db:doctor has nothing to run against.');
+    info('db:doctor has no --database-url venue yet (unlike db:provision). To verify a bring-your-own database meanwhile, apply grants with `db:reconcile --apply --database-url <url>` and inspect roles/grants with psql. A direct db:doctor venue is on the way.');
+  };
+
   let report: any;
   try {
     report = await invokeAction(config.region, opsFunction(config), 'db:doctor', {});
   } catch (err: any) {
     fail(`db:doctor failed: ${err.message}`);
-    for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
+    if (/Unknown action/i.test(String(err.message))) noOpsHint();
+    else for (const line of opsAdviceLines(err, [IAM_ADVICE])) info(line);
     process.exit(1);
   }
 
   if (report?.error) {
     fail(`db:doctor failed: ${report.error}`);
+    if (/Unknown action/i.test(String(report.error))) noOpsHint();
     process.exit(1);
   }
 

package/src/cli/commands/update.ts

@@ -32,6 +32,46 @@ export interface UpdateFlags {
   export?: string;
 }
 
+/**
+ * The runtimeVersion as a STRING — the only shape the release path can carry.
+ * Expo's config allows a policy object; interpolating one into the S3 key
+ * produced `releases/dev/[object Object]/…` (a consumer field report). Locally
+ * derivable policies resolve here; the build-time ones (fingerprint,
+ * nativeVersion — computed by native tooling, undefined for a web publish)
+ * are refused with the remedies instead of silently corrupting the key.
+ */
+export function resolveRuntimeVersion(appConfig: {
+  runtimeVersion?: unknown;
+  version?: string;
+  sdkVersion?: string;
+}): string {
+  const rv = appConfig.runtimeVersion;
+  if (typeof rv === 'string') return rv;
+  const policy = (rv as { policy?: string } | undefined)?.policy;
+  if (policy === 'appVersion') {
+    if (!appConfig.version) {
+      throw new Error("runtimeVersion policy 'appVersion' needs a \"version\" field in app.json — add one, or set an explicit string runtimeVersion.");
+    }
+    return appConfig.version;
+  }
+  if (policy === 'sdkVersion') {
+    if (!appConfig.sdkVersion) {
+      throw new Error("runtimeVersion policy 'sdkVersion' needs an \"sdkVersion\" field in app.json — add one, or set an explicit string runtimeVersion.");
+    }
+    return appConfig.sdkVersion;
+  }
+  if (policy === 'fingerprint' || policy === 'nativeVersion') {
+    throw new Error(
+      `runtimeVersion policy '${policy}' is computed by the native build tooling (EAS / @expo/fingerprint) — `
+      + 'everystack update cannot resolve it, and for a web publish it is undefined. '
+      + 'Use an explicit string runtimeVersion, or { "policy": "appVersion" } to track your app version.',
+    );
+  }
+  throw new Error(
+    `Unsupported runtimeVersion ${JSON.stringify(rv)} — use an explicit string, { "policy": "appVersion" }, or { "policy": "sdkVersion" }.`,
+  );
+}
+
 export async function updateCommand(flags: UpdateFlags & Record<string, string>): Promise<void> {
   // Signal publish context so app.config.js can detect it's not a dev session.
   // Without this, dotenv guards that skip .env.local for EAS_BUILD/EAS_UPDATE
@@ -98,15 +138,22 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
   // Read app config
   step('Reading app config...');
   const appConfig = await loadAppConfig();
-  const runtimeVersion = appConfig.runtimeVersion;
 
-  if (!runtimeVersion) {
+  if (!appConfig.runtimeVersion) {
     fail('No runtimeVersion found in app.json/app.config.js');
     info('Add "runtimeVersion" to your app.json, e.g.:');
-    info('  { "expo": { "runtimeVersion": { "policy": "fingerprint" } } }');
+    info('  { "expo": { "runtimeVersion": "1.0.0" } }        (explicit string)');
+    info('  { "expo": { "runtimeVersion": { "policy": "appVersion" } } }  (tracks "version")');
     info('See: https://docs.expo.dev/eas-update/runtime-versions/');
     process.exit(1);
   }
+  let runtimeVersion: string;
+  try {
+    runtimeVersion = resolveRuntimeVersion(appConfig);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
   success(`Runtime version: ${runtimeVersion}`);
 
   const distDir = path.resolve('dist');
@@ -561,13 +608,20 @@ export async function updateCommand(flags: UpdateFlags & Record<string, string>)
         );
         if (result?.error) {
           info(`DB mirror skipped: ${result.error}`);
+          // The dispatcher answers Unknown action as result.error, not a throw — explain
+          // there too, or the miss reads like a failure with no remedy.
+          if (/Unknown action/i.test(String(result.error))) {
+            info('This is optional — the S3 manifests are the source of truth for serving.');
+            info('For DB-backed release tracking, add updatesPlugin (from @everystack/cli/plugin) to the deployed handler.');
+          }
         } else {
           info(`Release mirrored to DB: channel=${result?.channel || channel}`);
         }
       } catch (err: any) {
         // register-web is optional — the S3 manifests are the source of truth.
         if (err.message?.includes('Unknown action')) {
-          info('Tip: add a "register-web" case to onAction for DB-backed release tracking.');
+          info('DB mirror skipped (optional — S3 manifests are the source of truth).');
+          info('For DB-backed release tracking, add updatesPlugin (from @everystack/cli/plugin) to the deployed handler.');
         } else {
           info(`DB mirror skipped: ${err.message}`);
         }

package/src/cli/index.ts

@@ -353,7 +353,7 @@ Usage:
   everystack db:psql           --stage <name>  Interactive ADMIN psql (IAM-gated; resolves the admin URL in-process)
   everystack db:psql           [--stage <name>] -c <command>  Run one query via Lambda (works for private RDS)
   everystack db:doctor         [--stage <name>]  Check the DB is least-privilege + RLS-subject (api vs operator connection)
-  everystack db:provision      [--stage <name>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB)
+  everystack db:provision      --stage <name> [--direct | --database-url <url>]  Create the least-privilege role chain on an EXISTING database (idempotent; creates no DB). No flag = ops-Lambda venue (auto-falls to direct via the ADMIN_DATABASE_URL secret if the handler has no dbPlugin). --direct = direct connection reading that secret (master never on argv); --database-url = explicit URL. Declared schemas are baked into the minted DATABASE_URL as search_path
   everystack db:snapshot       [--stage <name>] [--instance <id>]  Take a physical RDS snapshot (instant DR point; RDS only — use db:backup for portable logical backups)
   everystack db:snapshots      [--stage <name>] [--instance <id>]  List manual RDS snapshots for the instance
   everystack db:backup:probe   [--stage <name>]  Verify the pg_dump layer is attached + version-compatible with the server
@@ -367,7 +367,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 (direct connection only, atomic — DDL + provenance in one transaction) and records provenance + schema_log. 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] [--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: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)
   everystack db:plan           [--stage <name> | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only — works via the ops Lambda; plans are ephemeral, never committed

package/src/reconcile.ts

@@ -0,0 +1,11 @@
+/**
+ * @everystack/cli/reconcile — the derived-layer reconcile core, for the ops-Lambda lane.
+ *
+ * db:apply runs the STATE edge credential-free in the ops Lambda (@everystack/cli/apply). This is
+ * its DERIVED-edge twin: the ops `db:reconcile` action loads executeReconcile here and runs the
+ * whole reconcile (introspect → plan → apply) on the operator connection, so `db:reconcile --apply
+ * --stage` needs no raw admin URL on the deployer's machine.
+ */
+
+export { executeReconcile, buildReconcileReport } from './cli/commands/db-reconcile.js';
+export type { ReconcileRun, ExecuteOptions } from './cli/commands/db-reconcile.js';