First draft to be agent finished

This commit is contained in:
Dandaedre 2026-09-13 12:06:51 +02:00
parent 5331f9ca0f
commit b68ee590d3
12 changed files with 1932 additions and 1 deletions

743
AGENTS.md Normal file
View File

@ -0,0 +1,743 @@
# 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.

629
AGENT_TASKS.md Normal file
View File

@ -0,0 +1,629 @@
# AGENT_TASKS.md
## Goal
Finish the `rust-binstall-publisher` proof-of-concept described in `AGENT.md`.
Work in small, verifiable increments. Prefer completing one stage cleanly before adding the next.
---
## Phase 0 — Establish the project skeleton
- [ ] Create the final directory structure from `AGENT.md`.
- [ ] Add `worker/__init__.py`.
- [ ] Add `worker/__main__.py`.
- [ ] Add `requirements.txt`.
- [ ] Add `config.toml`.
- [ ] Add or update `README.md`.
- [ ] Ensure the package launches through `python -m worker`.
### Acceptance criteria
```bash
source .venv/bin/activate
python -m worker --help
```
works without traceback.
---
## Phase 1 — Harden `release.sh`
- [ ] Add `set -euo pipefail`.
- [ ] Resolve the script directory reliably.
- [ ] Detect whether `VIRTUAL_ENV` is set.
- [ ] If `.venv` exists but is not active, refuse and print:
```bash
source .venv/bin/activate
```
- [ ] If `.venv` does not exist and stdin is interactive, ask to create it.
- [ ] On approval:
- [ ] run `python3 -m venv .venv`;
- [ ] upgrade/install pip if desired;
- [ ] install `requirements.txt`;
- [ ] exit after setup.
- [ ] Do not pretend to activate the environment from the child shell.
- [ ] If another venv is active, warn and ask whether to continue.
- [ ] In non-interactive mode, fail instead of prompting.
- [ ] End with:
```bash
exec python -m worker "$@"
```
### Acceptance criteria
Test all four cases:
1. no venv, no `.venv`;
2. no venv, `.venv` exists;
3. wrong venv active;
4. project `.venv` active.
---
## Phase 2 — CLI and configuration
- [ ] Implement a Typer CLI without a redundant mandatory `release` subcommand.
- [ ] Add positional `SOURCE`.
- [ ] Add:
- [ ] `--tag`
- [ ] repeatable `--target`
- [ ] `--dry-run`
- [ ] `--fix-metadata`
- [ ] `--skip-tests`
- [ ] `--skip-binstall-test`
- [ ] `--draft`
- [ ] `--prerelease`
- [ ] `--replace-assets`
- [ ] `--keep-workdir`
- [ ] `--verbose`
- [ ] `--stop-after`
- [ ] Implement `config.py`.
- [ ] Parse `config.toml`.
- [ ] Merge CLI overrides over config defaults.
- [ ] Keep the default build target list in configuration or one centralized policy object.
### Acceptance criteria
```bash
./release.sh --help
```
shows all supported options clearly.
---
## Phase 3 — Command runner
- [ ] Implement a shared command runner.
- [ ] Do not use `shell=True`.
- [ ] Support:
- [ ] captured output;
- [ ] streamed output for long-running builds;
- [ ] working directory;
- [ ] custom environment overrides;
- [ ] verbose command logging.
- [ ] Create a dedicated exception for command failures.
- [ ] Include useful stderr in errors.
- [ ] Hide Python tracebacks by default.
### Acceptance criteria
A deliberately failing command produces a concise readable error.
---
## Phase 4 — Acquire project source
- [ ] Accept local paths.
- [ ] Accept HTTPS Git URLs.
- [ ] Accept SSH-style Git URLs.
- [ ] Clone remote repositories into a temporary directory.
- [ ] Support checking out `--tag`.
- [ ] Record:
- [ ] source URL/path;
- [ ] root path;
- [ ] commit SHA;
- [ ] selected tag.
- [ ] Respect `--keep-workdir`.
- [ ] Never delete a local source project.
### Acceptance criteria
Both work:
```bash
./release.sh ./sample-project --dry-run
```
and:
```bash
./release.sh https://gitea.example.org/user/sample-project.git --dry-run
```
---
## Phase 5 — Cargo project inspection
- [ ] Read `Cargo.toml` with `tomlkit`.
- [ ] Run:
```bash
cargo metadata --format-version=1 --no-deps
```
- [ ] Discover:
- [ ] package name;
- [ ] version;
- [ ] repository URL;
- [ ] binary targets.
- [ ] Detect workspace-only roots.
- [ ] Detect multiple matching packages.
- [ ] Detect multiple binaries.
- [ ] For unsupported ambiguous cases, stop with a clear message instead of guessing.
- [ ] Populate shared dataclasses in `models.py`.
### Acceptance criteria
Dry-run prints a project summary containing:
```text
package
version
repository
binary
commit
tag
```
---
## Phase 6 — Tag/version validation
- [ ] Read `tag-prefix` from config.
- [ ] Generate expected tag from Cargo version.
- [ ] If `--tag` is supplied, require an exact match by default.
- [ ] Fail before build on mismatch.
- [ ] Add unit tests.
### Acceptance criteria
For version `0.3.1`:
```text
expected: v0.3.1
```
and `--tag v0.3.0` fails clearly.
---
## Phase 7 — cargo-binstall metadata policy
- [ ] Centralize artifact naming policy.
- [ ] Centralize archive root-directory naming policy.
- [ ] Centralize expected cargo-binstall metadata.
- [ ] Use:
```text
{name}-{target}-v{version}.tgz
```
- [ ] Use the corresponding directory name inside the archive.
- [ ] Add target-aware binary extension handling.
- [ ] Inspect `[package.metadata.binstall]`.
- [ ] Report:
- [ ] missing section;
- [ ] missing keys;
- [ ] mismatched values.
- [ ] Represent issues as structured objects rather than plain strings.
- [ ] Add unit tests for generated metadata.
### Acceptance criteria
Dry-run can show:
```text
Binstall metadata
missing: package.metadata.binstall
proposed pkg-url: ...
proposed pkg-fmt: tgz
proposed bin-dir: ...
```
without modifying the file.
---
## Phase 8 — Metadata repair
- [ ] Implement `--fix-metadata`.
- [ ] Preserve Cargo.toml formatting/comments with `tomlkit`.
- [ ] Change only the relevant metadata.
- [ ] Print a concise before/after or list of changed keys.
- [ ] Do not commit.
- [ ] Do not push.
- [ ] In dry-run, never write the file even if `--fix-metadata` is present.
- [ ] Add tests using temporary Cargo.toml fixtures.
### Acceptance criteria
Running twice is idempotent:
```bash
./release.sh ./project --fix-metadata
./release.sh ./project --fix-metadata
```
The second run should report no further metadata change.
---
## Phase 9 — Prerequisite validation
- [ ] Check `git`.
- [ ] Check `cargo`.
- [ ] Check `cross`.
- [ ] Check the container backend used by `cross`.
- [ ] Check Cargo.lock expectations if `locked = true`.
- [ ] Report all missing prerequisites together where practical.
- [ ] In dry-run, report status without building.
### Acceptance criteria
Example output:
```text
Tools
✓ git
✓ cargo
✓ cross
✓ docker
```
or a clear grouped error.
---
## Phase 10 — Pre-build verification
- [ ] Run `cargo metadata`.
- [ ] Run a fast project check before cross compiling.
- [ ] Prefer:
```bash
cargo check --locked
```
when locked mode is enabled.
- [ ] Honor `--skip-tests` if test/check behavior expands.
- [ ] Stop before expensive builds if verification fails.
### Acceptance criteria
A broken Rust project fails before `cross build` starts.
---
## Phase 11 — Build implementation
- [ ] Implement `build.py`.
- [ ] Build each configured target using `cross`.
- [ ] Default command:
```bash
cross build --release --locked --target TARGET
```
- [ ] Respect configured profile.
- [ ] Respect locked/unlocked mode.
- [ ] Stream compiler output.
- [ ] Locate the produced binary deterministically.
- [ ] Record build outputs in artifact/build dataclasses.
- [ ] Stop on the first failed target.
- [ ] Print target progress.
### Acceptance criteria
All three default binaries are produced for a compatible sample project.
---
## Phase 12 — Packaging
- [ ] Implement `package.py`.
- [ ] Create or clean a controlled `dist/` directory.
- [ ] For each target:
- [ ] create archive root directory;
- [ ] copy the binary;
- [ ] preserve Unix executable bit;
- [ ] create `.tgz`;
- [ ] remove unnecessary staging content if appropriate.
- [ ] Generate deterministic archive filenames.
- [ ] Generate SHA-256 for each archive.
- [ ] Generate `SHA256SUMS`.
- [ ] Add checksum unit tests.
### Acceptance criteria
Expected result resembles:
```text
dist/
├── 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
└── SHA256SUMS
```
Each archive contains only its expected root directory and binary.
---
## Phase 13 — Gitea client
- [ ] Implement `gitea.py` using `httpx`.
- [ ] Read token from configured environment variable.
- [ ] Never print the token.
- [ ] Parse Gitea base URL and owner/repository safely.
- [ ] Support explicit CLI/config override if repository URL inference is ambiguous.
- [ ] Implement:
- [ ] release lookup by tag;
- [ ] release creation;
- [ ] asset listing;
- [ ] asset upload;
- [ ] asset deletion for replacement mode.
- [ ] Handle HTTP errors with useful messages.
- [ ] Structure API methods so they can be mocked in tests.
### Acceptance criteria
With mocked HTTP responses, tests cover:
- release missing;
- release exists;
- upload success;
- duplicate asset;
- replacement flow;
- authentication failure.
---
## Phase 14 — Release creation/reuse
- [ ] Derive release name from tag.
- [ ] Reuse an existing release with the requested tag.
- [ ] Otherwise create one.
- [ ] Honor:
- [ ] `--draft`
- [ ] `--prerelease`
- [ ] Do not create releases in `--dry-run`.
- [ ] Print the intended release destination during dry-run.
### Acceptance criteria
Repeated publication attempts do not create duplicate releases for the same tag.
---
## Phase 15 — Asset upload and collision behavior
- [ ] Upload all `.tgz` files.
- [ ] Upload `SHA256SUMS`.
- [ ] Before upload, inspect existing asset names.
- [ ] Default on collision: fail.
- [ ] With `--replace-assets`: delete existing matching asset and upload replacement.
- [ ] Never rename duplicates automatically.
- [ ] Print uploaded asset names.
### Acceptance criteria
Running a second time without `--replace-assets` fails safely.
Running with `--replace-assets` replaces exact matching assets only.
---
## Phase 16 — Published artifact verification
- [ ] Implement `verify.py`.
- [ ] Verify each expected published asset can be resolved.
- [ ] Download to a temporary location where practical.
- [ ] Check SHA-256 against local artifact.
- [ ] Open the archive.
- [ ] Verify expected root directory.
- [ ] Verify expected binary filename.
- [ ] Ensure verification never overwrites local project binaries.
### Acceptance criteria
A deliberately malformed or mismatched uploaded archive is detected.
---
## Phase 17 — cargo-binstall verification
- [ ] Verify the cargo-binstall contract after upload.
- [ ] Prefer a temporary install location.
- [ ] Avoid modifying the user’s normal Cargo bin directory.
- [ ] Use the local manifest when appropriate.
- [ ] Verify at least the current host-compatible target automatically.
- [ ] For non-host targets, validate URL/archive structure even if execution is impossible.
- [ ] Honor `--skip-binstall-test`.
### Acceptance criteria
On a supported host, the just-published host-target binary can be installed into a temporary bin directory via cargo-binstall or an equivalent safe verification path.
---
## Phase 18 — `--stop-after`
- [ ] Implement the stage enum.
- [ ] Support:
- [ ] `inspect`
- [ ] `metadata`
- [ ] `verify`
- [ ] `build`
- [ ] `package`
- [ ] `release`
- [ ] `upload`
- [ ] `binstall`
- [ ] Stop successfully immediately after the requested completed stage.
- [ ] Ensure cleanup still runs.
### Acceptance criteria
```bash
./release.sh ./project --stop-after package
```
builds/packages but never contacts Gitea.
---
## Phase 19 — Dry-run completion
- [ ] Confirm `--dry-run` performs no mutation.
- [ ] It must not:
- [ ] edit Cargo.toml;
- [ ] build;
- [ ] create releases;
- [ ] delete assets;
- [ ] upload.
- [ ] It should report:
- [ ] project;
- [ ] version/tag;
- [ ] metadata status;
- [ ] proposed fixes;
- [ ] prerequisite status;
- [ ] build matrix;
- [ ] expected artifact names;
- [ ] expected release destination.
### Acceptance criteria
A dry-run can be used safely against an important repository.
---
## Phase 20 — Documentation
- [ ] Update README with real behavior only.
- [ ] Document installation:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
- [ ] Document wrapper-assisted venv creation.
- [ ] Document prerequisites:
- [ ] Rust/Cargo
- [ ] cross
- [ ] Docker/Podman
- [ ] cargo-binstall for final verification
- [ ] Document Gitea token:
```bash
export GITEA_TOKEN="..."
```
- [ ] Document dry-run.
- [ ] Document metadata repair.
- [ ] Document target list.
- [ ] Document artifact naming.
- [ ] Document known limitations.
---
## Phase 21 — Tests and cleanup
- [ ] Add unit tests for pure logic.
- [ ] Add manifest fixture tests.
- [ ] Add mocked Gitea tests.
- [ ] Ensure no token is printed in tests/logging.
- [ ] Run Python formatting/linting if tooling is added.
- [ ] Run tests.
- [ ] Remove dead code.
- [ ] Ensure no temporary release artifacts are committed unintentionally.
- [ ] Ensure `.venv/` is gitignored.
- [ ] Ensure Python cache files are gitignored.
- [ ] Ensure `dist/` is ignored unless intentionally retained.
Suggested `.gitignore`:
```text
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
dist/
```
---
# Final integration test
Use a real or disposable single-binary Rust project on Gitea.
## Setup
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GITEA_TOKEN="..."
```
## Inspect
```bash
./release.sh \
https://gitea.example.org/owner/tool.git \
--tag v0.1.0 \
--dry-run
```
Confirm:
- [ ] project recognized;
- [ ] tag/version valid;
- [ ] binstall metadata status shown;
- [ ] targets shown;
- [ ] prerequisites shown;
- [ ] no mutation.
## Publish
```bash
./release.sh \
https://gitea.example.org/owner/tool.git \
--tag v0.1.0 \
--fix-metadata
```
Confirm:
- [ ] metadata corrected locally if needed;
- [ ] all target builds succeed;
- [ ] all archives exist;
- [ ] `SHA256SUMS` exists;
- [ ] release exists;
- [ ] assets are attached;
- [ ] published artifacts verify;
- [ ] cargo-binstall verification succeeds for the host-compatible artifact.
---
# Non-goals for this PoC
Do not delay completion for these:
- [ ] automatic Git commits;
- [ ] automatic Git pushes;
- [ ] automatic crate publishing to crates.io;
- [ ] Windows MSVC cross-compilation;
- [ ] macOS artifacts;
- [ ] multi-package workspace orchestration;
- [ ] multiple binary selection UI;
- [ ] artifact signing;
- [ ] release changelog generation;
- [ ] CI integration;
- [ ] parallel cross builds.
These can be follow-up work once the single-package release path is reliable.

View File

@ -1,2 +1,24 @@
# rust_realease
# Rust Binstall Publisher
Small release helper for Rust CLI projects.
Its intended job is to:
1. acquire a Rust project;
2. inspect and validate its Cargo metadata;
3. ensure cargo-binstall metadata is correct;
4. cross-compile supported targets;
5. package release artifacts;
6. create a Gitea release;
7. upload the artifacts;
8. verify that cargo-binstall can install them.
## Setup
The wrapper intentionally refuses to run without an active Python
virtual environment.
Run:
```bash
./release.sh --help

