rust_realease/AGENT_TASKS.md

630 lines
14 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_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.