fix(cli, migrate): address CodeRabbit feedback on encryption-migrations

Aggregates the actionable items from CodeRabbit's review of #357. None
introduce new behaviour; each closes a specific defect.

Security / correctness:

- drizzle-helper: replace `execSync` with `spawnSync` so caller-provided
  migration names can't escape into the shell.
- migrate/backfill: drop the value preview from the leak-guard error
  message — the path that hits this branch is precisely where the
  encryption client passed plaintext through, so the value is sensitive.
- cli/backfill: emit a generic catch-block error instead of bubbling
  `error.message` (same plaintext-leak risk via upstream library
  exception text).

Schema-qualified table names:

- requireTable: fall back to unqualified-name lookup so
  `--table public.users` resolves to a schema whose `tableName === 'users'`.
- status: use lastIndexOf('.') when splitting `${table}.${column}` keys
  so schema-qualified table names don't drop the column segment.
- cutover.buildRenameMigrationSql + drop.dropSql: split `schema.table`
  into separate quoted identifiers so the generated `ALTER TABLE` is
  valid and the `information_schema` probe matches.

EQL state / SQL:

- push, activate, cutover, eql.discardPendingConfig, status: schema-
  qualify `eql_v2_configuration` as `public.eql_v2_configuration` so a
  custom `search_path` doesn't shadow or hide the table.
- countEncryptedWithActiveConfig: return `bigint` instead of `number` —
  the BIGINT row count silently truncates past `Number.MAX_SAFE_INTEGER`
  on the exact large tables this is meant to sanity-check.

Process / lifecycle hygiene:

- Every CLI handler that did `process.exit(1)` inside a try/catch with
  an async `finally`: replace with an `exitCode` flag and a single
  `if (exitCode) process.exit(exitCode)` after the finally, so
  `client.end()` actually runs on the error path.
- backfill: move `pool.connect()` inside the same try/finally that
  registers the SIGINT handlers, so handlers/pool are cleaned up if
  connection acquisition fails.
- cutover: catch proxy `reloadConfig()` failures separately and warn —
  reload runs after the cutover transaction commits, so a transient
  Proxy connectivity blip shouldn't make the outer catch report the
  whole cutover as failed.

Schema validation:

- manifest: replace `castAs: z.string()` with a `z.enum(...)` of the
  supported EQL types so a typo (`timestampz`, `strnig`) fails at
  manifest read instead of at use-time.

Doc + skill accuracy:

- setup-prompt: drop the incorrect "no read-path code change" claim
  from the migrate-existing-column flow. Add an explicit step 6
  pointing at `decryptModel` / `encryptedSupabase` — without it the
  agent ships read paths returning raw ciphertext to end users.
- stash-drizzle: `createProtectOperators` → `createEncryptionOperators`
  (the only correct name; every other reference in the file already
  uses it).
- stash-encryption: fix the `runBackfill` example's parameter names
  (`table` → `tableName`, `column` → `schemaColumnKey/plaintextColumn/
  encryptedColumn`, `client` → `encryptionClient`, plus the missing
  `tableSchema` and `pkColumn`).
- design doc: cutover section now reflects the shipped flow
  (`migrate_config()` + `activate_config()` inside the transaction
  alongside the rename), and the read-path claim matches the skill.

Test infrastructure:

- backfill.integration.test.ts: import `dotenv/config` so PG_TEST_URL
  loads from `.env`; add `dotenv` to devDependencies.

Deferred (separate follow-up entry):

- The cutover preflight only verifies one column's phase, but the
  underlying EQL function promotes the whole pending config in one
  call — already tracked as item 3.8 in the working follow-ups doc.

Author: coderdan

docs/plans/encryption-migrations.md

@@ -139,14 +139,19 @@ For each column in `backfilled` phase, in a single transaction:
 BEGIN;
 -- Renames <col> -> <col>_plaintext, <col>_encrypted -> <col>
 SELECT eql_v2.rename_encrypted_columns();
