fix(cli): honest Drizzle EQL outcome + close test gaps (review on #687)

Differential review (Codex) found the completion gate still reported a
successful, complete setup for `stash init --drizzle` before EQL was in the
database: the Drizzle path only *generates* a v2 migration (applied later with
`drizzle-kit migrate`), yet `installEqlStep` returned `eqlInstalled: true` for
every non-throwing outcome — the exact false-success this PR removes elsewhere.

- `installCommand` now returns a structured `InstallOutcome`
  (`installed` | `already-installed` | `migration-generated` | `dry-run`).
- `installEqlStep` maps `migration-generated` to a new `eqlMigrationPending`
  state (EQL not in the DB yet) instead of `eqlInstalled`.
- The init summary reports it honestly — "○ EQL migration generated — apply it
  with `drizzle-kit migrate`" — and excuses it from the "Setup incomplete"
  hard-fail (exit 0), the same treatment Prisma Next already gets.
- Changeset + stash-cli skill updated to match.

Test-gap review: added the previously-uncovered branches —
- init summary's three-way encryption-client checkmark (scaffolded / kept);
- the Drizzle migration-pending gate (cross-layer: outcome → step → summary);
- handoff-claude / handoff-codex launch-prompt skills clause (stripped build
  drops the skills dir; codex keeps AGENTS.md).

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

Author: coderdan

.changeset/honest-noninteractive-init.md

@@ -13,9 +13,13 @@ setup that didn't fully complete.
   Interactive runs still offer to align. A *newer* install stays a warn (the
   install is likely fine; update the CLI instead).
 - **No false "Setup complete".** If the EQL extension isn't installed at the
-  end (and the integration isn't Prisma Next, which installs it via
-  `migration apply`), the summary reads "Setup incomplete" and init exits
-  non-zero, pointing at `stash eql install`.
+  end — and the integration isn't one that installs it out-of-band — the
+  summary reads "Setup incomplete" and init exits non-zero, pointing at
+  `stash eql install`. Integrations that install EQL via a migration are
+  reported honestly rather than as failures: Prisma Next (installs it via
+  `migration apply`) and the Drizzle flow, which *generates* an EQL migration
+  and now says "EQL migration generated — apply it with `drizzle-kit migrate`"
+  instead of claiming the extension is already installed.
 - **Honest checkmarks.** The summary no longer claims "Database connection
   verified" (init resolves a URL but doesn't open a connection) — it now says
   "Database URL resolved" — and only shows "Encryption client scaffolded" when

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

@@ -169,7 +169,28 @@ async function resolveInstallContext(
   return { databaseUrl, clientPath }
 }
 
-export async function installCommand(options: InstallOptions) {
+/**
+ * What `installCommand` actually did — so callers (notably `stash init`'s
+ * completion gate) can tell "EQL is now in the database" from "a migration
+ * file was written but nothing was applied yet".
+ *
+ * - `installed` / `already-installed`: EQL is present in the target database.
+ * - `migration-generated`: a migration file was written (Drizzle, or the
+ *   Supabase `--migration` mode); the user still has to APPLY it
+ *   (`drizzle-kit migrate` / `supabase db push`) before EQL exists in the DB.
+ * - `dry-run`: nothing was changed.
+ *
+ * Terminal error paths call `process.exit(1)` and never return an outcome.
+ */
+export type InstallOutcome =
+  | 'installed'
+  | 'already-installed'
+  | 'migration-generated'
+  | 'dry-run'
+
+export async function installCommand(
+  options: InstallOptions,
+): Promise<InstallOutcome> {
   p.intro(runnerCommand(detectPackageManager(), 'stash eql install'))
 
   // Validate mutually-exclusive / supabase-required flags BEFORE doing any
@@ -238,7 +259,9 @@ export async function installCommand(options: InstallOptions) {
       supabase: resolved.supabase,
       excludeOperatorFamily: resolved.excludeOperatorFamily,
     })
-    return
+    // A Drizzle migration file was written — NOT applied. EQL only lands in
+    // the database once the user runs `drizzle-kit migrate`.
+    return 'migration-generated'
   }
 
   // Supabase non-Drizzle path: pick between writing a migration file and
@@ -270,7 +293,9 @@ export async function installCommand(options: InstallOptions) {
         force: options.force,
         dryRun: options.dryRun,
       })