18
config.toml Normal file
View File

@ -0,0 +1,18 @@
[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"

131
release.sh Executable file
View File

@ -0,0 +1,131 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(
cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
pwd
)"
VENV_DIR="${SCRIPT_DIR}/.venv"
REQUIREMENTS="${SCRIPT_DIR}/requirements.txt"
die() {
echo "error: $*" >&2
exit 1
}
setup_venv() {
command -v python3 >/dev/null 2>&1 || \
die "python3 is required to create the virtual environment."
echo
echo "Creating virtual environment:"
echo " ${VENV_DIR}"
echo
python3 -m venv "${VENV_DIR}"
echo "Installing worker dependencies..."
"${VENV_DIR}/bin/python" -m pip install --upgrade pip
"${VENV_DIR}/bin/python" -m pip install -r "${REQUIREMENTS}"
echo
echo "Virtual environment is ready."
echo
echo "Activate it with:"
echo
echo " source .venv/bin/activate"
echo
echo "Then run:"
echo
echo " ./release.sh $*"
echo
exit 0
}
# ---------------------------------------------------------------------------
# Environment guard
# ---------------------------------------------------------------------------
if [[ -z "${VIRTUAL_ENV:-}" ]]; then
echo
echo "rust-binstall-publisher requires an active Python virtual environment."
echo
if [[ -d "${VENV_DIR}" ]]; then
echo "A project virtual environment already exists:"
echo
echo " ${VENV_DIR}"
echo
echo "Activate it first:"
echo
echo " source .venv/bin/activate"
echo
echo "Then rerun this command."
echo
exit 2
fi
echo "No .venv exists yet."
echo
if [[ -t 0 ]]; then
read -r -p "Create and set up .venv now? [Y/n] " answer
case "${answer:-Y}" in
y|Y|yes|YES|"")
setup_venv "$@"
;;
*)
echo
echo "Environment setup cancelled."
echo
echo "Create it manually with:"
echo
echo " python3 -m venv .venv"
echo " source .venv/bin/activate"
echo " pip install -r requirements.txt"
echo
exit 2
;;
esac
fi
die "no virtual environment active and stdin is non-interactive."
fi
# ---------------------------------------------------------------------------
# Extra sanity check:
# ensure we're using the project's environment, not some random venv.
# ---------------------------------------------------------------------------
EXPECTED_VENV="$(cd "${VENV_DIR}" 2>/dev/null && pwd || true)"
ACTIVE_VENV="$(cd "${VIRTUAL_ENV}" 2>/dev/null && pwd || true)"
if [[ -d "${VENV_DIR}" && "${ACTIVE_VENV}" != "${EXPECTED_VENV}" ]]; then
echo
echo "warning: an environment is active, but it is not this project's .venv:"
echo
echo " active: ${VIRTUAL_ENV}"
echo " expected: ${VENV_DIR}"
echo
read -r -p "Continue anyway? [y/N] " answer
case "${answer:-N}" in
y|Y|yes|YES)
;;
*)
exit 2
;;
esac
fi
exec python -m worker "$@"

