fix(cli,scripts): per-integration query guidance, and linters that catch their own rot

Follow-up to the #772 review findings, addressing what the review of that
review turned up.

`stash init`'s setup prompt named `createEncryptionOperators` unconditionally.
That symbol is exported by `@cipherstash/stack-drizzle` alone, so a Supabase or
Prisma Next project was sent after a package that is not in its dependency
tree — the previous `protectOps.eq` was wrong for everyone, this was wrong for
three integrations out of four. Step 5 now branches through
`queryOperatorGuidance()`, following the `migrationCommands()` pattern already
in the file: `ops.eq` for Drizzle, the `encryptedSupabase` wrapper's own
filters for Supabase, the `eql*` column operators for Prisma Next, and
`client.encryptQuery(...)` for plain Postgres — which is also pointed at
`stash-encryption`, since it is the default integration and installs no
integration skill, making "see the integration skill" a dangling pointer.

The package-path linter reported an untracked-but-present package as "does not
exist" — finding 15's false alarm pointed the other way, at a directory sitting
right there on disk. The live set now unions `git ls-files --others
--exclude-standard`. `--directory` is deliberately not passed: it collapses an
all-ignored directory to one entry and would resurrect exactly the `dist/`-and-
`node_modules/` shells the linter exists to catch (verified both ways). git
failing now exits 2 with an actionable message instead of a raw ENOENT stack
trace and exit 1, which was indistinguishable from a genuine lint failure, and
an empty live set refuses to run rather than flagging every reference at once.

The `scans scripts/ but not its fixtures` test asserted the repo was clean —
byte-for-byte what the suite's first test already asserted, and passing whether
or not `scripts` was in TARGETS. It now plants an offender in the scanned
directory. Verified by mutation: it dies when `scripts` is dropped, as the
untracked-package test dies without the union and the git-failure test dies
when the exit code is flipped.

The runners linter now requires each allowlist entry to exist and to still
contain an unexcused `npx` literal. It immediately found a second stale entry
the sibling linter structurally cannot see, since it only matches the
`packages/<name>` shape: `setup-prompt.ts` has had no `npx` since its switch
moved to `utils.ts`. Removed.

Also corrects two claims: the test comment saying `packages/drizzle` never
existed in git history (it was added speculatively by c671560, became
load-bearing 31 minutes later with 9d259e6, and rotted when 413ca39 deleted
the package), and the `AnyEncryptedTable` doc comment still promising v3 is
"purely additive and no existing caller has to change" — true of decrypt, false
of encrypt since the v2 write overloads were removed.

Author: tobyhede

.changeset/decrypt-chaining-docs.md

@@ -23,5 +23,9 @@ 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 operators come from `createEncryptionOperators(client)`, conventionally
-bound to `ops`.
+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.

.changeset/dynamodb-eql-v3.md

@@ -13,11 +13,11 @@ the typed client from `EncryptionV3` and the nominal client from
 
 EQL v2 tables continue to be **readable** — `decryptModel` /
 `bulkDecryptModels` still accept one, so existing items stay accessible. Writing
-through a v2 table is a separate matter: the encrypt overloads for it are
-removed in this same release (see the DynamoDB v2 write-removal entry), so a
-caller that still encrypts through a v2 table does need to change. The table
-decides which wire format is used, so a DynamoDB table populated under one
-version must keep being read with that version.
+through a v2 table is a separate matter: `encryptModel` / `bulkEncryptModels`
+narrowed to EQL v3 tables in this same release, so a caller that still encrypts
+through a v2 table does need to change. The table decides which wire format is
+used, so a DynamoDB table populated under one version must keep being read with
+that version.
 
 This fixes a latent bug that made v3 unusable: the write path detected an
 encrypted value by its `k: 'ct'` tag, but EQL v3 scalars carry no `k`

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

@@ -105,6 +105,45 @@ describe('renderSetupPrompt — orient + route (implement mode)', () => {
     expect(out).toContain('pnpm exec drizzle-kit migrate')
   })
 
