The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: add release script and Makefile target for automated CLI versioning and tagging
0xken150925271c1955
diff --git a/Makefile b/Makefileindex 9c05275cf..d73be70f2 100644--- a/Makefile+++ b/Makefile@@ -4,12 +4,18 @@# make install-cli ARGS="--no-restart"# make upload-cli ARGS="0.1.0"-.PHONY: cli-test install-cli upload-cli remote-machine+.PHONY: cli-test install-cli upload-cli release remote-machine## cli-test: typecheck + run the CLI test suite.cli-test:cd cli && npx tsc --noEmit && npx vitest run+## release: tag this commit and push the tag — CI bundles the CLI, publishes it to GCS, and cuts the+## GitHub Release. The version is bumped from max(last git tag, live metadata.json's `cli` key).+## ARGS="--dry-run" to preview.+release:+ bash cli/scripts/release-cli.sh $(ARGS)+## install-cli: bundle the CLI from THIS working tree and install it into ~/.harness/cli — the local dev## loop, nothing published. Restarts the daemon on the new bytes. Self-update stays ON: the build is## labelled with the published version, which the release you are level with cannot outrank, so your bytesdiff --git a/cli/RELEASE.md b/cli/RELEASE.mdnew file mode 100644index 000000000..3a3f74bd8--- /dev/null+++ b/cli/RELEASE.md@@ -0,0 +1,122 @@+# Releasing the CLI++Running daemons self-update from a public GCS bucket (`src/lib/selfUpdate.ts`). Releasing is pushing a+tag: `.github/workflows/release.yml` bundles the CLI, publishes it to that bucket, and cuts the GitHub+Release. **The tag IS the version — CI never bumps.**++```bash+make release # bump the patch, tag, push — CI does the rest+make release ARGS="--dry-run" # print the version it would cut and the notes, do nothing+make release ARGS="0.2.0" # release an explicit version+make release ARGS="--notes-file notes.md" # hand-written release notes+```++Nothing is built locally and no GCS credentials are needed: the only things `cli/scripts/release-cli.sh`+touches are git and a public HTTPS read of the manifest. See [`../docs/cicd.md`](../docs/cicd.md) for+what the release workflow itself does, step by step.++**Why the version comes from two places.** `cli/scripts/release-cli.sh` takes the highest of the last+git tag and the version published under the `cli` key of `harness/cli/metadata.json`. Publishing by+hand (`make upload-cli`, below) bumps from the manifest and tags nothing, so the two can drift — a+maintainer who runs it, or a scratch publish that slipped, leaves the manifest ahead of the last tag.+Bumping from tags alone there would produce a version LOWER than what's already served — every daemon+refuses it (`shouldUpdate` / `semverGt` in `src/lib/selfUpdate.ts`) while the release still reports+success.++Unlike `autonomous-harness-desktop`'s `make release`, there is no `--minor` flag: `shouldUpdate` is a+plain "strictly newer" check with no major/minor-triggers-a-forced-update concept, so every release+just needs to outrank what's live.++`package.json`'s `version` field is never touched by this script; the published version is baked into+the bundle via `ADAPTER_VERSION` at build time (see `make upload-cli` below).++## Publishing by hand++`cli/scripts/upload-cli.sh` is the publishing step. CI invokes it with the version taken from the tag;+it's also reachable directly when CI cannot be:++```bash+make upload-cli # auto-bump (0.1.2 -> 0.1.3; 0.1.99 -> 0.2.1)+make upload-cli ARGS="0.2.0" # explicit version+make upload-cli ARGS="--no-bump" # rebuild and re-upload the current version+make upload-cli ARGS="--no-build" # upload the existing dist/ artifact as-is+```++**This creates no git tag.** It bumps from the remote manifest, so the repo stops reflecting what's+published. Prefer `make release`; if you do publish by hand, cut a `make release` afterwards to bring+the tag back in line.++1. Reads the current version from the live manifest (falling back to `package.json` if the manifest is+ unreadable), then bumps or takes the version it was given.+2. Bundles with `ADAPTER_VERSION="$VERSION" npm run bundle` and asserts `node dist/cli.js version`+ reads back that exact string before uploading anything.+3. Uploads `cli.js` and `notify.mjs` to `harness/cli/<version>/`, then download-merge-reuploads+ `metadata.json` in a single write, touching only the `cli` key.++A failed build stops the release; nothing is uploaded and no version is consumed.++## Local install (no upload)++`bash cli/scripts/install-cli.sh` bundles **this working tree** into `~/.harness/cli` — the same+layout the public installer produces — and restarts the daemon on it, so `harness` on this machine+means your code without publishing anything:++```bash+make install-cli # bundle + install + restart the daemon+make install-cli ARGS="--no-restart" # skip restarting the daemon+make install-cli ARGS="--no-updates" # pin self-update off (see below)+```++Self-update stays **on** by default: the local build is labelled with the currently published version,+which the release you're level with cannot outrank, so your bytes survive until a genuinely newer+version ships — then the daemon quietly swaps back to it. `--no-updates` pins your build instead.++## GCS layout and manifest shape++```+gs://s3-autonomous-upgrade-3/harness/cli/metadata.json+gs://s3-autonomous-upgrade-3/harness/cli/<version>/cli.js+gs://s3-autonomous-upgrade-3/harness/cli/<version>/notify.mjs+```++```json+{+ "cli": {+ "version": "0.1.72",+ "url": "https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/0.1.72/cli.js",+ "sha256": "<64 hex>",+ "size": 2103552+ }+}+```++The bucket must be public-read — that is bucket policy, not something the scripts set.++## How a running daemon self-updates++1. Polls `ADAPTER_UPDATE_URL` every `ADAPTER_UPDATE_CHECK_MS` (default 60 s) — see `src/config/env.ts`.+2. Compares the manifest's `cli.version` against its own — strictly newer only (`semverGt`), so+ republishing an old build can never downgrade a fleet.+3. Downloads `cli.js` + `notify.mjs` and verifies each sha256/size against the manifest **before**+ anything is swapped in. A mismatch is discarded.+4. Swaps the bundle in when the daemon is idle and restarts, with rollback on a bad build.++**There is no undo.** A bad release is rolled back by publishing a *higher* version containing the+older code — never by deleting the new one, which just leaves every daemon pointed at a 404. Disable+self-update on one machine with `ADAPTER_UPDATE_DISABLE=true`.++## Rolling out safely++Publish to a scratch manifest before touching the real one, then point a local build at it:++```bash+gh workflow run release.yml -f version=9.9.9 -f metadata_path=harness/cli/metadata-test.json+```++```bash+ADAPTER_UPDATE_URL=https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/metadata-test.json harness start+```++No daemon polls `metadata-test.json`, so nothing self-updates from it. The *artifacts* still go to+their real home (`harness/cli/<version>/` is hardcoded in `upload-cli.sh`), so use an unmistakable+version and delete `gs://s3-autonomous-upgrade-3/harness/cli/9.9.9/` afterwards.diff --git a/cli/scripts/release-cli.sh b/cli/scripts/release-cli.shnew file mode 100755index 000000000..f71651cf4--- /dev/null+++ b/cli/scripts/release-cli.sh@@ -0,0 +1,224 @@+#!/usr/bin/env bash+# Cut a CLI release: work out the next version, tag it, push the tag. CI does everything else —+# .github/workflows/release.yml bundles the CLI, publishes it to GCS, and creates the GitHub Release.+# The tag IS the version; CI never bumps on its own.+#+# Usage:+# bash cli/scripts/release-cli.sh # bump the patch and release+# bash cli/scripts/release-cli.sh --dry-run # print everything, tag nothing, push nothing+# bash cli/scripts/release-cli.sh 0.2.0 # release an explicit version+# bash cli/scripts/release-cli.sh --notes-file f.md # hand-written release notes instead of the+# # generated commit list+#+# THE NEXT VERSION COMES FROM TWO SOURCES, AND BOTH MATTER — same reasoning as+# autonomous-harness-desktop/scripts/release-desktop.sh. Git tags alone are not enough:+# `cli/scripts/upload-cli.sh` bumps from the live metadata.json and tags nothing, so a maintainer who+# publishes by hand (or a scratch/dry-run publish that slipped) can leave the manifest ahead of the+# last tag. Bumping from tags alone there would produce a version LOWER than what's already served,+# which every daemon refuses (`semverGt` in cli/src/lib/selfUpdate.ts) while the release still looks+# successful. So the current version is max(highest git tag, the manifest's `cli` key version).+#+# Unlike the desktop, there is no --minor flag here: `shouldUpdate` in selfUpdate.ts is a plain+# semverGt with no major/minor-triggers-a-forced-update concept, so a "MANDATORY UPDATE" framing would+# invent semantics this CLI doesn't have. Every release just needs to be strictly newer.+#+# Requires: git, curl, python3, and push access to origin. No GCS credentials — the manifest is read+# over public HTTPS, exactly as cli/scripts/upload-cli.sh reads it.+set -euo pipefail++ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"+cd "$ROOT"++# --- config (all overridable via env) ---+GCS_BUCKET="${GCS_BUCKET:-s3-autonomous-upgrade-3}"+GCS_PUBLIC_BASE_URL="${GCS_PUBLIC_BASE_URL:-https://storage.googleapis.com/${GCS_BUCKET}}"+METADATA_PATH="${METADATA_PATH:-harness/cli/metadata.json}"+OTA_KEY="${OTA_KEY:-cli}" # must match ADAPTER_UPDATE_KEY in cli/src/config/env.ts+META_URL="${META_URL:-${GCS_PUBLIC_BASE_URL%/}/${METADATA_PATH#/}}"+BRANCH="${BRANCH:-main}"++DRY_RUN=0+ALLOW_NO_MANIFEST=0+NEW_VER=""+NOTES_FILE=""++want_notes_file=0+for arg in "$@"; do+ if [ "$want_notes_file" -eq 1 ]; then NOTES_FILE="$arg"; want_notes_file=0; continue; fi+ case "$arg" in+ --dry-run) DRY_RUN=1 ;;+ --allow-no-manifest) ALLOW_NO_MANIFEST=1 ;;+ --notes-file) want_notes_file=1 ;;+ --notes-file=*) NOTES_FILE="${arg#*=}" ;;+ -h|--help) sed -n '2,23p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;+ -*) echo "ERROR unknown flag: $arg" >&2; exit 1 ;;+ *) NEW_VER="$arg" ;;+ esac+done+[ "$want_notes_file" -eq 0 ] || { echo "ERROR --notes-file needs a path" >&2; exit 1; }++# Same rule as next_adapter_version() in cli/scripts/upload-cli.sh:28-42, which is where this+# convention is defined. Note the rollover: .99 goes to the next MINOR at .1, not .0.+next_patch_version() {+ local current="$1" major minor patch+ if [[ ! "$current" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then+ echo "ERROR version '$current' must look like X.Y.Z" >&2+ return 1+ fi+ major=$((10#${BASH_REMATCH[1]}))+ minor=$((10#${BASH_REMATCH[2]}))+ patch=$((10#${BASH_REMATCH[3]}))+ if (( patch >= 99 )); then+ printf '%d.%d.1\n' "$major" "$((minor + 1))"+ else+ printf '%d.%d.%d\n' "$major" "$minor" "$((patch + 1))"+ fi+}++# Strictly greater, comparing X.Y.Z numerically — the same test the daemon applies before it will+# install anything (semverGt, cli/src/lib/selfUpdate.ts).+version_gt() {+ [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -1)" = "$1" ]+}++# --- preflight: tooling ---+for tool in git curl python3; do+ command -v "$tool" >/dev/null 2>&1 || { echo "ERROR $tool not found — it is needed to cut a release" >&2; exit 1; }+done++# --- preflight: the tag must capture exactly what was tested, and CI must be able to fetch it ---+git rev-parse --git-dir >/dev/null 2>&1 || { echo "ERROR not a git repository: $ROOT" >&2; exit 1; }+git fetch --tags --quiet origin++if [ -n "$(git status --porcelain)" ]; then+ echo "ERROR working tree is dirty — a release tag must capture the tested source exactly:" >&2+ git status --short | sed 's/^/ /' >&2+ exit 1+fi++HEAD_SHA="$(git rev-parse HEAD)"+if ! git merge-base --is-ancestor "$HEAD_SHA" "origin/$BRANCH" 2>/dev/null; then+ echo "ERROR HEAD is not on origin/$BRANCH — push the commit first, or CI will build a commit nobody else has." >&2+ exit 1+fi++# --- current version, source 1: the highest release tag in git ---+# The brace group keeps `set -e` from killing the script when grep legitimately matches nothing.+TAG_VER="$(git tag -l 'v*' \+ | { grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' || true; } \+ | sed -E 's/^v//' \+ | sort -V | tail -1)"+LAST_TAG=""+[ -z "$TAG_VER" ] || LAST_TAG="v${TAG_VER}"+TAG_VER="${TAG_VER:-0.0.0}"++# --- current version, source 2: the version actually being served ---+GCS_VER="$(curl -fsSL "$META_URL" 2>/dev/null | python3 -c '+import json, re, sys+try:+ data = json.load(sys.stdin)+except Exception:+ sys.exit(0)+if not isinstance(data, dict):+ sys.exit(0)+entry = data.get(sys.argv[1])+if not isinstance(entry, dict):+ sys.exit(0)+version = entry.get("version")+if not isinstance(version, str) or not re.match(r"^\d+\.\d+\.\d+$", version.strip()):+ sys.exit(0)+print(version.strip())+' "$OTA_KEY" 2>/dev/null || true)"++if [ -z "$GCS_VER" ]; then+ if [ "$ALLOW_NO_MANIFEST" -eq 1 ]; then+ echo ">> WARNING could not read $META_URL — continuing on git tags alone (--allow-no-manifest)" >&2+ GCS_VER="0.0.0"+ else+ echo "ERROR could not read the live manifest at $META_URL" >&2+ echo " It is the only record of what daemons are actually running, and releasing without it" >&2+ echo " risks publishing a version LOWER than the one already being served." >&2+ echo " Re-run with --allow-no-manifest only if the bucket is genuinely down." >&2+ exit 1+ fi+fi++# --- the next version ---+CUR="$TAG_VER"+version_gt "$GCS_VER" "$CUR" && CUR="$GCS_VER"++if [ -n "$NEW_VER" ]; then+ VER="$NEW_VER"+else+ VER="$(next_patch_version "$CUR")"+fi++if [[ ! "$VER" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ echo "ERROR version '$VER' must look like X.Y.Z — release.yml rejects anything else" >&2+ exit 1+fi++TAG="v${VER}"++# The last gate against a release no daemon can install.+if ! version_gt "$VER" "$GCS_VER"; then+ echo "ERROR $VER is not higher than $GCS_VER, which is already published." >&2+ echo " Every running daemon would refuse it and the release would still look successful." >&2+ exit 1+fi++if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then+ echo "ERROR tag $TAG already exists. Re-tagging a released version breaks the tag<->build mapping." >&2+ exit 1+fi++# --- release notes: the tag message IS the GitHub Release body ---+# release.yml's github-release job hard-fails on a lightweight tag or an empty message — and it runs+# AFTER the manifest is already live, so a missing message means a half-done release: daemons are+# already running a build that has no Release page. Refuse to tag without notes rather than find out+# then.+NOTES="$(mktemp)"+trap 'rm -f "${NOTES:-}"' EXIT+if [ -n "$NOTES_FILE" ]; then+ [ -f "$NOTES_FILE" ] || { echo "ERROR notes file not found: $NOTES_FILE" >&2; exit 1; }+ cat "$NOTES_FILE" > "$NOTES"+else+ {+ printf 'Harness CLI %s\n\n' "$VER"+ if [ -n "$LAST_TAG" ]; then+ git log --no-merges --pretty='- %s' "${LAST_TAG}..HEAD"+ else+ git log --no-merges --pretty='- %s' -20+ fi+ } > "$NOTES"+fi+[ -s "$NOTES" ] || { echo "ERROR release notes are empty — CI would fail after publishing" >&2; exit 1; }++# --- summary (shared by dry runs and real ones) ---+echo ""+echo " last git tag ${LAST_TAG:-(none)} ($TAG_VER)"+echo " live on GCS $GCS_VER ($OTA_KEY key)"+if version_gt "$GCS_VER" "$TAG_VER"; then+ echo " NOTE the manifest is ahead of git — versions were published without a tag."+ echo " Bumping from tags alone here would publish a downgrade."+fi+echo " releasing $VER (tag $TAG on ${HEAD_SHA:0:12})"+echo ""+echo " release notes:"+sed 's/^/ /' "$NOTES"+echo ""++if [ "$DRY_RUN" -eq 1 ]; then+ echo " dry run — nothing tagged, nothing pushed."+ exit 0+fi++# --- tag and push ---+git tag -a "$TAG" --cleanup=verbatim -F "$NOTES"+git push origin "$TAG"++echo ""+echo " pushed $TAG → CI bundles the CLI, publishes to GCS, and cuts the GitHub Release."+echo " running daemons self-update within ~1 min of the manifest moving."+echo " watch : gh run watch \$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"+echo ""diff --git a/docs/cicd.md b/docs/cicd.mdindex 8f54b06ad..0265f28c5 100644--- a/docs/cicd.md+++ b/docs/cicd.md@@ -29,6 +29,19 @@ because the artifacts are two JavaScript files whose integrity is the sha256 in## Cutting a release+```bash+make release # bump the patch, tag, push — CI does the rest+make release ARGS="--dry-run" # print the version it would cut and the notes, do nothing+make release ARGS="0.2.0" # release an explicit version+```++`cli/scripts/release-cli.sh` works out the next version as `max(last git tag, live metadata.json's cli+key)`, refuses to publish anything that isn't strictly newer than what's live, and refuses an empty+release message before tagging. See [`cli/RELEASE.md`](../cli/RELEASE.md) for the full rundown,+including local installs and manual publishing.++The manual fallback, for when `make release` itself can't be used:+```bash# What is live right now — the next tag is one above this. Someone may have released by hand.curl -fsS https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/metadata.json@@ -114,10 +127,3 @@ whose `node_modules` came from pnpm. `ci.yml` now runs `pnpm install --frozen-lo--lockfile-only` before anything else, which resolves in about five seconds, installs nothing andfails naming the dependency that drifted. So: if you touch `package.json`, update **both**lockfiles.--## Known gap--`cli/README.md` links to `cli/RELEASE.md` twice (publishing, and the local-install path). That file-does not exist in this repository — it did not survive the split out of the monorepo. Both links are-dead, and the material is currently spread across the headers of `cli/scripts/upload-cli.sh` and-`cli/scripts/install-cli.sh`, plus this file.