Skip to content

[Rust port] Lockstep 2.0 release (TS 1.x final + cutover + npm deprecate) #249

@willwashburn

Description

@willwashburn

Parent: #240

Context

Lockstep 2.0 release: cut the final TS 1.x, ship Rust binaries + crates + npm packages, deprecate the retired npm packages, document the migration. Single-day coordinated release — the orchestration, not the porting.

Scope

Pre-cutover

  • Cut a final 1.x lockstep release of all 8 TS packages so anyone who can't migrate has a stable pin.
  • Update root CHANGELOG.md with a migration note explaining the v2 transition.
  • Update README.md to point at the Rust install paths.

Cutover day

Single GitHub Actions workflow that, in order:

  1. Builds + tests the entire Cargo workspace.
  2. Builds prebuilt burn binaries for darwin-arm64, darwin-x64, linux-arm64, linux-x64 (optionally win32-x64).
  3. Publishes relayburn-sdk@1.0.0 and relayburn-cli@1.0.0 to crates.io (OIDC trusted-publisher).
  4. Builds + publishes @relayburn/sdk@2.0.0 (umbrella) + per-platform packages (@relayburn/sdk-darwin-arm64, etc.) via the napi-rs CI matrix.
  5. Builds + publishes relayburn@2.0.0 as a postinstall download shim that fetches the right burn binary from GitHub Releases.
  6. Creates GitHub Release tagged v2.0.0 with the prebuilt binaries attached.

Post-cutover (same day)

  • Run npm deprecate on the six retired packages with messages pointing at 2.0:
    • @relayburn/reader → "merged into @relayburn/sdk 2.0; internal Rust crate now"
    • @relayburn/ledger → same
    • @relayburn/analyze → same
    • @relayburn/ingest → same
    • @relayburn/mcp → "use burn mcp-server from the burn binary, or @relayburn/sdk for embedded MCP"
    • @relayburn/cli → "use the burn binary from the relayburn npm package or GitHub Releases"
  • Don't unpublish — pinned consumers should keep working forever.

Wash bump

  • Coordinate with wash team to bump to relayburn-sdk = "1" immediately after publish.

Decommission

  • Remove packages/{reader,ledger,analyze,ingest,sdk,mcp,cli} from the repo. Only packages/sdk-node survives.
  • Repo becomes a Cargo workspace with one TS subdirectory for the npm facade.
  • Update CLAUDE.md to reflect the new layout.

Depends on

#241, #242, #243, #244, #245, #246, #247, #248

Acceptance

  • Final TS 1.x lockstep release published.
  • cargo install relayburn-cli on a clean machine produces a working burn binary.
  • curl -fsSL <github-release-url> | tar xz produces a working burn binary on all 4 primary platforms.
  • npm i -g relayburn on a clean machine downloads the right burn binary via postinstall.
  • npm i @relayburn/sdk resolves the prebuilt napi-rs umbrella + correct platform package.
  • All 6 deprecated packages show npm deprecation warnings with the messages above.
  • Wash builds successfully against relayburn-sdk = "1".
  • packages/{reader,ledger,analyze,ingest,sdk,mcp,cli} removed from the repo.
  • Migration note merged into root CHANGELOG.md + README.md.
  • gh issue close 218 (already closed, but cross-link to v2 SDK in a comment for posterity).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions