fix(cli): direction-aware version skew + release-train version lockstep

[coderdan]

Why

Follow-up closing the one #666 review finding deliberately left out of that PR: post-GA staleness of the version embed. stash has no publishable dependency edge to the runtime packages, so a runtime-only release would not republish stash — the live CLI tarball would keep embedding (and init would keep pinning/recommending) outdated versions, and the skew warning would tell users on correctly-newer versions to downgrade (versionSkew was a bare !== with no direction).

What

1. Changesets fixed group — the whole release train: stash, @cipherstash/stack, @cipherstash/stack-drizzle, @cipherstash/stack-supabase, @cipherstash/prisma-next, @cipherstash/wizard version in lockstep: any release republishes all, so the embed can never go stale against the packages it pins. prisma-next joins per Dan (its version lines up with the train too); a new test asserts fixed group == RELEASE_TRAIN_MANIFESTS exactly, so a future train package can't silently version outside the lockstep. Companion changesets give wizard (0.5.x→train) and prisma-next (0.4.x→train) CHANGELOG entries explaining the version-line jump. changeset status + a dry-run changeset version validated (whole train converges; pre-mode safe — verified against @changesets/assemble-release-plan's fixed-group handling).

2. Direction-aware skew — versionSkew entries carry direction: 'behind' | 'ahead' via a small prerelease-aware comparator (no new dependency, per the supply-chain policy), now guarded by a strict shape gate: anything not exactly digits.digits.digits[-well-formed-prerelease] (build metadata included) is not comparable → classified behind → safe reinstall guidance. This closes the whole malformed-version family (1.0.0-, +sha, 1.0, 1.0.0beta, 9.9.10rc), not just NaN cores.

• behind (or unreadable/malformed manifest): align offer / pinned install command, as in fix(cli): pin init's installs to the release's own package versions (#661) #666.
• ahead: never a downgrade — the warning prints the exact npm install -D stash@<installed> (lockstep guarantees that release exists) and, when missing packages are about to be installed beside newer ones, says the pairing may not match and to update stash first (no more silently-manufactured cross-train mixes).
• skills/stash-cli skew guidance is now direction-aware to match (rule 8).

Tests

497 unit + 58 e2e green. Comparator matrix covers every malformed class; ahead/mixed paths asserted end-to-end; fixed-group growth guard in release-train.test.ts.

After merge

Rebase #655 onto this so CJ's prisma-next work rides the same train version.

https://claude.ai/code/session_01MxTTPaPP16m6br7Hoab94w

Summary by CodeRabbit

• New Features

  • stash init now distinguishes outdated and newer installed packages.
  • Outdated packages receive alignment and reinstall guidance.
  • Newer packages trigger an update recommendation for the stash CLI instead of a downgrade.
  • Missing packages are installed with the versions required by the current release, with mismatch warnings when necessary.
  • Related packages now release together at matching versions.

• Documentation

  • Expanded guidance explains how to resolve version mismatches and when to update the CLI.

[changeset-bot]

🦋 Changeset detected

Latest commit: daa25b8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@cipherstash/prisma-next	Patch
stash	Patch
@cipherstash/wizard	Patch
@cipherstash/prisma-next-example	Patch
@cipherstash/basic-example	Patch
@cipherstash/e2e	Patch
@cipherstash/stack	Patch
@cipherstash/stack-drizzle	Patch
@cipherstash/stack-supabase	Patch
@cipherstash/bench	Patch
@cipherstash/test-kit	Patch

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e64eaf86-0d13-4456-b4d9-507052ce49a0

📥 Commits

Reviewing files that changed from the base of the PR and between 7d1226a and daa25b8.

📒 Files selected for processing (10)

• .changeset/config.json
• .changeset/prisma-next-joins-release-train.md
• .changeset/release-train-coupling.md
• .changeset/wizard-joins-release-train.md
• packages/cli/src/__tests__/release-train.test.ts
• packages/cli/src/__tests__/runtime-versions.test.ts
• packages/cli/src/commands/init/steps/__tests__/install-deps.test.ts
• packages/cli/src/commands/init/steps/install-deps.ts
• packages/cli/src/runtime-versions.ts
• skills/stash-cli/SKILL.md

---

📝 Walkthrough

Walkthrough

Changes

Release train alignment

Layer / File(s)	Summary
Release-train version comparison packages/cli/src/runtime-versions.ts, packages/cli/src/__tests__/runtime-versions.test.ts	Adds strict release and prerelease version comparison, with coverage for precedence and malformed versions.
Direction-aware init dependency handling packages/cli/src/commands/init/steps/install-deps.ts, packages/cli/src/commands/init/steps/__tests__/install-deps.test.ts, skills/stash-cli/SKILL.md, .changeset/release-train-coupling.md	Classifies installed packages as behind or ahead, warns against downgrading newer packages, and continues installing missing packages with release-pinned versions.
Fixed release-train configuration and validation .changeset/config.json, .changeset/*release-train*.md, packages/cli/src/__tests__/release-train.test.ts	Defines the fixed package group, adds release metadata for Prisma Next and Wizard, and verifies the group matches the CLI release-train manifests.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant StashInit
  participant InstallDepsStep
  participant PackageManifests
  User->>StashInit: run init
  StashInit->>InstallDepsStep: inspect release-train packages
  InstallDepsStep->>PackageManifests: read installed versions
  PackageManifests-->>InstallDepsStep: package versions
  InstallDepsStep-->>User: show alignment or CLI update guidance

Loading

Possibly related PRs

• cipherstash/stack#666: Updates the related stash init pinned-version and runtime-version handling.

Suggested reviewers: calvinbrewer

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main changes: direction-aware version skew handling and release-train lockstep versioning.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/release-train-coupling

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR hardens the stash init version-pinning workflow by (1) preventing “downgrade” guidance when a project already has newer runtime packages installed, and (2) ensuring the CLI’s embedded runtime-version map can’t go stale by locking the release-train packages to a single Changesets fixed version line.

Changes:

• Add a lightweight semver-precedence comparator to classify version skew as “behind” vs “ahead”.
• Update stash init dependency installation step to only offer “align” actions for behind packages, and emit a distinct warning for ahead packages (update stash, never downgrade runtime deps).
• Couple the release-train packages into a Changesets fixed group and add a changeset describing the behavior change; expand unit/E2E coverage for the new “ahead” path.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/cli/src/runtime-versions.ts	Adds compareVersions helper for prerelease-aware ordering used by skew direction logic.
packages/cli/src/commands/init/steps/install-deps.ts	Introduces direction-aware skew classification and warning text; only “behind” skew gets alignment handling.
packages/cli/src/commands/init/steps/tests/install-deps.test.ts	Updates mocks to retain real helpers; adds coverage asserting “ahead” never triggers downgrade/align commands.
packages/cli/src/tests/runtime-versions.test.ts	Adds a comparator precedence matrix for compareVersions.
.changeset/release-train-coupling.md	Documents the direction-aware skew behavior and the new lockstep release-train coupling.
.changeset/config.json	Defines a Changesets fixed group for the release-train packages to enforce lockstep versioning.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderdan]

Human and AI review (Copilot, Claude/Fable).