@everystack/cli 0.4.17 → 0.4.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -76,6 +76,11 @@
   "dependencies": {
     "@aws-sdk/client-cloudfront": "3.1053.0",
     "@aws-sdk/client-cloudfront-keyvaluestore": "3.1053.0",
+    "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
+    "@aws-sdk/client-lambda": "3.1053.0",
+    "@aws-sdk/client-s3": "3.1053.0",
+    "@aws-sdk/client-ssm": "3.1053.0",
+    "@aws-sdk/client-sts": "3.1053.0",
     "@aws-sdk/signature-v4a": "3.1048.0",
     "glob": "13.0.6",
     "node-forge": "1.4.0",
@@ -87,18 +92,13 @@
   "peerDependencies": {
     "@everystack/server": ">=0.1.0",
     "@aws-sdk/client-cloudwatch": "3.1053.0",
-    "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
-    "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-rds": "3.1053.0",
-    "@aws-sdk/client-s3": "3.1053.0",
-    "@aws-sdk/client-ssm": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "drizzle-orm": "0.41.0",
     "expo-updates": "55.0.21",
     "postgres": "3.4.9",
     "react": "19.2.0",
-    "react-native": "0.83.6",
-    "@aws-sdk/client-sts": "3.1053.0"
+    "react-native": "0.83.6"
   },
   "peerDependenciesMeta": {
     "postgres": {
@@ -110,21 +110,9 @@
     "@aws-sdk/client-cloudwatch": {
       "optional": true
     },
-    "@aws-sdk/client-cloudwatch-logs": {
-      "optional": true
-    },
-    "@aws-sdk/client-s3": {
-      "optional": true
-    },
-    "@aws-sdk/client-lambda": {
-      "optional": true
-    },
     "@aws-sdk/client-rds": {
       "optional": true
     },
-    "@aws-sdk/client-ssm": {
-      "optional": true
-    },
     "expo-updates": {
       "optional": true
     },
@@ -136,18 +124,11 @@
     },
     "@aws-sdk/s3-request-presigner": {
       "optional": true
-    },
-    "@aws-sdk/client-sts": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@aws-sdk/client-cloudwatch": "3.1053.0",
-    "@aws-sdk/client-cloudwatch-logs": "3.1053.0",
-    "@aws-sdk/client-lambda": "3.1053.0",
     "@aws-sdk/client-rds": "3.1053.0",
-    "@aws-sdk/client-s3": "3.1053.0",
-    "@aws-sdk/client-ssm": "3.1053.0",
     "@aws-sdk/s3-request-presigner": "3.1053.0",
     "@types/jest": "29.5.14",
     "@types/node": "22.19.18",
@@ -156,8 +137,7 @@
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
     "react": "19.2.0",
-    "ts-jest": "29.4.9",
-    "@aws-sdk/client-sts": "3.1053.0"
+    "ts-jest": "29.4.9"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-authority.ts

@@ -24,6 +24,8 @@
  * by the command shell.
  */
 
+import { importOptionalAws } from './aws.js';
+
 /** The SSM parameter holding the approver set — a JSON array of entries. */
 export function approverParamName(appName: string, stage: string): string {
   return `/everystack/${appName}/${stage}/db-approvers`;
@@ -89,7 +91,9 @@ export function checkDestructiveAuthority({ approvers, identity }: AuthorityInpu
 
 /** Read the approver set from SSM. Null when the parameter does not exist. */
 export async function readApproverParam(region: string, appName: string, stage: string): Promise<string[] | null> {
-  const { SSMClient, GetParameterCommand } = await import('@aws-sdk/client-ssm');
+  const { SSMClient, GetParameterCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-ssm'), '@aws-sdk/client-ssm', 'db:approvers',
+  );
   const client = new SSMClient({ region });
   try {
     const result = await client.send(new GetParameterCommand({ Name: approverParamName(appName, stage) }));
@@ -116,7 +120,9 @@ export function parseApproverValue(value: string): string[] {
 
 /** Declare (or replace) the approver set. Stored as a JSON array. */
 export async function writeApproverParam(region: string, appName: string, stage: string, approvers: string[]): Promise<void> {
-  const { SSMClient, PutParameterCommand } = await import('@aws-sdk/client-ssm');
+  const { SSMClient, PutParameterCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-ssm'), '@aws-sdk/client-ssm', 'db:approvers',
+  );
   const client = new SSMClient({ region });
   await client.send(new PutParameterCommand({
     Name: approverParamName(appName, stage),
@@ -128,7 +134,9 @@ export async function writeApproverParam(region: string, appName: string, stage:
 
 /** Remove the declaration entirely — the stage returns to the undeclared (ceremony-only) posture. */
 export async function removeApproverParam(region: string, appName: string, stage: string): Promise<void> {
-  const { SSMClient, DeleteParameterCommand } = await import('@aws-sdk/client-ssm');
+  const { SSMClient, DeleteParameterCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-ssm'), '@aws-sdk/client-ssm', 'db:approvers',
+  );
   const client = new SSMClient({ region });
   try {
     await client.send(new DeleteParameterCommand({ Name: approverParamName(appName, stage) }));
@@ -139,7 +147,9 @@ export async function removeApproverParam(region: string, appName: string, stage
 
 /** The caller's real identity — the STS ARN. Null when credentials can't answer. */
 export async function resolveCallerIdentity(region: string): Promise<string | null> {
-  const { STSClient, GetCallerIdentityCommand } = await import('@aws-sdk/client-sts');
+  const { STSClient, GetCallerIdentityCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-sts'), '@aws-sdk/client-sts', 'destructive apply authorization',
+  );
   const client = new STSClient({ region });
   try {
     const result = await client.send(new GetCallerIdentityCommand({}));

package/src/cli/aws.ts

@@ -15,7 +15,9 @@ let rdsClient: InstanceType<typeof import('@aws-sdk/client-rds').RDSClient> | nu
 
 async function getS3(region: string) {
   if (!s3Client) {
-    const { S3Client } = await import('@aws-sdk/client-s3');
+    const { S3Client } = await importOptionalAws(
+      () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'this command',
+    );
     s3Client = new S3Client({ region });
   }
   return s3Client;
@@ -23,12 +25,49 @@ async function getS3(region: string) {
 
 async function getLambda(region: string) {
   if (!lambdaClient) {
-    const { LambdaClient } = await import('@aws-sdk/client-lambda');
+    const { LambdaClient } = await importOptionalAws(
+      () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'this command',
+    );
     lambdaClient = new LambdaClient({ region });
   }
   return lambdaClient;
 }
 
+/**
+ * A missing optional-peer dependency, marked so a command's catch block can print the install
+ * remedy INSTEAD of its default AWS/IAM advice. Blaming IAM for a missing npm package sends the
+ * operator to debug permissions they already have (a consumer field report).
+ */
+export class MissingOptionalDependencyError extends Error {
+  readonly missing: string[];
+  constructor(feature: string, missing: string[]) {
+    const plural = missing.length > 1;
+    super(
+      `${feature} needs ${missing.join(', ')}, which ${plural ? 'are' : 'is'} not installed `
+      + `(optional peer ${plural ? 'dependencies' : 'dependency'}). Install ${plural ? 'them' : 'it'}:\n`
+      + `  pnpm add ${missing.join(' ')}`,
+    );
+    this.name = 'MissingOptionalDependencyError';
+    this.missing = missing;
+  }
+}
+
+/** True when `err` is a missing optional dependency — the signal to skip IAM advice. */
+export function isMissingOptionalDependencyError(err: unknown): boolean {
+  return err instanceof MissingOptionalDependencyError;
+}
+
+/** Whether a caught error is Node's "package/module not found" (ESM or CJS). */
+function isModuleNotFound(err: unknown): boolean {
+  const code = (err as { code?: string })?.code;
+  const message = String((err as { message?: string })?.message ?? err);
+  return (
+    code === 'ERR_MODULE_NOT_FOUND' ||
+    code === 'MODULE_NOT_FOUND' ||
+    /Cannot find (package|module)/.test(message)
+  );
+}
+
 /**
  * Lazily load an optional-peer AWS SDK client, turning a missing dependency into a one-line
  * install remedy instead of a raw `ERR_MODULE_NOT_FOUND` at the call site. The `@aws-sdk/*`
@@ -44,21 +83,35 @@ export async function importOptionalAws<T>(
   try {
     return await load();
   } 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(
-        `${feature} needs ${pkg}, which isn't installed (it's an optional peer dependency). Install it:\n  pnpm add ${pkg}`,
-      );
-    }
+    if (isModuleNotFound(err)) throw new MissingOptionalDependencyError(feature, [pkg]);
     throw err;
   }
 }
 
+/**
+ * Preflight EVERY optional-peer package a command needs, and name the FULL missing set in one
+ * error — not one crash at a time. A command that uses ssm+s3 (secrets) reports both missing at
+ * once with a single `pnpm add` line, so the operator installs everything the step needs in one
+ * go instead of discovering them serially through repeated failures (a consumer field report).
+ * Each `load` is a literal `() => import('@aws-sdk/...')` so the specifiers stay statically
+ * analyzable; ESM caches the module, so the real call site re-imports for free.
+ */
+export async function ensureOptionalAws(
+  deps: Array<{ load: () => Promise<unknown>; pkg: string }>,
+  feature: string,
+): Promise<void> {
+  const missing: string[] = [];
+  for (const { load, pkg } of deps) {
+    try {
+      await load();
+    } catch (err: unknown) {
+      if (isModuleNotFound(err)) missing.push(pkg);
+      else throw err;
+    }
+  }
+  if (missing.length > 0) throw new MissingOptionalDependencyError(feature, missing);
+}
+
 async function getRds(region: string) {
   if (!rdsClient) {
     const { RDSClient } = await importOptionalAws(
@@ -206,7 +259,9 @@ export async function resolveFunctionName(
   // Include the trailing dash so the prefix can't match a longer resource name.
   const basePrefix = functionName.slice(0, lastDash + 1).toLowerCase();
 
-  const { LambdaClient, ListFunctionsCommand } = await import('@aws-sdk/client-lambda');
+  const { LambdaClient, ListFunctionsCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'this command',
+  );
   const client = new LambdaClient({ region });
 
   const candidates: Array<{ name: string; modified: number }> = [];
@@ -315,7 +370,9 @@ export async function invokeAction(
 
 /** Recent CloudWatch log text for a function's log group (last `windowMs`, capped). */
 async function fetchRecentLogText(region: string, logGroupName: string, windowMs = 5 * 60_000): Promise<string> {
-  const { CloudWatchLogsClient, FilterLogEventsCommand } = await import('@aws-sdk/client-cloudwatch-logs');
+  const { CloudWatchLogsClient, FilterLogEventsCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-cloudwatch-logs'), '@aws-sdk/client-cloudwatch-logs', 'reading logs',
+  );
   const client = new CloudWatchLogsClient({ region });
   const res = await client.send(new FilterLogEventsCommand({
     logGroupName,
@@ -331,7 +388,9 @@ export async function fetchRecentLogEvents(
   logGroupName: string,
   windowMs: number,
 ): Promise<Array<{ timestamp?: number; message?: string }>> {
-  const { CloudWatchLogsClient, FilterLogEventsCommand } = await import('@aws-sdk/client-cloudwatch-logs');
+  const { CloudWatchLogsClient, FilterLogEventsCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-cloudwatch-logs'), '@aws-sdk/client-cloudwatch-logs', 'reading logs',
+  );
   const client = new CloudWatchLogsClient({ region });
   const res = await client.send(new FilterLogEventsCommand({
     logGroupName,
@@ -376,7 +435,9 @@ async function defaultLogGroupIo(region: string): Promise<LogGroupIo> {
       return cfg.LoggingConfig?.LogGroup ?? undefined;
     },
     describeLogGroups: async (prefix, limit) => {
-      const { CloudWatchLogsClient, DescribeLogGroupsCommand } = await import('@aws-sdk/client-cloudwatch-logs');
+      const { CloudWatchLogsClient, DescribeLogGroupsCommand } = await importOptionalAws(
+        () => import('@aws-sdk/client-cloudwatch-logs'), '@aws-sdk/client-cloudwatch-logs', 'reading logs',
+      );
       const client = new CloudWatchLogsClient({ region });
       const res = await client.send(new DescribeLogGroupsCommand({ logGroupNamePrefix: prefix, limit }));
       return res.logGroups ?? [];
@@ -528,7 +589,9 @@ export async function presignGet(
 ): Promise<string> {
   const client = await getS3(region);
   const { GetObjectCommand } = await import('@aws-sdk/client-s3');
-  const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
+  const { getSignedUrl } = await importOptionalAws(
+    () => import('@aws-sdk/s3-request-presigner'), '@aws-sdk/s3-request-presigner', 'db:backup:download',
+  );
   return await getSignedUrl(client as any, new GetObjectCommand({ Bucket: bucket, Key: key }), { expiresIn });
 }
 

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

@@ -42,6 +42,7 @@ import {
   renderSchemaLogInsert,
   derivedSearchPath,
   renderSetSearchPath,
+  renderEnsureObjectSchemas,
   ENSURE_RECONCILER_SQL,
 } from '../derived-apply.js';
 import { resolveDbSource, createUrlRunner, connectingVia, type DbSource } from '../db-source.js';
@@ -151,6 +152,12 @@ export async function executeReconcile(
   // as it was. See derivedSearchPath.
   const setSearchPath = renderSetSearchPath(derivedSearchPath(parsed.objects), atomic);
 
+  // A schema populated only by derived objects has no model in it, so the state layer never
+  // CREATE SCHEMAs it — the derived apply ensures its own object schemas (+ their USAGE
+  // grants) before anything is created in them. Empty for all-public apps. See
+  // renderEnsureObjectSchemas.
+  const ensureSchemas = renderEnsureObjectSchemas(parsed.objects);
+
   if (atomic) await runner('BEGIN');
   try {
     // The session guard: postgres-js `max: 1` is a pool of one, not a session lease — a
@@ -166,7 +173,7 @@ export async function executeReconcile(
       if (atomic) {
         // The SET rides the same simple-query batch (and the same transaction) as the DDL,
         // so bare body refs resolve to their real schema; SET LOCAL resets it at COMMIT.
-        await runner([setSearchPath, ...rendered.statements].filter(Boolean).join(';\n'));
+        await runner([...ensureSchemas, setSearchPath, ...rendered.statements].filter(Boolean).join(';\n'));
       } else {
         // Self-committing statements (CONCURRENTLY, VACUUM) refuse ANY transaction block —
         // including the implicit one a joined multi-statement simple query runs in, so the
@@ -174,6 +181,7 @@ export async function executeReconcile(
         // earlier statements committed: the documented cost of the unwrapped path; the next
         // plan re-converges from what actually landed. The session SET precedes them so every
         // create resolves its bare refs.
+        for (const statement of ensureSchemas) await runner(statement);
         if (setSearchPath) await runner(setSearchPath);
         for (const statement of rendered.statements) await runner(statement);
       }
@@ -211,7 +219,7 @@ export async function executeReconcile(
     bookkeeping.push(renderSchemaLogInsert({
       kind: 'compute reconcile',
       sql: rendered.statements.length > 0
-        ? [setSearchPath, ...rendered.statements].filter(Boolean).join(';\n')
+        ? [...ensureSchemas, setSearchPath, ...rendered.statements].filter(Boolean).join(';\n')
         : '-- provenance-only (baseline/rebaseline/prune)',
       outcome: 'applied',
       actor: options.actor, gitRef: options.gitRef, planRef: options.planRef,

package/src/cli/commands/logs.ts

@@ -11,7 +11,7 @@
  */
 
 import { resolveConfig } from '../config.js';
-import { resolveLogGroup, fetchRecentLogEvents } from '../aws.js';
+import { resolveLogGroup, fetchRecentLogEvents, importOptionalAws } from '../aws.js';
 import { summarizeRuntimeFailures } from '../ops-diagnostics.js';
 import { queryLogArchive, type ObservabilityQuery } from '../observability.js';
 import { step, success, fail, info } from '../output.js';
@@ -281,9 +281,9 @@ export async function logsTailCommand(flags: Record<string, string>): Promise<vo
   step(`Tailing logs (filter: ${filterPattern || 'none'}, since: ${since})...`);
 
   try {
-    // Import AWS SDK dynamically
-    const { CloudWatchLogsClient, FilterLogEventsCommand } =
-      await import('@aws-sdk/client-cloudwatch-logs');
+    const { CloudWatchLogsClient, FilterLogEventsCommand } = await importOptionalAws(
+      () => import('@aws-sdk/client-cloudwatch-logs'), '@aws-sdk/client-cloudwatch-logs', 'logs:tail',
+    );
 
     const client = new CloudWatchLogsClient({ region: config.region });
 

package/src/cli/commands/secrets.ts

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { step, success, fail, info, warn } from '../output.js';
 import { loadSstSecrets, putSstSecrets } from '../utils/secrets.js';
 import { parseDotenv, serializeDotenv } from '../utils/dotenv.js';
+import { isMissingOptionalDependencyError } from '../aws.js';
 
 interface SecretsContext {
   appName: string;
@@ -296,7 +297,11 @@ export async function secretsCommand(
     }
   } catch (err: any) {
     fail(err.message);
-    info('Ensure your IAM user/role has ssm:GetParameter, s3:GetObject, and kms:Decrypt permissions.');
+    // A missing npm package is not an IAM problem — the message already names the install.
+    // Printing IAM advice here is the field-reported misdirection.
+    if (!isMissingOptionalDependencyError(err)) {
+      info('Ensure your IAM user/role has ssm:GetParameter, s3:GetObject, and kms:Decrypt permissions.');
+    }
     process.exit(1);
   }
 }

package/src/cli/commands/status.ts

@@ -12,7 +12,7 @@
  */
 
 import { resolveConfig, opsFunction, type CliConfig } from '../config.js';
-import { invokeAction } from '../aws.js';
+import { invokeAction, importOptionalAws } from '../aws.js';
 import { fail, info, step } from '../output.js';
 
 export interface MetricSpec {
@@ -70,7 +70,9 @@ async function defaultGetMetric(
   spec: MetricSpec,
   hours: number,
 ): Promise<number | null> {
-  const { CloudWatchClient, GetMetricDataCommand } = await import('@aws-sdk/client-cloudwatch');
+  const { CloudWatchClient, GetMetricDataCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-cloudwatch'), '@aws-sdk/client-cloudwatch', 'status metrics',
+  );
   const client = new CloudWatchClient({ region: spec.region ?? region });
   const end = new Date();
   const start = new Date(end.getTime() - hours * 3600_000);

package/src/cli/deploy-probe.ts

@@ -17,7 +17,7 @@
  */
 
 import { isOpsHandlerCrash } from './ops-diagnostics.js';
-import { diagnoseOpsCrash } from './aws.js';
+import { diagnoseOpsCrash, importOptionalAws } from './aws.js';
 import { step, success, fail, info } from './output.js';
 
 /** The raw outcome of one probe invoke, before classification. */
@@ -80,7 +80,9 @@ export function probeTargets(config: {
 /** One raw `_health` invoke → outcome. Never throws; every failure mode lands in the outcome. */
 async function probeFunction(region: string, functionName: string): Promise<ProbeOutcome> {
   try {
-    const { LambdaClient, InvokeCommand } = await import('@aws-sdk/client-lambda');
+    const { LambdaClient, InvokeCommand } = await importOptionalAws(
+      () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'the deploy health probe',
+    );
     const client = new LambdaClient({ region });
     const response = await client.send(new InvokeCommand({
       FunctionName: functionName,
@@ -160,7 +162,9 @@ async function invokeHttpGet(
   queryString = '',
 ): Promise<{ statusCode?: number; body?: string } | null> {
   try {
-    const { LambdaClient, InvokeCommand } = await import('@aws-sdk/client-lambda');
+    const { LambdaClient, InvokeCommand } = await importOptionalAws(
+      () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'the deploy health probe',
+    );
     const client = new LambdaClient({ region });
     const response = await client.send(new InvokeCommand({
       FunctionName: functionName,

package/src/cli/derived-apply.ts

@@ -15,6 +15,7 @@
 
 import { normalizeSql, parseQualified, type SourceObject } from './derived-source.js';
 import type { ReconcilePlan } from './derived-plan.js';
+import { parseGrantAttachments } from './derived-grants.js';
 import { quoteIdent, quoteQualified } from './pg-ident.js';
 
 /** SQL string literal with '' doubling (standard_conforming_strings). */
@@ -136,6 +137,43 @@ export function renderSetSearchPath(schemas: string[], local: boolean): string |
   return `SET ${local ? 'LOCAL ' : ''}search_path = ${schemas.map(quoteIdent).join(', ')}`;
 }
 
+/**
+ * `CREATE SCHEMA IF NOT EXISTS` for each non-public schema the declared objects LIVE
+ * in — migration-compile's rule 0a mirrored into the derived layer. Rule 0a only
+ * creates schemas a MODEL lives in, so a schema populated purely by derived objects
+ * (the derivation half of a stats/stat_views split) was never created and a
+ * from-scratch apply died on its first CREATE. Object schemas only, never
+ * declaredDeps schemas: a dependency's schema belongs to the models that own it, and
+ * a missing one must still fail at CREATE instead of being silently minted empty.
+ *
+ * `GRANT USAGE` rides along per schema (0a-bis mirrored), derived from the objects'
+ * own grant attachments: a role granted SELECT on a matview in a non-public schema
+ * cannot reach it without USAGE, so the object grant is dead without this. A PUBLIC
+ * that appears only as explicitly-revoked gets nothing. Empty for all-public apps —
+ * their apply stays byte-identical. Idempotent when the state layer already created
+ * the schema (a model schema also carrying derived objects).
+ */
+export function renderEnsureObjectSchemas(objects: SourceObject[]): string[] {
+  const statements: string[] = [];
+  const schemas = [...new Set(objects.map((o) => o.schema))].filter((s) => s !== 'public').sort();
+  for (const schema of schemas) {
+    statements.push(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`);
+    const roles = new Set<string>();
+    for (const o of objects) {
+      if (o.schema !== schema) continue;
+      const { grants } = parseGrantAttachments(o.attachments);
+      for (const [role, privileges] of Object.entries(grants)) {
+        if (privileges.length > 0) roles.add(role);
+      }
+    }
+    if (roles.size > 0) {
+      const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+      statements.push(`GRANT USAGE ON SCHEMA ${quoteIdent(schema)} TO ${targets}`);
+    }
+  }
+  return statements;
+}
+
 export function renderReconcileSql(plan: ReconcilePlan, source: SourceObject[]): RenderedReconcile {
   const srcById = new Map(source.map((o) => [o.identity, o]));
   const statements: string[] = [];

package/src/cli/discover.ts

@@ -13,6 +13,7 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { importOptionalAws } from './aws.js';
 
 /** Mirrors CliConfig from config.ts — defined locally to avoid circular imports. */
 interface DiscoveredConfig {
@@ -141,10 +142,9 @@ export async function discoverFunction(
   prefix: string,
   resourceName: string,
 ): Promise<string | undefined> {
-  const {
-    LambdaClient,
-    ListFunctionsCommand,
-  } = await import('@aws-sdk/client-lambda');
+  const { LambdaClient, ListFunctionsCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'resource discovery',
+  );
 
   const client = new LambdaClient({ region });
   const needle = `${prefix}${resourceName}`.toLowerCase();
@@ -185,10 +185,9 @@ export async function discoverLambda(
   }
 
   // Get env vars for routerUrl (CDN_URL)
-  const {
-    LambdaClient,
-    GetFunctionConfigurationCommand,
-  } = await import('@aws-sdk/client-lambda');
+  const { LambdaClient, GetFunctionConfigurationCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-lambda'), '@aws-sdk/client-lambda', 'resource discovery',
+  );
 
   const client = new LambdaClient({ region });
   const config = await client.send(
@@ -219,7 +218,9 @@ export async function discoverBuckets(
   region: string,
   prefix: string,
 ): Promise<BucketsResult> {
-  const { S3Client, ListBucketsCommand } = await import('@aws-sdk/client-s3');
+  const { S3Client, ListBucketsCommand } = await importOptionalAws(
+    () => import('@aws-sdk/client-s3'), '@aws-sdk/client-s3', 'resource discovery',
+  );
 
   const client = new S3Client({ region });
   const res = await client.send(new ListBucketsCommand({}));

package/src/cli/swap-execute.ts

@@ -107,7 +107,7 @@ export async function executeSwap(runner: QueryRunner, opts: ExecuteSwapOptions)
     try { await runner(`DROP SCHEMA IF EXISTS "${plan.incoming}" CASCADE`); } catch { /* best effort */ }
     return {
       status: 'refused-integrity',
-      reason: `the swap transaction failed — usually the cross-schema FK re-validation (an app row references a ${opts.schema} key the artifact dropped): ${String(err?.message ?? err)}`,
+      reason: `the swap transaction failed and rolled back whole: ${String(err?.message ?? err)}. Candidate causes: a cross-schema FK re-validating against the new data (an app row references a ${opts.schema} key the artifact dropped), or an authz statement colliding with authz the artifact already carries — the message above names the actual failing statement.`,
     };
   }
 

package/src/cli/utils/secrets.ts

@@ -15,6 +15,22 @@
 
 import crypto from 'node:crypto';
 import { gunzipSync } from 'node:zlib';
+import { ensureOptionalAws } from '../aws.js';
+
+/**
+ * Preflight the two optional-peer clients EVERY secrets operation needs (ssm for the passphrase,
+ * s3 for the blob), naming both at once if missing — the operator installs everything in one
+ * `pnpm add` instead of discovering them one crash at a time (a consumer field report).
+ */
+function ensureSecretsAws(): Promise<void> {
+  return ensureOptionalAws(
+    [
+      { load: () => import('@aws-sdk/client-ssm'), pkg: '@aws-sdk/client-ssm' },
+      { load: () => import('@aws-sdk/client-s3'), pkg: '@aws-sdk/client-s3' },
+    ],
+    'secrets',
+  );
+}
 
 export interface LoadSecretsOptions {
   appName: string;
@@ -130,6 +146,8 @@ export async function loadSstSecrets(
 ): Promise<Record<string, string>> {
   const { appName, stage, region } = options;
 
+  await ensureSecretsAws();
+
   // 1. Get the state bucket name from /sst/bootstrap
   const bucket = await getStateBucket(region);
 
@@ -166,6 +184,8 @@ export async function putSstSecrets(
 ): Promise<void> {
   const { appName, stage, region } = options;
 
+  await ensureSecretsAws();
+
   const bucket = await getStateBucket(region);
   const passphrase = await getPassphrase(region, appName, stage);