4
requirements.txt Normal file
View File

@ -0,0 +1,4 @@
tomlkit>=0.13,<1
rich>=14,<15
typer>=0.16,<1
httpx>=0.28,<1

1
worker/__init__.py Normal file
View File

@ -0,0 +1 @@
__version__ = "0.1.0"

5
worker/__main__.py Normal file
View File

@ -0,0 +1,5 @@
from .cli import app
if __name__ == "__main__":
app()

192
worker/cli.py Normal file
View File

@ -0,0 +1,192 @@
from __future__ import annotations
from pathlib import Path
import typer
from rich.console import Console
from rich.table import Table
from . import __version__
from .project import (
acquire_project,
cleanup_project,
)
from .manifest import inspect_project
app = typer.Typer(
no_args_is_help=True,
pretty_exceptions_enable=False,
)
console = Console()
DEFAULT_TARGETS = [
"x86_64-unknown-linux-musl",
"aarch64-unknown-linux-musl",
"x86_64-pc-windows-gnu",
]
@app.command()
def release(
source: str = typer.Argument(
...,
help="Git repository URL or local project path.",
),
tag: str | None = typer.Option(
None,
"--tag",
"-t",
help="Git tag to release.",
),
target: list[str] | None = typer.Option(
None,
"--target",
help="Build target. May be repeated.",
),
dry_run: bool = typer.Option(
False,
"--dry-run",
help="Inspect and plan without changing anything.",
),
keep_workdir: bool = typer.Option(
False,
"--keep-workdir",
help="Keep temporary cloned repositories.",
),
):
targets = target or DEFAULT_TARGETS
console.print(
f"[bold]rust-binstall-publisher[/bold] "
f"[dim]v{__version__}[/dim]"
)
console.print()
project_source = acquire_project(source)
try:
project = inspect_project(
project_source.path
)
table = Table(
title="Project",
show_header=False,
)
table.add_column("Property")
table.add_column("Value")
table.add_row(
"Path",
str(project.root),
)
table.add_row(
"Package",
project.package_name,
)
table.add_row(
"Version",
project.version,
)
table.add_row(
"Repository",
project.repository or "[red]missing[/red]",
)
table.add_row(
"Binary",
", ".join(project.binaries),
)
table.add_row(
"Commit",
project.commit or "unknown",
)
if tag:
table.add_row(
"Requested tag",
tag,
)
console.print(table)
console.print()
target_table = Table(
title="Planned build matrix"
)
target_table.add_column("Target")
target_table.add_column("Artifact")
for triple in targets:
suffix = ".exe" if "windows" in triple else ""
binary = project.binaries[0]
target_table.add_row(
triple,
f"{binary}{suffix}",
)
console.print(target_table)
console.print()
if len(project.binaries) != 1:
console.print(
"[yellow]warning:[/yellow] "
"multiple binaries are not fully supported yet."
)
if project.repository is None:
console.print(
"[red]error:[/red] "
"package.repository is required for release publishing."
)
raise typer.Exit(1)
if tag:
expected = f"v{project.version}"
if tag != expected:
console.print(
f"[red]error:[/red] "
f"tag {tag!r} does not match "
f"package version {project.version!r} "
f"(expected {expected!r})."
)
raise typer.Exit(1)
console.print()
if dry_run:
console.print(
"[cyan]DRY RUN[/cyan] — "
"no files changed, built, or uploaded."
)
else:
console.print(
"[yellow]Release execution is not implemented yet.[/yellow]"
)
finally:
if project_source.temporary:
if keep_workdir:
console.print(
f"\nTemporary workdir kept at "
f"[bold]{project_source.path}[/bold]"
)
else:
cleanup_project(project_source)

