nix-release-build

name	nix-release-build
description	Use when building and publishing the Nix tarball release artifacts for this repository with `nix build`. Covers flake target selection, tarball packaging, installer compatibility, GitHub release creation, and Homebrew tap updates for the current tarball-based cask path.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
user-invocable	true

Nix Release Build Skill

This skill provides the repository-specific workflow for producing tarball release artifacts with nix build, publishing them as GitHub releases, and keeping them compatible with the repository's root install.sh.

When to Apply

Apply this skill when:

• Building a release artifact with nix build
• Creating or updating the tarball-based Darwin installer artifact
• Creating a Linux release for this Tauri application
• Packaging Nix build outputs into a distributable archive
• Publishing or verifying GitHub releases for this repository
• Checking whether release artifacts still match the install script contract

Do not use this skill for .app / .dmg macOS distribution, signing, or notarization. Use macos-release-build for that path.

Repository Facts

• The flake defines the release package as .#chilla.
• README.md documents task nix-build as nix build .#chilla.
• src-tauri/tauri.conf.json currently keeps "bundle": { "active": false } for the base Nix package flow.
• the default flake release output remains the tarball-oriented package layout used by install.sh
• src-tauri/tauri.macos.release.conf.json exists as a separate macOS bundle path and is out of scope for this skill
• result/bin/chilla is currently a wrapper script generated by Nix, not a standalone native binary.
• The root install.sh expects tarball assets under the naming scheme chilla-v<version>-<target>.tar.gz plus an optional tarball checksum file chilla-v<version>-<target>.sha256.
• The install script supports aarch64-darwin, x86_64-darwin, aarch64-linux, and x86_64-linux.

The packaged release tree currently looks like:

result/
├── bin/chilla
└── lib/

The staging directory for generated release assets is release/. That directory is for local packaging output and is gitignored except for release/README.md.

Build Workflow

1. Confirm the target

Check the local architecture first:

uname -sm

Use the native flake package unless the user explicitly requests another system:

nix build .#chilla

If the task is to inspect outputs before building, use:

nix flake show --json .

2. Verify the Nix output

After the build:

ls -la result
find -L result -maxdepth 4 | sort
file result/bin/chilla
otool -L result/bin/chilla | sed -n '1,40p'

Confirm that:

• result points to the built store path
• result/bin/chilla exists
• the wrapper resolves to the intended platform build

3. Package a release artifact

The preferred release artifact is a versioned tarball copied out of the Nix store. Use the target suffix that matches the build platform:

mkdir -p release
cp -RL result release/chilla-v<version>-aarch64-darwin
tar -C release -czf release/chilla-v<version>-aarch64-darwin.tar.gz chilla-v<version>-aarch64-darwin
shasum -a 256 release/chilla-v<version>-aarch64-darwin.tar.gz | \
  awk '{ print $1 "  chilla-v<version>-aarch64-darwin.tar.gz" }' \
  > release/chilla-v<version>-aarch64-darwin.sha256

Adjust the target suffix if the build target is not aarch64-darwin.

The release/ directory should end up with files like:

release/
├── README.md
├── chilla-v0.1.0-aarch64-darwin.tar.gz
├── chilla-v0.1.0-aarch64-darwin.sha256
├── chilla-v0.1.0-x86_64-linux.tar.gz
└── chilla-v0.1.0-x86_64-linux.sha256

Important:

• the checksum file must describe the tarball, not bin/chilla
• the tarball root directory must match the tarball basename without .tar.gz
• the install script can use this local release/ directory directly before any GitHub release is published

4. Installer compatibility

The repository root install.sh is part of the release contract.

It supports:

• ./install.sh
• ./install.sh v<version>
• ./install.sh uninstall

Installer expectations:

• if release/ contains a matching chilla-v<version>-<target>.tar.gz, the installer prefers it over GitHub
• otherwise the installer downloads from GitHub releases
• it verifies chilla-v<version>-<target>.sha256 when present
• it installs under ~/.local/share/chilla/ and links ~/.local/bin/chilla
• it may update a shell profile with a managed PATH block unless --no-modify-path is used

When changing artifact names, directory layout, or checksum behavior, update install.sh, this skill, and release/README.md together.

GitHub Release Workflow

Preconditions

Before creating the release:

• ensure git status --short --branch is understood
• identify the target commit with git rev-parse HEAD
• check existing tags with git tag --sort=-creatordate
• verify gh auth status

Release creation

Use a semver tag unless the user specifies a different versioning scheme.

1. Create and push the tag:

git tag -a v<version> <commit> -m "Release v<version>"
git push origin refs/tags/v<version>

2. Create the GitHub release and upload assets:

gh release create v<version> \
  --repo tacogips/chilla \
  --target <commit> \
  --title "chilla v<version>" \
  --notes-file /tmp/chilla-release-notes.md \
 release/chilla-v<version>-<target>.tar.gz \
  release/chilla-v<version>-<target>.sha256

3. Verify the release:

gh release view v<version> --repo tacogips/chilla --json url,isDraft,assets

If gh release create partially succeeds or leaves a draft in an odd state, inspect the release with gh api repos/tacogips/chilla/releases and repair it before reporting success.

Homebrew Tap Maintenance

If the repository ships a custom Homebrew cask:

• keep end-user installation instructions in README.md limited to the user commands such as brew tap ... and brew install --cask ...
• keep maintainer-only details about the tap repository out of the user-facing README
• update the tap repository, for example tacogips/homebrew-tap, when the release URL, checksum, version, or architecture coverage changes
• treat release/README.md and this skill as the right place for tap-maintenance notes

Current Repository Layout

• the operational Homebrew cask does not live in this repository
• the cask source of truth lives in the tap repository tacogips/homebrew-tap
• users install from that tap with:

brew tap tacogips/tap
brew install --cask chilla

When the Cask Must Be Updated

Update the tap repository whenever any of the following change:

• the release version
• the GitHub release asset filename
• the asset checksum
• the supported macOS architectures
• the install artifact type, for example moving from .tar.gz to .dmg or .zip

Current Cask Shape

The current cask is expected to:

• target the published Darwin GitHub release asset
• use a binary artifact that links bin/chilla
• constrain installation to Apple Silicon if only the aarch64-darwin artifact is published
• include caveats that the current artifact is Nix-dependent and not a self-contained .app

Maintainer Workflow After Publishing a Release

After a new macOS release is published:

1. Compute or copy the SHA-256 for the Darwin release tarball.
2. Update the cask in tacogips/homebrew-tap.
3. Commit and push the tap change.
4. Verify the cask from Homebrew using the tap, not from a local path in this repository.

Representative verification commands:

brew tap tacogips/tap
brew info --cask tacogips/tap/chilla
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask tacogips/tap/chilla
brew uninstall --cask chilla

Documentation Boundary

• README.md should stay user-facing
• release/README.md can describe the existence and behavior of the Homebrew cask
• this skill should carry maintainer guidance about when and how to update tacogips/homebrew-tap

Download-and-Run Verification

When asked to verify the published artifact:

1. Download into /tmp
2. Verify the tarball checksum
3. Extract the archive
4. Launch the downloaded binary from the extracted directory
5. Confirm the process stays alive for a short interval

Representative commands:

mkdir -p /tmp/chilla-release-check
curl -L -o /tmp/chilla-release-check/chilla-v<version>-<target>.tar.gz \
  https://github.com/tacogips/chilla/releases/download/v<version>/chilla-v<version>-<target>.tar.gz
curl -L -o /tmp/chilla-release-check/chilla-v<version>-<target>.sha256 \
  https://github.com/tacogips/chilla/releases/download/v<version>/chilla-v<version>-<target>.sha256
shasum -a 256 /tmp/chilla-release-check/chilla-v<version>-<target>.tar.gz
tar -xzf /tmp/chilla-release-check/chilla-v<version>-<target>.tar.gz -C /tmp/chilla-release-check
cd /tmp/chilla-release-check/chilla-v<version>-<target> && ./bin/chilla

Installer-oriented verification:

LOCAL_RELEASE_DIR=/tmp/chilla-release-check ./install.sh v<version>
./install.sh uninstall

Useful checks:

ps -p <pid> -o pid=,stat=,etime=,command=
osascript -e 'tell application "System Events" to get name of every process whose name contains "chilla"'

Important Caveat

The current Darwin release artifact is not fully self-contained for non-Nix systems.

otool -L result/bin/chilla may show dependencies from /nix/store, for example libiconv. When this is true:

• report that the release was validated on a Nix-enabled Darwin machine
• do not describe the artifact as a universal standalone macOS distribution
• call out that .app or .dmg packaging would require additional packaging work beyond the current nix build .#chilla path

Reporting Requirements

When finishing a release task, report:

• the exact nix build target used
• the target commit and tag
• the release URL
• the artifact filenames
• the checksum you verified
• whether the downloaded binary was launched successfully
• whether the artifact is Nix-dependent or self-contained