@r1z4x/tezgah 1.9.0 → 1.9.2

package/CHANGELOG.md

@@ -6,6 +6,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.9.2] - 2026-10-17
+
+### Fixed
+
+- **1.9.2 ships what 1.9.1 carried.** The v1.9.1 release run failed its own CI on the changelog's prose. So npm and Homebrew never received 1.9.1. This release carries the same changes.
+
+## [1.9.1] - 2026-10-17
+
+### Fixed
+
+- **A token fetches a private repository's release.** GitHub answers `404` to `releases/download/...` from a session without one. So `brew install`, `upgrade.sh` and the `curl | sh` first install all broke when the repository went private. `upgrade.sh` and `install.sh` read `TEZGAH_GITHUB_TOKEN`, `GITHUB_TOKEN` or `GH_TOKEN`. With a token, they read the tarball through the REST asset endpoint. `install.ps1` sends the same header. The Homebrew formula names that endpoint and reads `HOMEBREW_GITHUB_API_TOKEN`, and its caveats say so. With no token, the public URLs stand and a failed fetch names the token to set. The bearer reaches curl on stdin (`-H @-`), so no other user's `ps` shows it. An install still on 1.9.0 has no token support: install the new release with the token set.
+- **The formula's caveats keep their text.** Backticks in the template ran as commands in the release step's unquoted heredoc. The caveats lost the token scope and the failure line, and the step stayed green. The test now renders the template the way the step does.
+
 ## [1.9.0] - 2026-10-17
 
 ### Added
@@ -1206,7 +1219,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   the copy could not find `hooks/` and died on import. It now links into the
   installed tree, and also installs the command as `tezgah`.
 
