# Local development
# Run the test suite.
test:
cargo test --all
# Run clippy in deny-warnings mode against everything.
lint:
cargo clippy --all-targets -- -D warnings
# Verify formatting without modifying anything.
fmt-check:
cargo fmt --all -- --check
# Apply formatting.
fmt:
cargo fmt --all
# Release pipeline maintenance
# Regenerate the dist workflow. Run this any time you change
# dist-workspace.toml or upgrade cargo-dist.
#
# Note: cargo-dist's `plan` step does an internal "is the generated
# workflow up to date" check and hard-fails CI on any divergence, so we
# can't post-process the output here. The "axo bot" attribution on tap
# repo commits stays as-is until upstream exposes a config knob.
dist-regen:
dist generate
# Validate the crate tarball without uploading. Run before tagging to
# catch packaging errors (missing license, README, dirty tree, etc.)
# while there's still time to fix them.
release-cargo-publish-check:
cargo publish -p quicknode-cli --dry-run
# Publish the crate to crates.io. Normally invoked from CI by the
# custom-publish-crates job in release.yml; this recipe is for manual
# recovery if CI's publish step fails and we need to retry from a
# clean local tree. Requires `cargo login` first.
release-cargo-publish:
cargo publish -p quicknode-cli
# Manually update the Homebrew tap with the formula attached to a given
# release. Use this until CI has a PAT with contents:write on the tap
# repo and can automate the formula push — at which point we add
# "homebrew" to publish-jobs in dist-workspace.toml, the cargo-dist
# workflow takes over, and this recipe becomes a manual-recovery fallback.
#
# Usage: just release-update-homebrew-tap 0.1.0 ~/qn/homebrew-tap
#
# Precondition: tap_path is a clean local clone of quicknode/homebrew-tap.
release-update-homebrew-tap version tap_path:
#!/usr/bin/env bash
set -euo pipefail
if [[ ! -d "{{tap_path}}/.git" ]]; then
echo "Error: {{tap_path}} is not a git checkout. Clone quicknode/homebrew-tap there first." >&2
exit 1
fi
if ! git -C "{{tap_path}}" diff --quiet || ! git -C "{{tap_path}}" diff --cached --quiet; then
echo "Error: {{tap_path}} has uncommitted changes. Commit or stash them first." >&2
exit 1
fi
formula_url="https://github.com/quicknode/cli/releases/download/v{{version}}/qn.rb"
if ! curl -sfL "$formula_url" -o /tmp/qn.rb; then
echo "Error: could not download $formula_url (does the release exist?)" >&2
exit 1
fi
mkdir -p "{{tap_path}}/Formula"
cp /tmp/qn.rb "{{tap_path}}/Formula/qn.rb"
rm /tmp/qn.rb
cd "{{tap_path}}"
if git diff --quiet Formula/qn.rb && ! git ls-files --error-unmatch Formula/qn.rb >/dev/null 2>&1; then
# New file
git add Formula/qn.rb
elif git diff --quiet Formula/qn.rb; then
echo "Formula/qn.rb is already at v{{version}}. Nothing to commit."
exit 0
else
git add Formula/qn.rb
fi
git commit -m "qn {{version}}"
echo
echo "Committed qn {{version}} to {{tap_path}}. To publish:"
echo " git -C {{tap_path}} push"
# Manually update the AUR `qn-bin` package with a PKGBUILD + .SRCINFO
# for a given release. Use this until CI has SSH access to push to the
# AUR git remote — at which point a CI publish-aur job takes over and
# this recipe becomes a manual-recovery fallback.
#
# The PKGBUILD downloads our prebuilt linux-gnu tarballs from the GitHub
# release (separate sha256 per arch). x86_64 and aarch64 only — cargo-dist
# does not build i686 or armv7.
#
# Usage: just release-update-aur-bin 0.1.4 ~/qn/aur-qn-bin
#
# Precondition: aur_path is a clean local clone of
# ssh://aur@aur.archlinux.org/qn-bin.git. First-time setup requires the
# package name `qn-bin` to be registered on the AUR — see AUR docs for
# the initial `git clone` + push.
release-update-aur-bin version aur_path:
#!/usr/bin/env bash
set -euo pipefail
if [[ ! -d "{{aur_path}}/.git" ]]; then
echo "Error: {{aur_path}} is not a git checkout. Clone ssh://aur@aur.archlinux.org/qn-bin.git there first." >&2
exit 1
fi
if ! git -C "{{aur_path}}" diff --quiet || ! git -C "{{aur_path}}" diff --cached --quiet; then
echo "Error: {{aur_path}} has uncommitted changes. Commit or stash them first." >&2
exit 1
fi
# Fetch both sha256 sidecars from the release.
x86_url="https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-x86_64-unknown-linux-gnu.tar.xz.sha256"
arm_url="https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-aarch64-unknown-linux-gnu.tar.xz.sha256"
if ! x86_line=$(curl -sfL "$x86_url"); then
echo "Error: could not download $x86_url (does the release exist?)" >&2
exit 1
fi
if ! arm_line=$(curl -sfL "$arm_url"); then
echo "Error: could not download $arm_url" >&2
exit 1
fi
# Each sidecar is `<hex> *<filename>` — take just the hex.
x86_hash=$(echo "$x86_line" | awk '{print $1}')
arm_hash=$(echo "$arm_line" | awk '{print $1}')
for h in "$x86_hash" "$arm_hash"; do
if [[ ! "$h" =~ ^[0-9a-f]{64}$ ]]; then
echo "Error: parsed hash '$h' is not a 64-char hex string." >&2
exit 1
fi
done
cat > "{{aur_path}}/PKGBUILD" <<EOF
# Maintainer: Quicknode <support@quicknode.com>
pkgname=qn-bin
pkgver={{version}}
pkgrel=1
pkgdesc='Command-line interface for the Quicknode SDK'
arch=('x86_64' 'aarch64')
url='https://github.com/quicknode/cli'
license=('MIT')
depends=('glibc')
provides=('qn')
conflicts=('qn')
source_x86_64=("\$pkgname-\$pkgver-x86_64.tar.xz::https://github.com/quicknode/cli/releases/download/v\$pkgver/quicknode-cli-x86_64-unknown-linux-gnu.tar.xz")
source_aarch64=("\$pkgname-\$pkgver-aarch64.tar.xz::https://github.com/quicknode/cli/releases/download/v\$pkgver/quicknode-cli-aarch64-unknown-linux-gnu.tar.xz")
sha256sums_x86_64=('$x86_hash')
sha256sums_aarch64=('$arm_hash')
package() {
local archdir
case "\$CARCH" in
x86_64) archdir='quicknode-cli-x86_64-unknown-linux-gnu' ;;
aarch64) archdir='quicknode-cli-aarch64-unknown-linux-gnu' ;;
esac
install -Dm755 "\$archdir/qn" "\$pkgdir/usr/bin/qn"
install -Dm644 "\$archdir/LICENSE" "\$pkgdir/usr/share/licenses/\$pkgname/LICENSE"
install -Dm644 "\$archdir/README.md" "\$pkgdir/usr/share/doc/\$pkgname/README.md"
}
EOF
# Generate .SRCINFO manually — we can't run `makepkg --printsrcinfo` on
# macOS dev boxes. Mirrors the deterministic field order makepkg emits.
cat > "{{aur_path}}/.SRCINFO" <<EOF
pkgbase = qn-bin
pkgdesc = Command-line interface for the Quicknode SDK
pkgver = {{version}}
pkgrel = 1
url = https://github.com/quicknode/cli
arch = x86_64
arch = aarch64
license = MIT
depends = glibc
provides = qn
conflicts = qn
source_x86_64 = qn-bin-{{version}}-x86_64.tar.xz::https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-x86_64-unknown-linux-gnu.tar.xz
sha256sums_x86_64 = $x86_hash
source_aarch64 = qn-bin-{{version}}-aarch64.tar.xz::https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-aarch64-unknown-linux-gnu.tar.xz
sha256sums_aarch64 = $arm_hash
pkgname = qn-bin
EOF
cd "{{aur_path}}"
# Stage both, even if only one changed; AUR convention is to commit them together.
git add PKGBUILD .SRCINFO
if git diff --cached --quiet PKGBUILD .SRCINFO; then
echo "PKGBUILD/.SRCINFO already at v{{version}}. Nothing to commit."
exit 0
fi
git commit -m "qn-bin {{version}}"
echo
echo "Committed qn-bin {{version}} to {{aur_path}}. To publish:"
echo " git -C {{aur_path}} push"
# Manually update the Scoop bucket with a manifest for a given release.
# Use this until CI has a PAT with contents:write on the bucket repo and
# can automate the push — at which point a CI job takes over and this
# recipe becomes a manual-recovery fallback.
#
# The generated manifest includes `checkver` + `autoupdate` so Scoop
# users get new versions on `scoop update` even without us pushing a
# new manifest for every release. We still push to bump the canonical
# `version` field so `scoop search` is honest about what's current.
#
# Usage: just release-update-scoop-bucket 0.1.4 ~/qn/scoop-bucket
#
# Precondition: bucket_path is a clean local clone of quicknode/scoop-bucket.
release-update-scoop-bucket version bucket_path:
#!/usr/bin/env bash
set -euo pipefail
if [[ ! -d "{{bucket_path}}/.git" ]]; then
echo "Error: {{bucket_path}} is not a git checkout. Clone quicknode/scoop-bucket there first." >&2
exit 1
fi
if ! git -C "{{bucket_path}}" diff --quiet || ! git -C "{{bucket_path}}" diff --cached --quiet; then
echo "Error: {{bucket_path}} has uncommitted changes. Commit or stash them first." >&2
exit 1
fi
sha_url="https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-x86_64-pc-windows-msvc.zip.sha256"
if ! sha_line=$(curl -sfL "$sha_url"); then
echo "Error: could not download $sha_url (does the release exist?)" >&2
exit 1
fi
# The .sha256 sidecar is `<hex> *<filename>`; take just the hex.
hash=$(echo "$sha_line" | awk '{print $1}')
if [[ ! "$hash" =~ ^[0-9a-f]{64}$ ]]; then
echo "Error: parsed hash '$hash' is not a 64-char hex string." >&2
exit 1
fi
mkdir -p "{{bucket_path}}/bucket"
cat > "{{bucket_path}}/bucket/qn.json" <<EOF
{
"version": "{{version}}",
"description": "Command-line interface for the Quicknode SDK",
"homepage": "https://github.com/quicknode/cli",
"license": "MIT",
"architecture": {
"64bit": {
"url": "https://github.com/quicknode/cli/releases/download/v{{version}}/quicknode-cli-x86_64-pc-windows-msvc.zip",
"hash": "$hash"
}
},
"bin": "qn.exe",
"checkver": "github",
"autoupdate": {
"architecture": {
"64bit": {
"url": "https://github.com/quicknode/cli/releases/download/v\$version/quicknode-cli-x86_64-pc-windows-msvc.zip"
}
}
}
}
EOF
cd "{{bucket_path}}"
if git diff --quiet bucket/qn.json && ! git ls-files --error-unmatch bucket/qn.json >/dev/null 2>&1; then
git add bucket/qn.json
elif git diff --quiet bucket/qn.json; then
echo "bucket/qn.json is already at v{{version}}. Nothing to commit."
exit 0
else
git add bucket/qn.json
fi
git commit -m "qn {{version}}"
echo
echo "Committed qn {{version}} to {{bucket_path}}. To publish:"
echo " git -C {{bucket_path}} push"
# Run release-update-{homebrew-tap,scoop-bucket,aur-bin} in sequence for
# the latest release tag, then print the three `git push` commands the
# maintainer needs to run to publish. Auto-detects the version from the
# most recent git tag (`v<X.Y.Z>` → `<X.Y.Z>`), or accepts an override.
#
# Expects three sibling clones under `root` (defaults to ~/qn):
# ~/qn/homebrew-tap → quicknode/homebrew-tap
# ~/qn/scoop-bucket → quicknode/scoop-bucket
# ~/qn/qn-bin → ssh://aur@aur.archlinux.org/qn-bin.git
#
# Usage:
# just release-sync-manual-channels # auto-detect version, default root
# just release-sync-manual-channels ~/work/quicknode # override root
# just release-sync-manual-channels ~/qn 0.1.4 # override both
release-sync-manual-channels root="~/qn" version="":
#!/usr/bin/env bash
set -euo pipefail
# Expand a leading ~/ to $HOME/ since bash doesn't expand tildes inside
# variables. Absolute paths pass through unchanged.
root="{{root}}"
case "$root" in
"~") root="$HOME" ;;
"~/"*) root="$HOME/${root#\~/}" ;;
esac
# If no version was passed, take the latest tag (strip leading v).
version="{{version}}"
if [[ -z "$version" ]]; then
git fetch --tags --quiet
tag=$(git describe --tags --abbrev=0 2>/dev/null || true)
if [[ -z "$tag" ]]; then
echo 'Error: no git tags found and no version override passed. Run: just release-sync-manual-channels ROOT VERSION' >&2
exit 1
fi
version="${tag#v}"
fi
echo "Syncing manual channels at v${version} from clones under ${root}/"
echo
just release-update-homebrew-tap "$version" "${root}/homebrew-tap"
echo
just release-update-scoop-bucket "$version" "${root}/scoop-bucket"
echo
just release-update-aur-bin "$version" "${root}/qn-bin"
echo
echo "All three channels updated. To publish, run:"
echo " git -C ${root}/homebrew-tap push"
echo " git -C ${root}/scoop-bucket push"
echo " git -C ${root}/qn-bin push"
# Release Phase 1: bump → branch → PR → merge → tag → GH release → wait for CI.
# Each recipe is callable on its own; release-prepare orchestrates them with prompts.
# Bump version in Cargo.toml on a fresh release/vX.Y.Z branch.
# Usage: just release-bump 0.2.0
release-bump version:
#!/usr/bin/env bash
set -euo pipefail
raw_version="{{version}}"
if [[ "$raw_version" =~ ^v ]]; then
echo "Error: version '$raw_version' must not start with 'v'. The 'v' prefix is added automatically when tagging. Try: just release-bump ${raw_version#v}" >&2
exit 1
fi
if [[ ! "$raw_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
echo "Error: version '$raw_version' is not valid semver (expected X.Y.Z or X.Y.Z-rc.N)." >&2
exit 1
fi
current_branch=$(git rev-parse --abbrev-ref HEAD)
if [[ "$current_branch" != "main" ]]; then
echo "Error: must be on main to start a release (currently on '$current_branch')." >&2
exit 1
fi
if ! git diff --quiet || ! git diff --cached --quiet; then
echo "Error: working tree is not clean. Commit or stash changes before bumping." >&2
exit 1
fi
current_version=$(sed -nE 's/^version = "(.+)"/\1/p' Cargo.toml | head -1)
if [[ "$current_version" == "{{version}}" ]]; then
echo "Cargo.toml is already at {{version}}. No bump needed — skip to: just release-tag-main {{version}}" >&2
exit 0
fi
git checkout -b "release/v{{version}}"
sed -i.bak 's/^version = ".*"/version = "{{version}}"/' Cargo.toml && rm Cargo.toml.bak
# Refresh Cargo.lock so it matches the new version.
cargo check --quiet
git add Cargo.toml Cargo.lock
git commit -m "Release v{{version}}"
echo "Committed bump on branch release/v{{version}}. Next: just release-open-pr {{version}}"
# Push the release branch and open a PR for the bump commit.
release-open-pr version:
#!/usr/bin/env bash
set -euo pipefail
git push -u origin "release/v{{version}}"
gh pr create \
--base main \
--head "release/v{{version}}" \
--title "Release v{{version}}" \
--body "Automated release bump for v{{version}}. Merging this PR triggers the rest of the release flow (tag, GitHub release, CI artifacts)."
# Squash-merge the release PR (with confirmation) and poll until MERGED.
release-merge-pr version:
#!/usr/bin/env bash
set -euo pipefail
pr_state=$(gh pr view "release/v{{version}}" --json state -q .state)
if [[ "$pr_state" == "MERGED" ]]; then
echo "PR for release/v{{version}} already merged."
exit 0
fi
read -r -p "Merge release PR for v{{version}} now via 'gh pr merge --squash --delete-branch'? [y/N] " response
if [[ "$response" =~ ^[Yy]$ ]]; then
gh pr merge "release/v{{version}}" --squash --delete-branch
else
echo "Aborted. Merge the PR manually in GitHub, then re-run: just release-prepare {{version}}" >&2
exit 1
fi
for attempt in $(seq 1 20); do
pr_state=$(gh pr view "release/v{{version}}" --json state -q .state)
if [[ "$pr_state" == "MERGED" ]]; then
echo "PR merged."
exit 0
fi
sleep 3
done
echo "Error: PR for release/v{{version}} did not reach MERGED state." >&2
exit 1
# Tag the post-merge HEAD of main and push the tag. The tag push is what
# triggers .github/workflows/release.yml.
release-tag-main version:
#!/usr/bin/env bash
set -euo pipefail
git checkout main
git pull --ff-only origin main
git tag "v{{version}}"
git push origin "v{{version}}"
# Manual recovery only. Normally cargo-dist's `host` job in release.yml creates
# the GitHub release as part of its upload step; calling this from release-prepare
# would race that job ("release with the same tag name already exists"). Use this
# only when cargo-dist's host job didn't create the release (e.g. CI was disabled
# or failed before the host step).
release-create-tag version:
gh release create v{{version}} --generate-notes --target main --title "v{{version}}"
# Wait for the release-triggered run of release.yml to finish.
release-wait-ci version:
#!/usr/bin/env bash
set -euo pipefail
echo "Waiting for release.yml run for tag v{{version}}..."
for attempt in $(seq 1 30); do
run_id=$(gh run list --workflow=release.yml --event=push --limit 20 --json databaseId,headBranch \
--jq '.[] | select(.headBranch == "v{{version}}") | .databaseId' | head -n1)
if [[ -n "${run_id:-}" ]]; then
echo "Found release.yml run $run_id for v{{version}}"
gh run watch "$run_id" --exit-status
exit 0
fi
echo " attempt $attempt/30: run not visible yet, sleeping 5s..."
sleep 5
done
echo "Error: timed out waiting for release.yml run for v{{version}} to appear." >&2
exit 1
# Orchestrates the full Phase 1 release with two confirmation checkpoints:
# one before pushing the bump branch, one before squash-merging the PR.
# Pass yes=1 to skip prompts (for automation).
# Usage: just release-prepare 0.2.0
release-prepare version yes="0":
#!/usr/bin/env bash
set -euo pipefail
if [[ "{{yes}}" != "1" ]]; then
echo "About to release v{{version}}:"
echo " 1. Bump version in Cargo.toml"
echo " 2. Commit on branch release/v{{version}}"
echo " --- review diff and confirm before push ---"
echo " 3. Push branch + open PR (review checkpoint)"
echo " 4. Merge PR via 'gh pr merge --squash --delete-branch'"
echo " 5. Tag the merge commit on main and push the tag"
echo " 6. Wait for release.yml CI (cargo-dist creates the GitHub release + attaches artifacts)"
echo
read -r -p "Continue? [y/N] " response
[[ "$response" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 1; }
fi
just release-bump {{version}}
echo
echo "=== Bump commit (HEAD) ==="
git --no-pager show --stat HEAD
echo
echo "=== Diff vs main ==="
git --no-pager diff main...HEAD -- Cargo.toml Cargo.lock
echo
if [[ "{{yes}}" != "1" ]]; then
echo "Review the bump above. Pushing will open a PR for review."
read -r -p "Push branch release/v{{version}} and open PR? [y/N] " response
if [[ ! "$response" =~ ^[Yy]$ ]]; then
echo "Aborted before push. The bump commit exists locally on release/v{{version}} — undo with:"
echo " git checkout main && git branch -D release/v{{version}}"
exit 1
fi
fi
just release-open-pr {{version}}
just release-merge-pr {{version}}
just release-tag-main {{version}}
just release-wait-ci {{version}}
echo
echo "Phase 1 complete. Inspect the release at:"
echo " https://github.com/$(gh repo view --json nameWithOwner -q .nameWithOwner)/releases/tag/v{{version}}"