# parcel: a mail client for the Linux desktop. `just --list` shows the # recipes. AGENTS.md holds the working conventions. # # `zig` is the compiler: bs for development builds, or upstream Zig where # bs is not installed. `just zig=zig test` uses upstream Zig anyway, for a # release build or what bs cannot compile. zig := `command -v bs >/dev/null && echo bs || echo zig` # `just setup` makes baskingspot-lint from github.com/baskingspot/nix at # this commit: its script and its ast-grep rules. rules_rev := "b246e853a3836a6279526db1d8f8fa54c14e6b7a" # parcel's own DID and its knot, where `just release` attaches each # release's build to its tagged commit and `just fetch` finds the newest. repo := "did:plc:j6saj57bvabjqrinmdxtkeo7" knot := "https://knot1.tangled.sh/xrpc" handle := "rockorager.dev" # parcel.rockorager.dev: the Cloudflare account and Pages project `just # site` deploys it to, and the wrangler that uploads it. pages_account := "7026bdfd47696bdbd844ae8830af977f" pages_project := "parcel" wrangler := "wrangler@4.162.0" # `cid FILE` prints the CID the knot names FILE's bytes by as a blob # (CIDv1, raw, sha256, base32), for `just release` to check its upload # and `just fetch` its download. cid := '''cid() { printf 'b%s\n' "$(printf '\x01\x55\x12\x20%b' "$(sha256sum "$1" | cut -c1-64 | sed 's/../\\x&/g')" | basenc -w0 --base32 | tr -d = | tr '[:upper:]' '[:lower:]')"; }''' [private] default: @just --list [doc("Make baskingspot-lint in ~/.local/bin from its pin; `mise install` installs the rest")] [group("build")] setup: #!/usr/bin/env bash set -euo pipefail bin=$HOME/.local/bin rules=${XDG_CACHE_HOME:-$HOME/.cache}/parcel/baskingspot-nix-{{ rules_rev }} if [ ! -d "$rules" ]; then rm -rf "$rules.tmp" git init -q "$rules.tmp" git -C "$rules.tmp" fetch -q --depth 1 https://github.com/baskingspot/nix {{ rules_rev }} git -C "$rules.tmp" checkout -q FETCH_HEAD mv "$rules.tmp" "$rules" fi mkdir -p "$bin" cat >"$bin/baskingspot-lint" <&2; exit 1; } name=$(jq -r .name <<<"$build") echo "$name of $(jq -r .subject.oid <<<"$build"), built $(jq -r .createdAt <<<"$build")" tmp=$(mktemp -d) trap 'rm -rf "$tmp"' EXIT link=$(jq -r '.artifact.ref."$link"' <<<"$build") curl -fsS --retry 3 -o "$tmp/parcel.tar.gz" "$knot/com.atproto.sync.getBlob?did=$repo&cid=$link" # The CID is the bytes' hash, so this download is the one published. if [ "$(cid "$tmp/parcel.tar.gz")" != "$link" ]; then echo "the download of $name is not the build published, so $prefix is left as it was" >&2 exit 1 fi mkdir "$tmp/root" tar -xzf "$tmp/parcel.tar.gz" -C "$tmp/root" # A build for a CPU or a glibc this machine lacks dies before it says # its version. version=${name#parcel-} version=${version%-x86_64-linux.tar.gz} out=$("$tmp/root/bin/parcel" --version 2>&1) || true if [ "$out" != "parcel $version" ]; then printf '%s does not say "parcel %s" when run here, so %s is left as it was:\n%s\n' "$name" "$version" "$prefix" "$out" >&2 exit 1 fi # Each file goes in by a rename, so a parcel running keeps the one it # started from, and an install cut short leaves no file half written. (cd "$tmp/root" && find . -type f) | while IFS= read -r file; do mkdir -p "$(dirname "$prefix/$file")" cp "$tmp/root/$file" "$prefix/$file.new" mv -f "$prefix/$file.new" "$prefix/$file" done echo "installed $prefix/bin/parcel" [doc("Release origin/main: VERSION is patch (the default), minor, major, or X.Y.Z. Commit the version, build, push, publish it, and deploy the site")] [group("build")] release version="": #!/usr/bin/env bash set -euo pipefail # An app password for `handle`, an owner or collaborator of the repo. # In an orb it is the rockorager/parcel project's secret of this name. : "${RELEASE_APP_PASSWORD:?needs an app password for {{ handle }}}" export RELEASE_APP_PASSWORD # For the site, which goes out last: asked for now, so a release is # not left with a changelog that lacks it. : "${CLOUDFLARE_API_TOKEN:?needs a Cloudflare token that may edit Pages, to deploy the site}" repo={{ repo }} knot={{ knot }} {{ cid }} die() { echo "$*" >&2 exit 1 } git fetch -q --tags origin main base=$(git rev-parse origin/main) echo "origin/main is $(git log -1 --format='%h %s' "$base")" ahead=$(git rev-list --count origin/main..HEAD) if [ "$ahead" -gt 0 ]; then echo "HEAD has $ahead commits origin/main lacks, which this release leaves out" >&2 fi # A release cut short finishes when run again: origin/main tagged # without its build, as a run that pushed but did not publish leaves # it, gets the build under that tag. tagged=$(git describe --exact-match --tags --match 'v[0-9]*' "$base" 2>/dev/null || true) # The tags are the versions, by semver: the newest one bumped, its # patch unless told minor or major, or the version given. A release # cut short keeps the version it was tagged. version="{{ version }}" last=$(git tag -l 'v[0-9]*' --sort=-v:refname | head -1) if [ -n "$tagged" ] && [[ $version =~ ^(|patch|minor|major)$ ]]; then version=${tagged#v} elif [[ $version =~ ^(|patch|minor|major)$ ]]; then IFS=. read -r major minor patch <<<"${last:-v0.0.0}" major=${major#v} case $version in major) version=$((major + 1)).0.0 ;; minor) version=$major.$((minor + 1)).0 ;; *) version=$major.$minor.$((patch + 1)) ;; esac fi [[ $version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || die "$version is not patch, minor, major, or a version, MAJOR.MINOR.PATCH" tag=v$version name=parcel-$version-x86_64-linux.tar.gz if [ -n "$tagged" ] && [ "$tagged" != "$tag" ]; then die "origin/main is $tagged already, not $tag" elif [ -z "$tagged" ]; then if git rev-parse -q --verify "refs/tags/$tag" >/dev/null; then die "$tag is $(git rev-parse --short "$tag^{commit}") already" fi if [ "$(printf '%s\n' "$last" "$tag" | sort -V | tail -1)" != "$tag" ]; then die "$tag is older than the newest release, $last" fi # For checking the bump: semver's patch for fixes, minor for # features, major for what breaks. echo "releasing as $tag what came since ${last:-the start}:" git log --format=' %h %s' "${last:+$last..}$base" fi # What the knot holds under this name, and whether origin has the tag. records=$(curl -fsS --retry 3 "$knot/com.atproto.repo.listRecords?repo=$repo&collection=org.tangled.repo.artifact&limit=100&reverse=true") published=$(jq -r --arg name "$name" '[.records[].value | select(.name == $name) | .subject.oid] | first // empty' <<<"$records") if [ -n "$published" ] && [ "$published" = "$base" ] && [ -n "$tagged" ]; then die "origin/main is released already, as $tag" elif [ -n "$published" ]; then die "the knot has $name already, for ${published:0:7}" fi pushed=$(git ls-remote --tags origin "refs/tags/$tag" 2>/dev/null) || die "cannot list origin's tags" # Signed in before the build, so a wrong password costs no build. did=$(curl -fsS --retry 3 "https://bsky.social/xrpc/com.atproto.identity.resolveHandle?handle={{ handle }}" | jq -er .did) pds=$(curl -fsS --retry 3 "https://plc.directory/$did" | jq -er '.service[] | select(.id == "#atproto_pds") | .serviceEndpoint') # The password reaches jq through its environment, not its arguments. jwt=$(jq -n --arg id "{{ handle }}" '{identifier: $id, password: env.RELEASE_APP_PASSWORD}' | curl -fsS "$pds/xrpc/com.atproto.server.createSession" -H "Content-Type: application/json" --data-binary @- | jq -er .accessJwt) || die "cannot sign in as {{ handle }}: is RELEASE_APP_PASSWORD its app password?" # Each write to the knot needs a token of its own, from the PDS. token() { curl -fsS -G "$pds/xrpc/com.atproto.server.getServiceAuth" \ --data-urlencode "aud=$repo" --data-urlencode "lxm=$1" \ -H "Authorization: Bearer $jwt" | jq -er .token } # The pushed commit alone, whatever this checkout holds, in a worktree # every release reuses: Zig's cache keys hold the sources' paths, so # only there does it find what the last release compiled. One another # clone made, or this clone forgot, starts over. src=${XDG_CACHE_HOME:-$HOME/.cache}/parcel/release git worktree prune if [ -e "$src/.git" ] && [ "$(git -C "$src" rev-parse --git-common-dir 2>/dev/null)" -ef "$(git rev-parse --git-common-dir)" ]; then git -C "$src" checkout -q --force --detach "$base" else rm -rf "$src" git worktree add -q --detach "$src" "$base" fi # mise runs a checkout's own pins only once it is trusted. if command -v mise >/dev/null; then mise trust -q "$src/mise.toml" (cd "$src" && mise install -q) fi # The release commit sets build.zig.zon's version, which parcel # --version reports, unless origin/main says it already. sha=$base if [ -z "$tagged" ]; then sed -i "s/^ \.version = \".*\",\$/ .version = \"$version\",/" "$src/build.zig.zon" grep -q "^ \.version = \"$version\",\$" "$src/build.zig.zon" || die "build.zig.zon names no version to set" if ! git -C "$src" diff --quiet; then git -C "$src" commit -q -am "release: $version" sha=$(git -C "$src" rev-parse HEAD) fi fi tmp=$(mktemp -d) trap 'rm -rf "$tmp"' EXIT # Nothing else checks a push, so the release runs the commit's own # build, tests, and lint first. (cd "$src" && just ci) # For x86-64-v3 (AVX2, 2013 on), not this machine's CPU: an orb's has # AVX-512, which laptops such as Lunar Lake lack, and parcel built for # it dies there at its first such instruction. # GOOGLE_CLIENT_SECRET, a project secret too, gives it the built-in # Google client (src/oauth.zig), so Gmail needs no client file. (cd "$src" && zig build -Doptimize=ReleaseFast -Dcpu=x86_64_v3 \ -Ddynamic-linker=/lib64/ld-linux-x86-64.so.2 \ ${GOOGLE_CLIENT_SECRET:+-Dgoogle-client-secret="$GOOGLE_CLIENT_SECRET"} -p "$tmp/root") bin=$tmp/root/bin/parcel strip "$bin" # It runs on other machines, so it must find their libraries, not the # paths of the one that built it (a Nix shell's, say). if grep -qE 'RPATH|RUNPATH' <<<"$(readelf -d "$bin")"; then die "parcel names a library path; build outside a Nix shell" fi # Nor may it need a glibc newer than theirs, 2.38. The braces keep grep # finding nothing from passing for objdump failing, which pipefail # reports. glibc=$(objdump -T "$bin" | { grep -oE 'GLIBC_[0-9.]+' || true; } | sort -Vu | tail -1) if [ "$(printf '%s\n' "$glibc" GLIBC_2.38 | sort -V | tail -1)" != GLIBC_2.38 ]; then die "parcel needs $glibc, newer than the 2.38 the desktops it is for have" fi out=$("$bin" --version 2>&1) || true [ "$out" = "parcel $version" ] || die "parcel does not say it is $version: $out" # Owned by root, so an install by root leaves no files of this uid. tar -C "$tmp/root" --owner=0 --group=0 --numeric-owner -czf "$tmp/$name" . echo "$name of ${sha:0:7}: $(du -h "$bin" | cut -f1) binary, $(du -h "$tmp/$name" | cut -f1) archive" blob=$(curl -fsS --retry 3 "$knot/com.atproto.repo.uploadBlob" \ -H "Authorization: Bearer $(token com.atproto.repo.uploadBlob)" \ -H "Content-Type: application/gzip" --data-binary "@$tmp/$name" | jq -ce .blob) || die "cannot upload $name; nothing is pushed yet" link=$(jq -r '.ref."$link"' <<<"$blob") [ "$link" = "$(cid "$tmp/$name")" ] || die "the knot took $name as $link, not the bytes sent" # Pushed once its build is uploaded, the release commit and its tag # together or neither: main moved since the fetch takes neither. if [ -z "$pushed" ]; then [ -n "$tagged" ] || git tag -a "$tag" -m "parcel $version" "$sha" refs=("refs/tags/$tag") [ "$sha" = "$base" ] || refs+=("$sha:refs/heads/main") if ! git push -q --atomic origin "${refs[@]}"; then # Untagged again, so the next release is not numbered past it. [ -n "$tagged" ] || git tag -d "$tag" >/dev/null die "cannot push $tag; if main moved, run just release again" fi fi # Then its build, which the Tags page lists under the tag. made=$(jq -n --arg repo "$repo" --arg oid "$sha" --arg name "$name" \ --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --argjson blob "$blob" \ '{repo: $repo, collection: "org.tangled.repo.artifact", record: { "$type": "org.tangled.repo.artifact", subject: {"$type": "org.tangled.git.oid", oid: $oid}, name: $name, createdAt: $now, artifact: $blob}}' | curl -fsS "$knot/com.atproto.repo.createRecord" \ -H "Authorization: Bearer $(token com.atproto.repo.createRecord)" \ -H "Content-Type: application/json" --data-binary @- | jq -er .uri) || die "$tag is pushed without its build: run just release again to publish it" # What just fetch downloads is what was built. if [ "$(curl -fsS --retry 3 "$knot/com.atproto.sync.getBlob?did=$repo&cid=$link" | cid -)" != "$link" ]; then die "the knot does not serve $name as uploaded" fi echo "published $made" # The site's changelog and feed are made from the tags, so it goes # out once this one is pushed, from the commit released. (cd "$src" && just site) || die "$tag is released, but the site is not deployed: run just site" [doc("Build parcel.rockorager.dev with the releases' changelog and deploy it to Cloudflare Pages")] [group("build")] site: #!/usr/bin/env bash set -euo pipefail # A token that may edit Cloudflare Pages in the account. In an orb it # is the rockorager/parcel project's secret of this name. : "${CLOUDFLARE_API_TOKEN:?needs a Cloudflare token that may edit Pages}" export CLOUDFLARE_API_TOKEN export CLOUDFLARE_ACCOUNT_ID={{ pages_account }} git fetch -q --tags origin python3 site/build.py # To the production branch by name: a release builds from a detached # commit, which wrangler would deploy as a preview. npx --yes {{ wrangler }} pages deploy zig-out/site --project-name {{ pages_project }} --branch main [doc("Build and run parcel on the Wayland display")] [group("build")] run *ARGS: {{ zig }} build run -- {{ ARGS }} [doc("Run a mailbox-view prototype by name; no name lists them")] [group("prototypes")] proto *ARGS: {{ zig }} build proto -- {{ ARGS }} [doc("Render the prototypes headless to zig-out/shots; names pick some")] [group("prototypes")] shots *ARGS: {{ zig }} build proto-shots -- {{ ARGS }} [doc("The tests, on siv's headless backend: no display needed")] [group("test")] test *ARGS: {{ zig }} build test --summary failures {{ ARGS }} [doc("Lint Zig, shell, and this justfile: zig fmt, baskingspot-lint, shellcheck, shfmt, and just --fmt; bs lints with ziglint's rules as it builds")] [group("lint")] lint: zig fmt --check build.zig build.zig.zon src baskingspot-lint build.zig src shellcheck .agents/setup .agents/resume shfmt --diff .agents/setup .agents/resume just --unstable --fmt --check [doc("Format everything lint checks")] [group("lint")] fmt: zig fmt build.zig build.zig.zon src shfmt --write .agents/setup .agents/resume just --unstable --fmt [doc("The build, the tests, and lint; tests alone leave unused code unchecked")] [group("ci")] ci: build test lint