fix(release): guard publish dist-tags and matrices

[IvGolovach]

Summary

• Add a release workflow safety checker that keeps the native-build and publish matrices aligned before build or publish jobs run.
• Guard npm publishing so prerelease versions derive a prerelease dist-tag and cannot accidentally publish to latest.
• Extend release-state and launcher smoke coverage to catch package metadata, installed wrapper, platform binary, and stale PATH fallback regressions.
• Align publish workflow environment settings with the native build workflow and remove unsupported ARM Linux strip commands from the publish matrix.

Why

Tokscale publishes platform packages and wrapper packages directly to npm from a manual release workflow. Small drift between the test-only native build matrix, the publish build matrix, and the platform publish matrix can produce release-only failures that are hard to see in normal PR checks. The same is true for npm dist-tags: a prerelease should not be able to land on latest by accident. This PR adds deterministic local and CI checks for those release invariants before a release publish can proceed.

Diff scope

• .github/workflows/publish-cli.yml: adds top-level release build environment parity, runs the release safety checker, and avoids unsupported ARM Linux strip commands in the publish matrix.
• .github/workflows/build-native.yml: runs the same release safety checker during native-build PR validation.
• scripts/check-release-workflow-safety.py: validates workflow env parity, build matrix parity, package directory mapping, artifact names, binary names, and platform package manifest names.
• scripts/publish-npm-package.sh: derives npm dist-tags from semver prerelease identifiers and refuses prerelease publishes with latest.
• scripts/test-release-workflow-safety.sh: covers accepted and rejected workflow drift cases.
• scripts/test-npm-release-state.sh: covers stable and prerelease npm dist-tag behavior.
• scripts/test-package-launchers.sh: supports debug smoke builds, verifies installed wrapper/package paths, and checks stale PATH fallback failure behavior.

Branch integrity

• Base branch: main
• Validated base SHA: a86e688d620939d2c973c6d5625baa815ea223d7
• Ahead/behind against fetched origin/main: 0 behind / 1 ahead
• Merge base: a86e688d620939d2c973c6d5625baa815ea223d7
• Diff proof was computed against the fetched base.

Commit integrity

• Introduced commit: 5600a47776f7184d4c0db51ba59e2b716cb70928 fix(release): guard publish dist-tags and matrices
• Final PR diff contains only the intended release workflow, publish script, and release verification test changes.
• Ledger: not applicable - not required for selected validation mode/change family.
• Version: not applicable - not required for selected validation mode/change family.

Diff hygiene

• git diff --name-status origin/main...HEAD: M .github/workflows/build-native.yml, M .github/workflows/publish-cli.yml, A scripts/check-release-workflow-safety.py, M scripts/publish-npm-package.sh, M scripts/test-npm-release-state.sh, M scripts/test-package-launchers.sh, A scripts/test-release-workflow-safety.sh
• git diff --check origin/main...HEAD: PASS, no output

Validation mode and proof

• Validation mode: Mode 4 - CI/release workflow and release verification tooling changed.
• python3 scripts/check-release-workflow-safety.py: PASS
• bash scripts/test-release-workflow-safety.sh: PASS
• bash scripts/test-npm-release-state.sh: PASS
• TOKSCALE_SMOKE_BUILD_PROFILE=debug bash scripts/test-package-launchers.sh: PASS
• bash -n scripts/*.sh: PASS
• python3 -m py_compile scripts/check-release-workflow-safety.py: PASS
• ruby -e 'require "yaml"; YAML.load_file(".github/workflows/publish-cli.yml"); YAML.load_file(".github/workflows/build-native.yml"); puts "YAML parse OK"': PASS
• git diff --check origin/main...HEAD: PASS, no output
• actionlint: not run - not installed in this local environment.

CI context confirmation

• Pending - required GitHub Actions checks will run after the PR is created.
• CI workflow context names unchanged; this PR adds checks inside existing workflows rather than renaming contexts.

Runtime safety

Not applicable - no CLI runtime session parsing, frontend runtime, database, auth, or server API path changed.

Release safety

• The publish and native build matrices are now checked for target, host, build command, strip command, binary name, artifact name, package directory, and platform package manifest drift.
• The publish script now uses latest only for stable versions and derives prerelease dist-tags such as beta for versions like 3.1.0-beta.1.
• The publish script refuses prerelease packages when the effective npm dist-tag is latest.
• Launcher smoke coverage validates the installed wrapper and platform package layout and confirms missing platform binaries do not silently fall back to a stale tokscale on PATH.

Migration notes

Not applicable - no DB migration changed.

Documentation integrity

Not applicable - no docs or runbooks changed. This PR enforces existing release expectations through scripts and workflow checks.

Rollback plan

Rollback: revert this PR.
DB downgrade: not applicable.
Data repair: not applicable.
Operational caveats: reverting removes the new release safety checks and restores the previous npm publish dist-tag behavior.

Known residual risks

• Remote CI has not run yet because the PR has not been opened.
• Local actionlint proof is unavailable because actionlint is not installed in this environment; workflow YAML was parsed locally and the release safety checker exercises the changed matrix invariants.

---

Summary by cubic

Adds a release safety checker to keep native-build and publish matrices/env in sync, and prevents prerelease versions from publishing with the latest npm tag. Expands tests, aligns publish env with native build, and removes unsupported ARM Linux strip commands.

• New Features

  • Adds scripts/check-release-workflow-safety.py and runs it in build-native and publish workflows to enforce env/matrix/artifact/binary/package parity.
  • Updates scripts/publish-npm-package.sh to derive npm dist-tags from semver (stable -> latest, prerelease -> first identifier like beta) and reject prerelease publishes with latest.
  • Extends tests: workflow drift checks; npm dist-tag cases (prerelease, build metadata, explicit NPM_DIST_TAG); launcher smokes add debug/release profiles, verify installed wrapper/CLI/platform paths, and assert PATH fallback failures.

• Bug Fixes

  • Aligns publish workflow top-level env with native build.
  • Removes unsupported ARM Linux strip commands from the publish matrix.

^{Written for commit b030c90. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
tokscale	Ignored	Preview	Jun 5, 2026 3:44am

[cubic-dev-ai]

3 issues found across 7 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>