fix(cli): integrate cutover/drop with drizzle-kit; phase-aware status

Three issues from the spike's lifecycle smoke-test, all in the
encrypt CLI. Bundled into one commit because they touch adjacent
files.

Issue 1: `encrypt drop` wrote a self-named timestamped migration
(`20260504112456_drop_*.sql`) that drizzle-kit migrate refused to
pick up — no journal entry, wrong prefix. Same shape `db install
--drizzle` already gets right by shelling out to `drizzle-kit
generate --custom`.

Fix: detect drizzle and route through a new
`packages/cli/src/commands/encrypt/drizzle-helper.ts` that wraps
`drizzle-kit generate --custom --name=...`, locates the generated
file, and writes the drop SQL into it. The migration now lands
with a journal entry; `drizzle-kit migrate` applies it like any
other migration. Non-drizzle projects keep the timestamped-file
fallback (Prisma / raw-SQL paths planned).

Issue 2: `encrypt cutover` ran `eql_v2.rename_encrypted_columns()`
live and never told drizzle. Drizzle's `meta/_journal.json` and
snapshot stayed pinned to the pre-rename shape, so the next
`drizzle-kit generate` against the source produced a confused
diff trying to recreate the old layout.

Fix: after cutover succeeds (transaction committed), scaffold a
follow-up custom drizzle migration containing idempotent
`ALTER TABLE … RENAME COLUMN` statements wrapped in a `DO` block
that checks whether `<col>_encrypted` still exists. On the source
DB the rename already ran, so the block is a no-op and Drizzle's
journal still records the migration; on a fresh restore the block
performs the rename. Same file, both behaviours, reproducible.
Non-drizzle projects skip the resync step (logged-only warning if
scaffolding fails).

Issue 3: `encrypt status` rendered `rowsProcessed/rowsTotal (pct%)`
uniformly across every phase. The same fraction means different
things at different points in the lifecycle, and `0/0 (100%)` for
a `backfilled` column that needed no encrypting reads as
nonsense.

Fix: phase-aware framing for the PROGRESS column. `schema-added`
shows `—`. `dual-writing` shows `(awaiting backfill)`. `backfilling`
keeps the fraction. `backfilled` / `cut-over` / `dropped` show a
plain completion marker instead of a degenerate ratio. Same data,
phase-appropriate label.

Wire `--migrations-dir <path>` through to cutover for projects with
non-default drizzle out dirs.

166 tests pass; biome clean.

Coverage check during dual-writing (the bug report's bonus
suggestion — show "rows-with-both-columns / total" rather than
just "awaiting backfill") needs a live SELECT against the user's
table, not just the cs_migrations data we already have. Tracked
as a follow-up; today's status surfaces phase awareness without
new queries.

Author: coderdan

packages/cli/src/bin/stash.ts