+-- Promote the pending config that was registered by the most recent
+-- `stash db push` (which the user ran after switching the schema to
+-- declare the encrypted column under its final name).
+SELECT eql_v2.migrate_config();   -- pending → encrypting
+SELECT eql_v2.activate_config();  -- encrypting → active (prior active → inactive)
 COMMIT;
 
 -- If Proxy URL is configured, force refresh
 \c <proxy_url>
 SELECT eql_v2.reload_config();
 ```
 
-Record `cut_over` event. App's existing `SELECT email FROM users` now returns the encrypted column (decrypted transparently by Proxy or client-side by Stack). No app code change required for reads — this is the big payoff of the rename approach.
+Record `cut_over` event. App's existing `SELECT email FROM users` returns the encrypted column post-cutover; reading code paths must decrypt via the encryption client (e.g. `decryptModel(rows[0], usersTable)` in Drizzle, or the equivalent `encryptedSupabase` wrapper in Supabase) so the call site receives plaintext. No write-path code change beyond removing the dual-write logic — that comes after cutover.
 
 ### 6. `stash encrypt drop`
 

packages/cli/src/commands/db/activate.ts

@@ -35,18 +35,20 @@ export async function activateCommand(
     databaseUrlFlag: options.databaseUrl,
   })
   const client = new pg.Client({ connectionString: stashConfig.databaseUrl })
+  let exitCode = 0
 
   try {
     await client.connect()
 
     const pending = await client.query<{ exists: boolean }>(
-      "SELECT EXISTS(SELECT 1 FROM eql_v2_configuration WHERE state = 'pending') AS exists",
+      "SELECT EXISTS(SELECT 1 FROM public.eql_v2_configuration WHERE state = 'pending') AS exists",
     )
     if (pending.rows[0]?.exists !== true) {
       p.log.error(
         'No pending EQL configuration to activate. Run `stash db push` first to register a change.',
       )
-      process.exit(1)
+      exitCode = 1
+      return
     }
 
     await client.query('BEGIN')
@@ -63,8 +65,9 @@ export async function activateCommand(
     p.outro('Done.')
   } catch (error) {
     p.log.error(error instanceof Error ? error.message : 'Activation failed.')
-    process.exit(1)
+    exitCode = 1
   } finally {
     await client.end()
   }
+  if (exitCode) process.exit(exitCode)
 }

packages/cli/src/commands/db/push.ts

@@ -77,15 +77,16 @@ export async function pushCommand(options: {
   }
 
   const client = new pg.Client({ connectionString: config.databaseUrl })
+  let exitCode = 0
 
   try {
     s.start('Connecting to Postgres...')
     await client.connect()
     s.stop('Connected to Postgres.')
 
-    s.start('Checking eql_v2_configuration state...')
+    s.start('Checking public.eql_v2_configuration state...')
     const activeResult = await client.query<{ exists: boolean }>(
-      "SELECT EXISTS(SELECT 1 FROM eql_v2_configuration WHERE state = 'active') AS exists",
+      "SELECT EXISTS(SELECT 1 FROM public.eql_v2_configuration WHERE state = 'active') AS exists",
     )
     const hasActive = activeResult.rows[0]?.exists === true
     s.stop(
@@ -99,7 +100,7 @@ export async function pushCommand(options: {
       // Proxy reading the active config. Insert directly as `active`.
       s.start('Writing initial active configuration...')
       await client.query(
-        "INSERT INTO eql_v2_configuration (state, data) VALUES ('active', $1)",
+        "INSERT INTO public.eql_v2_configuration (state, data) VALUES ('active', $1)",
         [eqlConfig],
       )
       s.stop('Active configuration written.')
@@ -118,7 +119,7 @@ export async function pushCommand(options: {
     try {
       await discardPendingConfig(client)
       await client.query(
-        "INSERT INTO eql_v2_configuration (state, data) VALUES ('pending', $1)",
+        "INSERT INTO public.eql_v2_configuration (state, data) VALUES ('pending', $1)",
         [eqlConfig],
       )
       await client.query('COMMIT')
@@ -151,8 +152,9 @@ export async function pushCommand(options: {
     p.log.error(
       error instanceof Error ? error.message : 'Failed to push configuration.',
     )
-    process.exit(1)
+    exitCode = 1
   } finally {
     await client.end()
   }
+  if (exitCode) process.exit(exitCode)
 }

packages/cli/src/commands/encrypt/backfill.ts

@@ -116,11 +116,13 @@ export async function backfillCommand(options: BackfillCommandOptions) {
     p.log.warn('Interrupt received; finishing current chunk and exiting.')
     controller.abort()
   }
-  process.on('SIGINT', onSignal)
-  process.on('SIGTERM', onSignal)
 
-  const db = await pool.connect()
+  let db: pg.PoolClient | undefined
+  let exitCode = 0
   try {
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+    db = await pool.connect()
     const pkColumn =
       options.pkColumn ?? (await detectPkColumn(db, options.table))
 
@@ -249,14 +251,23 @@ export async function backfillCommand(options: BackfillCommandOptions) {
       `Backfill complete. ${result.rowsProcessed.toLocaleString()} rows encrypted.`,
     )
   } catch (error) {
-    p.log.error(error instanceof Error ? error.message : 'Backfill failed.')
-    process.exit(1)
+    // Generic message only — `error.message` may include plaintext sample
+    // values bubbled up from the encryption pipeline (e.g. the leak guard
+    // in @cipherstash/migrate now emits type-only diagnostics, but
+    // upstream libraries can still embed offending input in their
+    // exception text). Preserve exit behaviour but stop the message path
+    // from leaking sensitive data.
+    p.log.error(
+      `Backfill failed${error instanceof Error && /^[\w. -]+$/.test(error.name) ? ` (${error.name})` : ''}. Re-run with diagnostic logging if you need details.`,
+    )
+    exitCode = 1
   } finally {
     process.off('SIGINT', onSignal)
     process.off('SIGTERM', onSignal)
-    db.release()
+    db?.release()
     await pool.end()
   }
+  if (exitCode) process.exit(exitCode)
 }
 
 /**

packages/cli/src/commands/encrypt/context.ts

@@ -146,19 +146,30 @@ export async function loadEncryptionContext(): Promise<EncryptionContext> {
  * context. Exits the process with code `1` if the table is not declared
  * in the user's encryption client file — without this schema, backfill
  * cannot call `bulkEncryptModels`.
+ *
+ * Accepts schema-qualified inputs (`public.users`) and falls back to the
+ * unqualified name when no exact match is found — `EncryptedTable.tableName`
+ * is typically declared without a schema, so `public.users` should still
+ * resolve to a table whose `tableName === 'users'`.
  */
 export function requireTable(
   ctx: EncryptionContext,
   tableName: string,
 ): EncryptedTableLike {
-  const table = ctx.tables.get(tableName)
-  if (!table) {
-    const available = Array.from(ctx.tables.keys()).join(', ') || '(none)'
-    console.error(
-      `Error: Table "${tableName}" was not found in the encryption client exports.\n` +
-        `Available: ${available}`,
-    )
-    process.exit(1)
+  const direct = ctx.tables.get(tableName)
+  if (direct) return direct
+
+  const dot = tableName.lastIndexOf('.')
+  if (dot >= 0) {
+    const unqualified = tableName.slice(dot + 1)
+    const fallback = ctx.tables.get(unqualified)
+    if (fallback) return fallback
   }
-  return table
+
+  const available = Array.from(ctx.tables.keys()).join(', ') || '(none)'
+  console.error(
+    `Error: Table "${tableName}" was not found in the encryption client exports.\n` +
+      `Available: ${available}`,
+  )
+  process.exit(1)
 }

packages/cli/src/commands/encrypt/cutover.ts

@@ -56,6 +56,7 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
 
   const config = await loadStashConfig()
   const client = new pg.Client({ connectionString: config.databaseUrl })
+  let exitCode = 0
 
   try {
     await client.connect()
@@ -65,7 +66,8 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
       p.log.error(
         `Cannot cut over: ${options.table}.${options.column} is in phase '${state?.phase ?? '—'}'. Must be 'backfilled'.`,
       )
-      process.exit(1)
+      exitCode = 1
+      return
     }
 
     // Verify a pending EQL config exists. cutover assumes the user has
@@ -74,13 +76,14 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
     // db push writes that as pending, and cutover transitions
     // pending → encrypting → active alongside the physical rename.
     const pending = await client.query<{ exists: boolean }>(
-      "SELECT EXISTS(SELECT 1 FROM eql_v2_configuration WHERE state = 'pending') AS exists",
+      "SELECT EXISTS(SELECT 1 FROM public.eql_v2_configuration WHERE state = 'pending') AS exists",
     )
     if (pending.rows[0]?.exists !== true) {
       p.log.error(
         'No pending EQL configuration. Update your schema to point at the encrypted column (drop the `_encrypted` suffix), then run `stash db push` to register the pending change before cutting over.',
       )
-      process.exit(1)
+      exitCode = 1
+      return
     }
 
     // Full lifecycle in one transaction:
@@ -142,13 +145,26 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
       }
     }
 
+    // Proxy reload runs *after* the cutover transaction has committed.
+    // Any error from here on is post-commit cosmetic — the rename and
+    // config promotion are durable. Catch the proxy reload separately so
+    // a transient Proxy connectivity blip doesn't make the outer catch
+    // exit(1), which would falsely tell automation the cutover failed
+    // and encourage unsafe retries.
     const proxyUrl = options.proxyUrl ?? process.env.CIPHERSTASH_PROXY_URL
     if (proxyUrl) {
       const proxy = new pg.Client({ connectionString: proxyUrl })
       try {
         await proxy.connect()
-        await reloadConfig(proxy)
-        p.log.success('Proxy config reloaded.')
+        try {
+          await reloadConfig(proxy)
+          p.log.success('Proxy config reloaded.')
+        } catch (err) {
+          const reason = err instanceof Error ? err.message : String(err)
+          p.log.warn(
+            `Proxy config reload failed (${reason}). The cutover itself is committed and durable; Proxy will pick up the new config on its next 60s refresh.`,
+          )
+        }
       } finally {
         await proxy.end()
       }
@@ -163,10 +179,11 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
     )
   } catch (error) {
     p.log.error(error instanceof Error ? error.message : 'Cut-over failed.')
-    process.exit(1)
+    exitCode = 1
   } finally {
     await client.end()
   }
+  if (exitCode) process.exit(exitCode)
 }
 
 /**
@@ -176,8 +193,20 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
  * block does nothing), but on a fresh restore the rename hasn't run yet
  * (so the block performs the swap). Same migration file, both behaviours,
  * idempotent.
+ *
+ * Splits `schema.table` into separate identifiers so the generated SQL is
+ * correct regardless of whether the user passed `users` or `public.users`.
  */
 function buildRenameMigrationSql(table: string, column: string): string {
+  const dot = table.indexOf('.')
+  const [schema, tableName] =
+    dot >= 0 ? [table.slice(0, dot), table.slice(dot + 1)] : [null, table]
+
+  const qualified = schema ? `"${schema}"."${tableName}"` : `"${tableName}"`
+  const schemaPredicate = schema
+    ? `table_schema = '${schema.replace(/'/g, "''")}' AND `
+    : ''
+
   return `-- Generated by stash encrypt cutover.
 -- Records the rename that eql_v2.rename_encrypted_columns() performed
 -- so Drizzle's snapshot stays in sync. Idempotent: a no-op on the DB
@@ -186,11 +215,11 @@ DO $$
 BEGIN
   IF EXISTS (
     SELECT 1 FROM information_schema.columns
-    WHERE table_name = '${table}'
+    WHERE ${schemaPredicate}table_name = '${tableName.replace(/'/g, "''")}'
       AND column_name = '${column}_encrypted'
   ) THEN
-    ALTER TABLE "${table}" RENAME COLUMN "${column}" TO "${column}_plaintext";
-    ALTER TABLE "${table}" RENAME COLUMN "${column}_encrypted" TO "${column}";
+    ALTER TABLE ${qualified} RENAME COLUMN "${column}" TO "${column}_plaintext";
+    ALTER TABLE ${qualified} RENAME COLUMN "${column}_encrypted" TO "${column}";
   END IF;
 END $$;
 `