108
worker/manifest.py Normal file
View File

@ -0,0 +1,108 @@
from __future__ import annotations
import json
from pathlib import Path
import tomlkit
from .models import RustProject
from .runner import run
def inspect_project(root: Path) -> RustProject:
manifest_path = root / "Cargo.toml"
if not manifest_path.exists():
raise RuntimeError(
f"Cargo.toml not found: {manifest_path}"
)
raw = manifest_path.read_text(
encoding="utf-8"
)
document = tomlkit.parse(raw)
package = document.get("package")
if package is None:
raise RuntimeError(
"workspace-only Cargo.toml is not supported yet"
)
name = package.get("name")
version = package.get("version")
if not name:
raise RuntimeError(
"package.name is missing"
)
if not version:
raise RuntimeError(
"package.version is missing"
)
repository = package.get("repository")
metadata_raw = run(
"cargo",
"metadata",
"--format-version",
"1",
"--no-deps",
cwd=root,
)
metadata = json.loads(metadata_raw)
packages = metadata.get("packages", [])
matching = [
pkg
for pkg in packages
if pkg["name"] == name
]
if len(matching) != 1:
raise RuntimeError(
f"could not uniquely identify package {name!r}"
)
cargo_package = matching[0]
binaries = [
target["name"]
for target in cargo_package["targets"]
if "bin" in target["kind"]
]
if not binaries:
raise RuntimeError(
"package contains no binary targets"
)
commit = None
try:
commit = run(
"git",
"rev-parse",
"HEAD",
cwd=root,
)
except Exception:
pass
return RustProject(
root=root,
manifest=manifest_path,
package_name=name,
version=str(version),
repository=str(repository)
if repository
else None,
binaries=binaries,
commit=commit,
)

