release: v1.21.18 (self-update token fix, terraphim-ai#3428)

[AlexMikhalev]

Release prep for v1.21.18: ships the self-update token fix (terraphim/terraphim-ai#3428, Gitea).

What

1. Cherry-picks (-x) the three commits of Gitea PR terraphim/terraphim-clients#353 (merged on Gitea as c7ae82033) onto the canonical GitHub line:
   • 52ba0ae fix(update): send GitHub token on every API call
   • 8ee184e test(update): guard auto-check repo default and check 403 wording
   • c518198 docs(update): github_api_url only affects API lookups, not asset downloads
2. 4db4f42 chore: bump workspace version to 1.21.18. Same shape as chore: bump workspace version to 1.21.17 #40: Cargo.toml plus 14 Cargo.lock lines.

The fix: terraphim-agent update returned a GitHub 403 even with GITHUB_TOKEN set, because the verified-update release lookup never applied the token. The auto-check also still targeted the old terraphim-ai repo. All GitHub API calls now go through one builder that applies the repo, the token (GITHUB_TOKEN, then GH_TOKEN) and the API URL. 12 new tests run against a real local HTTP server.

Verification

• The ported files (crates/terraphim_update/src/lib.rs, crates/terraphim_agent/tests/update_functionality_tests.rs) are byte-identical to Gitea main.
• cargo test -p terraphim_update --lib: 151 passed. cargo clippy -p terraphim_update --all-targets -- -D warnings: clean.
• cargo build --release -p terraphim_agent -p terraphim_grep -p terraphim-cli: all three report 1.21.18.
• Live check of the built agent against the real GitHub API (TERRAPHIM_UPDATE_BACKEND=github):
  • with GITHUB_TOKEN: [OK] Already running latest version: 1.21.18;
  • without a token: GitHub API rate limit exceeded. Set GITHUB_TOKEN (or GH_TOKEN) …, the new wording.
• The fix's original Gitea PR #353 had two pi-rust structural reviews; the final one found no P0/P1.

After merge

Follow docs/release-operator-checklist.md: tag v1.21.18 at the merge commit, dispatch release-binaries.yml, inspect the sealed stage, obtain separate publication authorisation, then run scripts/promote-release.sh.

Note: GitHub Actions currently has an open major-outage incident, so CI on this PR and the producer run may be delayed.

🤖 Generated with Claude Code

[AlexMikhalev]

Pre-merge review of record: pi-rust (openai-codex/gpt-5.5, structural-pr-review skill, read-only tools) on head 4db4f42.

Pre-merge review: PR terraphim/terraphim-clients#52

Scope reviewed: git diff github/main...HEAD and git log --oneline github/main..HEAD for:

• crates/terraphim_update/src/lib.rs
• crates/terraphim_agent/tests/update_functionality_tests.rs
• Cargo.toml
• Cargo.lock

Head reviewed: 4db4f42.

Findings

P0

None.

P1

None.

P2

None.

Confidence

Confidence: 5/5

The scoped diff is small enough to inspect directly, the release-version changes are limited to expected version fields, and the updater change is covered by local real-HTTP-server tests plus cargo test.

Validation run

• git log --oneline github/main..HEAD shows the expected four commits:
  • 52ba0ae fix(update): send GitHub token on every API call
  • 8ee184e test(update): guard auto-check repo default and check 403 wording
  • c518198 docs(update): github_api_url only affects API lookups, not asset downloads
  • 4db4f42 chore: bump workspace version to 1.21.18
• cargo test -p terraphim_update --lib: passed, 151 passed, 0 failed.
• cargo metadata --format-version 1 --no-deps: local package versions are consistent with the scoped bump: packages previously at 1.21.17 are now 1.21.18; pre-existing explicitly-versioned workspace members remain unchanged.

Mermaid overview

flowchart TD
    Env["GITHUB_TOKEN / GH_TOKEN"] --> Source["GitHubSource"]
    Config["UpdaterConfig"] --> Source
    Source --> Builder["self_update GitHub builder"]
    Builder --> Check["check_update_github"]
    Builder --> Update["update_github"]
    Builder --> Verified["update_with_verification"]
    Builder --> Auto["check_for_updates_auto"]
    Source --> ErrorText["token-aware 403 wording"]
    ApiUrl["github_api_url override"] --> Source
    Source --> Repo["terraphim/terraphim-clients"]

Loading

Per-file overview

crates/terraphim_update/src/lib.rs

• Adds DEFAULT_REPO_OWNER and DEFAULT_REPO_NAME at lines 33-36, correctly targeting terraphim/terraphim-clients.
• Adds github_token_from_env() at lines 38-45, using GITHUB_TOKEN first and GH_TOKEN second.
• Introduces private GitHubSource at lines 56-133, centralising:
  • repository owner/name,
  • auth token,
  • optional API base URL,
  • binary-name normalisation,
  • install path setup,
  • token-aware 403 wording.
• UpdaterConfig gains github_api_url at lines 269-272 and with_github_api_url() at lines 366-371.
• GitHub backend call sites now use GitHubSource::builder():
  • check path: lines 653-662
  • update path: lines 783-816
  • verified update path: lines 918-930
  • auto-check path: via GitHubSource::from_env()
• Tests added around lines 2172 onward exercise real local HTTP requests and verify:
  • token is sent,
  • no token means no auth header,
  • auto-check uses terraphim/terraphim-clients,
  • 403 wording distinguishes token-present from token-absent,
  • github_api_url affects API lookups.

No release-blocking risk found.

crates/terraphim_agent/tests/update_functionality_tests.rs

• Updates the expected default repository from the old literal terraphim-ai to exported constants:
  • lines 153-161.
• This matches the intended release repository and avoids duplicating the repo string in the agent test.

No release-blocking risk found.

Cargo.toml

• Workspace package version changes from 1.21.17 to 1.21.18 at line 18.
• No dependency, member-list, patch, or registry-policy changes in the scoped diff.

No release-blocking risk found.

Cargo.lock

• Only expected workspace-package version fields changed from 1.21.17 to 1.21.18:
  • terraphim-cli
  • terraphim-session-analyzer
  • terraphim_agent
  • terraphim_grep
  • terraphim_hooks
  • terraphim_lsp
  • terraphim_negative_contribution
• No dependency resolution changes, checksum changes, or stray package additions/removals observed in the scoped diff.

No release-blocking risk found.

---

Author verification: no findings to dispute.

[AlexMikhalev]

Pre-merge review of record: pi-rust (openai-codex/gpt-5.5, structural-pr-review skill, read-only tools) on final head f94b892 (second review; the first, on 4db4f42, found no issues).

Pre-merge re-review: PR #52 at f94b892

Scope reviewed:

• git diff github/main...HEAD
• git diff 4db4f42..HEAD
• Specific known PKGBUILD/version-contract item

Findings

P0

None.

P1

None.

P2

None.

Known item assessment

tests/test_pkgbuild_release_contract.py:151 still requires pkgbuilds/terraphim-clients-bin/PKGBUILD:21 pkgver to match the workspace version. The current state is:

• Workspace version: 1.21.18
• PKGBUILD pkgver: 1.21.16
• Failing assertion: tests/test_pkgbuild_release_contract.py:151
• Source value: pkgbuilds/terraphim-clients-bin/PKGBUILD:21

I do not consider this release-blocking for this PR, given the stated release sequencing constraint: the PKGBUILD pkgver and sha256sums must be generated from the published v1.21.18 release assets, so bumping it before publication would either be unverifiable or require placeholder digests. This failure is also pre-existing on github/main, so it is not introduced by f94b892.

Confidence: 5/5.

Since previous review

git diff 4db4f42..HEAD contains exactly one assertion update:

tests/test_release_binaries_workflow_contract.py:179
1.21.17 -> 1.21.18

This is correct: the test pins the checked-in workspace version and now matches the release branch version.

Confidence: 5/5.

Validation run

python3 -m unittest -v tests.test_release_binaries_workflow_contract
Ran 35 tests in 0.364s
OK

python3 -m unittest -v tests.test_pkgbuild_release_contract
Ran 7 tests
FAILED: test_pkgbase_identity_and_version

The single failure is the known PKGBUILD lag described above. One .SRCINFO test was skipped because makepkg is only available on Arch.

Release flow note

flowchart TD
    A[Workspace version bumped to 1.21.18] --> B[Release PR validates workflow contracts]
    B --> C[Publish v1.21.18 release assets]
    C --> D[Compute asset sha256sums]
    D --> E[Follow-up bumps PKGBUILD pkgver and sha256sums]
    E --> F[PKGBUILD contract returns green]

    G[Current PR] --> H{Blocks release?}
    H -->|No| C

Loading

Per-file overview

File	Change / status	Review result
tests/test_release_binaries_workflow_contract.py	Assertion updated from 1.21.17 to 1.21.18 at line 179	Correct and necessary for the checked-in workspace version
tests/test_pkgbuild_release_contract.py	No change in this PR; still enforces PKGBUILD pkgver == workspace version at line 151	Contract is valid; current failure is known pre-existing release sequencing debt
pkgbuilds/terraphim-clients-bin/PKGBUILD	No change in this PR; pkgver=1.21.16 at line 21	Acceptable as follow-up after v1.21.18 assets and digests exist
Cargo.toml, Cargo.lock, crates/terraphim_update/src/lib.rs, crates/terraphim_update/tests/update_functionality_tests.rs	Part of github/main...HEAD; previously reviewed at 4db4f42 with no issues	No new concerns from the incremental diff

Conclusion

No new P0/P1/P2 findings. The 1.21.18 assertion update is correct. The PKGBUILD mismatch should be fixed in a follow-up immediately after the v1.21.18 assets are published and their sha256sums are available; it is not release-blocking for this PR.

---

Author verification: agreed. The PKGBUILD contract failure is pre-existing on main (CI red on every commit since before v1.21.17), and it gets a follow-up PR bumping pkgver and sha256sums from the published v1.21.18 assets. Merging by rebase: branch protection requires linear history.