packages/cli/src/commands/encrypt/drizzle-helper.ts

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { readdir, writeFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
@@ -37,23 +37,19 @@ export async function scaffoldDrizzleMigration(opts: {
   }
 
   // `drizzle-kit generate --custom` scaffolds an empty migration file with
-  // the right prefix and records the journal/snapshot entry. Stderr is
-  // captured so a missing-drizzle-kit error surfaces cleanly.
-  try {
-    execSync(`npx drizzle-kit generate --custom --name=${opts.name}`, {
-      stdio: 'pipe',
-      encoding: 'utf-8',
-    })
-  } catch (error) {
-    const stderr =
-      error !== null &&
-      typeof error === 'object' &&
-      'stderr' in error &&
-      typeof error.stderr === 'string'
-        ? error.stderr.trim()
-        : undefined
+  // the right prefix and records the journal/snapshot entry. spawnSync
+  // (not execSync) so opts.name can't escape into the shell — names like
+  // `cutover_T_C` are agent-controlled and could in principle include
+  // special characters.
+  const cp = spawnSync(
+    'npx',
+    ['drizzle-kit', 'generate', '--custom', `--name=${opts.name}`],
+    { stdio: 'pipe', encoding: 'utf-8' },
+  )
+  if (cp.error || cp.status !== 0) {
+    const stderr = typeof cp.stderr === 'string' ? cp.stderr.trim() : undefined
     throw new Error(
-      `Failed to scaffold Drizzle migration: ${stderr ?? (error instanceof Error ? error.message : String(error))}`,
+      `Failed to scaffold Drizzle migration: ${stderr ?? cp.error?.message ?? 'unknown error'}`,
     )
   }
 

packages/cli/src/commands/encrypt/drop.ts

@@ -52,6 +52,7 @@ export async function dropCommand(options: DropCommandOptions) {
 
   const config = await loadStashConfig()
   const client = new pg.Client({ connectionString: config.databaseUrl })
+  let exitCode = 0
 
   try {
     await client.connect()
@@ -61,10 +62,16 @@ export async function dropCommand(options: DropCommandOptions) {
       p.log.error(
         `Cannot generate drop migration: ${options.table}.${options.column} is in phase '${state?.phase ?? '—'}'. Must be 'cut-over'.`,
       )
-      process.exit(1)
+      exitCode = 1
+      return
     }
 
-    const dropSql = `-- Generated by stash encrypt drop\n-- Drops the plaintext column now that ${options.table}.${options.column} is encrypted.\n\nALTER TABLE "${options.table}" DROP COLUMN "${options.column}_plaintext";\n`
+    const dot = options.table.indexOf('.')
+    const qualifiedTable =
+      dot >= 0
+        ? `"${options.table.slice(0, dot)}"."${options.table.slice(dot + 1)}"`
+        : `"${options.table}"`
+    const dropSql = `-- Generated by stash encrypt drop\n-- Drops the plaintext column now that ${options.table}.${options.column} is encrypted.\n\nALTER TABLE ${qualifiedTable} DROP COLUMN "${options.column}_plaintext";\n`
 
     const cwd = process.cwd()
     const migrationsDir = options.migrationsDir ?? 'drizzle'
@@ -119,8 +126,9 @@ export async function dropCommand(options: DropCommandOptions) {
     p.log.error(
       error instanceof Error ? error.message : 'Drop generation failed.',
     )
-    process.exit(1)
+    exitCode = 1
   } finally {
     await client.end()
   }
+  if (exitCode) process.exit(exitCode)
 }

packages/cli/src/commands/encrypt/plan.ts

@@ -24,6 +24,7 @@ export async function planCommand() {
   }
 
   const client = new pg.Client({ connectionString: config.databaseUrl })
+  let exitCode = 0
   try {
     await client.connect()
     const state = await latestByColumn(client)
@@ -51,8 +52,9 @@ export async function planCommand() {
     p.outro('Done.')
   } catch (error) {
     p.log.error(error instanceof Error ? error.message : 'Plan failed.')
-    process.exit(1)
+    exitCode = 1
   } finally {
     await client.end()
   }
+  if (exitCode) process.exit(exitCode)
 }