feat(cli,examples,docs)!: de-suffix the init scaffold, rewrite examples/basic to v3, sweep the meta (EQL v2 removal PR 7)#776
Conversation
🦋 Changeset detectedLatest commit: 5282281 The changes in this PR will be included in the next version bump. This PR includes changesets to release 11 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
freshtonic
left a comment
freshtonic
left a comment
There was a problem hiding this comment.
Approve
Reviewed the full diff against the PR branch source (base remove-v2). This is a well-scoped correctness sweep for the v2 removal — one small functional change plus scaffold/example/doc/skill corrections — and everything I checked holds up.
Verified
The one functional change — export { Encryption } from @cipherstash/stack/v3 (packages/stack/src/encryption/v3.ts)
Encryptionis the value imported from@/ffi; the re-export is legitimate.- No duplicate-export hazard:
@/eql/v3(pulled in by the adjacentexport *) exports noEncryptionsymbol, soexport *+export { Encryption }can't collide.export const EncryptionV3 = Encryptionalready coexists with thatexport *, which is the same guarantee. - This is what makes the scaffold's emitted
import { Encryption, encryptedTable, types } from '@cipherstash/stack/v3'resolve to a single specifier — the deprecation example inv3.tshad documented that import without it resolving.
Scaffold + its tests — utils.ts flips every EncryptionV3 → Encryption (real template output + placeholder comments); utils-codegen.test.ts adds .not.toContain('EncryptionV3') negatives mirroring the drizzle precedent, so a regression to the deprecated name fails a test rather than shipping silently.
examples/basic — deleted src/lib/supabase/* and src/queries/contacts.ts are gone with no dangling importers; encrypt.ts / index.ts / src/encryption/index.ts are clean; tsconfig.json and the typecheck script exist; package name @cipherstash/basic-example matches the CI --filter. The turbo typecheck task's dependsOn: ["^build"] correctly builds stack/stack-drizzle/stash first, and the gate lands on the .github/workflows/tests.yml typecheck stage.
Doc/skill corrections are accurate, not aspirational — confirmed against packages/stack-supabase/src/index.ts on this branch: encryptedSupabase is the v3 factory and encryptedSupabaseV3 is export const … = encryptedSupabase (@deprecated). So the AGENTS.md / SECURITY.md / supabase-sdk.md / stash-cli / stash-encryption / stash-drizzle / stash-prisma-next edits all match reality. The "DynamoDB writes v3, reads v2" reframing lines up with the merged #725 work and the stack-encryption skill.
Changesets — stash + @cipherstash/stack patch covers scaffold + re-export + skills (skills ship in the stash tarball); @cipherstash/stack-drizzle patch covers the README. Correct.
Minor, non-blocking
turbo.json's newtypechecktask sets"cache": false. Typecheck is deterministic and cacheable, but with a single consumer and no remote cache the win is negligible — fine as-is, just noting it's inconsistent withbuildbeing cached.
Couldn't independently run the live/credential-gated @cipherstash/stack suite (as the PR notes, those need CS_* secrets CI supplies), but the additive re-export's only real risk — the index.ts ↔ v3.ts circular import — is covered by cjs-require.test.ts. LGTM.
…sic to v3 PRs 3-5 of the EQL v2 removal froze the target names, but nothing type-checks the artefacts that describe them, so two were left wrong. `stash init` scaffolded `EncryptionV3` into customer source. That name is a deprecated alias now, and the scaffold is a template literal, so only an assertion can catch it — the codegen tests pinned the old form, so they are flipped with negatives added, mirroring the drizzle precedent from 7b783ee. `@cipherstash/stack/v3` exported `EncryptionV3` but not `Encryption`, so the scaffold could not emit a single clean import. Re-export it — the deprecation example in v3.ts already told users to import it from there. `examples/basic` had not compiled since the removal deleted `encryptedType` and the v2 `encryptedSupabase`. Ported to the v3 types.* factories. Its Supabase branch is deleted rather than ported: it imported a `contactsTable` that was never exported, so it was already dead before this work, and examples/supabase-worker carries the Supabase story. Root `build`/`test` filter to ./packages/*, so CI never compiled any example and the breakage sat on a green board. Gate examples/basic through a new turbo `typecheck` task so `^build` builds its deps first. Verified the gate fails on the exact regression that shipped.
PRs 3-5 froze the API names but the prose describing them was not swept, so the shipped guidance told users the opposite of what the code does. The worst of it is in skills/, which ship inside the stash tarball and get copied into customer repos: stash-encryption and stash-cli both described `encryptedSupabase` as the legacy EQL v2 wrapper. It is the EQL v3 factory — the v2 wrapper was deleted in #769. stash-drizzle taught `EncryptionV3` as the canonical client, contradicting stash-encryption, which correctly calls it deprecated. Also corrects the @cipherstash/stack README, the npm landing page, which claimed DynamoDB "still requires v2" and pointed at #657 — #768 removed the v2 write overloads and #657 is closed. The root README quickstart still taught the v2 chainable builders as the primary example. Reframes the "Legacy: EQL v2" sections to say what is actually true now: v2 is a read path, not an authoring surface. Left alone deliberately: the v2 CLI/database sections in supabase-sdk.md and the v2 read path in stash-dynamodb — both accurate today, and the CLI text moves with the SQL teardown. `export { Encryption }` in v3.ts is ordered after the `export *` so Biome's organizeImports is satisfied without detaching the comment from its subject.
f2cccf8 to
5282281
Compare
2 participants
PR 7 of the EQL v2 removal stack (#707), on top of
remove-v2. Part of #752.PRs 3–5 froze the target names —
EncryptionoverEncryptionV3,encryptedSupabaseas the v3 factory,stack-drizzle's./v3collapsed to root. Nothing type-checks the artefacts that describe those names, so three classes of them were left wrong.What was broken
stash initscaffolded the deprecated name into customer source.init/utils.tsemittedEncryptionV3in template literals. Commit7b783eeffixed the drizzle half; the@cipherstash/stack/v3half was missed, andutils-codegen.test.tsactively pinned the old form.examples/basichad not compiled since the removal. It importedencryptedType(deleted in #770) and called the v2encryptedSupabase({ encryptionClient, supabaseClient })(deleted in #769). Rootbuild/testfilter to./packages/*, so no example was ever compiled by CI — this sat on a fully green board.Shipped skills inverted the Supabase naming.
skills/ships in thestashtarball and is copied into customer repos.stash-encryptionandstash-cliboth describedencryptedSupabaseas the legacy v2 wrapper; it is the v3 factory.stash-drizzletaughtEncryptionV3as canonical, contradictingstash-encryption, which correctly calls it deprecated.Changes
@cipherstash/stack/v3now re-exportsEncryption. It exportedEncryptionV3but not the name it aliases, so the scaffold could not emit one clean import — and the deprecation example inv3.tsalready told users to importEncryptionfrom there, which did not resolve.Scaffold and its tests flipped, with negative assertions added mirroring the drizzle precedent.
examples/basicported to the v3types.*factories. Its Supabase branch is deleted rather than ported:src/lib/supabase/andsrc/queries/imported acontactsTablethatsrc/encryption/index.tsnever exported, so they were already dead before this work — andexamples/supabase-workercarries the Supabase story. Rebuilding a working demo there would mean authoring a table that never existed, which is example-writing, not v2 removal.New turbo
typechecktask gatesexamples/basicin CI so^buildbuilds its deps first. Verified the gate fails on the exact regression that shipped (reintroducedencryptedType, confirmederror TS2305, reverted).Docs corrected: the
@cipherstash/stackREADME claimed DynamoDB "still requires v2" and pointed at #657 — #768 removed the v2 write overloads and #657 is closed. The root README quickstart still taught the v2 chainable builders as its primary example.Deliberately not in scope
The v2 CLI/database sections of
docs/reference/supabase-sdk.md,packages/cli/README.md, and thedb push/--eql-version 2parts ofskills/stash-cliare accurate today and move with the SQL teardown. Likewise the v2 read path documented instash-dynamodb— that is intentional per design Decision 6.Verification
code:checkclean (0 errors),lint:package-paths,lint:runners,test:scripts, fullbuild, cli suite (837), type tests for stack/drizzle/supabase, prisma-next + wizard typechecks,examples/basictypecheck, and thecjs-requirecircular-import guard — all pass.18
@cipherstash/stacktests fail locally withKey provider error: Profile not found; they are credential-gated and CI supplies theCS_*secrets. The additive re-export's one real risk was the knownindex.ts ↔ v3.tscircular import, whichcjs-require.test.tsguards — it passes.Branch is rebased on
remove-v2— two commits, no merge commits.packages/stack-drizzle/README.mdis fixed against the version currently onremove-v2; #775's rewrite of that file lands separately whenremove-v2next takesmain, and will need the sameEncryptionV3→Encryptionfix applied to its new text.