13 KiB
AGENT.md
Mission
Finish the rust-binstall-publisher proof-of-concept as a small, maintainable release tool for Rust CLI projects.
The tool must:
- refuse to run from the Bash wrapper unless a Python virtual environment is active;
- offer to create
.venvwhen no project venv exists; - inspect a local Rust project or clone a Git repository;
- validate package metadata and
cargo-binstallmetadata; - optionally repair missing or incorrect metadata without silently pushing changes;
- validate that the Git tag matches the Cargo package version;
- cross-compile release binaries for the default target matrix;
- package artifacts using a deterministic naming/layout convention;
- generate SHA-256 checksums;
- create or reuse a Gitea release;
- upload release assets;
- verify that
cargo-binstallcan consume the published artifact metadata.
The intended default targets are:
x86_64-unknown-linux-muslaarch64-unknown-linux-muslx86_64-pc-windows-gnu
The tool is initially optimized for a single Cargo package producing a single CLI binary. Multi-package workspaces and multi-binary packages should be detected and reported cleanly rather than guessed at.
Repository layout
Target layout:
rust-binstall-publisher/
├── release.sh
├── requirements.txt
├── config.toml
├── README.md
├── AGENT.md
├── AGENT_TASKS.md
└── worker/
├── __init__.py
├── __main__.py
├── cli.py
├── config.py
├── models.py
├── runner.py
├── project.py
├── manifest.py
├── build.py
├── package.py
├── gitea.py
└── verify.py
Tests may be added under:
tests/
Do not collapse everything into one large Python file.
User experience
Preferred final CLI:
./release.sh SOURCE [OPTIONS]
Examples:
./release.sh ./my-tool --dry-run
./release.sh \
https://gitea.example.org/user/my-tool.git \
--tag v0.3.1 \
--dry-run
./release.sh \
https://gitea.example.org/user/my-tool.git \
--tag v0.3.1 \
--fix-metadata
Avoid requiring a redundant subcommand such as:
./release.sh release ...
unless Typer makes the simpler interface unreasonable.
Bash wrapper requirements
release.sh must be intentionally strict.
Without an active venv
If .venv exists:
- refuse to run the worker;
- print the exact activation command;
- exit non-zero.
Expected guidance:
source .venv/bin/activate
If .venv does not exist and stdin is interactive:
- ask whether to create it;
- if accepted:
- run
python3 -m venv .venv; - install
requirements.txt; - report success;
- exit;
- run
- do not attempt to “activate” the environment from inside the script.
If stdin is non-interactive:
- fail with a clear message instead of prompting.
With an active venv
If it is the project .venv, proceed.
If another venv is active:
- warn;
- interactively ask whether to continue;
- in non-interactive mode, fail rather than guessing.
The wrapper must use:
set -euo pipefail
and finish with:
exec python -m worker "$@"
or the equivalent project-local interpreter invocation.
Python dependencies
Dependencies are acceptable.
Use:
tomlkitfor preservingCargo.tomlcomments and formatting;richfor readable terminal output;typerfor CLI parsing;httpxfor Gitea HTTP operations.
Prefer the standard library for everything else.
Do not add large frameworks.
Configuration
config.toml should provide sane defaults.
Suggested initial shape:
[release]
tag-prefix = "v"
[build]
targets = [
"x86_64-unknown-linux-musl",
"aarch64-unknown-linux-musl",
"x86_64-pc-windows-gnu",
]
profile = "release"
locked = true
[package]
format = "tgz"
[gitea]
token-env = "GITEA_TOKEN"
CLI options override configuration values.
Do not hardcode one specific Gitea instance.
Source acquisition
Support:
- a local path;
- a Git HTTP/HTTPS URL;
- SSH-style URLs such as
git@host:owner/repo.git.
For remote repositories:
- clone into a temporary directory;
- support checking out a requested tag;
- remove the temporary directory unless
--keep-workdiris set.
For local repositories:
- never delete or move the user’s project;
- do not commit or push changes automatically.
Cargo inspection
Use:
cargo metadata --format-version=1 --no-deps
to discover:
- package name;
- package version;
- repository;
- binary target names.
Also read Cargo.toml through tomlkit for editable metadata.
For the first supported release path:
- exactly one package;
- exactly one binary.
If multiple binaries or ambiguous workspace packages exist:
- show what was discovered;
- exit with a clear unsupported-case message.
Do not guess which binary the user intended.
Version/tag policy
Default tag prefix:
v
For package version:
0.3.1
expected tag:
v0.3.1
If --tag is supplied and does not match, fail before building.
Do not silently retag or rewrite package versions.
cargo-binstall metadata policy
The tool should standardize artifact naming.
Preferred archive name:
{name}-{target}-v{version}.tgz
Examples:
mytool-x86_64-unknown-linux-musl-v0.3.1.tgz
mytool-aarch64-unknown-linux-musl-v0.3.1.tgz
mytool-x86_64-pc-windows-gnu-v0.3.1.tgz
Preferred archive layout:
mytool-x86_64-unknown-linux-musl-v0.3.1/
└── mytool
Windows:
mytool-x86_64-pc-windows-gnu-v0.3.1/
└── mytool.exe
Expected metadata should be generated from the chosen convention rather than duplicated in several modules.
Suggested metadata:
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
If actual cargo-binstall behavior requires a small adjustment, centralize it in one policy function and document the reason.
Modes
Default:
check only
With:
--fix-metadata
the tool may edit the checked-out Cargo.toml.
It must:
- preserve formatting/comments where practical;
- print what changed;
- not commit;
- not push.
A future --commit-metadata option may be added, but it is not required for this PoC.
Prerequisite validation
Before a real build, check for:
gitcargocross- a usable Docker/Podman backend required by
cross
Do not discover missing build prerequisites halfway through target 3.
A dry run should report prerequisite availability but not build anything.
Build policy
Use cross build.
Default pattern:
cross build \
--release \
--locked \
--target TARGET
Respect config values for:
- profile;
- locked/unlocked behavior;
- target list.
If Cargo.lock does not exist and locked mode is enabled, fail clearly or require an explicit override.
Do not switch to x86_64-pc-windows-msvc automatically.
The Windows default for this Linux-hosted PoC is:
x86_64-pc-windows-gnu
Packaging policy
Create a local dist/ staging directory inside the working copy or an explicitly managed temporary location.
For each target:
- locate the compiled binary;
- copy it into the standardized top-level archive directory;
- preserve executable mode on Unix binaries;
- create
.tgz; - compute SHA-256.
Generate:
SHA256SUMS
with one line per archive.
Do not include build directories or unrelated project files in the archives.
Gitea authentication
Read the token from an environment variable.
Default:
GITEA_TOKEN
Never require the token as a normal CLI argument.
Do not log or print the token.
Support overriding the token environment-variable name through config if easy.
Gitea repository/release handling
The tool should derive owner/repository from either:
- the project repository URL;
- the clone source URL;
- explicit CLI options if necessary.
Do not guess silently if the repository cannot be identified.
Release behavior:
- look up the release by tag;
- if none exists, create it;
- if it exists, reuse it;
- upload artifacts.
Default release:
name: same as tag
draft: false
prerelease: false
Support:
--draft
--prerelease
if straightforward.
Asset collision policy
Default:
- if a release already contains an asset with the same filename, fail.
With:
--replace-assets
the tool may delete/replace matching assets.
Never silently create duplicate assets with altered filenames.
Verification
After publishing, verify the release contract.
At minimum:
- construct the expected asset URL;
- verify the asset exists;
- download it or otherwise validate that it is accessible;
- verify archive structure;
- verify binary filename.
Preferred final verification:
cargo binstall ...
using the checked-out manifest or a safe temporary install root.
Do not overwrite an unrelated user binary during verification.
Use a temporary Cargo home or bin directory where practical.
The tool should report verification results per target where feasible.
CLI flags
Implement or reserve cleanly for:
--tag TAG
--target TARGET repeatable
--dry-run
--fix-metadata
--skip-tests
--skip-binstall-test
--draft
--prerelease
--replace-assets
--keep-workdir
--verbose
--stop-after STAGE
Useful stage names:
inspect
metadata
verify
build
package
release
upload
binstall
--stop-after should stop successfully after the requested completed stage.
Dry-run semantics
--dry-run must not:
- edit the manifest;
- build binaries;
- create releases;
- upload assets;
- delete assets.
It should:
- acquire/inspect the project;
- report package information;
- validate version/tag;
- validate metadata;
- report proposed metadata changes;
- report planned build targets;
- report prerequisites;
- print intended artifact filenames and release destination.
Dry-run should be useful enough to diagnose most configuration problems.
Error handling
Prefer clear, short messages.
Bad:
KeyError: 'package'
Good:
error: Cargo.toml contains no [package] table.
Workspace-only manifests are not supported by this proof-of-concept.
External command failures should show:
- command;
- exit status;
- useful stderr.
Do not expose Python tracebacks by default.
--verbose may expose more detail.
Code organization
Keep responsibilities separated:
runner.py
External command execution and streaming.
project.py
Clone/local-path handling, checkout, cleanup, Git metadata.
manifest.py
Cargo/TOML inspection and binstall metadata validation/repair.
build.py
Prerequisites and cross compilation.
package.py
Artifact staging, archives, hashes.
gitea.py
HTTP client, release lookup/create, asset lookup/upload/delete.
verify.py
Published artifact and cargo-binstall verification.
models.py
Dataclasses shared across modules.
config.py
Config file parsing and default/CLI merge.
cli.py
Argument parsing and orchestration only.
Do not put HTTP logic in cli.py.
Do not put TOML-editing logic in build.py.
Testing expectations
At minimum, add tests for pure logic where practical:
- repository URL parsing;
- expected tag from version;
- archive naming;
- binary filename per target;
- cargo-binstall metadata generation;
- manifest validation/repair;
- checksum generation.
Avoid requiring a live Gitea instance for the basic test suite.
Gitea API calls should be structured so they can be mocked.
Security constraints
- never print
GITEA_TOKEN; - never embed tokens in URLs;
- never push Git changes automatically;
- never delete a user’s local source tree;
- never replace remote assets unless explicitly requested;
- never run arbitrary commands from repository metadata;
- treat repository content as untrusted input;
- avoid
shell=Truein Python subprocess calls.
Documentation expectations
Update README.md as features become real.
Document:
- setup;
- venv behavior;
- prerequisites;
- supported targets;
- dry-run;
- metadata repair;
- Gitea token setup;
- example publish command;
- current limitations.
Do not document unsupported features as if they already work.
Definition of done
The PoC is complete when this workflow works against a real single-binary Rust CLI project hosted on Gitea:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GITEA_TOKEN="..."
./release.sh \
https://gitea.example.org/owner/tool.git \
--tag v0.1.0 \
--fix-metadata
and the result is:
- package metadata validated;
- binaries built for all default targets;
- three
.tgzartifacts produced; SHA256SUMSproduced;- a Gitea release created or reused;
- all assets uploaded;
- the cargo-binstall URL/layout validated;
- no unrelated files or remote Git history modified.