@@ -286,7 +286,12 @@ async function runEncryptCommand(
       const { cutoverCommand } = await requireStack(
         () => import('../commands/encrypt/cutover.js'),
       )
-      await cutoverCommand({ table, column, proxyUrl: values['proxy-url'] })
+      await cutoverCommand({
+        table,
+        column,
+        proxyUrl: values['proxy-url'],
+        migrationsDir: values['migrations-dir'],
+      })
       break
     }
     case 'drop': {

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

@@ -1,3 +1,4 @@
+import { detectDrizzle } from '@/commands/db/detect.js'
 import { loadStashConfig } from '@/config/index.js'
 import {
   activateConfig,
@@ -9,6 +10,7 @@ import {
 } from '@cipherstash/migrate'
 import * as p from '@clack/prompts'
 import pg from 'pg'
+import { scaffoldDrizzleMigration } from './drizzle-helper.js'
 
 /**
  * Options accepted by `stash encrypt cutover`. Swaps the plaintext and
@@ -35,6 +37,12 @@ export interface CutoverCommandOptions {
    * Also readable from `CIPHERSTASH_PROXY_URL` in the environment.
    */
   proxyUrl?: string
+  /**
+   * Drizzle migrations directory (passed to `drizzle-kit generate
+   * --custom`). Defaults to `./drizzle`. Only used when the project is
+   * Drizzle — non-Drizzle projects skip the snapshot-resync step.
+   */
+  migrationsDir?: string
 }
 
 /**
@@ -104,6 +112,36 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
       `Renamed ${options.column} → ${options.column}_plaintext and ${options.column}_encrypted → ${options.column}; pending config promoted to active.`,
     )
 
+    // Drizzle snapshot resync. The rename above ran outside drizzle-kit's
+    // authority — the snapshot at `<out>/meta/<idx>_snapshot.json` still
+    // describes the pre-rename column shape. If we don't acknowledge the
+    // change in Drizzle's metadata, the next `drizzle-kit generate` will
+    // produce a confused diff trying to re-create the old layout.
+    //
+    // Scaffolding a custom migration with idempotent rename SQL solves
+    // both problems: it adds the journal entry + snapshot diff that
+    // Drizzle expects, and the SQL itself is a no-op on the source DB
+    // (the pre-rename column doesn't exist any more) but applies
+    // correctly when migrating a fresh database.
+    if (detectDrizzle(process.cwd())) {
+      try {
+        const renameSql = buildRenameMigrationSql(options.table, options.column)
+        const result = await scaffoldDrizzleMigration({
+          name: `cutover_${options.table}_${options.column}`,
+          outDir: options.migrationsDir ?? 'drizzle',
+          sql: renameSql,
+        })
+        p.log.success(
+          `Drizzle snapshot updated: ${result.path} (idempotent — no-op on this DB, applies on a fresh restore).`,
+        )
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err)
+        p.log.warn(
+          `Could not scaffold the Drizzle rename migration: ${reason}\nDrizzle's snapshot may be out of sync with the live schema. Run \`drizzle-kit pull\` to resync, or scaffold the rename migration manually.`,
+        )
+      }
+    }
+
     const proxyUrl = options.proxyUrl ?? process.env.CIPHERSTASH_PROXY_URL
     if (proxyUrl) {
       const proxy = new pg.Client({ connectionString: proxyUrl })
@@ -130,3 +168,30 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
     await client.end()
   }
 }
+
+/**
+ * Build the SQL body for the post-cutover Drizzle migration. Wrapped in a
+ * `DO` block that checks whether `<col>_encrypted` still exists — on the
+ * source database the rename already ran (so the column is gone and the
+ * 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.
+ */
+function buildRenameMigrationSql(table: string, column: string): string {
+  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
+-- where cutover already ran; applies on a fresh restore.
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_name = '${table}'
+      AND column_name = '${column}_encrypted'
+  ) THEN
+    ALTER TABLE "${table}" RENAME COLUMN "${column}" TO "${column}_plaintext";
+    ALTER TABLE "${table}" RENAME COLUMN "${column}_encrypted" TO "${column}";
+  END IF;
+END $$;
+`
+}

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

@@ -0,0 +1,84 @@
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readdir, writeFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Scaffold a custom Drizzle Kit migration file with a known name and write
+ * the supplied SQL into it. Mirrors the dance `db install --drizzle` already
+ * does — `drizzle-kit generate --custom` creates the file and records the
+ * journal entry / snapshot, then we overwrite the empty body with our SQL.
+ *
+ * Used by `encrypt drop` (to ship the plaintext-column drop migration in a
+ * shape `drizzle-kit migrate` actually picks up) and `encrypt cutover` (to
+ * record the live rename so Drizzle's snapshot reflects post-cutover
+ * reality).
+ *
+ * Throws if `drizzle-kit` isn't on PATH or the generated file can't be
+ * located afterwards. Callers should fall back to the self-named-file
+ * approach for non-Drizzle projects.
+ */
+export async function scaffoldDrizzleMigration(opts: {
+  /**
+   * Migration name passed to `drizzle-kit generate --custom --name=<name>`.
+   * Drizzle prefixes with the next sequential index (`0003_<name>.sql`).
+   */
+  name: string
+  /** Drizzle's `out` directory, defaults to `./drizzle` if unset. */
+  outDir: string
+  /** SQL to write into the generated file. */
+  sql: string
+}): Promise<{ path: string }> {
+  const outDir = resolve(opts.outDir)
+  if (!existsSync(outDir)) {
+    throw new Error(
+      `Drizzle output directory not found: ${outDir}\nMake sure drizzle-kit is configured correctly (check drizzle.config.ts's \`out\`).`,
+    )
+  }
+
+  // `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
+    throw new Error(
+      `Failed to scaffold Drizzle migration: ${stderr ?? (error instanceof Error ? error.message : String(error))}`,
+    )
+  }
+
+  const generatedPath = await findLatestNamedMigration(outDir, opts.name)
+  await writeFile(generatedPath, opts.sql, 'utf-8')
+
+  return { path: generatedPath }
+}
+
+/**
+ * Find the most recent `0NNN_<name>.sql` in the Drizzle out directory.
+ * Drizzle's flat numbered prefix means string-sort is the right order.
+ */
+async function findLatestNamedMigration(
+  outDir: string,
+  name: string,
+): Promise<string> {
+  const entries = await readdir(outDir)
+  const matching = entries
+    .filter((entry) => entry.endsWith('.sql') && entry.includes(name))
+    .sort()
+  if (matching.length === 0) {
+    throw new Error(
+      `Could not find a migration matching "${name}" in ${outDir} after running drizzle-kit generate.`,
+    )
+  }
+  return join(outDir, matching[matching.length - 1] as string)
+}

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

