fix(cli,scripts): close the review nits, and the same defect where it repeats

Remediation for the two review rounds on #789, plus what verifying them turned
up in the same code.

**The linter fix the review asked for twice.** `livePackages` moving from
`readdirSync` to `git ls-files` was the highest-value change in the PR and had
no test that pinned it. It still doesn't fail under the revert anyone would
actually write: keeping the git call and unioning the filesystem back in passes
every existing test while fully restoring the false negative. The new fixture
builds the discriminating case — a package deleted from git whose gitignored
`dist/` and `node_modules/` shells survive on disk — and is the only test that
fails under both a naive `readdirSync` revert and that hybrid. The
`git status` guard is scoped to the probe, not to `packages/`, so an unrelated
uncommitted file doesn't turn it into an assertion about nothing.

**A missing target no longer passes in silence.** A linter whose entire job is
catching dead paths in configuration skipped dead paths in its own: rename a
target and it dropped out of coverage forever, green. Its sibling already
exits 2 for a stale allowlist entry. Both now do, and both report a target
outside the repo by name instead of as a `../../../../..` chain climbing out
of the root — the review's cosmetic nit, which turned out to sit in both files.

**Every step that names an integration-specific API now branches.** Step 5 was
fixed for this; steps 1, 2 and the read-path step were not. A Prisma Next
project was sent at `types.*` / `encryptedTable` — the client `stash schema
build` explicitly refuses to scaffold for it — and a plain-Postgres project was
pointed three times at "the integration skill" it never gets installed.
`encryptQuery` is shown taking the schema objects rather than an
object-shorthand that read as three required strings. `queryOperatorGuidance`
is a switch with a neutral default rather than an if-chain ending in Drizzle's
answer: tsup transpiles without type-checking and this package has no
typecheck script, so nothing would have caught a fifth integration inheriting
it.

One test asserted nothing: it scoped to a `#### Encryption cutover` heading
that does not exist, and `substring(-1)` returns the whole document.

Author: tobyhede

.changeset/decrypt-chaining-docs.md

@@ -23,9 +23,27 @@ with no lock-context argument.
 
 Also fixes the setup prompt `stash init` writes for coding agents, which
 referenced `protectOps.eq` — an API that does not exist anywhere in the repo.
-The step now names the query API each integration can actually import:
-`createEncryptionOperators(client)` (conventionally `ops`) for Drizzle, the
-`encryptedSupabase` wrapper's own filters for Supabase, the `eql*` column
-operators for Prisma Next, and `client.encryptQuery(...)` for a plain Postgres
-project — which is also pointed at `stash-encryption`, since it is installed
-with no integration skill.
+Every step naming an integration-specific API now branches on the project's
+actual integration, instead of naming Drizzle's and Supabase's and leaving the
+other two to guess:
+
+- **Query paths.** `createEncryptionOperators(client)` (conventionally `ops`)
+  for Drizzle, the `encryptedSupabase` wrapper's own filters for Supabase, the
+  `eql*` column operators for Prisma Next, and `client.encryptQuery(...)` for a
+  plain Postgres project.
+- **Schema authoring.** The `types.*` column factories for Drizzle, the
+  `eql_v3_encrypted` domain in migration SQL for Supabase, the `cipherstash.*`
+  field constructors in `schema.prisma` for Prisma Next, and `encryptedTable`
+  for plain Postgres. Prisma Next was previously sent at `types.*` /
+  `encryptedTable` — the client `stash schema build` explicitly refuses to
+  scaffold for that integration.
+- **Read paths.** `decryptModel(row, usersSchema)` where that applies, and the
+  wrapper's transparent decryption where it does not.
+- **Skill pointers.** A plain Postgres project installs no integration-specific
+  skill, so each "see the integration skill" was a pointer at a file that was
+  never written. Those now point at `stash-encryption`, which it does get.
+
+`client.encryptQuery` is also shown taking the schema objects themselves
+(`{ table: usersSchema, column: usersSchema.email }`) rather than an
+object-shorthand that read as three required strings — `queryType` is inferred
+from the column's configured indexes.

