deskctl/docs/releasing.md

Releasing deskctl

This document covers the operator flow for shipping deskctl across:

• GitHub Releases
• crates.io
• npm
• the repo flake

GitHub Releases are the canonical binary source. The npm package consumes those release assets instead of building a separate binary.

Package Names

• crate: deskctl
• npm package: deskctl
• installed command: deskctl

Prerequisites

Before the first live publish on each registry:

• npm ownership for deskctl
• crates.io ownership for deskctl
• repository secrets:
  • NPM_TOKEN
  • CARGO_REGISTRY_TOKEN

These are user-owned prerequisites. The repo can validate and automate the rest, but it cannot create registry ownership for you.

Normal Release Flow

1. Merge release-ready changes to main.
2. Let CI run:
   • validation
   • integration
   • distribution validation
   • release asset build
3. Confirm the GitHub Release exists for the version tag and includes:
   • deskctl-linux-x86_64
   • checksums.txt
4. Trigger the Publish Registries workflow with:
   • tag
   • publish_npm
   • publish_crates
5. Confirm the publish summary for each channel.

What CI Validates

The repository validates:

• cargo publish --dry-run --locked
• npm package metadata and packability
• npm install smoke path on Linux using the packaged deskctl command
• repo flake evaluation/build

The repository release workflow:

• builds the Linux release binary
• publishes the canonical GitHub Release asset
• uploads checksums.txt

The registry publish workflow:

• targets an existing release tag
• checks that Cargo, npm, and the requested tag all agree on version
• checks whether that version is already published on npm and crates.io
• only publishes the channels explicitly requested

Rerun Safety

Registry publishing is intentionally separate from release asset creation.

If a partial failure happens:

• GitHub Release assets remain the source of truth
• rerun the Publish Registries workflow for the same tag
• already-published channels are reported and skipped
• remaining channels can still be published

Local Validation

Run the distribution checks locally with:

make cargo-publish-dry-run
make npm-package-check
make nix-flake-check
make dist-validate

Notes:

• make npm-package-check does a runtime smoke test only on Linux
• make nix-flake-check requires a local Nix installation
• Docker remains a local Linux build convenience, not the canonical release path

Nix Boundary

The repo-owned flake.nix is the supported Nix surface in this phase.

In scope:

• nix run github:harivansh-afk/deskctl
• nix profile install github:harivansh-afk/deskctl
• CI validation for the repo flake

Out of scope for this phase:

• nixpkgs upstreaming
• extra distro packaging outside the repo