rust_realease/AGENT_TASKS.md

14 KiB
Raw Blame History

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_ENV is set.
  • If .venv exists but is not active, refuse and print:
    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:
    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

./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.toml with tomlkit.
  • 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-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:

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-metadata is 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:
    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:
    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.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

./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:
    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;
  • 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.