+  // The "wire the column through" step names the query API by hand. It used to
+  // name `protectOps.eq`, which exists nowhere; naming `createEncryptionOperators`
+  // unconditionally is the same mistake one step smaller — that symbol is
+  // exported only by `@cipherstash/stack-drizzle`, which a Supabase or Prisma
+  // project does not even have in its dependency tree. Each integration gets
+  // the API it can actually import.
+  describe('query-operator guidance is per-integration', () => {
+    const render = (integration: SetupPromptContext['integration']) =>
+      renderSetupPrompt({ ...baseCtx, integration })
+
+    it('names the Drizzle operators for drizzle', () => {
+      const out = render('drizzle')
+      expect(out).toContain('createEncryptionOperators(client)')
+      expect(out).toContain('ops.eq')
+    })
+
+    it('names the wrapper builder for supabase, not the Drizzle operators', () => {
+      const out = render('supabase')
+      expect(out).not.toContain('createEncryptionOperators')
+      expect(out).toContain('encryptedSupabase')
+    })
+
+    it('names the eql* column operators for prisma-next', () => {
+      const out = render('prisma-next')
+      expect(out).not.toContain('createEncryptionOperators')
+      expect(out).toContain('eqlEq')
+    })
+
+    // `postgresql` is the default when nothing is detected, and it gets no
+    // integration skill at all (install-skills.ts) — so "see the integration
+    // skill" is a dangling pointer for it too.
+    it('names the core encryptQuery path for plain postgresql', () => {
+      const out = render('postgresql')
+      expect(out).not.toContain('createEncryptionOperators')
+      expect(out).toContain('encryptQuery')
+      expect(out).toContain('stash-encryption')
+    })
+  })
+
   it('emits supabase migration commands for supabase integration', () => {
     const out = renderSetupPrompt({
       ...baseCtx,

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

@@ -68,6 +68,30 @@ function migrationCommands(
   return undefined
 }
 
+/**
+ * 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".
+ */
+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'
+  }
+  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)'
+  }
+  return 'query paths use the right operator (`ops.eq`, from `createEncryptionOperators(client)`) — see the integration skill'
+}
+
 function bullet(line: string): string {
   return `- ${line}`
 }
