feat(cli): add stash eql migration --drizzle (v3, migration-first EQL install) (#691)

* feat(cli): add `stash eql migration --drizzle` (v3, migration-first EQL install)

First of the three PRs in #690: make migration-first, ORM-agnostic EQL v3 install
the front door, so every integration sources install SQL from one place (the CLI's
bundled variants) instead of vendoring its own. This is the pattern that keeps
Drizzle Supabase-safe; prisma-next's superuser-on-Supabase failure is fixed by the
stacked follow-ups (`--prisma` emitter + removing prisma-next's baked baseline),
which land on top of the prisma-next EQL v3 work (#655).

`stash eql migration --drizzle [--supabase] [--name] [--out] [--dry-run]`:
- Generates a Drizzle custom migration (via `drizzle-kit generate --custom`, then
  injects the SQL) carrying the bundled EQL **v3** install script + the
  `cs_migrations` tracking schema — one `drizzle-kit migrate` does everything
  `stash encrypt …` needs.
- `--supabase` appends the v3 role grants (`eql_v3` + `eql_v3_internal` →
  anon/authenticated/service_role), matching `stash eql install --supabase`.
- v3 only — no `--eql-version` (prisma-next never shipped v2).
- `--prisma` is registered but fails with a pointer to #690 until the stacked PR.

The SQL assembly (`buildEqlV3MigrationSql`) is a pure, unit-tested function; the
drizzle-kit scaffold/inject orchestration reuses the proven helpers from the v2
`install --drizzle` path (`findGeneratedMigration`, `cleanupMigrationFile`, now
exported). Registry + dispatch + help + `stash-cli`/`stash-drizzle` skills updated.

Tests: 4 new unit (bundle present, grants gated on --supabase, tracking schema),
544 CLI unit green, manifest resolves the command, biome clean. Changeset: stash minor.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

* fix(cli): harden `stash eql migration` per review (#691)

Addresses the review on #691 — correctness, security, telemetry, and coverage:

- Run the PROJECT-LOCAL drizzle-kit (`pnpm exec` / `npx --no-install`), not the
  `pnpm dlx`/`yarn dlx` download-and-run form, so it resolves the project's own
  drizzle.config.ts + schema. New shared `execCommand`/`execArgv` in init/utils
  (setup-prompt's private copy folded in).
- Invoke via `spawnSync` with an argv array instead of `execSync` on a shell
  string — a `--name` with spaces or shell metacharacters is now one inert token
  (no word-splitting, no command injection). Plus a `[\w-]+` name guard.
- Pass `--out` through to `drizzle-kit generate` (always) so the flag actually
  steers where the migration is written, and our lookup can't miss it.
- Validation exits and every abort throw `CliExit(1)` instead of `process.exit`,
  so the telemetry `finally` runs and the branches are unit-testable.
- Guard `loadBundledEqlSql` (corrupt bundle → clean error, not a fatal trace),
  add the missing `p.intro`, and call `printNextSteps()` so the now-preferred
  install path isn't less helpful than `eql install`.
- HELP banner lists `eql migration`.

Tests: 14 migration unit (target selection incl. `--supabase`-alone, name guard,
dry-run, argv threading, non-zero drizzle-kit, write-failure cleanup, SQL order),
3 `findGeneratedMigration` unit (now public API), e2e smoke + `eql migration
--help`. 557 unit / 65 e2e green, code:check clean.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

* fix(cli): bun exec must not surprise-download; drop type-erased test cast

CodeRabbit review on #691:

- `execArgv`/`execCommand` bun case emitted `bun x`, which auto-installs a
  missing binary from npm — contradicting the "run a project-local binary,
  never surprise-download" contract these helpers exist to honour (the npm case
  already passes `--no-install`). Bun supports `--no-install`; pass it for both
  the argv and shell forms. Updated the setup-prompt assertion to match.
- migration.test.ts: replaced the type-erasing `undefined as unknown as
  writeFileSync` hoisted-mock placeholder with a throwing placeholder cast to the
  specific type — fails loud if the mock factory never runs, and drops the
  `as unknown` (test files are plugin-exempt, but this is cleaner).

CLI build + 566 unit tests green; biome clean.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

* docs(cli): correct stale `--prisma` copy now that prisma-next v3 has shipped

Dan's review on #691: the `stash eql migration --prisma` copy said the flag
"ships with prisma-next EQL v3 support" / "not available yet" — but that support
has shipped (#655/#683/#685), and Prisma Next installs EQL v3 through its OWN
migration system (`prisma-next migration apply`), not through this command.

Reframed all five spots to current reality (not "coming soon", but "use
prisma-next migration apply"): the user-facing message + its doc comment, the
`eqlMigrationCommand` code comment, the `--prisma` flag help in the registry,
the changeset, and the stash-cli skill (which ships to customers).

No behaviour change — `--prisma` still fails with a pointer. Build + 566 tests green.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

* docs(cli): correct `--prisma` copy to match #690 (planned emitter, not "use prisma-next")

My previous pass framed `--prisma` as "not supported — use `prisma-next
migration apply`", which contradicts #690: the `--prisma` emitter IS a planned
follow-up (PR3) that writes the install migration in the framework `Migration`
shape and lets prisma-next DROP its baked install baseline. Pointing users at
`prisma-next migration apply` is the very approach #690 replaces.

Reframe all five spots to "not available yet — the Prisma Next emitter is a
follow-up tracked in #690; use `--drizzle` today": the message + its doc comment,
the `eqlMigrationCommand` code comment, the `--prisma` flag help, the changeset,
and the stash-cli skill. (The `stash eql install` guard + stash-prisma-next skill
keep their `prisma-next migration apply` wording — that correctly describes the
current baked-baseline install, which is a different thing from this CLI emitter.)

No behaviour change. Build + 566 tests green.

Claude-Session: https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Author: coderdan

.changeset/eql-migration-command.md

@@ -0,0 +1,22 @@
+---
+'stash': minor
+---
+
+Add `stash eql migration` — generate an EQL **v3** install migration for your ORM
+instead of running the SQL directly against the database (`stash eql install`).
+Migration-first is the preferred path: the install lands in your migration history
+and ships to every environment through the ORM's own migrate step.
+
+```bash
+stash eql migration --drizzle              # Drizzle custom migration
+stash eql migration --drizzle --supabase   # also grants eql_v3 to anon/authenticated/service_role
+```
+
+The migration carries the CLI's bundled v3 install SQL (one source of truth) plus
+the `cs_migrations` tracking schema, so a single `drizzle-kit migrate` covers
+everything `stash encrypt …` needs. `--supabase` appends the `eql_v3` +
+`eql_v3_internal` role grants for PostgREST/RLS access.
+
+`--prisma` is registered but not available yet — the Prisma Next migration
+emitter is a follow-up (tracked in cipherstash/stack#690) that will let
+prisma-next drop its baked install baseline. It fails with a pointer for now.

packages/cli/src/bin/main.ts

@@ -108,6 +108,7 @@ Commands:
   telemetry <sub>      Manage anonymous usage analytics (status, enable, disable)
 
   eql install          Scaffold stash.config.ts (if missing) and install EQL extensions
+  eql migration        Generate an EQL v3 install migration for your ORM (Drizzle)
   eql upgrade          Upgrade EQL extensions to the latest version
   eql status           Show EQL installation status
 
@@ -232,6 +233,20 @@ async function runEqlCommand(
     case 'install':
       await runInstall(flags, values)
       break
+    case 'migration': {
+      const { eqlMigrationCommand } = await import(
+        '../commands/eql/migration.js'
+      )
+      await eqlMigrationCommand({
+        drizzle: flags.drizzle,
+        prisma: flags.prisma,
+        supabase: flags.supabase,
+        name: values.name,
+        out: values.out,
+        dryRun: flags['dry-run'],
+      })
+      break
+    }
     case 'upgrade':
       await runUpgrade(flags, values)
       break

packages/cli/src/cli/registry.ts

@@ -377,6 +377,45 @@ export const registry: CommandGroup[] = [
           DATABASE_URL_FLAG,
         ],
       },
+      {
+        name: 'eql migration',
+        summary:
+          'Generate an EQL v3 install migration for your ORM (Drizzle now; Prisma Next soon)',
+        examples: [
+          'eql migration --drizzle',
+          'eql migration --drizzle --supabase',
+        ],
+        flags: [
+          {
+            name: '--drizzle',
+            description:
+              'Emit a Drizzle custom migration containing the EQL v3 install SQL.',
+          },
+          {
+            name: '--prisma',
+            description:
+              'Emit a Prisma Next migration — not available yet; the emitter is a follow-up tracked in cipherstash/stack#690.',
+          },
+          {
+            name: '--supabase',
+            description:
+              'Append the Supabase role grants (eql_v3 + eql_v3_internal for anon/authenticated/service_role).',
+          },
+          {
+            name: '--name',
+            value: '<name>',
+            description:
+              'Name for the generated migration (Drizzle). Letters, numbers, dashes, underscores only. Defaults to `install-eql`.',
+          },
+          {
+            name: '--out',
+            value: '<path>',
+            description:
+              'Directory drizzle-kit writes the migration into (passed to `drizzle-kit generate --out`). Defaults to `drizzle`; set it to match your drizzle.config.ts.',
+          },
+          DRY_RUN_FLAG,
+        ],
+      },
       {
         name: 'eql upgrade',
         summary: 'Upgrade EQL extensions to the latest version',

packages/cli/src/commands/db/__tests__/find-generated-migration.test.ts

@@ -0,0 +1,49 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { findGeneratedMigration } from '../install.js'
+
+/**
+ * `findGeneratedMigration` was promoted to public API by the `eql migration`
+ * command and now has two consumers (`db install --drizzle` and
+ * `eql migration --drizzle`), so its branches are pinned directly — a change for
+ * one consumer must not silently break the other.
+ */
+describe('findGeneratedMigration', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'stash-find-migration-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('throws when the out directory does not exist', async () => {
+    await expect(
+      findGeneratedMigration(join(dir, 'nope'), 'install-eql'),
+    ).rejects.toThrow(/output directory not found/)
+  })
+
+  it('throws when no .sql file matches the migration name', async () => {
+    writeFileSync(join(dir, '0000_other.sql'), '')
+    await expect(findGeneratedMigration(dir, 'install-eql')).rejects.toThrow(
+      /Could not find a migration matching "install-eql"/,
+    )
+  })
+
+  it('returns the highest-numbered match, ignoring non-.sql and non-matching entries', async () => {
+    for (const f of [
+      '0000_install-eql.sql',
+      '0010_install-eql.sql',
+      '0011_install-eql.txt', // not .sql
+      '0001_users.sql', // doesn't match the name
+    ]) {
+      writeFileSync(join(dir, f), '')
+    }
+    // Relies on drizzle-kit's zero-padded 4-digit prefix for lexical == numeric.
+    expect(await findGeneratedMigration(dir, 'install-eql')).toBe(
+      join(dir, '0010_install-eql.sql'),
+    )
+  })
+})

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

@@ -413,7 +413,7 @@ function resolveProviderOptions(
   return { supabase, drizzle, excludeOperatorFamily }
 }
 
-function printNextSteps(): void {
+export function printNextSteps(): void {
   p.note(
     [
       'Your project is set up. To encrypt your first column, pick the path',
@@ -887,7 +887,7 @@ async function writeSupabaseMigrationFile(
  * Find the most recently generated migration file matching the given name.
  * Drizzle-kit generates flat SQL files like `0000_install-eql.sql`.
  */
-async function findGeneratedMigration(
+export async function findGeneratedMigration(
   outDir: string,
   migrationName: string,
 ): Promise<string> {
@@ -915,7 +915,7 @@ async function findGeneratedMigration(
 /**
  * Attempt to clean up a generated migration file on failure.
  */
-function cleanupMigrationFile(filePath: string | undefined): void {
+export function cleanupMigrationFile(filePath: string | undefined): void {
   if (!filePath) return
 
   try {