vuer-release CLI pinning (.cliversion) and the 1.0.3 → 1.1.1 toolchain traps

TechTeamer/vuer-release pins the release CLI to an exact version via a .cliversion file, and the toolchain around that pin is broken in several independent ways. Source-verified 2026-09-04 while cutting cib@1. Read this before touching .cliversion, before running the CLI locally, and before hand-writing a release.json.

For Agents

• vuer-release/.cliversion currently reads 1.0.3. It is an equality pin, not a minimum.
• Do not bump .cliversion to 1.1.1 — the CI runner’s asset name changed and the download step will fail. See Bumping to 1.1.1 breaks the runner.
• To run the pinned CLI locally you must patch its pyproject.toml first (it is invalid TOML) and invoke it as python run.py, not release-tool.
• Always generate release.json with the pinned version — 1.0.3 and 1.1.1 emit different key sets and ordering.
• The CLI-source facts recorded in vuer-release-build-flow were read from 1.0.3, i.e. the version CI actually runs. They remain accurate for the runner; they are not accurate for 1.1.1.

The pin is exact equality

release_tool/pkg/util.py → validate_cli_version compares

Version(current) != Version(required)

So a newer CLI is rejected exactly like an older one. There is no “minimum supported version” semantics anywhere in the tool. The value comes from vuer-release/.cliversion.

Bumping to 1.1.1 breaks the runner

The self-hosted runner fetches the CLI in .github/scripts/download-release-cli.sh, which selects the GitHub release asset named release_tool (underscore).

CLI release	Asset name	Runner outcome
1.0.3 (pinned)	release_tool	works
1.1.1 (current latest)	release-tool (hyphen)	ERROR: Asset 'release_tool' not found

Bumping .cliversion alone is not enough

Moving to 1.1.1 requires changing download-release-cli.sh too. Editing .cliversion on its own turns every subsequent partner build red at the download step, before any component is even cloned.

Running 1.0.3 locally — two blockers

1. pyproject.toml is invalid TOML

In CLI 1.0.3, pyyaml and typing_extensions are unquoted inside the dependencies list. pip install -e . therefore dies with:

tomllib.TOMLDecodeError   # at pyproject.toml line 16

Patch the file locally (quote both entries) to install it at all. This is a defect in the released 1.0.3 source, not a local environment problem.

2. There is no release-tool entry point in 1.0.3

1.0.3 ships no [project.scripts] section, so no release-tool console script is created. Invoke it directly:

python run.py <command> ...

Typing release-tool … (the name used in vuer-release-cut-recipe and vuer-release-build-flow to describe what CI runs) will simply not resolve locally on the pinned version.

3. (1.1.1 only) missing dependency

CLI 1.1.1’s requirements.txt omits packaging, which the tool imports. Install it manually if you experiment with 1.1.1.

1.0.3 and 1.1.1 emit DIFFERENT release.json

Generate the descriptor with the pinned version, or hand-copy the previous one

The two versions disagree on both the required-key set and the shape of the requirement declaration:

	1.0.3	1.1.1
REQUIRED_ENV_VALUES	{"VERSION": "", "BUILD_NUMBER": ""}	{"VERSION": …, "TAG": …}, values are a required-flag dict
resulting key ordering in release.json	1.0.3 ordering	different

A descriptor generated by 1.1.1 and then built by the pinned 1.0.3 runner is not a safe assumption. The hand-copy-the-previous-release.json recipe sidesteps this entirely and is the reason it is the recommended path.

Note that the REQUIRED_ENV_VALUES = {"VERSION": "", "BUILD_NUMBER": ""} line quoted in vuer-release-build-flow (and the “TAG is not required → janus is never cloned” trap built on it) is 1.0.3 behaviour. 1.1.1 promotes TAG into the required set, which would change that trap — but 1.1.1 is not what runs.

Config file: same path, incompatible schemas

Both versions read ~/.release-tool/config.json, and they parse it differently:

Version	Schema
1.0.3	flat keys — release_repo_path, release_repo_git_remote, release_branch
1.1.1	context map — {"current_context": …, "contexts": {…}}

A config written by one version is not readable by the other. There is no migration and no version marker in the file.

Other 1.0.3 → 1.1.1 behaviour changes

Thing	1.0.3	1.1.1
Release commit message	Release: <target>, version: <N>	chore(release): <target>, release version: <N>
repository.create()	takes no args	takes cfg

The commit-message difference matters when reading history: older vuer-release commits made by the tool look like Release: nusz, version: 13. Hand-made commits (the normal path today) do not follow either form — the cib@1 commit was chore: [asscib-166] cib 1.9.11.102 release/1, which is fine — vuer-release-cut-recipe documents that vuer-release has no commit-message ruleset.

Related

• vuer-release-cut-recipe — the cut procedure this pins the tooling for.
• vuer-release-build-flow — what the CLI does internally (read from 1.0.3 source).
• component-list-is-not-a-full-manifest — the other release.json correction from the same session.
• cib-1.9.11.102 — the cut during which all of this was found.
• release-cut-mechanics · Releases index · FaceKom