graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
Build prereleases from current release branch
Rach Pradhan183747035432
diff --git a/.github/workflows/beta-release.yml b/.github/workflows/beta-release.ymlnew file mode 100644index 00000000..2a09e0c4--- /dev/null+++ b/.github/workflows/beta-release.yml@@ -0,0 +1,143 @@+name: beta release++on:+ push:+ branches: ['release/v*']+ workflow_dispatch:++permissions:+ contents: write++# Publication is serialized across every release branch. The guard checks the+# remote head again after the builds, so queued work cannot revive an old beta.+concurrency:+ group: beta-release+ cancel-in-progress: false++jobs:+ plan:+ runs-on: ubuntu-latest+ outputs:+ build: ${{ steps.beta.outputs.build }}+ version: ${{ steps.beta.outputs.version }}+ tag: ${{ steps.beta.outputs.tag }}+ steps:+ - uses: actions/checkout@v7+ - name: Select the latest release branch head+ id: beta+ run: |+ python3 scripts/beta-release.py plan \+ --branch "$GITHUB_REF_NAME" --sha "$GITHUB_SHA" \+ --run-number "$GITHUB_RUN_NUMBER" --run-attempt "$GITHUB_RUN_ATTEMPT"++ cli:+ needs: plan+ if: needs.plan.outputs.build == 'true'+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ - uses: ./.github/actions/setup-codegraff-zig+ - name: Cross-compile beta CLI+ env:+ BETA_VERSION: ${{ needs.plan.outputs.version }}+ run: |+ set -euo pipefail+ mkdir -p beta-cli+ for target in aarch64-macos x86_64-macos x86_64-linux aarch64-linux x86_64-windows aarch64-windows; do+ zig build graff -Doptimize=ReleaseFast -Dtarget="$target" -Dversion="$BETA_VERSION"+ name="graff-$target"+ mkdir "$name"+ case "$target" in *-windows) bin=graff.exe ;; *) bin=graff ;; esac+ cp "zig-out/bin/$bin" "$name/$bin"+ cp README.md LICENSE "$name/"+ tar -czf "beta-cli/$name.tar.gz" "$name"+ rm -r "$name"+ done+ (cd beta-cli && sha256sum graff-*.tar.gz > SHA256SUMS)+ cp install.sh beta-cli/+ - uses: actions/upload-artifact@v7+ with:+ name: beta-cli+ path: beta-cli/+ if-no-files-found: error++ desktop-linux:+ needs: plan+ if: needs.plan.outputs.build == 'true'+ runs-on: ubuntu-latest+ timeout-minutes: 40+ steps:+ - uses: actions/checkout@v7+ - uses: oven-sh/setup-bun@v2+ with:+ bun-version: '1.4.2'+ - uses: ./.github/actions/setup-codegraff-zig+ - name: Package beta Linux desktop+ env:+ BETA_VERSION: ${{ needs.plan.outputs.version }}+ BETA_TAG: ${{ needs.plan.outputs.tag }}+ run: |+ set -euo pipefail+ GRAFF_VERSION="$BETA_VERSION" bash apps/native/electron/build.sh+ deb_version="${BETA_VERSION/-beta./~beta.}"+ dpkg --compare-versions "$deb_version" lt "${BETA_VERSION%%-beta.*}"+ test "$(dpkg-deb --field "zig-out/electron/codegraff_${deb_version}_amd64.deb" Version)" = "$deb_version"+ bash apps/native/electron/publish-linux.sh --prepare beta-linux "$BETA_TAG" zig-out/electron+ - uses: actions/upload-artifact@v7+ with:+ name: beta-linux+ path: beta-linux/+ if-no-files-found: error++ desktop-macos:+ needs: plan+ if: needs.plan.outputs.build == 'true'+ runs-on: macos-26+ timeout-minutes: 40+ steps:+ - uses: actions/checkout@v7+ - uses: oven-sh/setup-bun@v2+ with:+ bun-version: '1.4.2'+ - uses: ./.github/actions/setup-codegraff-zig+ - name: Build beta macOS app for signing+ env:+ GRAFF_VERSION: ${{ needs.plan.outputs.version }}+ run: |+ set -euo pipefail+ test "$(uname -m)" = arm64+ bash apps/native/electron/build.sh+ ditto -c -k --keepParent zig-out/electron/Codegraff.app beta-macos-build.zip+ - uses: actions/upload-artifact@v7+ with:+ name: beta-macos-build+ path: beta-macos-build.zip+ if-no-files-found: error+ retention-days: 7++ publish:+ needs: [plan, cli, desktop-linux, desktop-macos]+ if: needs.plan.outputs.build == 'true'+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v7+ - uses: actions/download-artifact@v7+ with:+ name: beta-cli+ path: beta-assets+ - uses: actions/download-artifact@v7+ with:+ name: beta-linux+ path: beta-assets+ - name: Publish beta prerelease+ env:+ GH_TOKEN: ${{ github.token }}+ BETA_TAG: ${{ needs.plan.outputs.tag }}+ run: |+ set -euo pipefail+ python3 scripts/beta-release.py guard --branch "$GITHUB_REF_NAME" --sha "$GITHUB_SHA"+ test -f beta-assets/SHA256SUMS+ test -f beta-assets/Codegraff-linux-amd64.deb+ gh release create "$BETA_TAG" beta-assets/* \+ --target "$GITHUB_SHA" --prerelease --latest=false \+ --title "$BETA_TAG" --notes 'Beta build from the latest release branch.'diff --git a/AGENTS.md b/AGENTS.mdindex e2537405..309561cd 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -126,6 +126,26 @@ If asked to merge open PRs onto the **release branch**, merge **only** that bran`gh pr merge` uses the PR's base, which is usually `main`. That is not landing on `release/v…`. Cherry-pick or merge the PR head into the named release branch instead.+## Release branch beta versions++The newest numeric `release/vX.Y.Z` or `release/vX.Y.Z.W` branch is the beta+source. Compare numeric components, treating a missing fourth component as+zero; do not use lexical branch order or assume releases always have three+components. Every push to the current branch builds a unique+`v<branch-version>-beta.<workflow-run>.<attempt>` prerelease from that exact+commit. A queued build must recheck the remote branch and commit before it+publishes. Older release branches and superseded commits cannot replace the+latest beta.++Beta releases are GitHub prereleases and must explicitly remain outside the+stable `latest` pointer and desktop updater feed. The stable tag workflow is+unchanged. CI can publish the CLI and unsigned Linux desktop package; macOS+desktop distribution still requires the repository's Developer ID signing,+provisioning profile, and notarization on a configured Mac. Its CI build is an+intermediate artifact only. Attach a signed beta DMG to that same prerelease+with `publish-beta-macos.sh` after `distribute.sh` passes its gates. Never upload+an unsigned macOS app as a release download or add `latest-mac.yml` to a beta.+## Before you pushInstall the tracked hooks once, and the checks run themselves:diff --git a/apps/native/electron/README.md b/apps/native/electron/README.mdindex 1bd4e75d..b5c995c0 100644--- a/apps/native/electron/README.md+++ b/apps/native/electron/README.md@@ -259,6 +259,30 @@ GRAFF_VERSION=VERSION bash apps/native/electron/build.shbash apps/native/electron/publish-linux.sh vVERSION zig-out/electron```+## Beta builds++Every push to the newest numeric `release/v...` branch starts the beta workflow.+The prerelease tag includes the branch version, workflow run number and attempt+(for example `v0.0.302.4-beta.20.1`). CI publishes CLI tarballs and an unsigned+Linux desktop package to a GitHub prerelease. The macOS job saves its built+`Codegraff.app` as a short-lived workflow artifact for signing. It is not a+download in the prerelease until a configured Mac signs and notarizes it.++On that Mac, download and extract the matching `beta-macos-build` workflow+artifact. With the same signing environment used for stable releases, run:++```sh+GRAFF_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)" \+GRAFF_NOTARY_PROFILE="notary-local" \+GRAFF_WEBAUTHN_PROFILE="signing/Codegraff.provisionprofile" \+bash apps/native/electron/distribute.sh Codegraff.app zig-out/beta-distribution+bash apps/native/electron/publish-beta-macos.sh vVERSION-beta.RUN.ATTEMPT zig-out/beta-distribution+```++The beta DMG receives the same signing, notarization and Gatekeeper checks as+stable releases. Beta apps carry no stable update feed, and beta releases never+become GitHub's stable Latest release. Install a later release manually.+That attaches `Codegraff-linux-amd64.deb` (or `arm64`) and`Codegraff-linux-<arch>-SHA256SUMS`. An AppImage is included when`appimagetool` was on `PATH` during the build. There is no notarization stepdiff --git a/apps/native/electron/build-linux.sh b/apps/native/electron/build-linux.shindex 4946aa01..90a23615 100755--- a/apps/native/electron/build-linux.sh+++ b/apps/native/electron/build-linux.sh@@ -61,6 +61,9 @@ EOFpackage_linux_deb() {local app="$1" arch+ # Debian sorts a tilde prerelease before its matching stable version.+ # Keep the app and graff binary on the canonical -beta version.+ local deb_version="${version/-beta./~beta.}"case "$(uname -m)" inx86_64) arch=amd64 ;;aarch64|arm64) arch=arm64 ;;@@ -84,7 +87,7 @@ EOFln -s /opt/codegraff/codegraff "$stage/usr/bin/codegraff"cat > "$stage/DEBIAN/control" <<EOFPackage: codegraff-Version: ${version}+Version: ${deb_version}Section: develPriority: optionalArchitecture: ${arch}@@ -107,7 +110,7 @@ fiexit 0EOFchmod 755 "$stage/DEBIAN/postinst"- dpkg-deb --root-owner-group --build "$stage" "$out/codegraff_${version}_${arch}.deb"+ dpkg-deb --root-owner-group --build "$stage" "$out/codegraff_${deb_version}_${arch}.deb"}package_linux_appimage() {diff --git a/apps/native/electron/build.sh b/apps/native/electron/build.shindex 942ab873..df5e01ef 100755--- a/apps/native/electron/build.sh+++ b/apps/native/electron/build.sh@@ -62,8 +62,16 @@ xcrun clang -O2 -bundle -undefined dynamic_lookup -mmacosx-version-min=14.0 \bun "$here/check-native-symbols.cjs" "$resources/native"/usr/libexec/PlistBuddy -c "Set :CFBundleIdentifier $bundle_id" "$bundle/Contents/Info.plist"/usr/libexec/PlistBuddy -c "Set :CFBundleName $app_name" "$bundle/Contents/Info.plist"-/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $version" "$bundle/Contents/Info.plist"-/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $version" "$bundle/Contents/Info.plist"+plist_version="$version"+plist_build="$version"+if [[ "$version" =~ ^([0-9]+\.[0-9]+\.[0-9]+)(\.[0-9]+)?-beta\.([0-9]+)\.([0-9]+)$ ]]; then+ # Apple bundle fields are numeric; the full beta version remains in the+ # packaged app metadata and CLI binary.+ plist_version="${BASH_REMATCH[1]}"+ plist_build="${BASH_REMATCH[3]}.${BASH_REMATCH[4]}"+fi+/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $plist_build" "$bundle/Contents/Info.plist"+/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $plist_version" "$bundle/Contents/Info.plist"/usr/libexec/PlistBuddy -c 'Set :LSMinimumSystemVersion 14.0' "$bundle/Contents/Info.plist"/usr/libexec/PlistBuddy -c "Set :CFBundleDisplayName $app_name" "$bundle/Contents/Info.plist" 2>/dev/null || truemacos="$bundle/Contents/MacOS"diff --git a/apps/native/electron/distribute.sh b/apps/native/electron/distribute.shindex 9da709e8..4c5d9646 100755--- a/apps/native/electron/distribute.sh+++ b/apps/native/electron/distribute.sh@@ -17,12 +17,20 @@ cleanup() { rm -rf "$work"; }trap cleanup EXITditto "$source_app" "$app"bun "$here/release-identity.cjs" "$app"-version="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$app/Contents/Info.plist")"-# 3-part (0.0.302) or 4-part hotfix (0.0.302.3). The feed maps 4-part onto-# semver so electron-updater can compare; the zip name keeps the graff version.-[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$ ]] || { echo 'Distribution requires a stable version.' >&2; exit 1; }-# Only distribution builds opt into online updates; include the feed in the signature.-bun "$here/update-artifacts.cjs" config "$app/Contents/Resources/app-update.yml"+version="$(bun -p 'require(require("node:path").resolve(process.argv[1])).version' "$app/Contents/Resources/app/package.json")"+# Beta distributions use the same signing and notarization gates, but must+# never carry the stable update feed. Stable releases retain its manifest.+beta=0+if [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?-beta\.[0-9]+\.[0-9]+$ ]]; then+ beta=1+elif [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?$ ]]; then+ echo 'Distribution requires a stable or beta version.' >&2; exit 1+fi+if [[ "$beta" == 0 ]]; then+ bun "$here/update-artifacts.cjs" config "$app/Contents/Resources/app-update.yml"+else+ rm -f "$app/Contents/Resources/app-update.yml"+fibun "$here/sign-bundle.mjs" "$app"codesign --verify --deep --strict "$app"ditto -c -k --keepParent "$app" "$work/app.zip"@@ -34,11 +42,13 @@ spctl --assess --type execute --verbose=2 "$app"# Squirrel.Mac needs a ZIP of the signed, stapled app, not a disk image.archive="$out/Codegraff-$version-macos-arm64.zip"ditto -c -k --keepParent "$app" "$archive"-bun "$here/update-artifacts.cjs" "$version" "$archive" "$out/latest-mac.yml"+if [[ "$beta" == 0 ]]; then+ bun "$here/update-artifacts.cjs" "$version" "$archive" "$out/latest-mac.yml"# The 0.0.299 zip passed every gate below yet installed an app that never# checked for updates: its bundle had no app-update.yml. Prove the upload# bytes carry the feed config before anything else touches this directory.-bun "$here/update-artifacts.cjs" verify-bundle "$app" "$archive"+ bun "$here/update-artifacts.cjs" verify-bundle "$app" "$archive"+fibash "$here/create-dmg.sh" "$app" "$dmg"codesign --sign "$GRAFF_SIGN_IDENTITY" --timestamp "$dmg"xcrun notarytool submit "$dmg" --keychain-profile "$GRAFF_NOTARY_PROFILE" --wait --output-format json > "$out/dmg-notary.json"diff --git a/apps/native/electron/publish-beta-macos.sh b/apps/native/electron/publish-beta-macos.shnew file mode 100644index 00000000..11210a3a--- /dev/null+++ b/apps/native/electron/publish-beta-macos.sh@@ -0,0 +1,29 @@+#!/usr/bin/env bash+# Attach a locally signed, notarized macOS beta to its existing prerelease.+set -euo pipefail+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+tag="${1:?Usage: publish-beta-macos.sh vVERSION distribution-directory}"+out="${2:?Provide the notarized distribution directory}"+repo="${GRAFF_RELEASE_REPO:-justrach/codegraff}"+[[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?-beta\.[0-9]+\.[0-9]+$ ]] || {+ echo 'Expected a beta tag.' >&2; exit 1;+}+[[ "$(gh release view "$tag" --repo "$repo" --json isPrerelease --jq .isPrerelease)" == true ]] || {+ echo 'The target release must be a prerelease.' >&2; exit 1;+}+[[ "$(bun -p 'require(require("node:path").resolve(process.argv[1])).version' "$out/Codegraff.app/Contents/Resources/app/package.json")" == "${tag#v}" ]] || {+ echo 'App version does not match the beta tag.' >&2; exit 1;+}+[[ ! -e "$out/latest-mac.yml" && ! -e "$out/Codegraff.app/Contents/Resources/app-update.yml" ]] || {+ echo 'Beta builds must not contain the stable update feed.' >&2; exit 1;+}+bun "$here/release-identity.cjs" "$out/Codegraff.app"+codesign --verify --deep --strict "$out/Codegraff.app"+xcrun stapler validate "$out/Codegraff.app"+xcrun stapler validate "$out/Codegraff-macos-arm64.dmg"+spctl --assess --type execute "$out/Codegraff.app"+spctl --assess --type open --context context:primary-signature "$out/Codegraff-macos-arm64.dmg"+(cd "$out" && shasum -a 256 -c Codegraff-DMG-SHA256SUMS)+gh release upload "$tag" --repo "$repo" \+ "$out/Codegraff-macos-arm64.dmg" "$out/Codegraff-DMG-SHA256SUMS" \+ "$out/Codegraff-${tag#v}-macos-arm64.zip"diff --git a/apps/native/electron/publish-linux.sh b/apps/native/electron/publish-linux.shindex 44c58485..ea879638 100755--- a/apps/native/electron/publish-linux.sh+++ b/apps/native/electron/publish-linux.sh@@ -19,20 +19,21 @@ fitag="${1:?Usage: publish-linux.sh vVERSION package-directory}"src="${2:?Provide the directory that contains the .deb}"ver="${tag#v}"+package_ver="${ver/-beta./~beta.}"if [[ "$tag" == "$ver" || -z "$ver" ]]; thenecho "tag must look like v0.0.1" >&2exit 1fishopt -s nullglob-debs=("$src"/codegraff_"${ver}"_*.deb)+debs=("$src"/codegraff_"${package_ver}"_*.deb)if [[ ${#debs[@]} -ne 1 ]]; then- echo "expected one codegraff_${ver}_*.deb in $src" >&2+ echo "expected one codegraff_${package_ver}_*.deb in $src" >&2exit 1fideb="${debs[0]}"base="$(basename "$deb")"-arch="${base#codegraff_${ver}_}"+arch="${base#codegraff_${package_ver}_}"arch="${arch%.deb}"case "$arch" inamd64|arm64) ;;diff --git a/scripts/beta-release.py b/scripts/beta-release.pynew file mode 100644index 00000000..f836f35f--- /dev/null+++ b/scripts/beta-release.py@@ -0,0 +1,77 @@+#!/usr/bin/env python3+"""Plan a beta from the newest release branch and guard its publication."""++import argparse+import os+import re+import subprocess++BRANCH = re.compile(r"^release/v(\d+\.\d+\.\d+(?:\.\d+)?)$")+++def version_key(branch):+ match = BRANCH.fullmatch(branch)+ if not match:+ return None+ parts = tuple(int(part) for part in match[1].split("."))+ return parts + (0,) if len(parts) == 3 else parts+++def remote_heads():+ result = subprocess.run(+ ["git", "ls-remote", "--heads", "origin", "release/v*"],+ check=True, capture_output=True, text=True,+ )+ heads = {}+ for line in result.stdout.splitlines():+ sha, ref = line.split("\t", 1)+ branch = ref.removeprefix("refs/heads/")+ if version_key(branch) is not None:+ heads[branch] = sha+ return heads+++def current_beta(branch, sha, heads):+ key = version_key(branch)+ if key is None:+ raise ValueError("Expected a release/vX.Y.Z or release/vX.Y.Z.W branch")+ if not heads:+ raise ValueError("No release branches found on origin")+ latest = max(heads, key=lambda name: (version_key(name), name))+ return branch == latest and heads.get(branch) == sha+++def plan(branch, sha, run_number, run_attempt, heads):+ if not current_beta(branch, sha, heads):+ return None+ if run_number < 1 or run_attempt < 1:+ raise ValueError("Run number and attempt must be positive")+ version = f"{branch.removeprefix('release/v')}-beta.{run_number}.{run_attempt}"+ return {"version": version, "tag": f"v{version}"}+++def main():+ parser = argparse.ArgumentParser()+ parser.add_argument("mode", choices=("plan", "guard"))+ parser.add_argument("--branch", required=True)+ parser.add_argument("--sha", required=True)+ parser.add_argument("--run-number", type=int)+ parser.add_argument("--run-attempt", type=int)+ args = parser.parse_args()+ heads = remote_heads()+ if args.mode == "guard":+ if not current_beta(args.branch, args.sha, heads):+ raise SystemExit("Release branch or commit is no longer current; beta publication skipped")+ return+ result = plan(args.branch, args.sha, args.run_number, args.run_attempt, heads)+ if result is None:+ print("This push is not the latest release branch head; beta build skipped")+ output = os.environ["GITHUB_OUTPUT"]+ with open(output, "a", encoding="utf-8") as stream:+ stream.write(f"build={'true' if result else 'false'}\n")+ if result:+ stream.writelines(f"{key}={value}\n" for key, value in result.items())+++if __name__ == "__main__":+ main()diff --git a/scripts/test-beta-release.py b/scripts/test-beta-release.pynew file mode 100644index 00000000..a305b3e8--- /dev/null+++ b/scripts/test-beta-release.py@@ -0,0 +1,49 @@+import importlib.util+import pathlib+import unittest++module_path = pathlib.Path(__file__).with_name("beta-release.py")+spec = importlib.util.spec_from_file_location("beta_release", module_path)+beta = importlib.util.module_from_spec(spec)+spec.loader.exec_module(beta)+++class BetaReleaseTests(unittest.TestCase):+ def test_latest_branch_uses_numeric_three_and_four_part_order(self):+ heads = {+ "release/v0.0.302": "a",+ "release/v0.0.302.4": "b",+ "release/v0.0.302.10": "c",+ "release/v0.0.303": "d",+ }+ self.assertEqual(beta.version_key("release/v0.0.302"), (0, 0, 302, 0))+ self.assertGreater(beta.version_key("release/v0.0.302.10"), beta.version_key("release/v0.0.302.4"))+ self.assertFalse(beta.current_beta("release/v0.0.302.10", "c", heads))+ self.assertTrue(beta.current_beta("release/v0.0.303", "d", heads))++ def test_stale_branch_or_sha_cannot_publish(self):+ heads = {"release/v0.0.302.4": "new"}+ self.assertFalse(beta.current_beta("release/v0.0.302.4", "old", heads))+ self.assertFalse(beta.current_beta("release/v0.0.302.3", "old", heads))+ self.assertIsNone(beta.plan("release/v0.0.302.4", "old", 20, 1, heads))++ def test_run_attempts_get_distinct_beta_versions(self):+ heads = {"release/v0.0.302.4": "sha"}+ first = beta.plan("release/v0.0.302.4", "sha", 20, 1, heads)+ second = beta.plan("release/v0.0.302.4", "sha", 20, 2, heads)+ third = beta.plan("release/v0.0.302.4", "sha", 21, 1, heads)+ self.assertEqual(first, {"version": "0.0.302.4-beta.20.1", "tag": "v0.0.302.4-beta.20.1"})+ self.assertLess(first["version"], second["version"])+ self.assertNotEqual(second["tag"], third["tag"])+ with self.assertRaises(ValueError):+ beta.plan("release/v0.0.302.4", "sha", 20, 0, heads)++ def test_invalid_release_branch_is_rejected(self):+ for branch in ("main", "release/v0.0.302.4.1", "release/v0.0.302-beta.1", "release/vx.y.z"):+ self.assertIsNone(beta.version_key(branch))+ with self.assertRaises(ValueError):+ beta.current_beta(branch, "sha", {"release/v0.0.302.4": "sha"})+++if __name__ == "__main__":+ unittest.main()