Skip to content

F23.2 — A Python tool installs from a branch, a tag or a commit

State Closed
Parent E23
Iteration Release 9
Start Date 2026-11-17
Closed Date 2026-11-17
Predecessors F22.6
Source kiln F7.7, 2026-11-14

Stories: 3 Closed

Story State Depends on
S23.2.1 — install --ref installs a commit of a GitHub repository Closed (2026-11-17) —
S23.2.2 — upgrade, status and doctor follow the recorded ref Closed (2026-11-17) S23.2.1
S23.2.3 — PythonTool builds a runnable command Closed (2026-11-17) —

<tool> self install --ref <ref> installs any branch, tag or commit of a tool's GitHub repository, with no GitHub release needed. A Python tool's install holds a working command. The install state records what was asked for and what was installed, so status, upgrade and doctor report and act on it.

Context

Seen with kiln, the first tool to run the lifecycle outside its tests:

  • GitHubReleases.latest() reads releases/latest, and --version names the tag v<version>. A tool with no release, such as kiln before v0.1.0, cannot be installed, and neither can a branch. The version is also the directory name under versions/, which must be one path segment, and feature/v1 is not.
  • ToolProduct.build copies the release's source tree. For a Python tool that tree has no bin/<tool>, so the product's Link("bin/<tool>", "bin/<tool>") points at nothing. kiln's own product and every python-tool repository kiln generates declare exactly that link.
  • state.json holds version and schema_version, and doctor compares the version directory's name with the running version. An install from a commit has no release version to compare.

F22.6 reworks the install transaction (prepare, then mutate). This feature follows it so that the ref resolution and the uv build land in its prepare phase.

Design

  • GitHubReleases also resolves refs; there is no separate refs class:

    • resolve(ref) returns the 40-character commit SHA from GET /repos/{repo}/commits/{ref}, which accepts a branch, a tag or a SHA;
    • download_commit(sha, destination) fetches /{repo}/archive/{sha}.tar.gz;
    • latest() stays the newest release.
  • install --ref <ref>, a new option on the install verb, exclusive with --version and --archive. A ref install's version directory is named for the commit's first 12 characters.

  • state.json gains ref (as asked: the branch, the tag or the SHA, and for a --version install the tag) and commit (when known). It gains version, the package version the build reports, from the built tree's pyproject.toml [project] version. An install recorded before this feature reads as a release install whose ref is v<version>.

  • upgrade re-resolves a ref install's recorded ref. When the commit is unchanged, the result is already-current. A release install moves to the newest release, as it does now.

  • status prints installed: <version> (<ref> @ <commit 12>) for a ref install, and its --json output carries ref and commit.

  • doctor's install.version-mismatch compares the running version with state.json's version, not with the directory name.

  • PythonTool(ToolProduct), in rn_forge.tooling.install:

    • its build runs uv tool install <release_root> with UV_TOOL_DIR=<version_dir>/tool and UV_TOOL_BIN_DIR=<version_dir>/bin;
    • its default artifacts() is Link("bin/<name>", "bin/<name>");
    • uv missing from PATH is an AppException raised before anything is written, by its preflight(), a ToolProduct hook that install calls first and that does nothing by default.

    uv is a program on PATH, not a Python dependency, and no dependency is added.

S23.2.1 — install --ref installs a commit of a GitHub repository

State: Closed (2026-11-17)

Acceptance:

  • GitHubReleases.resolve and download_commit are tested against a fake HTTP server, for a branch, a tag and a SHA, and for a ref that does not exist, which is an AppException naming the ref that leaves the home untouched.
  • install --ref with --version or --archive is a usage error.
  • A ref install's directory is versions/<commit 12>, and state.json holds version, ref, commit and schema_version. This is a test.
  • A state.json without ref reads as a release install, and status and doctor report it without error. This is a test.

S23.2.2 — upgrade, status and doctor follow the recorded ref

State: Closed (2026-11-17) · Depends on: S23.2.1

Acceptance:

  • upgrade of a branch install moves to the branch's new commit, and returns already-current when the commit has not moved. upgrade of a release install moves to the newest release. There is one test for each.
  • status text and --json carry ref and commit for a ref install.
  • doctor reports install.version-mismatch from state.json's version. A ref install whose package version matches the running one reports none.

S23.2.3 — PythonTool builds a runnable command

State: Closed (2026-11-17)

Acceptance:

  • PythonTool.build from a minimal Python tool tree with one console script leaves <version_dir>/bin/<name>. After install, $RNF_HOME/bin/<name> runs through current. This is a test that needs uv and is skipped without it.
  • uv missing from PATH fails the install before versions/ is written. This is a test.
  • uninstall removes the uv tool environment with the version directory, and nothing is left under $RNF_HOME. This is a test.
  • The lifecycle guide (packages/rn-forge-tooling/docs/guides/lifecycle.md) and the install reference cover --ref, the new state.json fields and PythonTool.
  • rn-forge-tooling is released to pypi.org with F23.2, and kiln's upstream pin row for F23.2 can then read yes.

Acceptance

set -euo pipefail
task test -- rn-forge-tooling   # S23.2.1 S23.2.2 S23.2.3

Not scriptable: kiln F7.7's S7.7.4 run installs kiln from feature/v1 and from a commit, upgrades it, cleans it up and uninstalls it, and records the home and state.json at each step.

Considered and rejected

  • Install from GitHub releases only. It needs a release before a tool can be tested as installed, and kiln's release waits on that test.
  • Name a ref install's directory after the ref. A branch name is not one path segment, and a branch moves, so the same name would hold different commits.
  • uv tool install into uv's own tool directory. That leaves nothing for the home's versions/ and current to manage, so cleanup, the rollback and doctor would no longer describe the install.