fix(cli,migrate): close gaps found verifying the #787 review fixes

Follow-up to 1d14412, from an adversarial cross-check of that commit.

resolve-eql's private `columnExists` used a bare `to_regclass($1)`. That form
parses and case-folds unquoted identifiers, so on a Prisma-style "User" table
the probe reported the column missing, the recorded pairing was treated as
stale, and the #772 fail-closed silently did not fire — falling through to the
sole/convention rules and resolving the guess it exists to prevent. migrate
already documents this exact anti-pattern (REGCLASS_SQL) and its test asserts
`not.toMatch(/to_regclass\(\$1\)/)`. Moved to a shared, case-exact
`columnExists` export and deleted the CLI copy; the test double is now
case-exact too, so it cannot hide a regression.

The placeholder guard read the harvested export map while the `db push` /
`db validate` guard it mirrors reads `getEncryptConfig().tables`. Those
disagree in both directions on one file: `schemas: [placeholderTable]` minus
the `export` keyword fell through to "table not found … Available: (none)" —
the error the guard replaces — and a stale placeholder export beside real
tables wrongly fired it. Now reads the same source.

cutover's `via:'sole'` refusal was nested inside `version === 3`; drop's is
top-level. Equivalent today, but cutover's v2 ladder does an irreversible
rename plus config promotion, so a restored v2 classification or a v4 family
would let cutover rename on a guess drop refuses. Hoisted to match.

Text that was false:
- the scaffold `stash init` writes into every customer project (and both
  fixtures) claimed `stash encrypt` commands refuse to run; only backfill does
- skills/stash-cli listed the client as loaded by `schema build` and `encrypt *`,
  and omitted `db push`
- skills/stash-cli and skills/stash-encryption still said cutover on a backfilled
  v3 column exits 0. Since `.cipherstash/` is gitignored, a clone or CI runner
  hits the new `sole` refusal on a pure-v3 table with an unconventional column
  name — the changeset's "pure-v3 unaffected" was wrong too
- both `sole` messages said "the table's only EQL column"; pickEncryptedColumn
  excludes the plaintext column first, so it fires with two
- the remedy said to drive the v2 lifecycle "directly"; there is no CLI route,
  so it now says to run the eql_v2 SQL yourself
- vitest.config.ts and packages/cli/AGENTS.md claimed the unit suite is
  self-contained. It is not: @cipherstash/stack is still reached via
  migrate/src/backfill.ts. The alias removed one of two couplings

typecheck:scaffold ran `tsc` directly, bypassing turbo, so it needed a prior
build and passed only by accident of step ordering behind steps that read as
independently droppable. Now a turbo task with dependsOn ^build.

Added scripts/__tests__/cli-vitest-alias.test.mjs — the CLI's alias map sits
outside the vitest.shared.ts guard and must, since stackSourceAlias's '@/'
would clobber the CLI's own. Runs in test:scripts, ahead of the build-dependent
suite.

Verified: frozen-lockfile install clean; 891 CLI unit, 41 migrate, 93 scripts,
76 pty e2e; code:check 0 errors; scaffold gate green through turbo with
packages/stack/dist absent.

Author: tobyhede

.changeset/encrypt-lifecycle-mixed-table.md

@@ -35,10 +35,25 @@ all now fixed:
   column that actually encrypts the named one, and says explicitly not to record
   the guess.
 
