fix(cli): close the review findings on the release-train coupling

Seven findings from the code-review pass, all addressed:

1. compareVersions gets a strict shape gate (^\d+\.\d+\.\d+ with optional
   well-formed prerelease; build metadata rejected): empty prerelease
   ('1.0.0-'), '+metadata', truncated/extra cores, and parseInt trailing
   garbage ('9.9.10rc') all previously slipped the NaN-only guard and could
   classify a malformed install as 'ahead', suppressing the reinstall
   guidance. One gate now encodes the whole not-comparable policy; the NaN
   check is subsumed. Test matrix covers every class.
2. Mixed ahead+missing no longer silently manufactures a cross-train
   mismatch: when missing packages are about to be installed beside newer
   ones, the warning says the pairing may not match and to update stash
   first.
3. The ahead warning prints the exact update command (devInstallCommand of
   stash@<highest installed>) — lockstep guarantees that release exists —
   instead of an uncommanded "matching release".
4. @cipherstash/prisma-next JOINS the fixed group (per Dan: the prisma-next
   package should line up to the train version too). The changeset's
   "can never go stale" claim is now actually true — no residual exclusion.
5. release-train.test.ts gains the growth guard: the changesets fixed group
   must equal RELEASE_TRAIN_MANIFESTS exactly, so a future train package
   can't silently version outside the lockstep.
6. skills/stash-cli skew sentence is direction-aware (align when older;
   update stash — never downgrade — when newer), fixing the now-wrong
   unconditional "align versions before continuing".
7. Companion changesets for @cipherstash/wizard and @cipherstash/prisma-next
   so their CHANGELOGs explain the version-line jump onto the train.

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

Author: coderdan

.changeset/config.json

@@ -8,6 +8,7 @@
       "@cipherstash/stack",
       "@cipherstash/stack-drizzle",
       "@cipherstash/stack-supabase",
+      "@cipherstash/prisma-next",
       "@cipherstash/wizard"
     ]
   ],

.changeset/prisma-next-joins-release-train.md

@@ -0,0 +1,9 @@
+---
+'@cipherstash/prisma-next': patch
+---
+
+`@cipherstash/prisma-next` now versions in lockstep with the Stack release
+train (`stash`, `@cipherstash/stack`, and the other adapters) via a Changesets
+`fixed` group — `stash init` installs it pinned by exact version, so the two
+must always release together. This moves the package from its previous `0.4.x`
+line onto the shared train version; no API changes.

.changeset/release-train-coupling.md

@@ -7,17 +7,19 @@ Two guards for the release-train version embed (#661 follow-up):
 **Direction-aware version skew.** `stash init` now distinguishes an installed
 package that is *behind* this CLI release (offered alignment / the pinned
 install command, as before) from one that is *newer* than the release expects.
-A newer install no longer produces a downgrade command — init says the install
-is likely fine and to update the stash CLI to the matching release instead.
-Unreadable manifests still count as behind (a broken install should be offered
-the reinstall fix).
+A newer install no longer produces a downgrade command — init prints the exact
+`stash` update command instead (release-train lockstep guarantees that version
+exists), and when missing packages are about to be installed alongside newer
+ones it says the pairing may not match and to update `stash` first. Unreadable
+or malformed manifest versions always count as behind (a broken install should
+be offered the reinstall fix, never "looks newer, leave it").
 
 **Version lockstep.** The release-train packages (`stash`,
 `@cipherstash/stack`, `@cipherstash/stack-drizzle`,
-`@cipherstash/stack-supabase`, `@cipherstash/wizard`) are now a Changesets
-`fixed` group: a release of any of them republishes all of them at the same
-version, so the CLI's embedded version map can never go stale against the
-packages it pins (previously a stack-only release would have left the
-published CLI embedding — and recommending — outdated versions).
-`@cipherstash/prisma-next` stays on its own version line by design; the
-direction-aware messaging above covers it.
+`@cipherstash/stack-supabase`, `@cipherstash/prisma-next`,
+`@cipherstash/wizard`) are now a Changesets `fixed` group: a release of any of
+them republishes all of them at the same version, so the CLI's embedded
+version map can never go stale against the packages it pins (previously a
+runtime-package-only release would have left the published CLI embedding —
+and recommending — outdated versions). A test now asserts the fixed group
+stays exactly equal to the release train.

