codewhale/docs/RELEASE_RUNBOOK.md

DeepSeek TUI Release Runbook

This runbook is the source of truth for shipping Rust crates, GitHub release assets, and the deepseek-tui npm wrapper.

Current packaging note:

• deepseek-tui is the live runtime and TUI package shipped to users today.
• deepseek-tui-core is a supporting workspace crate for the extraction/parity effort, not a replacement for the shipping runtime.

Canonical Publish Targets

• End-user crates:
  • deepseek-tui
  • deepseek-tui-cli
• Supporting crates published from this workspace:
  • deepseek-config
  • deepseek-protocol
  • deepseek-state
  • deepseek-agent
  • deepseek-execpolicy
  • deepseek-hooks
  • deepseek-mcp
  • deepseek-tools
  • deepseek-core
  • deepseek-app-server
  • deepseek-tui-core
• deepseek-cli on crates.io is an unrelated crate and is not part of this release flow.

Version Coordination

• Rust crates inherit the shared workspace version from Cargo.toml.
• Internal path dependency versions should match the shared workspace version; stale older pins are release blockers once the workspace version moves.
• The npm wrapper version lives in npm/deepseek-tui/package.json.
• deepseekBinaryVersion controls which GitHub release binaries the npm wrapper downloads.
• Packaging-only npm releases are allowed:
  • bump the npm package version
  • leave deepseekBinaryVersion pinned to the previously released Rust binaries
  • rerun npm pack smoke checks before npm publish

Preflight

Run these from the repository root before cutting a tag:

cargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-features --locked
cargo publish --dry-run --locked --allow-dirty -p deepseek-tui
./scripts/release/publish-crates.sh dry-run

publish-crates.sh dry-run performs a full cargo publish --dry-run for crates without unpublished workspace dependencies and a packaging preflight for dependent workspace crates. That avoids false negatives from crates.io not yet containing the new workspace version while still validating package contents before publish.

For npm wrapper verification:

cargo build --release --locked -p deepseek-tui-cli -p deepseek-tui
node scripts/release/prepare-local-release-assets.js
python3 -m http.server 8123 --directory target/npm-release-assets
cd npm/deepseek-tui
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npm pack

Then install the generated tarball in a clean temp directory and smoke the entrypoints:

tmpdir="$(mktemp -d)"
cd "${tmpdir}"
npm init -y
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npm install /path/to/deepseek-tui-*.tgz
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npx --no-install deepseek --help
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npx --no-install deepseek-tui --help

To exercise npm run release:check locally as well, regenerate the local asset directory with a full asset matrix fixture before starting the server:

DEEPSEEK_TUI_PREPARE_ALL_ASSETS=1 node scripts/release/prepare-local-release-assets.js
cd npm/deepseek-tui
DEEPSEEK_TUI_VERSION=X.Y.Z DEEPSEEK_TUI_RELEASE_BASE_URL=http://127.0.0.1:8123/ npm run release:check

Set DEEPSEEK_TUI_VERSION to the npm package version you are verifying for that local run.

The CI workflow runs the same tarball install + smoke test on Linux and macOS.

Rust Crates Release

1. Update the workspace version in Cargo.toml.
2. Tag the release as vX.Y.Z.
3. Let .github/workflows/crates-publish.yml verify the workspace version and dry-run each crate.
4. Publish crates in this order:
   • deepseek-config
   • deepseek-protocol
   • deepseek-state
   • deepseek-agent
   • deepseek-execpolicy
   • deepseek-hooks
   • deepseek-mcp
   • deepseek-tools
   • deepseek-core
   • deepseek-app-server
   • deepseek-tui-core
   • deepseek-tui-cli
   • deepseek-tui
5. Wait for each published crate version to appear on crates.io before publishing dependents.

The publish helper is idempotent for reruns: already-published crate versions are skipped.

GitHub Release Assets

.github/workflows/release.yml builds these binaries:

• deepseek-linux-x64
• deepseek-macos-x64
• deepseek-macos-arm64
• deepseek-windows-x64.exe
• deepseek-tui-linux-x64
• deepseek-tui-macos-x64
• deepseek-tui-macos-arm64
• deepseek-tui-windows-x64.exe

The release job also uploads deepseek-artifacts-sha256.txt. The npm installer and release verification script both depend on that checksum manifest.

npm Wrapper Release

1. Set the npm package version in npm/deepseek-tui/package.json.
2. Set deepseekBinaryVersion to the GitHub release tag that should supply binaries.
3. Run:

cd npm/deepseek-tui
npm pack
npm publish

prepublishOnly verifies that all expected release assets and the checksum manifest exist.

Recovery and Rollback

• Crates publish partially:
  • rerun ./scripts/release/publish-crates.sh publish
  • already-published crate versions will be skipped
• GitHub assets missing or checksum manifest incomplete:
  • fix .github/workflows/release.yml
  • retag or upload corrected assets before npm publish
• npm packaging-only problem:
  • bump only the npm package version
  • keep deepseekBinaryVersion on the last known-good Rust release
  • repack and republish the wrapper
• A bad npm publish cannot be overwritten:
  • publish a new npm version with corrected metadata or install logic