34
worker/models.py Normal file
View File

@ -0,0 +1,34 @@
from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path
@dataclass(slots=True)
class RustProject:
root: Path
manifest: Path
package_name: str
version: str
repository: str | None = None
binaries: list[str] = field(default_factory=list)
commit: str | None = None
tag: str | None = None
@dataclass(slots=True)
class BuildTarget:
triple: str
@property
def is_windows(self) -> bool:
return "windows" in self.triple
def binary_filename(self, binary: str) -> str:
if self.is_windows:
return f"{binary}.exe"
return binary

44
worker/runner.py Normal file
View File

@ -0,0 +1,44 @@
from __future__ import annotations
import subprocess
from pathlib import Path
from rich.console import Console
console = Console()
class CommandError(RuntimeError):
pass
def run(
*args: str,
cwd: Path | None = None,
capture: bool = True,
) -> str:
console.print(
"[dim]$ " + " ".join(args) + "[/dim]"
)
proc = subprocess.run(
args,
cwd=cwd,
text=True,
stdout=subprocess.PIPE if capture else None,
stderr=subprocess.PIPE if capture else None,
)
if proc.returncode != 0:
stderr = proc.stderr.strip() if proc.stderr else ""
raise CommandError(
f"command failed ({proc.returncode}): "
f"{' '.join(args)}\n{stderr}"
)
if not capture:
return ""
return proc.stdout.strip()