@@ -280,7 +304,7 @@ export function renderImplementPrompt(ctx: SetupPromptContext): string {
     "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()`.",
     `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, query paths use the right operator (`ops.eq`, from `createEncryptionOperators(client)` — see the integration skill).',
+    `5. Wire the column through the application code: insert paths encrypt before write, select paths decrypt after read, ${queryOperatorGuidance(ctx.integration)}.`,
     '6. Verify with a round-trip: insert a record, select it back, confirm the value decrypts and the search ops work.',
     '',
     '### Migrate an existing column to encrypted',

packages/stack/src/dynamodb/types.ts

@@ -21,9 +21,14 @@ import type { EncryptModelOperation } from './operations/encrypt-model'
  * `encryptedColumn`/`encryptedField` from `@cipherstash/stack/schema`) or an
  * EQL v3 one (`encryptedTable` + `types.*` from `@cipherstash/stack/eql/v3`).
  *
- * Both are supported deliberately. DynamoDB shares none of the v2 Postgres
- * machinery — there is no EQL extension to install and no migration to run —
- * so accepting v3 is purely additive and no existing caller has to change.
+ * This union is the adapter's widest input type — the erased view the internal
+ * `CallableEncryptionClient` is declared against. It is NOT the public contract:
+ * the surface split the two versions apart. `encryptModel` /
+ * `bulkEncryptModels` narrowed to `AnyV3Table` (the v2 write overloads were
+ * removed, so a v2 encrypt call site does have to change); `decryptModel` /
+ * `bulkDecryptModels` still take either, so items stored under v2 stay
+ * readable. See {@link EncryptedDynamoDBInstance} for the overloads that decide
+ * this per method.
  */
 export type AnyEncryptedTable =
   | EncryptedTable<EncryptedTableColumn>

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

@@ -0,0 +1,3 @@
+# A package that exists on disk but is not yet tracked
+
+The new thing lives in packages/lint-untracked-probe, scaffolded but not staged.

scripts/__tests__/lint-no-dead-package-paths.test.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
@@ -8,9 +9,18 @@ const SCRIPT = resolve(
   '../../lint-no-dead-package-paths.mjs',
 )
 
+const REPO_ROOT = resolve(fileURLToPath(import.meta.url), '../../..')
+
 function run(...targets) {
+  return runWith({}, ...targets)
+}
+
+function runWith(opts, ...targets) {
   try {
-    execFileSync('node', [SCRIPT, ...targets], { encoding: 'utf8' })
+    execFileSync(process.execPath, [SCRIPT, ...targets], {
+      encoding: 'utf8',
+      ...opts,
+    })
     return { exitCode: 0, output: '' }
   } catch (err) {
     return {
@@ -63,12 +73,59 @@ describe('lint-no-dead-package-paths', () => {
   })
 
   // The linters carry package paths of their own; `scripts/` was not scanned,
-  // so a `packages/drizzle` allowlist entry for a package that never existed in
-  // git history sat there unnoticed. Its own fixtures must stay exempt.
+  // so lint-no-hardcoded-runners' `packages/drizzle/src/bin/runner.ts` allowlist
+  // entry — added speculatively by c6715608, load-bearing 31 minutes later once
+  // 9d259e6e created the file — sat dead for the two months after 413ca396
+  // deleted the package. Its sibling entry for `packages/protect` was removed
+  // with its package; this one was simply missed.
+  //
+  // Asserting the repo is clean would NOT pin this: the suite's first test
+  // already does that, and both pass whether or not `scripts` is in TARGETS.
+  // Plant an offender in the scanned directory instead.
   it('scans scripts/ but not its fixtures', () => {
-    const r = run()
-    expect(r.exitCode).toBe(0)
-    expect(r.output).toBe('')
+    const probe = resolve(REPO_ROOT, 'scripts/dead-path-probe.md')
+    try {
+      writeFileSync(probe, 'A reference to `packages/protect`, long gone.\n')
+      const r = run()
+      expect(r.exitCode).toBe(1)
+      expect(r.output).toMatch(/scripts\/dead-path-probe\.md:1/)
+      // `__tests__` stays skipped — the fixtures name dead packages on purpose,
+      // and so do the comments in this very file.
+      expect(r.output).not.toMatch(/__tests__/)
+    } finally {
+      rmSync(probe, { force: true })
+    }
+  })
+
+  // A package scaffolded a minute ago is live, but nothing about it is tracked
+  // yet. Deriving the live set from `git ls-files` alone reported it as "does
+  // not exist" — the same species of false alarm as the sentence-final one
+  // above, pointed the other way, at a directory sitting right there on disk.
+  it('treats a package that exists but is not yet tracked as live', () => {
+    const pkg = resolve(REPO_ROOT, 'packages/lint-untracked-probe')
+    try {
+      mkdirSync(resolve(pkg, 'src'), { recursive: true })
+      writeFileSync(resolve(pkg, 'src/index.ts'), 'export const x = 1\n')
+      const r = run(fx('untracked-package.md'))
+      expect(r.output).toBe('')
+      expect(r.exitCode).toBe(0)
+    } finally {
+      rmSync(pkg, { recursive: true, force: true })
+    }
+  })
+
+  // The live set is derived by shelling out to git, so git failing is a mode
+  // this linter has to own. Exiting 1 with a raw ENOENT stack trace would be
+  // indistinguishable from a genuine lint failure; exit 2 says "the linter
+  // could not run", not "your docs are wrong".
+  it('exits 2 with an actionable message when git is unavailable', () => {
+    const r = runWith({
+      env: { PATH: resolve(REPO_ROOT, 'scripts/nonexistent') },
+    })
+    expect(r.exitCode).toBe(2)
+    expect(r.output).toMatch(/git/)
+    expect(r.output).toMatch(/checkout/)
+    expect(r.output).not.toMatch(/at ModuleJob/)
   })
 
   it('names the file and line of each offender', () => {

scripts/__tests__/lint-no-hardcoded-runners.test.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
@@ -8,9 +9,9 @@ const SCRIPT = resolve(
   '../../lint-no-hardcoded-runners.mjs',
 )
 
-function run(target) {
+function runScript(script, ...targets) {
   try {
-    execFileSync('node', [SCRIPT, target], { encoding: 'utf8' })
+    execFileSync(process.execPath, [script, ...targets], { encoding: 'utf8' })
     return { exitCode: 0, output: '' }
   } catch (err) {
     return {
@@ -20,6 +21,10 @@ function run(target) {
   }
 }
 
+function run(target) {
+  return runScript(SCRIPT, target)
+}
+
 describe('lint-no-hardcoded-runners', () => {
   const fx = (name) =>
     resolve(fileURLToPath(import.meta.url), `../fixtures/${name}`)
@@ -70,3 +75,51 @@ describe('lint-no-hardcoded-runners', () => {
     expect(run(fx('identifier.ts')).exitCode).toBe(0)
   })
 })
+
+// An allowlist entry is a standing exemption. When the file it names is deleted
+// — or stops carrying the `npx` literal it was excused for — the entry becomes
+// silent dead weight, and the next reader takes it as evidence that the file
+// still needs an exemption. `packages/drizzle/src/bin/runner.ts` sat here for
+// the two months after 413ca396 deleted its package, and surfaced only because
+// a sibling linter happened to start scanning `scripts/` (#772 review, finding
+// 15). That sibling can only ever catch the `packages/<name>` shape; this check
+// covers every entry, including a stale path inside a live package.
+describe('lint-no-hardcoded-runners — allowlist hygiene', () => {
+  // A copy alongside the original so `REPO_ROOT` still resolves to the repo.
+  const PROBE = resolve(
+    fileURLToPath(import.meta.url),
+    '../../allowlist-probe.mjs',
+  )
+
+  function runWithExtraEntry(entry) {
+    const src = readFileSync(SCRIPT, 'utf8').replace(
+      'const ALLOWLISTED_PATHS = new Set([',
+      `const ALLOWLISTED_PATHS = new Set([\n  '${entry}',`,
+    )
+    try {
+      writeFileSync(PROBE, src)
+      return runScript(PROBE)
+    } finally {
+      rmSync(PROBE, { force: true })
+    }
+  }
+
+  it('rejects an entry whose file no longer exists', () => {
+    const r = runWithExtraEntry('scripts/deleted-helper.mjs')
+    expect(r.exitCode).toBe(2)
+    expect(r.output).toMatch(/scripts\/deleted-helper\.mjs/)
+    expect(r.output).toMatch(/no such file/)
+  })
+
+  it('rejects an entry whose file no longer needs the exemption', () => {
+    const r = runWithExtraEntry('scripts/vitest.config.mjs')
+    expect(r.exitCode).toBe(2)
+    expect(r.output).toMatch(/scripts\/vitest\.config\.mjs/)
+    expect(r.output).toMatch(/no longer contains/)
+  })
+
+  it('accepts the allowlist as it stands', () => {
+    const r = runScript(SCRIPT)
+    expect(r.exitCode).toBe(0)
+  })
+})

scripts/lint-no-dead-package-paths.mjs

@@ -37,8 +37,9 @@ const SKIP_DIRS = new Set([
   'plans',
   'superpowers',
   '.git',
-  // Fixtures for this linter's own self-tests deliberately reference deleted
-  // packages; scanning them would make the suite unrunnable.
+  // This linter's own self-tests deliberately reference deleted packages —
+  // in the fixtures, and in the prose comments of the test files themselves.
+  // Scanning them would make the suite unrunnable.
   '__tests__',
 ])
 const SKIP_FILES = new Set(['CHANGELOG.md'])
@@ -58,7 +59,7 @@ const TEXT_EXT = /\.(md|ya?ml|json|mjs|ts|txt)$/
 // (#772 review, finding 15).
 const PACKAGE_REF = /packages\/([a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?)/g
 
-// Live packages come from what git TRACKS, not from what is on disk.
+// Live packages come from git, not from what is on disk.
 //
 // `readdirSync` was wrong in the direction that matters: deleting a package
 // leaves its `dist/` and `node_modules/` behind, so the directory still exists
@@ -71,18 +72,61 @@ const PACKAGE_REF = /packages\/([a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?)/g
 // Note this deliberately does NOT require a `package.json`: `packages/utils` has
 // none (it is two loose files consumed by relative path from `packages/nextjs`)
 // yet is tracked, live, and referenced from AGENTS.md.
+//
+// Shelling out to git is a dependency this linter has to own: git missing, or a
+// tree with no `.git`, must not read as "every package is dead".
+function gitPackagePaths(...args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    })
+      .split('\0')
+      .filter(Boolean)
+  } catch (err) {
+    const detail = String(err.stderr || err.message || '').trim()
+    console.error(
+      `Could not list packages via \`git ${args.join(' ')}\`:\n\n  ${detail}\n\n` +
+        'This linter derives the live package set from git, so it cannot run\n' +
+        'without git on PATH or outside a git checkout.',
+    )
+    // Exit 2, not 1: the linter failed to run. Exit 1 means it ran and found
+    // dead references, which is a different thing to go and fix.
+    process.exit(2)
+  }
+}
+
 const livePackages = new Set(
-  execFileSync('git', ['ls-files', '-z', 'packages'], {
-    cwd: REPO_ROOT,
-    encoding: 'utf8',
-    maxBuffer: 64 * 1024 * 1024,
-  })
-    .split('\0')
-    .filter(Boolean)
+  [
+    ...gitPackagePaths('ls-files', '-z', 'packages'),
+    // Untracked but not ignored. A package scaffolded a minute ago is live
+    // even though nothing about it is staged yet, and reporting it as "does
+    // not exist" is the sentence-final false alarm all over again, pointed the
+    // other way. `--directory` is deliberately NOT passed: it collapses an
+    // all-ignored directory to a single entry, which would resurrect exactly
+    // the `dist/`-and-`node_modules/` shells this linter exists to catch.
+    ...gitPackagePaths(
+      'ls-files',
+      '--others',
+      '--exclude-standard',
+      '-z',
+      'packages',
+    ),
+  ]
     .map((file) => file.split('/')[1])
     .filter(Boolean),
 )
 
+if (livePackages.size === 0) {
+  console.error(
+    'git reported no packages at all under `packages/`. Refusing to run —\n' +
+      'every reference would be flagged. Check that `packages/` is present and\n' +
+      'not wholly ignored.',
+  )
+  process.exit(2)
+}
+
 function* walk(abs) {
   const stat = statSync(abs)
   if (stat.isFile()) {