.changeset/wizard-joins-release-train.md

@@ -0,0 +1,9 @@
+---
+'@cipherstash/wizard': patch
+---
+
+`@cipherstash/wizard` now versions in lockstep with the Stack release train
+(`stash`, `@cipherstash/stack`, and the adapters) via a Changesets `fixed`
+group — the `stash` CLI executes the wizard by exact version, so the two must
+always release together. This moves the package from its previous `0.5.x`
+line onto the shared train version; no API changes.

packages/cli/src/__tests__/release-train.test.ts

@@ -6,6 +6,7 @@ import { INTEGRATION_ADAPTER_PACKAGES } from '../commands/init/steps/install-dep
 import { RELEASE_TRAIN_MANIFESTS } from '../release-train.js'
 
 const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+const REPO_ROOT = resolve(CLI_ROOT, '../..')
 
 // The growth guard for #661: `RELEASE_TRAIN_MANIFESTS` is the single source
 // the build embeds versions from, and `INTEGRATION_ADAPTER_PACKAGES` is what
@@ -46,4 +47,20 @@ describe('release train coverage', () => {
       expect((m.version as string).length).toBeGreaterThan(0)
     }
   })
+
+  it('the changesets fixed group is exactly the release train (staleness guard)', () => {
+    // The staleness half of #661/#669 is release-process config: every train
+    // package must version in lockstep with `stash`, or a release of the odd
+    // one out ships while the published CLI still embeds — and pins — its old
+    // version. Guard the config like the code: group membership must equal
+    // the train, exactly.
+    const config = JSON.parse(
+      readFileSync(resolve(REPO_ROOT, '.changeset/config.json'), 'utf8'),
+    ) as { fixed?: string[][] }
+    const group = config.fixed?.find((g) => g.includes('stash'))
+    expect(group, 'a changesets fixed group containing stash').toBeDefined()
+    expect(new Set(group)).toEqual(
+      new Set(Object.keys(RELEASE_TRAIN_MANIFESTS)),
+    )
+  })
 })

packages/cli/src/__tests__/runtime-versions.test.ts

@@ -116,12 +116,26 @@ describe('compareVersions', () => {
     expect(compareVersions('1.0.0-rc.1', '1.0.0-rc.1')).toBe(0)
   })
 