@@ -1,5 +1,6 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { detectDrizzle } from '@/commands/db/detect.js'
 import { loadStashConfig } from '@/config/index.js'
 import {
   appendEvent,
@@ -8,6 +9,7 @@ import {
 } from '@cipherstash/migrate'
 import * as p from '@clack/prompts'
 import pg from 'pg'
+import { scaffoldDrizzleMigration } from './drizzle-helper.js'
 
 /**
  * Options accepted by `stash encrypt drop`. Generates a migration file
@@ -33,9 +35,17 @@ export interface DropCommandOptions {
 
 /**
  * CLI handler for `stash encrypt drop`. Requires the column to be in
- * phase `cut-over`; otherwise errors out. Writes a timestamped
- * `ALTER TABLE … DROP COLUMN <col>_plaintext` statement, appends a
- * `dropped` event, and prints instructions for applying the migration.
+ * phase `cut-over`; otherwise errors out.
+ *
+ * For Drizzle projects, scaffolds the migration via `drizzle-kit generate
+ * --custom` so the file lands with the correct sequential prefix and a
+ * journal/snapshot entry — which is what `drizzle-kit migrate` actually
+ * picks up. Hand-rolling the file (the prior behaviour) wrote a
+ * timestamped `<ts>_drop_*.sql` that Drizzle ignored.
+ *
+ * For non-Drizzle projects, falls back to the self-named file behaviour
+ * — a clearly named SQL file the user reviews and applies with their own
+ * tooling (Prisma migrate, psql, etc.).
  */
 export async function dropCommand(options: DropCommandOptions) {
   p.intro('npx @cipherstash/cli encrypt drop')
@@ -54,41 +64,56 @@ export async function dropCommand(options: DropCommandOptions) {
       process.exit(1)
     }
 
-    const migrationsDir = path.resolve(
-      process.cwd(),
-      options.migrationsDir ?? 'drizzle',
-    )
-    fs.mkdirSync(migrationsDir, { recursive: true })
+    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 ts = new Date()
-      .toISOString()
-      .replace(/[-:.TZ]/g, '')
-      .slice(0, 14)
-    const fileName = `${ts}_drop_${options.table}_${options.column}_plaintext.sql`
-    const filePath = path.join(migrationsDir, fileName)
+    const cwd = process.cwd()
+    const migrationsDir = options.migrationsDir ?? 'drizzle'
+    const isDrizzle = detectDrizzle(cwd)
+    let filePath: string
+    let nextStep: string
 
-    const sql = `-- Generated by @cipherstash/cli 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`
-    fs.writeFileSync(filePath, sql, 'utf-8')
+    if (isDrizzle) {
+      // Scaffold via drizzle-kit so the migration is journaled + snapshotted.
+      // Without this, the file ships but `drizzle-kit migrate` never picks it
+      // up because the journal doesn't reference it.
+      const result = await scaffoldDrizzleMigration({
+        name: `drop_${options.table}_${options.column}_plaintext`,
+        outDir: migrationsDir,
+        sql: dropSql,
+      })
+      filePath = result.path
+      nextStep =
+        'Apply with your usual Drizzle migrate command:\n  npx drizzle-kit migrate'
+    } else {
+      // Non-Drizzle fallback: emit a timestamped SQL file the user
+      // applies with whichever migration tool they're running.
+      const dirAbs = path.resolve(cwd, migrationsDir)
+      fs.mkdirSync(dirAbs, { recursive: true })
+      const ts = new Date()
+        .toISOString()
+        .replace(/[-:.TZ]/g, '')
+        .slice(0, 14)
+      const fileName = `${ts}_drop_${options.table}_${options.column}_plaintext.sql`
+      filePath = path.join(dirAbs, fileName)
+      fs.writeFileSync(filePath, dropSql, 'utf-8')
+      nextStep = `Review the migration, then apply with your migration tool:\n  - prisma migrate deploy\n  - psql -f ${fileName}`
+    }
 
     await appendEvent(client, {
       tableName: options.table,
       columnName: options.column,
       event: 'dropped',
       phase: 'dropped',
-      details: { migrationFile: filePath },
+      details: { migrationFile: filePath, drizzleScaffolded: isDrizzle },
     })
 
     // Bump the manifest's target phase so `encrypt plan` reflects the
     // user's commitment to fully removing the plaintext column. No-op
-    // when the column wasn't tracked in the manifest yet (e.g. migrations
-    // begun before the manifest-on-backfill behaviour shipped).
+    // when the column wasn't tracked in the manifest yet.
     await setManifestTargetPhase(options.table, options.column, 'dropped')
 
     p.log.success(`Migration written to ${filePath}`)
-    p.note(
-      `Review the migration, then apply it with your migration tool:\n  - drizzle-kit migrate\n  - prisma migrate deploy\n  - psql -f ${fileName}`,
-      'Next',
-    )
+    p.note(nextStep, 'Next')
     p.outro('Drop migration generated.')
   } catch (error) {
     p.log.error(

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

@@ -205,14 +205,13 @@ function renderRow(input: {
     ? eqlColumn.indexes.join(', ') || '(none)'
     : intentIndexes?.join(', ') || '—'
 
-  let progress = '—'
-  if (state && state.rowsTotal !== null && state.rowsTotal !== undefined) {
-    const pct =
-      state.rowsTotal > 0
-        ? Math.floor(((state.rowsProcessed ?? 0) / state.rowsTotal) * 100)
-        : 100
-    progress = `${state.rowsProcessed ?? 0}/${state.rowsTotal} (${pct}%)`
-  }
+  // The PROGRESS column means different things in different phases. The
+  // raw rowsProcessed/rowsTotal numbers in cs_migrations come from the
+  // backfill engine, but rendering them as a uniform fraction across
+  // every phase produces nonsense at the boundaries (e.g. `0/0 (100%)`
+  // for a `backfilled` column that needed no encrypting because dual-
+  // writes covered every row from seeding). Frame per phase.
+  const progress = formatProgress(phase, state)
 
   const flags: string[] = []
   if (intentIndexes && !eqlColumn) flags.push('not-registered')
@@ -234,6 +233,58 @@ function renderRow(input: {
   }
 }
 
+/**
+ * Phase-aware framing for the PROGRESS column.
+ *
+ *   schema-added  — no backfill has run, no progress data yet.
+ *   dual-writing  — backfill hasn't started either; the meaningful
+ *                   measurement here is "is dual-write code populating
+ *                   every new row?", which requires a live coverage
+ *                   query against the user's table. We don't run that
+ *                   here (the row would have to do its own SELECT) so
+ *                   we surface "(awaiting backfill)" — see follow-ups.
+ *   backfilling   — show backfill progress: rowsProcessed/rowsTotal.
+ *                   Percentage based on rows already done.
+ *   backfilled    — show "(complete)" instead of a degenerate ratio.
+ *                   `0/0` here means "nothing needed encrypting
+ *                   because dual-writes already covered every row" —
+ *                   not a failure, but unintuitive as a fraction.
+ *   cut-over      — physical rename complete, encrypted column live.
+ *   dropped       — plaintext column gone, lifecycle complete.
+ */
+function formatProgress(
+  phase: MigrationPhase | '—',
+  state: {
+    rowsProcessed: number | null
+    rowsTotal: number | null
+  } | null,
+): string {
+  switch (phase) {
+    case 'schema-added':
+      return '—'
+    case 'dual-writing':
+      return '(awaiting backfill)'
+    case 'backfilling': {
+      if (!state || state.rowsTotal === null || state.rowsTotal === undefined) {
+        return '—'
+      }
+      const pct =
+        state.rowsTotal > 0
+          ? Math.floor(((state.rowsProcessed ?? 0) / state.rowsTotal) * 100)
+          : 100
+      return `${state.rowsProcessed ?? 0}/${state.rowsTotal} (${pct}%)`
+    }
+    case 'backfilled':
+      return '(backfill complete)'
+    case 'cut-over':
+      return '(cut over)'
+    case 'dropped':
+      return '(dropped)'
+    default:
+      return '—'
+  }
+}
+
 function formatTable(rows: Row[]): string {
   const headers: Row = {
     table: 'TABLE',