14 KiB
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
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_ENVis set. - If
.venvexists but is not active, refuse and print:source .venv/bin/activate - If
.venvdoes 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.
- run
- 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:
exec python -m worker "$@"
Acceptance criteria
Test all four cases:
- no venv, no
.venv; - no venv,
.venvexists; - wrong venv active;
- project
.venvactive.
Phase 2 — CLI and configuration
- Implement a Typer CLI without a redundant mandatory
releasesubcommand. - 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
./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:
./release.sh ./sample-project --dry-run
and:
./release.sh https://gitea.example.org/user/sample-project.git --dry-run
Phase 5 — Cargo project inspection
- Read
Cargo.tomlwithtomlkit. - Run:
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:
package
version
repository
binary
commit
tag
Phase 6 — Tag/version validation
- Read
tag-prefixfrom config. - Generate expected tag from Cargo version.
- If
--tagis supplied, require an exact match by default. - Fail before build on mismatch.
- Add unit tests.
Acceptance criteria
For version 0.3.1:
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:
{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:
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-metadatais present. - Add tests using temporary Cargo.toml fixtures.
Acceptance criteria
Running twice is idempotent:
./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:
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:
when locked mode is enabled.cargo check --locked - Honor
--skip-testsif 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:
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:
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.pyusinghttpx. - 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
.tgzfiles. - 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:
inspectmetadataverifybuildpackagereleaseuploadbinstall
- Stop successfully immediately after the requested completed stage.
- Ensure cleanup still runs.
Acceptance criteria
./release.sh ./project --stop-after package
builds/packages but never contacts Gitea.
Phase 19 — Dry-run completion
- Confirm
--dry-runperforms 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:
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:
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:
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
dist/
Final integration test
Use a real or disposable single-binary Rust project on Gitea.
Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export GITEA_TOKEN="..."
Inspect
./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
./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;
SHA256SUMSexists;- 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.