-  it('treats a non-numeric core as not comparable (never "ahead")', () => {
-    // A corrupt manifest version must not NaN-poison the order into 1
-    // ("installed is newer") — that would suppress the align guidance.
+  it('treats any malformed version as not comparable (never "ahead")', () => {
+    // A corrupt manifest version must not partially parse into 1 ("installed
+    // is newer") — that would suppress the align guidance. The strict shape
+    // gate rejects every malformed class, not just NaN-able cores:
     expect(compareVersions('v1.0.0', '1.0.0')).toBe(0)
     expect(compareVersions('1.0.x', '1.0.0')).toBe(0)
     expect(compareVersions('garbage', '1.0.0')).toBe(0)
+    // truncated core — '1.0' padded to 1.0.0 would outrank 1.0.0-rc.2
+    expect(compareVersions('1.0', '1.0.0-rc.2')).toBe(0)
+    // extra core segment
+    expect(compareVersions('1.2.3.4', '1.2.3')).toBe(0)
+    // empty prerelease — '1.0.0-' as a release would outrank any rc
+    expect(compareVersions('1.0.0-', '1.0.0-rc.1')).toBe(0)
+    // parseInt trailing garbage — '9.9.10rc' would parse as core 9.9.10
+    expect(compareVersions('9.9.10rc', '9.9.9')).toBe(0)
+    expect(compareVersions('1.0.0beta', '1.0.0-rc.1')).toBe(0)
+    // build metadata — '2+sha' as an identifier would mis-order vs 'rc.10'
+    expect(compareVersions('1.0.0-rc.2+sha.abc', '1.0.0-rc.10')).toBe(0)
+    // empty prerelease identifier
+    expect(compareVersions('1.0.0-rc..1', '1.0.0-rc.1')).toBe(0)
   })
 
   it('numeric identifiers sort below alphanumeric; shorter below longer', () => {

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

@@ -13,6 +13,9 @@ vi.mock('../../utils.js', () => ({
       ...(dev.length ? [`npm install --save-dev ${dev.join(' ')}`] : []),
     ],
   ),
+  devInstallCommand: vi.fn(
+    (_pm: string, pkg: string) => `npm install -D ${pkg}`,
+  ),
   detectPackageManager: vi.fn(() => 'npm'),
 }))
 // Pin map: pretend this CLI release was built alongside these versions, so
@@ -234,12 +237,43 @@ describe('installDepsStep', () => {
         '@cipherstash/stack: installed 9.9.10 is newer than this release of stash expects (9.9.9-test.1)',
       ),
     )
+    // Lockstep means stash@<installed> must exist — the warning prints the
+    // exact update command instead of an uncommanded "matching release".
+    expect(p.log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('npm install -D stash@9.9.10'),
+    )
     // No align/downgrade guidance, no mutation, clean success.
     expect(p.note).not.toHaveBeenCalled()
     expect(execSyncMock).not.toHaveBeenCalled()
     expect(result.stackInstalled).toBe(true)
   })
 
