pi-daemon1.3

Reference

Release checklist

Pi Daemon releases are Git tags (vMAJOR.MINOR.PATCH) on a clean, tested main. The release workflow builds the npm tarball, writes a SHA-256 checksum, and creates GitHub release notes. Publishing to the npm registry remains an explicit operator action.

Before tagging

  1. Update the version in package.json, the root package in package-lock.json, src/version.ts, and flake.nix together.
  2. Move the matching changelog entry from “unreleased” to the ISO release date.
  3. Run npm run release:check -- --tag vMAJOR.MINOR.PATCH. The same preflight runs before the release workflow builds or publishes anything.
  4. On the Linux ms-dev* validation lane, run npm ci --ignore-scripts, npm run nix:deps-hash:check, the complete npm test, and npm run pack:check. The hash check keeps a release from shipping a flake.nix whose dependency cache no longer matches the lock file.
  5. Run the optional credentialed acceptance harness when model/provider behavior changed.
  6. Confirm Linux Nix checks and artifact versions are green. On macOS use npm run test:darwin for the explicit small correctness set plus Darwin package/version/signature checks. The Darwin Nix package selects this same subset. This is execution placement, not a waiver of the complete Linux gate.
  7. Confirm nix build .#pages succeeds and the published HTML resolves.
  8. Verify no prompt, model output, credential, environment, or private path is in logs/artifacts.

The release workflow installs the exact generated npm tarball and runs its pi-daemon version, then runs the Nix application and compares both versions with the tag and all four source metadata locations. A mismatch or an “unreleased” changelog section fails before gh release create.

Prove the release lane before tagging

Dispatch the release workflow on main without a tag:

gh workflow run release.yml --ref main

With no tag it runs the same test job (including the web view's headless Chromium smoke test) and the same packing and artifact-version checks against main, and skips gh release create, so it publishes nothing. Every step has its own timeout-minutes, npm test bounds each test with --test-timeout, and the browser smoke test bounds every DevTools call, so a hang fails at its bound instead of at the job timeout. Dispatching with tag set to an existing v* tag publishes that tag, exactly like pushing it.

Static documentation publication

The Pages workflow calls the shared self-hosted publisher (harryaskham.github.io publish-pages.yml), which runs nix build .#pages, checks the expected files, and deploys. After a publication, check the live HTML over HTTPS. Do not delete release assets or historical Actions evidence, and do not alter DNS or certificates as a publication side effect.

Tag

git tag -s v0.1.0 -m "pi-daemon v0.1.0"
git push origin v0.1.0

The workflow uploads harryaskham-pi-daemon-<version>.tgz and its checksum. Consumers should pin a tag or commit and make the Pi Daemon nixpkgs input follow their own fleet input.

Post-publish activation

Before activating a release, verify that the GitHub Release tarball checksum matches the uploaded checksum and that both the packed npm CLI and Nix application report the tag version. Do not publish the npm package as a side effect of this verification. Activate it through the host supervisor and roll back the supervisor to the prior immutable release on an activation failure.

Rollback

Do not move or force-push a published tag, overwrite its GitHub assets, or reuse its npm version. If a release is bad:

  1. Mark the GitHub release as withdrawn or pre-release and document the reason.
  2. If npm was explicitly published, deprecate that exact version with a concise migration message; do not unpublish a version that consumers may have pinned.
  3. Repoint supervisors and flake consumers to the prior known-good immutable tag.
  4. Fix forward and cut a new patch version with a new dated changelog section.

Rollback restores the complete prior package rather than mixing code or assets between tags.