packages/cli/src/commands/init/lib/__tests__/setup-prompt.test.ts

@@ -142,6 +142,78 @@ describe('renderSetupPrompt — orient + route (implement mode)', () => {
       expect(out).toContain('encryptQuery')
       expect(out).toContain('stash-encryption')
     })
+
+    // `EncryptQueryOptions` takes the schema OBJECTS — `usersSchema` and
+    // `usersSchema.email` — not their names as strings, and `queryType` is
+    // inferred from the column's indexes when omitted. The object-shorthand
+    // `{ table, column, queryType }` reads as three required string fields:
+    // the same species of plausible-but-wrong API as the `protectOps.eq` this
+    // PR exists to have removed.
+    it('shows encryptQuery taking schema objects, not string names', () => {
+      const out = render('postgresql')
+      expect(out).toContain('column: usersSchema.email')
+      expect(out).not.toContain('{ table, column, queryType }')
+    })
+
+    // `packages/cli` builds with tsup, which transpiles without type-checking,
+    // and has no `typecheck` script — so `Record<Integration, …>` buys nothing
+    // at build time here. An if-chain ending in a bare Drizzle `return` hands a
+    // future fifth integration the exact string this helper exists to stop it
+    // getting. Degrade to neutral guidance, as `skillsFor()` degrades to
+    // BASE_SKILLS.
+    it('degrades to neutral guidance for an unrecognised integration', () => {
+      const out = renderSetupPrompt({
+        ...baseCtx,
+        integration: 'mystery-orm' as SetupPromptContext['integration'],
+      })
+      expect(out).not.toContain('createEncryptionOperators')
+      expect(out).not.toContain('encryptedSupabase')
+      expect(out).toContain('encryptQuery')
+    })
+  })
+
+  // Step 2 named the Drizzle and Supabase schema APIs unconditionally — the
+  // identical defect step 5 above was just fixed for. A prisma-next project was
+  // sent at `types.*` / `encryptedTable`, which `stash schema build` explicitly
+  // refuses to scaffold for that integration; a plain-Postgres project was
+  // given no named path at all.
+  describe('schema-authoring guidance is per-integration', () => {
+    const render = (integration: SetupPromptContext['integration']) =>
+      renderSetupPrompt({ ...baseCtx, integration })
+
+    it('names the Drizzle column factories for drizzle', () => {
+      const out = render('drizzle')
+      expect(out).toContain('`types.*` column factories')
+      expect(out).toContain('@cipherstash/stack-drizzle')
+    })
+
+    it('names the eql_v3 domain for supabase', () => {
+      expect(render('supabase')).toContain('eql_v3_encrypted')
+    })
+
+    it('names the cipherstash.* field constructors for prisma-next', () => {
+      const out = render('prisma-next')
+      expect(out).toContain('cipherstash.TextSearch()')
+      expect(out).toContain('prisma/schema.prisma')
+      // The `types.*` client is precisely what `stash schema build` refuses to
+      // emit for prisma-next.
+      expect(out).not.toContain('`types.*` column factories')
+    })
+
+    it('names encryptedTable for plain postgresql', () => {
+      const out = render('postgresql')
+      expect(out).toContain('encryptedTable')
+      expect(out).toContain('@cipherstash/stack/v3')
+    })
+  })
+
+  // `postgresql` installs no integration-specific skill (SKILL_MAP), so every
+  // unconditional "see the integration skill" is a pointer at a file that was
+  // never written. Step 5's was fixed; two more survived elsewhere.
+  it('never points plain postgresql at "the integration skill"', () => {
+    const out = renderSetupPrompt({ ...baseCtx, integration: 'postgresql' })
+    expect(out).not.toMatch(/the integration skill/i)
+    expect(out).toContain('stash-encryption')
   })
 
   it('emits supabase migration commands for supabase integration', () => {
@@ -477,7 +549,12 @@ describe('renderSetupPrompt — no db push recommendations', () => {
     expect(out).toMatch(/1\.\s*\*\*Schema-add/)
     expect(out).toMatch(/2\.\s*\*\*Dual-write/)
     // Cutover is still covered, just without a db push workaround note.
-    const cutoverSection = out.substring(out.indexOf('#### Encryption cutover'))
+    // The heading has to be one that exists: `indexOf` returning -1 makes
+    // `substring(-1)` the whole document, so this scoped assertion was
+    // silently asserting nothing at all.
+    const heading = '#### Backfill and switch'
+    expect(out).toContain(heading)
+    const cutoverSection = out.substring(out.indexOf(heading))
     expect(cutoverSection).toMatch(/encrypt cutover/)
   })
 

packages/cli/src/commands/init/lib/setup-prompt.ts

@@ -68,28 +68,92 @@ function migrationCommands(
   return undefined
 }
 
+/**
+ * Where this integration's rules were actually written.
+ *
+ * `postgresql` is the fallback integration and installs no integration-specific
+ * skill (see `SKILL_MAP` in `install-skills.ts`), so "the integration skill" is
+ * a pointer at a file that was never created. Point it at `stash-encryption`,
+ * which it does get.
+ */
+function integrationSkillRef(integration: Integration): string {
+  switch (integration) {
+    case 'drizzle':
+    case 'supabase':
+    case 'prisma-next':
+      return 'the integration skill'
+    default:
+      return 'the `stash-encryption` skill'
+  }
+}
+
+/**
+ * How this integration declares an encrypted column in the schema.
+ *
+ * Per-integration for the same reason the query operators are: the APIs are not
+ * interchangeable, and `stash schema build` (`utils.ts`) refuses outright to
+ * scaffold a `types.*` client for prisma-next — that integration authors its
+ * columns with `cipherstash.*` constructors in `schema.prisma` instead.
+ */
+function schemaAuthoringGuidance(integration: Integration): string {
+  switch (integration) {
+    case 'drizzle':
+      return 'Declare it with the `types.*` column factories from `@cipherstash/stack-drizzle` on the existing `pgTable`'
+    case 'supabase':
+      return 'Declare the column with the `eql_v3_encrypted` domain in the migration SQL (`encryptedSupabase` derives its encryption config by introspecting those domains)'
+    case 'prisma-next':
+      return 'Declare the field with the `cipherstash.*` constructors in `prisma/schema.prisma` (`cipherstash.TextSearch()`, `cipherstash.DoubleOrd()`, …), with the `cipherstash` extension pack wired up per `@cipherstash/prisma-next/control`'
+    default:
+      return 'Declare the table with `encryptedTable` and the `types.*` domain factories from `@cipherstash/stack/v3`, then pass it to `Encryption({ schemas })`'
+  }
+}
+
 /**
  * How this integration filters on an encrypted column. Named per-integration
  * rather than generically because the APIs are not interchangeable and only one
  * of them is importable from any given project: `createEncryptionOperators` is
  * exported by `@cipherstash/stack-drizzle` alone, so naming it for a Supabase
  * or Prisma project sends the agent after a package that is not installed.
  *
- * `postgresql` is the fallback integration and is installed with no integration
- * skill (see `SKILL_MAP` in `install-skills.ts`), so it is pointed at
- * `stash-encryption` instead of "the integration skill".
+ * A `switch` with a neutral `default`, not an if-chain ending in the Drizzle
+ * string: `packages/cli` is built by tsup, which transpiles without
+ * type-checking, and the package has no `typecheck` script — so nothing would
+ * catch a fifth `Integration` variant silently inheriting Drizzle's answer.
+ * `skillsFor()` in `install-skills.ts` degrades the same way, for the same
+ * reason.
  */
 function queryOperatorGuidance(integration: Integration): string {
-  if (integration === 'supabase') {
-    return 'query paths filter through the `encryptedSupabase` wrapper (`es.from("users").select(...).eq("email", value)`) — it encrypts filter operands for encrypted columns automatically; see the integration skill'
+  switch (integration) {
+    case 'supabase':
+      return 'query paths filter through the `encryptedSupabase` wrapper (`es.from("users").select(...).eq("email", value)`) — it encrypts filter operands for encrypted columns automatically; see the integration skill'
+    case 'prisma-next':
+      return 'query paths use the `eql*` operators on the column inside `.where()` (`u.email.eqlEq(value)`, `eqlMatch`, `eqlGt`, …) — see the integration skill'
+    case 'drizzle':
+      return 'query paths use the right operator (`ops.eq`, from `createEncryptionOperators(client)`) — see the integration skill'
+    default:
+      // `table` and `column` are the schema OBJECTS, not their names as
+      // strings, and `queryType` is inferred from the column's configured
+      // indexes unless it is passed to override the inference.
+      return 'query paths encrypt the search term first — `client.encryptQuery(value, { table: usersSchema, column: usersSchema.email })`, passing the schema objects themselves rather than their names — and compare that against the encrypted column; see the `stash-encryption` skill (a plain Postgres project gets no integration-specific skill)'
   }
-  if (integration === 'prisma-next') {
-    return 'query paths use the `eql*` operators on the column inside `.where()` (`u.email.eqlEq(value)`, `eqlMatch`, `eqlGt`, …) — see the integration skill'
-  }
-  if (integration === 'postgresql') {
-    return 'query paths encrypt the search term first with `client.encryptQuery(value, { table, column, queryType })` and compare against the encrypted column — see the `stash-encryption` skill (a plain Postgres project gets no integration skill)'
+}
+
+/**
+ * How this integration turns ciphertext back into values on the read path.
+ *
+ * Named per-integration for the third time in this file, and for the third
+ * time because the answer is not portable: `decryptModel` is the typed
+ * client's, transparent decryption is the Supabase wrapper's.
+ */
+function readPathGuidance(integration: Integration): string {
+  switch (integration) {
+    case 'supabase':
+      return 'selects through the `encryptedSupabase` wrapper decrypt transparently'
+    case 'prisma-next':
+      return 'the encrypted fields decrypt through the Prisma Next client'
+    default:
+      return 'call `decryptModel(row, usersSchema)` — or `bulkDecryptModels` for a set — before returning the value to callers'
   }
-  return 'query paths use the right operator (`ops.eq`, from `createEncryptionOperators(client)`) — see the integration skill'
 }
 
 function bullet(line: string): string {
@@ -298,10 +362,10 @@ export function renderImplementPrompt(ctx: SetupPromptContext): string {
     '',
     '### Add a new encrypted column',
     '',
-    'Use when the column **does not yet exist** in the database (no plaintext predecessor to preserve). This is normal Drizzle / Supabase work plus the encryption client patterns from the integration skill.',
+    `Use when the column **does not yet exist** in the database (no plaintext predecessor to preserve). This is normal schema work in the project's own ORM or migration tooling, plus the encryption client patterns from ${integrationSkillRef(ctx.integration)}.`,
     '',
     "1. **If this is the first encrypted column in the project, configure the bundler exclusion first.** `@cipherstash/stack` cannot be bundled (it wraps a native FFI module). Next.js: add `serverExternalPackages: ['@cipherstash/stack', '@cipherstash/protect-ffi']` to `next.config.*`. Webpack: `externals`. esbuild: `external`. Vite SSR: `ssr.external`. Without this, the encryption client crashes at runtime with `Cannot find module '@cipherstash/protect-ffi-*'`. See the `stash-encryption` skill's Installation section for the full snippets.",
-    "2. Edit the user's real schema file (`src/db/schema.ts` or wherever they keep it) to declare the new encrypted column. Use the patterns in the integration skill — the `types.*` domain factories from `@cipherstash/stack-drizzle` for Drizzle, and the `types.*` factories from `@cipherstash/stack/eql/v3` (via `encryptedTable`, passed as `schemas`) for Supabase. Encrypted columns must be **nullable `jsonb`** at creation time. Never `.notNull()`.",
+    `2. Edit the user's real schema file (\`src/db/schema.ts\` or wherever they keep it) to declare the new encrypted column. ${schemaAuthoringGuidance(ctx.integration)} — the patterns are in ${integrationSkillRef(ctx.integration)}. Encrypted columns must be **nullable \`jsonb\`** at creation time (the \`eql_v3_*\` domains are over \`jsonb\`). Never \`.notNull()\`.`,
     `3. Generate the schema migration${migration ? ` — \`${migration.generate}\` (${migration.tool})` : " using the project's existing migration tooling"}.`,
     `4. Show the user the generated SQL before applying${migration ? ` — \`${migration.apply}\`` : ''}.`,
     `5. Wire the column through the application code: insert paths encrypt before write, select paths decrypt after read, ${queryOperatorGuidance(ctx.integration)}.`,
@@ -328,7 +392,7 @@ export function renderImplementPrompt(ctx: SetupPromptContext): string {
     '',
     `3. **Backfill.** Run \`${cli} encrypt backfill --table <T> --column <c>\`. The CLI prompts the user (or accepts \`--confirm-dual-writes-deployed\` non-interactively) to confirm dual-writes are live, then chunks through the existing rows. Resumable; checkpoints to \`cs_migrations\` after every chunk. SIGINT-safe.`,
     `4. **Switch reads to the encrypted column.** The step depends on the EQL version (\`${cli} encrypt backfill\` prints it; \`${cli} encrypt status\` shows it). **EQL v3 (the default):** there is no rename — update the schema and queries to read/write the encrypted column by its own name, and wire decryption through the encryption client. **EQL v2 (legacy data only):** update the schema file to declare the encrypted column under its final name (drop the twin suffix), then \`${cli} encrypt cutover --table <T> --column <c>\` runs the rename in one transaction (\`<col>\` → \`<col>_plaintext\`, twin → \`<col>\`). Do **not** declare a v2 column with a \`types.*\` domain — those are EQL v3 only. The adapters no longer author v2 (\`@cipherstash/stack-drizzle\` removed \`encryptedType\`), so a v2 column is a read path: declare it with the deprecated \`@cipherstash/stack/schema\` builders and decrypt through \`@cipherstash/stack\`.`,
-    '5. **Wire the read path through the encryption client.** The read column now holds ciphertext. Read code paths must decrypt before returning the value to callers — `decryptModel(row, table)` for Drizzle, the `encryptedSupabase` wrapper for Supabase, or the equivalent `decrypt`/`bulkDecryptModels` calls. Without this step, your read paths return raw encrypted payloads to end users. The integration skill has the exact API.',
+    `5. **Wire the read path through the encryption client.** The read column now holds ciphertext — ${readPathGuidance(ctx.integration)}. Without this step, your read paths return raw encrypted payloads to end users. See ${integrationSkillRef(ctx.integration)} for the exact API.`,
     '6. **Remove the dual-write code.** The plaintext column (still `<col>` on v3; renamed `<col>_plaintext` on v2) is no longer authoritative. Delete the dual-write logic from the persistence layer.',
     `7. **Drop.** Run \`${cli} encrypt drop --table <T> --column <c>\`. Generates a migration that removes the now-unused plaintext column (on v3 it first verifies no rows are still plaintext-only). Apply with the project's normal migration tooling.`,
     '',

scripts/__tests__/fixtures/lint-no-dead-package-paths/dead-shell.md

@@ -0,0 +1,4 @@
+# A deleted package whose build output survives on disk
+
+The old thing lived in packages/lint-dead-shell-probe, deleted from git but
+still sitting there as a `dist/` shell on any checkout that once built it.