+  it('mixed ahead + missing: warns that fresh installs pin to THIS release and may mismatch', async () => {
+    vi.mocked(isInteractive).mockReturnValue(false)
+    // stack is installed and NEWER; the supabase adapter is missing — init
+    // will install the adapter at this CLI's older embed, so it must say the
+    // pairing may not match rather than silently manufacturing a cross-train
+    // mismatch under a "likely fine" banner.
+    present('@cipherstash/stack', 'stash')
+    resolvedVersions({
+      '@cipherstash/stack': '9.9.10',
+      stash: FIXTURE_VERSIONS.stash,
+    })
+
+    await installDepsStep.run(baseState, supabaseProvider)
+
+    expect(p.log.warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "@cipherstash/stack-supabase will be installed at THIS release's versions",
+      ),
+    )
+    expect(p.log.warn).toHaveBeenCalledWith(
+      expect.stringContaining('npm install -D stash@9.9.10'),
+    )
+    // The missing adapter still installs (non-interactive default).
+    expect(execSyncMock).toHaveBeenCalled()
+  })
+
   it('reports an unreadable manifest as skew, not as a matching install', async () => {
     vi.mocked(isInteractive).mockReturnValue(false)
     present('@cipherstash/stack', 'stash')

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

@@ -12,6 +12,7 @@ import { CancelledError } from '../types.js'
 import {
   combinedInstallCommands,
   detectPackageManager,
+  devInstallCommand,
   installedVersion,
   isPackageInstalled,
 } from '../utils.js'
@@ -191,11 +192,6 @@ export const installDepsStep: InitStep = {
     if (skewed.length > 0) {
       p.log.warn(`Version skew detected:\n  ${skewLines(skewed)}`)
     }
-    if (ahead.length > 0) {
-      p.log.warn(
-        `Installed versions are newer than this release of stash:\n  ${aheadLines(ahead)}\nYour installs are likely fine — update the stash CLI to the matching release instead of downgrading.`,
-      )
-    }
 
     // What's missing outright (pinned, prod/dev split).
     const missing: string[] = []
@@ -204,6 +200,29 @@ export const installDepsStep: InitStep = {
     if (!cliPresent) missing.push(CLI_PACKAGE)
     const missingSplit = splitProdDev(missing)
 
+    if (ahead.length > 0) {
+      // Every release-train package versions in lockstep (the changesets
+      // `fixed` group), so a train package strictly ahead of this CLI's embed
+      // implies a stash release exists at that exact version — print the
+      // command instead of leaving the user to research "the matching
+      // release". Highest ahead version wins when several differ.
+      const target = ahead
+        .map(({ installed }) => installed)
+        .reduce((max, v) => (compareVersions(v, max) > 0 ? v : max))
+      const updateCmd = devInstallCommand(pm, `stash@${target}`)
+      // Installing MISSING packages now would pin them to this CLI's older
+      // embed, pairing them with the newer installed packages — a combination
+      // no lockstep release ever shipped. Say so instead of silently
+      // manufacturing the mismatch.
+      const missingNote =
+        missing.length > 0
+          ? `\nNote: ${missing.join(', ')} will be installed at THIS release's versions, which may not match the newer packages above — for a consistent set, update stash first and re-run init:\n  ${updateCmd}`
+          : `\nUpdate with:\n  ${updateCmd}\nthen re-run init.`
+      p.log.warn(
+        `Installed versions are newer than this release of stash:\n  ${aheadLines(ahead)}\nYour installs are likely fine — update the stash CLI to the matching release instead of downgrading.${missingNote}`,
+      )
+    }
+
     // Interactively, skewed packages can be aligned in the same install run.
     // Non-interactive runs never mutate an existing install: agents/CI get
     // the warning + exact commands above and keep going.

packages/cli/src/runtime-versions.ts

@@ -104,13 +104,22 @@ export function pinnedSpec(
  * (`x.y.z` and `x.y.z-rc.n`), so the skew warning can tell "behind" from
  * "ahead" without adding a dependency to the CLI.
  *
- * A version whose core isn't numeric (`v1.0.0`, `1.0.x`, garbage from a
- * corrupt manifest) is NOT COMPARABLE: return `0` rather than a
- * NaN-poisoned order. Callers classify non-ahead as behind, so an
- * unparseable installed version gets the safe treatment (align/reinstall
+ * A version that isn't strictly `digits.digits.digits` with an optional
+ * well-formed prerelease (`v1.0.0`, `1.0.x`, `1.0`, `1.0.0-`, `1.0.0beta`,
+ * `1.0.0-rc.2+sha` — build metadata deliberately rejected, and any other
+ * garbage from a corrupt manifest) is NOT COMPARABLE: return `0` rather
+ * than a partially-parsed order. Callers classify non-ahead as behind, so
+ * an unparseable installed version gets the safe treatment (align/reinstall
  * guidance) instead of being silently promoted to "newer, leave it".
  */
+/** Exactly three numeric core segments, optional dot-separated prerelease
+ * identifiers (each non-empty alphanumeric/hyphen). No build metadata: `+`
+ * fails the shape and the version is treated as not comparable — the safe
+ * direction — rather than mis-ordered by an identifier like `2+sha`. */
+const VERSION_SHAPE = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/
+
 export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  if (!VERSION_SHAPE.test(a) || !VERSION_SHAPE.test(b)) return 0
   const parse = (v: string) => {
     const [core, ...pre] = v.split('-')
     return {
@@ -120,10 +129,10 @@ export function compareVersions(a: string, b: string): -1 | 0 | 1 {
   }
   const pa = parse(a)
   const pb = parse(b)
-  if (pa.core.some(Number.isNaN) || pb.core.some(Number.isNaN)) return 0
   for (let i = 0; i < 3; i++) {
-    const da = pa.core[i] ?? 0
-    const db = pb.core[i] ?? 0
+    // The shape gate guarantees exactly three numeric segments.
+    const da = pa.core[i] as number
+    const db = pb.core[i] as number
     if (da !== db) return da < db ? -1 : 1
   }
   // Same core: a release (no prerelease) outranks any prerelease of it.

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 warns if an already-installed package's resolved version differs from the release's — treat that warning as a real problem and align versions before continuing.
+`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 warns if an already-installed package's resolved version differs from the release's. Treat that warning as a real problem — but 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).
 
 **If you are an agent, do this first:**