-[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.9.0...HEAD
+[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.9.2...HEAD
+[1.9.2]: https://github.com/r1z4x/tezgah/releases/tag/v1.9.2
+[1.9.1]: https://github.com/r1z4x/tezgah/releases/tag/v1.9.1
 [1.9.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.9.0
 [1.8.3]: https://github.com/r1z4x/tezgah/releases/tag/v1.8.3
 [1.8.2]: https://github.com/r1z4x/tezgah/releases/tag/v1.8.2

package/docs/environment.md

@@ -19,12 +19,12 @@ the kill switches are files, not variables, and live in
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `TEZGAH_PREFIX` | `packaging/install.sh:26`, `packaging/upgrade.sh`, `packaging/install.ps1`, `bin/tezgah-setup::default_prefix` | `$XDG_DATA_HOME/tezgah`, else `%LOCALAPPDATA%\tezgah` on Windows, else `~/.local/share/tezgah` | Where the artifact install unpacks its versions and the `current` link; `tezgah-setup` treats it as the install prefix. |
+| `TEZGAH_PREFIX` | `packaging/install.sh:30`, `packaging/upgrade.sh`, `packaging/install.ps1`, `bin/tezgah-setup::default_prefix` | `$XDG_DATA_HOME/tezgah`, else `%LOCALAPPDATA%\tezgah` on Windows, else `~/.local/share/tezgah` | Where the artifact install unpacks its versions and the `current` link; `tezgah-setup` treats it as the install prefix. |
 | `TEZGAH_VERSION` | `packaging/install.sh`, `packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh:70` | the newest GitHub release; `build.sh` falls back to `VERSION`/the CHANGELOG | The version to install, or the version `build.sh` stamps when `--version` is not given. |
-| `TEZGAH_REPO` | `packaging/install.sh:12`, `packaging/upgrade.sh`, `packaging/install.ps1` | `r1z4x/tezgah` | The GitHub repository releases are fetched from. |
+| `TEZGAH_REPO` | `packaging/install.sh:13`, `packaging/upgrade.sh`, `packaging/install.ps1` | `r1z4x/tezgah` | The GitHub repository releases are fetched from. |
 | `TEZGAH_UPDATE_URL` | `hooks/tezgah_update.py` | `https://github.com/<TEZGAH_REPO>/releases/latest` | Where the daily release check reads the newest tag: from the redirect, or from a JSON body's `tag_name`. Tests point it at a `file://` fixture. |
 | `TEZGAH_UPDATE_CHECK` | `hooks/tezgah_update.py` | unset | `0` turns off the update chip and the daily check. The test suite sets it, so no test reaches the network. |
-| `TEZGAH_DIST` | `packaging/upgrade.sh:74`, `packaging/install.ps1` | unset: the release URL | A directory holding `tezgah-<V>.tar.gz` and its `.sha256` (what `build.sh --out` writes) used instead of the release download; CI exercises the real fetch-verify-unpack path with it. |
+| `TEZGAH_DIST` | `packaging/upgrade.sh:105`, `packaging/install.ps1` | unset: the release URL | A directory holding `tezgah-<V>.tar.gz` and its `.sha256` (what `build.sh --out` writes) used instead of the release download; CI exercises the real fetch-verify-unpack path with it. |
 | `TEZGAH_GH` | `packaging/upgrade.sh` | `gh` on PATH | The `gh` that checks the tarball's build provenance (`gh attestation verify`). A path that does not exist reads as no `gh`: the upgrade prints `provenance not checked` and goes on. Tests point it at a stand-in. |
 | `TEZGAH_NO_DEPS` | `bin/tezgah-setup::main` | unset | Any value but empty or `0` is `--no-deps`: the optional tools (codegraph, orx, host CLIs) are not installed. |
 | `TEZGAH_NO_SYMLINK` | `bin/tezgah-setup::symlinks_refused` | unset | Any value but empty or `0` writes the copy layout a machine without symlinks gets, on a machine that has them. |

package/docs/operations.md

@@ -58,8 +58,8 @@ built by `packaging/build.sh` from the tracked `MANIFEST` plus a generated
 team can stay on one version and a rollback is one tree away: the older version is
 never removed, and going back is
 `ln -sfn <prefix>/<previous> <prefix>/current` (`packaging/upgrade.sh:9-11`,
-`packaging/upgrade.sh:118-137`). The prefix is `~/.local/share/tezgah` unless
-`TEZGAH_PREFIX` or `$XDG_DATA_HOME` says otherwise (`packaging/upgrade.sh:63`),
+`packaging/upgrade.sh:176-196`). The prefix is `~/.local/share/tezgah` unless
+`TEZGAH_PREFIX` or `$XDG_DATA_HOME` says otherwise (`packaging/upgrade.sh:94`),
 and `bin/tezgah-setup --prefix DIR` wins over both (`bin/tezgah-setup::INSTALL_PREFIX`).
 A farm link counts as tezgah's when it resolves into the checkout **or** into the
 install root, which is what keeps an upgrade from orphaning the wiring
@@ -68,30 +68,45 @@ install root, which is what keeps an upgrade from orphaning the wiring
 | Step | Command |
 |---|---|
 | first install, POSIX | `curl -fsSL https://raw.githubusercontent.com/r1z4x/tezgah/v<version>/packaging/install.sh \| sh -s -- --version <version>` |
-| from a tarball you hold | unpack it, then `sh packaging/install.sh --version <version>` — it finds `upgrade.sh` beside itself (`packaging/install.sh:30-32`) |
+| from a tarball you hold | unpack it, then `sh packaging/install.sh --version <version>` — it finds `upgrade.sh` beside itself (`packaging/install.sh:34-36`) |
 | first install, Windows | `$env:TEZGAH_VERSION = '<version>'; irm https://raw.githubusercontent.com/r1z4x/tezgah/v<version>/packaging/install.ps1 \| iex` |
 | upgrade | `tezgah update` (any channel), `bin/tezgah-setup --upgrade [VERSION]` from the installed tree, or `sh packaging/upgrade.sh --version X.Y.Z` |
 
 `packaging/install.sh` is a bootstrap, never a second implementation: it runs
 `packaging/upgrade.sh` — the one place a version is fetched, checksum-verified,
 unpacked and made current — and then starts `bin/tezgah-setup --install` from the
-tree that just became current (`packaging/install.sh:44-56`). `upgrade.sh`
+tree that just became current (`packaging/install.sh:54-66`). `upgrade.sh`
 compares the digest it fetched against the artifact before unpacking anything and
-stops, printing both, on a mismatch (`packaging/upgrade.sh:88-96`). It then
+stops, printing both, on a mismatch (`packaging/upgrade.sh:148-152`). It then
 checks the tarball's build provenance with `gh attestation verify` when `gh` is
 on PATH. Without `gh` it prints `provenance not checked`, and a `gh` that cannot
 answer is a warning: the checksum stays the gate.
 `TEZGAH_DIST` points `upgrade.sh` and `install.ps1` at a directory holding
 `tezgah-<version>.tar.gz` + `.sha256` instead of the release URL — the seam that
 installs a locally built artifact with no published release, which is what CI
-uses (`packaging/upgrade.sh:17-21`, `packaging/upgrade.sh:74-78`).
+uses (`packaging/upgrade.sh:17-24`, `packaging/upgrade.sh:105-111`).
+
+**A private `TEZGAH_REPO` needs a token.** GitHub answers `404` to
+`releases/download/...` from a session without one. Measured 2026-10-17: the token
+in the URL and a plain bearer header answered the same. So a token in
+`TEZGAH_GITHUB_TOKEN`, `GITHUB_TOKEN` or `GH_TOKEN` sends the fetch to the REST
+asset endpoint instead. That endpoint wants `Accept: application/octet-stream` plus
+`Authorization: Bearer`, and the script reads the asset's id out of the release
+JSON of the tag. The bearer reaches curl on stdin (`-H @-`). No other user's `ps`
+shows it as an argument. `packaging/install.sh` carries the same bearer for the
+`raw.githubusercontent.com` bootstrap. `packaging/install.ps1` carries it for the
+release JSON and the asset blobs. With no token, the public URLs stand and a failed
+fetch names the token to set. The brew formula takes the same shape. It names the
+asset endpoint and reads `HOMEBREW_GITHUB_API_TOKEN`. Homebrew leaves that variable
+in the environment it reads a formula with, so the token resolves at evaluation.
+Homebrew redacts it from the commands it logs.
 
 Windows goes through `packaging/install.ps1`, which assumes no `sh`, no `python3`
 and no symlink privilege: it unpacks with the `tar.exe` that Windows 10 1803+
 ships, materialises `current` as a directory junction, copies the tree where a
 junction is refused, and starts the installer with the first of `py -3`,
 `python`, `python3` it finds, passing `--prefix` on (`packaging/install.ps1:12-23`,
-`packaging/install.ps1:128-163`). The installer knows both shapes of `current`
+`packaging/install.ps1:179-195`). The installer knows both shapes of `current`
 (`bin/tezgah-setup::running_prefix`). A junction answers to
 `os.path.isjunction`, or to its reparse tag below Python 3.12. A copy is the
 running tree at `<prefix>/current` with no `.git`, whose `VERSION` names a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
   "license": "MIT",
   "repository": {

package/packaging/install.ps1

@@ -27,6 +27,11 @@
 
       $env:TEZGAH_VERSION = '0.1.0'; irm https://raw.githubusercontent.com/r1z4x/tezgah/main/packaging/install.ps1 | iex
 
+  The tezgah repository is private, so that fetch and the release below need a
+  token with read access, in `TEZGAH_GITHUB_TOKEN`, `GITHUB_TOKEN` or `GH_TOKEN`:
+
+      $env:GITHUB_TOKEN = 'ghp_...'
+
 .EXAMPLE
   .\install.ps1 -Version 0.1.0 -Prefix D:\tezgah
 #>
@@ -59,16 +64,29 @@ function Remove-Current([string]$Path) {
 }
 
 if ($env:TEZGAH_REPO) { $Repo = $env:TEZGAH_REPO }
+# A private repository serves no release file to an anonymous session, so the
+# token decides which URL is read: the REST asset endpoint with it, the plain
+# download URL without. `releases/download/...` answers 404 to both a token in
+# the URL and a bearer header (measured 2026-10-17), so the id comes first.
+$Token = $env:TEZGAH_GITHUB_TOKEN
+if (-not $Token) { $Token = $env:GITHUB_TOKEN }
+if (-not $Token) { $Token = $env:GH_TOKEN }
+$Headers = @{}
+$AssetHeaders = @{ Accept = 'application/octet-stream' }
+if ($Token) {
+    $Headers.Authorization = "Bearer $Token"
+    $AssetHeaders.Authorization = "Bearer $Token"
+}
 if (-not $Version) { $Version = $env:TEZGAH_VERSION }
 if (-not $Prefix) { $Prefix = $env:TEZGAH_PREFIX }
 if (-not $Prefix) { $Prefix = Join-Path $env:LOCALAPPDATA 'tezgah' }   # Windows' data dir
 $Prefix = Resolve-Full $Prefix
 if (-not $Version) {
     try {
-        $rel = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest"
+        $rel = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/latest" -Headers $Headers
         $Version = "$($rel.tag_name)".TrimStart('v')
     } catch {
-        throw "tezgah: cannot read the newest release of $Repo (no release yet, or no network): $_"
+        throw "tezgah: cannot read the newest release of $Repo (no release yet, or no network; a private repository needs TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN): $_"
     }
 }
 if (-not $Version -or $Version -match '[\\/]' -or $Version -in @('.', '..')) {
@@ -86,13 +104,28 @@ try {
     if ($env:TEZGAH_DIST) {
         $archive = Join-Path (Resolve-Full $env:TEZGAH_DIST) $name
         if (-not (Test-Path -LiteralPath $archive)) { throw "tezgah: no $archive" }
+    } elseif ($Token) {
+        $release = Invoke-RestMethod "https://api.github.com/repos/$Repo/releases/tags/v$Version" -Headers $Headers
+        $asset = $release.assets | Where-Object { $_.name -eq $name }
+        $sidecarAsset = $release.assets | Where-Object { $_.name -eq "$name.sha256" }
+        if (-not $asset -or -not $sidecarAsset) {
+            throw "tezgah: release v$Version of $Repo carries no $name"
+        }
+        try { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 } catch { }
+        Invoke-WebRequest -UseBasicParsing -Headers $AssetHeaders `
+            "https://api.github.com/repos/$Repo/releases/assets/$($asset.id)" -OutFile $archive
     } else {
         $base = "https://github.com/$Repo/releases/download/v$Version"
         try { [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 } catch { }
         Invoke-WebRequest -UseBasicParsing "$base/$name" -OutFile $archive
     }
     $sidecar = "$archive.sha256"
-    if (-not $env:TEZGAH_DIST) {
+    if ($env:TEZGAH_DIST) {
+        # already beside the archive
+    } elseif ($Token) {
+        Invoke-WebRequest -UseBasicParsing -Headers $AssetHeaders `
+            "https://api.github.com/repos/$Repo/releases/assets/$($sidecarAsset.id)" -OutFile $sidecar
+    } else {
         Invoke-WebRequest -UseBasicParsing "$base/$name.sha256" -OutFile $sidecar
     }
 

package/packaging/install.sh

@@ -6,10 +6,14 @@
 # Runs packaging/upgrade.sh (the one place a version is fetched, verified,
 # unpacked and made current), then the installer from the tree it made current.
 # Needs sh and curl; tar and sha256sum are upgrade.sh's. Env, unlike its flags:
-# TEZGAH_REPO, TEZGAH_DIST, TEZGAH_PREFIX, as in upgrade.sh.
+# TEZGAH_REPO, TEZGAH_DIST, TEZGAH_PREFIX, as in upgrade.sh, and the token below
+# (a private TEZGAH_REPO serves no file without one).
 set -eu
 
 REPO=${TEZGAH_REPO:-r1z4x/tezgah}
+# raw.githubusercontent.com answers 404 to a session without a token when the
+# repository is private, and serves the same file to one that carries the bearer.
+token=${TEZGAH_GITHUB_TOKEN:-${GITHUB_TOKEN:-${GH_TOKEN:-}}}
 VERSION_ARG=
 PREFIX_ARG=
 REPLY_ARG=
@@ -37,8 +41,14 @@ else
     [ -z "$VERSION_ARG" ] || ref=v$VERSION_ARG
     work=$(mktemp -d "${TMPDIR:-/tmp}/tezgah-install.XXXXXX") || exit 1
     up=$work/upgrade.sh
-    curl -fsSL "https://raw.githubusercontent.com/$REPO/$ref/packaging/upgrade.sh" -o "$up" \
-        || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref" >&2; exit 1; }
+    url="https://raw.githubusercontent.com/$REPO/$ref/packaging/upgrade.sh"
+    if [ -n "$token" ]; then
+        printf 'Authorization: Bearer %s\n' "$token" | curl -fsSL -H @- "$url" -o "$up" \
+            || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN" >&2; exit 1; }
+    else
+        curl -fsSL "$url" -o "$up" \
+            || { echo "tezgah: cannot fetch packaging/upgrade.sh at $ref - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN" >&2; exit 1; }
+    fi
 fi
 
 set -- --prefix "$PREFIX"                  # explicit flags: a prefix may hold a space

package/packaging/upgrade.sh

@@ -12,13 +12,15 @@
 # Callers: packaging/install.sh (a first install) and `tezgah-setup --upgrade`.
 # Neither re-implements the fetch, the checksum or the flip.
 #
-# Needs: sh, curl, tar, and sha256sum or shasum. No python. Uses `gh` when it
+# Needs: sh, curl, tar, awk, and sha256sum or shasum. No python. Uses `gh` when it
 # is on PATH to check the release's build provenance; without it, says so.
 # Env: TEZGAH_PREFIX, XDG_DATA_HOME, TEZGAH_VERSION, TEZGAH_REPO, TEZGAH_DIST
 #      (a directory holding tezgah-<V>.tar.gz + .sha256 - what build.sh --out
 #      writes; it swaps the release URL for that directory, one code path, and
 #      is how upgrade.sh is exercised without a published release), TEZGAH_GH
-#      (the gh to run for the provenance check; default `gh` on PATH).
+#      (the gh to run for the provenance check; default `gh` on PATH),
+#      TEZGAH_GITHUB_TOKEN / GITHUB_TOKEN / GH_TOKEN (the first one set is sent
+#      as the bearer a private $TEZGAH_REPO needs; with none, the public URLs).
 set -eu
 
 REPO=${TEZGAH_REPO:-r1z4x/tezgah}
@@ -39,10 +41,40 @@ die() {
     exit 1
 }
 
+# A private repository answers 404 to `releases/download/...` from a session without
+# a token (measured 2026-10-17, with the token as URL userinfo and as a header
+# alike), while the REST asset endpoint returns the blob for `Accept:
+# application/octet-stream` plus `Authorization: Bearer`. So the token decides which
+# URL is read, and a public repository - no token - keeps exactly the URL it had.
+token=${TEZGAH_GITHUB_TOKEN:-${GITHUB_TOKEN:-${GH_TOKEN:-}}}
+
+# Every read goes through here, so the bearer cannot be forgotten on one call. It
+# reaches curl on stdin (`-H @-`, curl 7.55+): an argument is in every user's `ps`.
+get() {   # get <url> [curl args...]
+    if [ -n "$token" ]; then
+        printf 'Authorization: Bearer %s\n' "$token" | curl -fsSL -H @- "$@"
+    else
+        curl -fsSL "$@"
+    fi
+}
+
+# The id of asset `$2` in the JSON of one release (`$1`). An asset's id is written
+# down in one place, its own `url` field, so the JSON is flattened, split at each
+# `"url":` - one fragment per asset, from its url to the next one - and the id read
+# from the fragment that names the file wanted. Empty, not an error, when the
+# release carries no such asset; the caller says so.
+asset_id() {
+    printf '%s\n' "$1" | tr -d '[:space:]' | awk -v want="\"name\":\"$2\"" '
+        { n = split($0, o, "\"url\":")
+          for (i = 1; i <= n; i++)
+              if (index(o[i], want) && match(o[i], /"id":[0-9]+/))
+                  { print substr(o[i], RSTART + 5, RLENGTH - 5); exit } }'
+}
+
 # The newest release tag. The API answers `tag_name`; the raw redirect would
 # too, but GitHub answers this without a rate-limit surprise on a repeat run.
 latest_release() {
-    body=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null) \
+    body=$(get "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null) \
         || return 1
     tag=$(printf '%s\n' "$body" \
         | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
@@ -77,18 +109,40 @@ if [ -n "${TEZGAH_DIST:-}" ]; then
         *)  dist=$PWD/$TEZGAH_DIST ;;
     esac
     base="file://$dist"
+    assets=
+elif [ -n "$token" ]; then
+    # The asset endpoint is addressed by id, and the release JSON is the only
+    # place that id is written down.
+    rel=$(get "https://api.github.com/repos/$REPO/releases/tags/v$VERSION") \
+        || die "cannot read release v$VERSION of $REPO with the token in TEZGAH_GITHUB_TOKEN/GITHUB_TOKEN/GH_TOKEN"
+    id=$(asset_id "$rel" "tezgah-$VERSION.tar.gz")
+    id_sidecar=$(asset_id "$rel" "tezgah-$VERSION.tar.gz.sha256")
+    [ -n "$id" ] && [ -n "$id_sidecar" ] \
+        || die "release v$VERSION of $REPO carries no tezgah-$VERSION.tar.gz"
+    base="https://api.github.com/repos/$REPO/releases/assets"
+    assets=$base
 else
     base="https://github.com/$REPO/releases/download/v$VERSION"
+    assets=
 fi
 
 work=$(mktemp -d "${TMPDIR:-/tmp}/tezgah-upgrade.XXXXXX") || die "cannot create a temp dir"
 trap 'rm -rf "$work"' EXIT INT TERM
 
 name=tezgah-$VERSION.tar.gz
-curl -fsSL "$base/$name" -o "$work/$name" \
-    || die "cannot fetch $name from $base"
-curl -fsSL "$base/$name.sha256" -o "$work/$name.sha256" \
-    || die "cannot fetch $name.sha256 from $base"
+if [ -n "$assets" ]; then
+    # Both files come from the same release, and neither blob is served without
+    # this Accept: the endpoint answers JSON metadata otherwise.
+    get -H "Accept: application/octet-stream" "$assets/$id" -o "$work/$name" \
+        || die "cannot fetch $name from $assets/$id"
+    get -H "Accept: application/octet-stream" "$assets/$id_sidecar" -o "$work/$name.sha256" \
+        || die "cannot fetch $name.sha256 from $assets/$id_sidecar"
+else
+    get "$base/$name" -o "$work/$name" \
+        || die "cannot fetch $name from $base - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN"
+    get "$base/$name.sha256" -o "$work/$name.sha256" \
+        || die "cannot fetch $name.sha256 from $base - if $REPO is private, set TEZGAH_GITHUB_TOKEN, GITHUB_TOKEN or GH_TOKEN"
+fi
 
 want=$(sed -n '1s/[[:space:]].*//p' "$work/$name.sha256")
 got=$(sha256_of "$work/$name")