-      return
+      // Migration file written, not applied — the user runs it via their
+      // Supabase migration workflow (`supabase db push`).
+      return 'migration-generated'
     }
     // mode === 'direct' — fall through to existing direct-install behavior.
   }
@@ -282,7 +307,7 @@ export async function installCommand(options: InstallOptions) {
       : `Would use bundled EQL${eqlVersion === 3 ? ' v3' : ''} install script`
     p.note(`${source}\nWould execute the SQL against the database`, 'Dry Run')
     p.outro('Dry run complete.')
-    return
+    return 'dry-run'
   }
 
   const installer = new EQLInstaller({
@@ -331,7 +356,7 @@ export async function installCommand(options: InstallOptions) {
     if (installed) {
       p.log.info('Use --force to re-run the install script.')
       p.outro('Nothing to do.')
-      return
+      return 'already-installed'
     }
   }
 
@@ -370,6 +395,7 @@ export async function installCommand(options: InstallOptions) {
 
   printNextSteps()
   p.outro('Done!')
+  return 'installed'
 }
 
 /**

packages/cli/src/commands/impl/steps/__tests__/handoff-claude.test.ts

@@ -0,0 +1,40 @@
+import { beforeEach, expect, it, vi } from 'vitest'
+import type { InitState } from '../../../init/types.js'
+
+// The launch prompt's skills clause is the unit under test. Mock the skill
+// installer so we control whether any skills were "copied", and stub the
+// artifact writer / agent spawner so no files are written and no process is
+// spawned. `impl.test.ts` mocks `howToProceedStep.run` out entirely, so
+// nothing there drives this prompt — this file is its dedicated coverage.
+const installSkills = vi.hoisted(() => vi.fn())
+vi.mock('../../../init/lib/install-skills.js', () => ({ installSkills }))
+vi.mock('../../../init/lib/handoff-helpers.js', () => ({
+  writeArtifacts: vi.fn(),
+  spawnAgent: vi.fn(async () => 0),
+}))
+vi.mock('@clack/prompts', () => ({
+  note: vi.fn(),
+  log: { success: vi.fn(), info: vi.fn(), warn: vi.fn() },
+}))
+
+import * as p from '@clack/prompts'
+import { handoffClaudeStep } from '../handoff-claude.js'
+
+// `agents` undefined → Claude "not installed" path, which routes the launch
+// prompt into a `p.note` (rather than spawning). That note's body is what we
+// assert on.
+const state = { integration: 'postgresql' } as unknown as InitState
+
+beforeEach(() => vi.clearAllMocks())
+
+it('launch prompt omits the skills dir when no skills were copied', async () => {
+  installSkills.mockReturnValue([])
+  await handoffClaudeStep.run(state)
+  expect(vi.mocked(p.note).mock.calls[0][0]).not.toContain('.claude/skills/')
+})
+
+it('launch prompt names the skills dir when skills were copied', async () => {
+  installSkills.mockReturnValue(['stash-encryption'])
+  await handoffClaudeStep.run(state)
+  expect(vi.mocked(p.note).mock.calls[0][0]).toContain('.claude/skills/')
+})

packages/cli/src/commands/impl/steps/__tests__/handoff-codex.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, expect, it, vi } from 'vitest'
+import type { InitState } from '../../../init/types.js'
+
+// Same seam as the handoff-claude test: the launch prompt's skills clause is
+// the unit under test. Mock the skill installer to control whether skills were
+// "copied". The Codex handoff also writes AGENTS.md to disk before printing
+// the prompt, so stub `node:fs` and the AGENTS.md builders to keep the test
+// hermetic (no file lands in the repo) — the assertion is purely on the
+// launch-prompt text.
+const installSkills = vi.hoisted(() => vi.fn())
+vi.mock('../../../init/lib/install-skills.js', () => ({ installSkills }))
+vi.mock('../../../init/lib/handoff-helpers.js', () => ({
+  writeArtifacts: vi.fn(),
+  spawnAgent: vi.fn(async () => 0),
+}))
+vi.mock('../../../init/lib/build-agents-md.js', () => ({
+  buildAgentsMdBody: vi.fn(() => '# managed doctrine'),
+}))
+vi.mock('../../../init/lib/sentinel-upsert.js', () => ({
+  upsertManagedBlock: vi.fn(() => '# AGENTS.md'),
+}))
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(() => false),
+  readFileSync: vi.fn(() => ''),
+  writeFileSync: vi.fn(),
+}))
+vi.mock('@clack/prompts', () => ({
+  note: vi.fn(),
+  log: { success: vi.fn(), info: vi.fn(), warn: vi.fn() },
+}))
+
+import * as p from '@clack/prompts'
+import { handoffCodexStep } from '../handoff-codex.js'
+
+// `agents` undefined → Codex "not installed" path, which routes the launch
+// prompt into a `p.note`.
+const state = { integration: 'postgresql' } as unknown as InitState
+
+beforeEach(() => vi.clearAllMocks())
+
+it('launch prompt drops .codex/skills/ but keeps AGENTS.md when no skills copied', async () => {
+  installSkills.mockReturnValue([])
+  await handoffCodexStep.run(state)
+  const body = vi.mocked(p.note).mock.calls[0][0]
+  expect(body).not.toContain('.codex/skills/')
+  // The durable rules live in AGENTS.md regardless, so the prompt still names it.
+  expect(body).toContain('AGENTS.md')
+})
+
+it('launch prompt names .codex/skills/ when skills were copied', async () => {
+  installSkills.mockReturnValue(['stash-encryption'])
+  await handoffCodexStep.run(state)
+  expect(vi.mocked(p.note).mock.calls[0][0]).toContain('.codex/skills/')
+})

packages/cli/src/commands/init/__tests__/init-command.test.ts

@@ -114,4 +114,63 @@ describe('initCommand — honest summary', () => {
       'Setup complete',
     )
   })
+
+  it('reports a generated Drizzle migration honestly — not installed, not incomplete', async () => {
+    // Differential review (PR #687): the Drizzle flow GENERATES an EQL
+    // migration; `installEqlStep` returns eqlMigrationPending (not
+    // eqlInstalled). The summary must neither claim "✓ EQL extension
+    // installed" nor hard-fail as "Setup incomplete" — it should say a
+    // migration was generated and point at `drizzle-kit migrate`, then exit 0.
+    eqlRun.mockImplementationOnce(async (s: InitState) => ({
+      ...s,
+      integration: 'drizzle',
+      eqlInstalled: false,
+      eqlMigrationPending: true,
+    }))
+
+    await expect(initCommand({}, {})).resolves.toBeUndefined()
+
+    const summary = vi
+      .mocked(p.note)
+      .mock.calls.find(([, title]) => title === 'Setup complete')
+    expect(summary).toBeDefined()
+    const body = summary?.[0] as string
+    expect(body).toContain('EQL migration generated')
+    expect(body).toContain('drizzle-kit migrate')
+    expect(body).not.toContain('✓ EQL extension installed')
+  })
+
+  it('summary says "kept (existing file)" when an existing client is kept', async () => {
+    // The three-way encryption-client checkmark fork was untested — the keep
+    // path (`build-schema` sets clientFilePath + schemaGenerated: false) now
+    // produces a different string with nothing locking it. This fails against
+    // the pre-change code, which always claimed "scaffolded".
+    eqlRun.mockImplementationOnce(async (s: InitState) => ({
+      ...s,
+      eqlInstalled: true,
+      clientFilePath: './src/encryption/index.ts',
+      schemaGenerated: false,
+    }))
+
+    await initCommand({}, {})
+    expect(vi.mocked(p.note)).toHaveBeenCalledWith(
+      expect.stringContaining('✓ Encryption client kept (existing file)'),
+      'Setup complete',
+    )
+  })
+
+  it('summary says "scaffolded" when a placeholder was written', async () => {
+    eqlRun.mockImplementationOnce(async (s: InitState) => ({
+      ...s,
+      eqlInstalled: true,
+      clientFilePath: './src/encryption/index.ts',
+      schemaGenerated: true,
+    }))
+
+    await initCommand({}, {})
+    expect(vi.mocked(p.note)).toHaveBeenCalledWith(
+      expect.stringContaining('✓ Encryption client scaffolded'),
+      'Setup complete',
+    )
+  })
 })

packages/cli/src/commands/init/index.ts

@@ -120,15 +120,34 @@ export async function initCommand(
       checkmarks.push('✓ `@cipherstash/stack` installed')
     }
     if (state.cliInstalled) checkmarks.push('✓ `stash` CLI installed')
-    if (state.eqlInstalled) checkmarks.push('✓ EQL extension installed')
+    if (state.eqlInstalled) {
+      checkmarks.push('✓ EQL extension installed')
+    } else if (state.eqlMigrationPending) {
+      // The Drizzle flow (and Supabase `--migration` mode) GENERATES an EQL
+      // migration rather than applying it — EQL isn't in the database until
+      // the user runs the migration. That's the intended, honest end state
+      // for these flows (applying is the ORM/migration tool's job), so it's
+      // NOT an incomplete setup — but we must not claim "installed" either.
+      const applyCmd =
+        state.integration === 'supabase'
+          ? 'supabase db push'
+          : 'drizzle-kit migrate'
+      checkmarks.push(
+        `○ EQL migration generated — apply it with \`${applyCmd}\``,
+      )
+    }
 
-    // EQL is required for encryption. Prisma Next installs it via `migration
-    // apply` (so `eqlInstalled` is false by design there); every other
-    // integration needs it installed here. If it's missing, setup is NOT
-    // complete — say so and exit non-zero so automation can't read a false
-    // success from a run where encryption would fail at query time.
+    // EQL is required for encryption. Some integrations install it out-of-band
+    // and legitimately leave `eqlInstalled` false here: Prisma Next installs it
+    // via `migration apply`, and the Drizzle flow generates a migration the
+    // user applies with `drizzle-kit migrate` (`eqlMigrationPending`). Only a
+    // run that neither installed EQL nor generated a migration to install it is
+    // genuinely incomplete — say so and exit non-zero so automation can't read
+    // a false success from a run where encryption would fail at query time.
     const eqlPending =
-      !state.eqlInstalled && state.integration !== 'prisma-next'
+      !state.eqlInstalled &&
+      !state.eqlMigrationPending &&
+      state.integration !== 'prisma-next'
     if (eqlPending) {
       checkmarks.push('✗ EQL extension NOT installed')
       p.note(checkmarks.join('\n'), messages.init.setupIncomplete)

packages/cli/src/commands/init/steps/__tests__/install-eql.test.ts

@@ -60,6 +60,7 @@ describe('installEqlStep', () => {
     // prompt. init must proceed with the default (install) rather than abort,
     // and still scaffold stash.config.ts via the EQL install.
     vi.mocked(isInteractive).mockReturnValue(false)
+    vi.mocked(installCommand).mockResolvedValueOnce('installed')
 
     const result = await installEqlStep.run(baseState, provider)
 
@@ -69,5 +70,37 @@ describe('installEqlStep', () => {
       'ensure',
     )
     expect(result.eqlInstalled).toBe(true)
+    expect(result.eqlMigrationPending).toBeFalsy()
+  })
+
+  it('treats an already-installed database as EQL installed', async () => {
+    vi.mocked(installCommand).mockResolvedValueOnce('already-installed')
+
+    const result = await installEqlStep.run(baseState, provider)
+
+    expect(result.eqlInstalled).toBe(true)
+    expect(result.eqlMigrationPending).toBeFalsy()
+  })
+
+  it('maps a generated Drizzle migration to eqlMigrationPending, NOT eqlInstalled', async () => {
+    // The Drizzle path only WRITES a v2 migration — EQL isn't in the DB until
+    // the user runs `drizzle-kit migrate`. `installEqlStep` must carry that
+    // distinction through so `initCommand` doesn't claim "EQL installed".
+    // This is the seam the differential review flagged (PR #687): the step
+    // used to return `eqlInstalled: true` for every non-throwing outcome.
+    const drizzleState = {
+      integration: 'drizzle',
+      databaseUrl: 'postgresql://localhost:5432/app',
+    } as unknown as InitState
+    vi.mocked(installCommand).mockResolvedValueOnce('migration-generated')
+
+    const result = await installEqlStep.run(drizzleState, {
+      name: 'drizzle',
+    } as unknown as InitProvider)
+
+    // Pinned to v2 for the Drizzle migration path (v3 rejects --drizzle).
+    expect(vi.mocked(installCommand).mock.calls[0][0].eqlVersion).toBe('2')
+    expect(result.eqlInstalled).toBe(false)
+    expect(result.eqlMigrationPending).toBe(true)
   })
 })

packages/cli/src/commands/init/steps/install-eql.ts

@@ -90,8 +90,9 @@ export const installEqlStep: InitStep = {
       return { ...state, eqlInstalled: false }
     }
 
+    let outcome: Awaited<ReturnType<typeof installCommand>>
     try {
-      await installCommand({
+      outcome = await installCommand({
         supabase: supabase || undefined,
         drizzle: drizzle || undefined,
         databaseUrl: state.databaseUrl,
@@ -115,6 +116,16 @@ export const installEqlStep: InitStep = {
       return { ...state, eqlInstalled: false }
     }
 
+    // The Drizzle path (and Supabase `--migration` mode) only WRITES a
+    // migration file — EQL isn't in the database until the user applies it.
+    // Report that honestly rather than claiming the extension is installed;
+    // the init summary turns this into "migration generated, apply it".
+    if (outcome === 'migration-generated') {
+      return { ...state, eqlInstalled: false, eqlMigrationPending: true }
+    }
+
+    // 'installed' | 'already-installed' — the extension is present in the DB.
+    // ('dry-run' never happens from init; it doesn't pass dryRun.)
     return { ...state, eqlInstalled: true }
   },
 }

packages/cli/src/commands/init/types.ts

@@ -45,8 +45,16 @@ export interface InitState {
   stackInstalled?: boolean
   /** True when the `stash` CLI is in the project's devDependencies. */
   cliInstalled?: boolean
-  /** True when EQL was installed (or already-installed) by install-eql. */
+  /** True when EQL was installed (or already-installed) by install-eql —
+   *  i.e. the extension is actually present in the target database. */
   eqlInstalled?: boolean
+  /** True when install-eql GENERATED a migration file but did not apply it
+   *  (the Drizzle v2 path, or Supabase `--migration` mode). EQL is not in the
+   *  database yet — the user applies it with `drizzle-kit migrate` (or their
+   *  Supabase migration workflow). Distinct from `eqlInstalled` so the init
+   *  summary reports "migration generated, apply it" instead of a false
+   *  "installed" or a spurious "setup incomplete". */
+  eqlMigrationPending?: boolean
   /** Detected ORM / framework integration. Set by build-schema. */
   integration?: Integration
   /** Schema definitions written to the encryption client. Carries every

skills/stash-cli/SKILL.md

@@ -36,7 +36,7 @@ npx stash init              # PostgreSQL / Drizzle / Prisma
 npx stash init --supabase   # Supabase
 ```
 
-`stash init` installs the CLI as a project dev dependency, so subsequent commands can drop the `npx`. The CLI is package-manager aware — before init, use whichever one-shot runner your project uses (`npx`, `pnpm dlx`, `bunx`, `yarn dlx`). Installs are **pinned to the exact `@cipherstash/*` versions this CLI release shipped with** (never bare dist-tags, which can lag behind a release), and init flags any already-installed `@cipherstash/*` package whose resolved version differs from the release's. The fix depends on direction, and init says which applies: an **older** install should be aligned to the release (init offers the exact command); a **newer** install must NOT be downgraded — update the `stash` CLI to the matching release instead (init prints that command too). **Non-interactively, an older ("behind") skew is fatal** — init refuses with a non-zero exit and the align command rather than scaffolding against mismatched packages and reporting a false success. Interactively it offers to align. Likewise, if the EQL extension isn't installed at the end (and the integration isn't Prisma Next, which installs it via `migration apply`), init reports **"Setup incomplete"** and exits non-zero — it never claims a setup is complete when encryption would fail at query time.
+`stash init` installs the CLI as a project dev dependency, so subsequent commands can drop the `npx`. The CLI is package-manager aware — before init, use whichever one-shot runner your project uses (`npx`, `pnpm dlx`, `bunx`, `yarn dlx`). Installs are **pinned to the exact `@cipherstash/*` versions this CLI release shipped with** (never bare dist-tags, which can lag behind a release), and init flags any already-installed `@cipherstash/*` package whose resolved version differs from the release's. The fix depends on direction, and init says which applies: an **older** install should be aligned to the release (init offers the exact command); a **newer** install must NOT be downgraded — update the `stash` CLI to the matching release instead (init prints that command too). **Non-interactively, an older ("behind") skew is fatal** — init refuses with a non-zero exit and the align command rather than scaffolding against mismatched packages and reporting a false success. Interactively it offers to align. Likewise, if the EQL extension isn't installed at the end, init reports **"Setup incomplete"** and exits non-zero — it never claims a setup is complete when encryption would fail at query time. Integrations that install EQL through a migration are the exception and exit 0: **Prisma Next** installs it via `migration apply`, and the **Drizzle** flow *generates* an EQL migration, which init reports honestly as "EQL migration generated — apply it with `drizzle-kit migrate`" rather than claiming the extension is already installed.
 
 **If you are an agent, do this first:**