rust_realease/AGENTS.md

13 KiB
Raw Blame History

AGENT.md

Mission

Finish the rust-binstall-publisher proof-of-concept as a small, maintainable release tool for Rust CLI projects.

The tool must:

  1. refuse to run from the Bash wrapper unless a Python virtual environment is active;
  2. offer to create .venv when no project venv exists;
  3. inspect a local Rust project or clone a Git repository;
  4. validate package metadata and cargo-binstall metadata;
  5. optionally repair missing or incorrect metadata without silently pushing changes;
  6. validate that the Git tag matches the Cargo package version;
  7. cross-compile release binaries for the default target matrix;
  8. package artifacts using a deterministic naming/layout convention;
  9. generate SHA-256 checksums;
  10. create or reuse a Gitea release;
  11. upload release assets;
  12. verify that cargo-binstall can consume the published artifact metadata.

The intended default targets are:

  • x86_64-unknown-linux-musl
  • aarch64-unknown-linux-musl
  • x86_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;
  • 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:

  • tomlkit for preserving Cargo.toml comments and formatting;
  • rich for readable terminal output;
  • typer for CLI parsing;
  • httpx for 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:

  1. a local path;
  2. a Git HTTP/HTTPS URL;
  3. 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-workdir is 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:

  • git
  • cargo
  • cross
  • 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:

  1. locate the compiled binary;
  2. copy it into the standardized top-level archive directory;
  3. preserve executable mode on Unix binaries;
  4. create .tgz;
  5. 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:

  1. look up the release by tag;
  2. if none exists, create it;
  3. if it exists, reuse it;
  4. 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=True in 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 .tgz artifacts produced;
  • SHA256SUMS produced;
  • a Gitea release created or reused;
  • all assets uploaded;
  • the cargo-binstall URL/layout validated;
  • no unrelated files or remote Git history modified.