rust_realease/AGENTS.md

744 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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:
```text
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:
```text
tests/
```
Do not collapse everything into one large Python file.
---
## User experience
Preferred final CLI:
```bash
./release.sh SOURCE [OPTIONS]
```
Examples:
```bash
./release.sh ./my-tool --dry-run
```
```bash
./release.sh \
https://gitea.example.org/user/my-tool.git \
--tag v0.3.1 \
--dry-run
```
```bash
./release.sh \
https://gitea.example.org/user/my-tool.git \
--tag v0.3.1 \
--fix-metadata
```
Avoid requiring a redundant subcommand such as:
```bash
./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:
```bash
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:
```bash
set -euo pipefail
```
and finish with:
```bash
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:
```toml
[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:
```bash
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:
```text
v
```
For package version:
```text
0.3.1
```
expected tag:
```text
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:
```text
{name}-{target}-v{version}.tgz
```
Examples:
```text
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:
```text
mytool-x86_64-unknown-linux-musl-v0.3.1/
└── mytool
```
Windows:
```text
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:
```toml
[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:
```text
check only
```
With:
```bash
--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:
```bash
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:
```text
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:
```text
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:
```text
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:
```text
name: same as tag
draft: false
prerelease: false
```
Support:
```bash
--draft
--prerelease
```
if straightforward.
---
## Asset collision policy
Default:
- if a release already contains an asset with the same filename, fail.
With:
```bash
--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:
```bash
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:
```text
--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:
```text
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:
```text
KeyError: 'package'
```
Good:
```text
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:
```bash
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.