-The new refusal is scoped to the mixed table it was written for: it applies only
-when the table actually holds EQL v3 columns that a guess could wrongly claim. A
-pure-v2 table has none, so it still falls through to the EQL v2 lifecycle exactly
-as before — including when `encrypt backfill` recorded an `encryptedColumn` for
-it, which it does for v2 columns too. Pure-v2 and pure-v3 tables are therefore
-unaffected, as are tables with two or more EQL v3 columns (resolution already
-failed closed there).
+The `unresolvedHint` refusal is scoped to tables that actually hold EQL v3
+columns a guess could wrongly claim. A **pure-v2** table has none, so it still
+falls through to the EQL v2 lifecycle exactly as before — including when
+`encrypt backfill` recorded an `encryptedColumn` for it, which it does for v2
+columns too.
+
+Two cases DO newly exit 1, both deliberately:
+
+- Any table with at least one EQL v3 column where the manifest records an
+  `encryptedColumn` that exists but is not one of them — not only the
+  v2-pair-plus-one-v3 shape. The recorded pairing is authoritative and
+  disagrees with every candidate, so guessing past it is the bug.
+
+- A column whose encrypted counterpart could only be identified **by
+  elimination** — no recorded `encryptedColumn`, no `<col>_encrypted` name
+  match, one EQL column left once the plaintext column itself is excluded.
+  `cutover` now refuses this as `drop` already did. Note `.cipherstash/` is
+  gitignored, so `migrations.json` is machine-local: a fresh clone or CI runner
+  can hit this on a **pure-v3** table whose encrypted column is named
+  unconventionally, where `cutover` previously exited 0 with "not applicable".
+  Re-run `stash encrypt backfill --table T --column C --encrypted-column <name>`
+  to record the pairing.

.changeset/migrate-column-exists.md

@@ -0,0 +1,21 @@
+---
+'@cipherstash/migrate': minor
+'stash': patch
+---
+
+Add `columnExists(client, tableName, columnName)` — a case-exact "does this
+column exist at all?" catalog probe, distinct from `detectColumnEqlVersion`'s
+"and is it an EQL column?".
+
+Callers need that difference to tell a STALE column reference (it is gone) from
+a live one the domain classifier simply does not recognise — most often a legacy
+`eql_v2_encrypted` counterpart.
+
+`stash encrypt cutover` / `drop` had a private copy of this probe built on a bare
+`to_regclass($1)`. That form *parses* its argument and case-folds unquoted
+identifiers, so on a Prisma-style `"User"` table it resolved `user`, reported the
+column missing, and treated a valid recorded pairing as stale — silently skipping
+the fail-closed that stops those commands acting on a guessed encrypted column.
+The shared implementation quotes with `format('%I')` first, like every other
+catalog probe in this package, so the lookup is case-exact while still honouring
+`search_path` for unqualified names.

.github/workflows/tests.yml

@@ -199,8 +199,14 @@ jobs:
       # emitting a project that fails its first `tsc` — with CI green (#772
       # review). The fixtures are pinned byte-for-byte to the generator by
       # `placeholder-client-fixture.test.ts`.
