630 lines
14 KiB
Markdown
630 lines
14 KiB
Markdown
# 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.
|
||
|