+      # Through turbo, not `pnpm run` — the fixtures import `@cipherstash/stack/v3`,
+      # so this needs that package BUILT. Invoked directly it passed only because
+      # earlier steps in this job happen to build it via their own `^build`; drop
+      # or reorder those (they read as guards for other packages, so they look
+      # independently removable) and this fails `TS2307`, which reads as "the
+      # scaffold is broken" rather than "you forgot to build" (#787 review).
       - name: Typecheck (stash init's scaffolded client)
-        run: pnpm --filter stash run typecheck:scaffold
+        run: pnpm exec turbo run typecheck:scaffold --filter stash
 
       - name: Lint — no hardcoded package-manager runners
         run: pnpm run lint:runners

packages/cli/AGENTS.md

@@ -6,11 +6,22 @@ This package has **two** Vitest configs. Run the right one for the change.
 
 | Command | Config | Scope | Needs build? |
 | --- | --- | --- | --- |
-| `pnpm --filter stash test` | `vitest.config.ts` | Unit tests under `src/__tests__/**` and `src/**/__tests__/**` | No |
+| `pnpm --filter stash test` | `vitest.config.ts` | Unit tests under `src/__tests__/**` and `src/**/__tests__/**` | **Partly** — needs `@cipherstash/stack` built (see below). Turbo's `^build` supplies it in CI. |
 | `pnpm --filter stash test:e2e` | `vitest.integration.config.ts` | E2E tests under `tests/e2e/**.e2e.test.ts` driving the built `dist/bin/stash.js` through a real pty (`node-pty`) | **Yes** — run `pnpm --filter stash build` first, or use the turbo `test:e2e` task which depends on `build`. |
 
 The unit config explicitly excludes `tests/e2e/**` so the default `pnpm test`
-stays fast and self-contained.
+stays fast.
+
+It is **not** fully self-contained, despite running standalone in CI. Some `src`
+modules import workspace packages that publish `./dist` only, so an unbuilt
+workspace fails at collection with `Failed to resolve entry for package …`
+rather than at an assertion. `vitest.config.ts` aliases `@cipherstash/migrate`
+to its source to remove one such coupling; `@cipherstash/stack` remains, reached
+via `packages/migrate/src/backfill.ts` and a direct import in
+`init/lib/introspect.test.ts`. Deleting `packages/stack/dist` fails 10 files.
+Closing it needs `vitest.shared.ts`'s `stackSourceAlias`, which cannot be spread
+into this config — its `'@/'` entry points at `packages/stack/src` and would
+clobber this package's own `'@/'` (#787 review).
 
 ## When to add or update an E2E test
 

packages/cli/__fixtures__/scaffold/drizzle.generated.ts

@@ -8,8 +8,10 @@
  * to reference the encrypted tables you declared there.
  *
  * Until that happens, the encryption client is initialised with a single
- * placeholder table so that this file compiles, and `stash encrypt`
- * commands refuse to run and point back here.
+ * placeholder table so that this file compiles, and `stash db push`,
+ * `stash db validate` and `stash encrypt backfill` refuse to run and point
+ * back here. (`stash encrypt cutover` / `drop` resolve against the database
+ * and never read this file.)
  *
  * This project uses EQL v3. Encrypted columns are concrete Postgres domains
  * built with the `types.*` factories from `@cipherstash/stack-drizzle`.
@@ -56,8 +58,8 @@ import { Encryption, encryptedTable, types } from '@cipherstash/stack/v3'
 
 // REPLACE THIS. It exists only so this file compiles before you have declared
 // any encrypted tables — `Encryption` requires at least one. Swap it for your
-// real tables (see the patterns above); `stash encrypt` refuses to run while
-// the placeholder is still here.
+// real tables (see the patterns above); `stash db push`, `stash db validate`
+// and `stash encrypt backfill` refuse to run while the placeholder is still here.
 export const placeholderTable = encryptedTable('__stash_placeholder__', {
   replace_me: types.Text('replace_me'),
 })

packages/cli/__fixtures__/scaffold/generic.generated.ts

@@ -7,8 +7,10 @@
  * `Encryption({ schemas: [...] })` call below to reference them.
  *
  * Until that happens, the encryption client is initialised with a single
- * placeholder table so that this file compiles, and `stash encrypt`
- * commands refuse to run and point back here.
+ * placeholder table so that this file compiles, and `stash db push`,
+ * `stash db validate` and `stash encrypt backfill` refuse to run and point
+ * back here. (`stash encrypt cutover` / `drop` resolve against the database
+ * and never read this file.)
  *
  * This project uses EQL v3. Encrypted columns are concrete Postgres domains
  * built with the `types.*` factories from `@cipherstash/stack/eql/v3`
@@ -51,8 +53,8 @@ import { Encryption, encryptedTable, types } from '@cipherstash/stack/v3'
 
 // REPLACE THIS. It exists only so this file compiles before you have declared
 // any encrypted tables — `Encryption` requires at least one. Swap it for your
-// real tables (see the patterns above); `stash encrypt` refuses to run while
-// the placeholder is still here.
+// real tables (see the patterns above); `stash db push`, `stash db validate`
+// and `stash encrypt backfill` refuse to run while the placeholder is still here.
 export const placeholderTable = encryptedTable('__stash_placeholder__', {
   replace_me: types.Text('replace_me'),
 })

packages/cli/src/commands/encrypt/__tests__/context-placeholder.test.ts

@@ -53,8 +53,12 @@ describe('loadEncryptionContext — the un-replaced init scaffold', () => {
   })
 
   it('exits 1 naming the sentinel when it is the only table declared', async () => {
+    // The scaffold's real shape: the sentinel is both exported AND the sole
+    // entry in the built encrypt config, because it was passed to `Encryption`.
     writeProject(
-      `export const encryptionClient = { getEncryptConfig: () => ({}) }
+      `export const encryptionClient = {
+         getEncryptConfig: () => ({ tables: { '${PLACEHOLDER_TABLE_NAME}': {} } }),
+       }
        export const placeholderTable = ${table(PLACEHOLDER_TABLE_NAME)}`,
     )
     const error = vi.spyOn(console, 'error').mockImplementation(() => {})
@@ -72,6 +76,54 @@ describe('loadEncryptionContext — the un-replaced init scaffold', () => {
     expect(message).not.toContain('was not found in the encryption client')
   })
 
+  /**
+   * #787 review. The guard originally read the harvested EXPORT map, while the
+   * `db push` / `db validate` guard it mirrors reads `getEncryptConfig().tables`.
+   * Those disagree in both directions on the same client file, so the two
+   * commands gave different answers for identical input.
+   */
+  it('fires when the placeholder is passed to Encryption but never exported', async () => {
+    // The false NEGATIVE. `schemas: [placeholderTable]` with a bare `const` —
+    // the scaffold minus one `export` keyword. Reading exports, the guard saw
+    // no tables and fell through to `requireTable`'s "table not found …
+    // Available: (none)" — the very error this guard exists to replace.
+    writeProject(
+      `export const encryptionClient = {
+         getEncryptConfig: () => ({ tables: { '${PLACEHOLDER_TABLE_NAME}': {} } }),
+       }`,
+    )
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit')
+    })
+
+    const { loadEncryptionContext } = await import('../context.js')
+    await expect(loadEncryptionContext()).rejects.toThrow('process.exit')
+
+    const message = error.mock.calls.flat().join('\n')
+    expect(message).toContain('still contains the placeholder table')
+    expect(message).not.toContain('was not found in the encryption client')
+  })
+
+  it('stays silent when a stale placeholder export sits beside real configured tables', async () => {
+    // The false POSITIVE, and the mirror of the case above: the user replaced
+    // the schema set but left the sentinel `export` behind (or imports their
+    // real tables without re-exporting them). Reading exports, the guard fired
+    // and told them to declare columns they had already declared. `db push`
+    // passes on this same file.
+    writeProject(
+      `export const encryptionClient = {
+         getEncryptConfig: () => ({ tables: { users: {} } }),
+       }
+       export const placeholderTable = ${table(PLACEHOLDER_TABLE_NAME)}`,
+    )
+
+    const { loadEncryptionContext } = await import('../context.js')
+    const ctx = await loadEncryptionContext()
+
+    expect(ctx.tables.has(PLACEHOLDER_TABLE_NAME)).toBe(true)
+  })
+
   it('allows the sentinel through once a real table sits alongside it', async () => {
     // Only the SOLE-placeholder case is the un-replaced scaffold. A user who
     // has added real tables must not be blocked by a leftover sentinel export.

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

@@ -142,14 +142,25 @@ export async function loadEncryptionContext(): Promise<EncryptionContext> {
     process.exit(1)
   }
 
-  // Same guard `loadEncryptConfig` applies for `stash db push` / `db validate`,
+  // The guard `loadEncryptConfig` applies for `stash db push` / `db validate`,
   // repeated here because `stash encrypt` does not go through that loader. The
   // scaffold `stash init` writes declares one sentinel table so the file
   // compiles; reaching here with only that table means it was never replaced.
   // Without this, `requireTable` reported `Table "users" was not found …
   // Available: __stash_placeholder__`, which names the symptom and not the
   // cause (#787 review).
-  if (tables.size === 1 && tables.has(PLACEHOLDER_TABLE_NAME)) {
+  //
+  // Read from `getEncryptConfig()` — the SAME source `loadEncryptConfig` uses —
+  // not from the harvested export map, or the two commands disagree on one
+  // file. `schemas: [placeholderTable]` with the `export` keyword dropped is
+  // still the un-replaced scaffold but exports nothing; conversely a stale
+  // `export const placeholderTable` beside real tables that are imported
+  // rather than re-exported is NOT (#787 review).
+  const configuredTables = Object.keys(client.getEncryptConfig()?.tables ?? {})
+  if (
+    configuredTables.length === 1 &&
+    configuredTables[0] === PLACEHOLDER_TABLE_NAME
+  ) {
     console.error(
       `Error: ${stashConfig.client} still contains the placeholder table \`${PLACEHOLDER_TABLE_NAME}\` that \`stash init\` wrote.\n\nDeclare your encrypted columns and pass those tables to Encryption({ schemas: [...] }) in that file, then re-run this command.`,
     )

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

@@ -95,23 +95,32 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
     }
     const state = await progress(client, options.table, options.column)
 
+    // `via: 'sole'` means only that this is the table's one remaining EQL
+    // candidate once the plaintext column itself is excluded — nothing ties it
+    // to the plaintext column the user named. On a mixed table (a v2 pair the
+    // classifier no longer sees, plus one unrelated v3 column) that guess is
+    // simply wrong, and reporting "nothing to do for EQL v3" for it told a
+    // scripted rollout the cut-over had succeeded when the v2 rename never ran
+    // (#772 review, finding 7).
+    //
+    // Deliberately at TOP LEVEL, not inside the `version === 3` branch, so it
+    // mirrors `drop.ts` exactly. Equivalent today — `classifyEqlDomain`
+    // recognises `eql_v3_*` only, so a non-null `info` is always version 3 —
+    // but the v2 ladder below performs an irreversible rename plus config
+    // promotion. Were v2 classification restored, or a v4 family added, a
+    // nested guard would let `cutover` rename on a guess that `drop` refuses
+    // (#787 review).
+    if (info?.via === 'sole') {
+      p.log.error(
+        `${options.table}.${info.column} (${info.domain}) is the only EQL column left on ${options.table} once "${options.column}" itself is excluded, but nothing confirms it encrypts "${options.column}" — refusing to report a cut-over outcome on that guess. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only): complete that column's v2 lifecycle yourself with the eql_v2 SQL — \`SELECT eql_v2.rename_encrypted_columns();\` plus the config promotion — since no stash command can drive it here. Otherwise record the pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <the column that actually encrypts ${options.column}>\`.`,
+      )
+      exitCode = 1
+      return
+    }
+
     if (info?.version === 3) {
       const encryptedColumn = info.column
 
-      // `via: 'sole'` means only that this is the table's ONE EQL v3 column —
-      // nothing ties it to the plaintext column the user named. On a mixed
-      // table (a v2 pair the classifier no longer sees, plus one unrelated v3
-      // column) that guess is simply wrong, and reporting "nothing to do for
-      // EQL v3" for it told a scripted rollout the cut-over had succeeded when
-      // the v2 rename never ran. `drop.ts` already refuses a `'sole'` match for
-      // the same reason (#772 review, finding 7).
-      if (info.via === 'sole') {
-        p.log.error(
-          `${options.table}.${encryptedColumn} (${info.domain}) is the table's only EQL v3 column, but nothing confirms it encrypts "${options.column}" — refusing to report a cut-over outcome on that guess. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only) — drive that column's v2 lifecycle against its own encrypted column directly. Otherwise record the pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <the column that actually encrypts ${options.column}>\`.`,
-        )
-        exitCode = 1
-        return
-      }
       if (state?.phase === 'dropped') {
         // Terminal phase — the lifecycle already finished. Not an error and
         // not "finish the backfill": there is nothing left to backfill.

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

@@ -113,7 +113,7 @@ export async function dropCommand(options: DropCommandOptions) {
     // live `DROP COLUMN` on the plaintext at exit 0 (#772 review, finding 7).
     if (info?.via === 'sole') {
       p.log.error(
-        `${options.table}.${info.column} (${info.domain}) is the table's only encrypted column, but nothing confirms it encrypts "${options.column}" — refusing to generate an irreversible drop on that guess. Identify the column that actually encrypts "${options.column}" and record that pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <name>\` (which writes it to the manifest), or set "encryptedColumn" for this column in .cipherstash/migrations.json. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only) — drive that column's v2 lifecycle against its own encrypted column directly, and do not record ${info.column}.`,
+        `${options.table}.${info.column} (${info.domain}) is the only EQL column left on ${options.table} once "${options.column}" itself is excluded, but nothing confirms it encrypts "${options.column}" — refusing to generate an irreversible drop on that guess. Identify the column that actually encrypts "${options.column}" and record that pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <name>\` (which writes it to the manifest), or set "encryptedColumn" for this column in .cipherstash/migrations.json. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only): complete that column's v2 lifecycle yourself with the eql_v2 SQL, since no stash command can drive it here — and do not record ${info.column}.`,
       )
       exitCode = 1
       return