rust_realease/AGENT_TASKS.md

24 KiB

AGENT_TASKS.md

Goal

Migrate rust_realease from its current Python implementation to a native Rust CLI without regressing release behavior.

The Python implementation remains the behavioral oracle until the Rust replacement passes parity and end-to-end release validation.

Updated product goals (2026-09-17)

  • Keep useful local unit and fixture tests throughout the rewrite.
  • Accept a project and eventually produce either local artifacts or a remote release.
  • Support local and remote project repair before building. An explicitly requested repair workflow may create an additional fix commit, tag, and push; ordinary release runs retain the existing mutation boundaries until that workflow is implemented and tested.
  • Defer live API release tests until a disposable token is provided.
  • Use the small target_test_project submodule for fast build and cross-target experiments.

Current Rust milestone: inspection, metadata, preparation, host verification, Cross build, packaging, Gitea publication, anonymous downloads, and isolated cargo-binstall orchestration are implemented. Gitea paths pass local HTTP mock tests; live publication and real cargo-binstall installation still need a disposable token. Preparation has disposable Git tests for dry-run, commit, tag safety, and destination refusal; atomic push still needs an isolated integration test. The tiny fixture built and packaged all three default targets locally.

Progress tracking: check a task only when the Rust behavior is implemented and locally verified. Keep phase gates open until their full fixture/parity criteria pass. The Python baseline has 45 passing tests and two opt-in tests skipped. CI runs Cargo tests only; Cross and live Gitea tests are deferred. Next work: isolated preparation-push test, broader parity fixtures, and offline publication edge cases.

Parity note: Python and Rust target_test_project --dry-run --stop-after verify both report the missing local release tag and exit nonzero. The Rust dry run now reports this as a prerequisite without creating a tag. Python and Rust metadata-stage runs both succeed on the fixture. Output formatting differs; full fixture parity remains open.

Run the repeatable local smoke comparison with .venv/bin/python tests/parity_smoke.py. It builds the Rust binary and compares inspect/metadata fields on the tiny fixture; when the fixture tag is absent, it also checks that both dry runs reject it. The full fixture matrix is still pending.

Work in small, testable phases. Commit migration work in coherent increments.


Migration rules

  • Do not delete the Python implementation before Rust parity is proven.
  • Do not change release semantics merely to simplify the port.
  • Keep mutation operations opt-in.
  • Preserve artifact names/layouts and cargo-binstall metadata.
  • Preserve workspace --package NAME behavior.
  • Preserve repository preparation behavior.
  • Preserve fresh build target directories.
  • Preserve Gitea asset collision/replacement semantics.
  • Preserve token redaction and secret isolation.
  • Treat live release operations as opt-in integration tests.
  • Record intentional incompatibilities in this file and README.

Phase 0 — Freeze and characterize the Python behavior

Inventory

  • Record the current CLI flags and defaults from the Python implementation.
  • Record the config schema/defaults.
  • Record stage ordering and --stop-after behavior.
  • Record workspace/package-selection behavior.
  • Record preparation flag dependency rules.
  • Record artifact naming and archive layout.
  • Record Gitea release and asset-collision semantics.
  • Record verification behavior.
  • Record token handling and redaction rules.

Baseline test run

  • Run the existing Python unit/mocked test suite.
  • Run existing opt-in cargo-binstall tests where the environment permits.
  • Save representative dry-run outputs for fixtures.
  • Save representative metadata-repair diffs.
  • Save representative preparation diffs.
  • Save representative archive listings and SHA256SUMS.

Compatibility fixtures

Create or preserve fixtures for:

  • standalone single-binary package;
  • workspace with an explicitly selected CLI package;
  • inherited workspace version/repository;
  • ambiguous workspace;
  • unknown package;
  • library-only package;
  • selected package with multiple binaries;
  • missing Cargo.lock;
  • missing binstall metadata;
  • conflicting binstall metadata;
  • custom/empty tag prefix;
  • existing release asset collision.

Gate

  • Existing behavior is sufficiently characterized that a Rust result can be compared against it.

Phase 1 — Create the Rust application skeleton

  • Add Cargo.toml.
  • Add Cargo.lock.
  • Add src/main.rs.
  • Add modules:
    • cli.rs
    • config.rs
    • error.rs
    • model.rs
    • runner.rs
    • project.rs
    • manifest.rs
    • prepare.rs
    • build.rs
    • package.rs
    • gitea.rs
    • verify.rs
  • Add test fixture directory.
  • Add cargo fmt --check gate.
  • Add strict Clippy gate.
  • Add cargo test --all gate.

Suggested dependencies:

  • clap
  • serde
  • toml
  • toml_edit
  • thiserror
  • reqwest with rustls
  • url
  • tempfile
  • sha2
  • tar
  • flate2

Test-only as useful:

  • assert_cmd
  • predicates
  • mock HTTP server crate

Gate

  • Rust binary builds.
  • --help works.
  • No release behavior has been removed from Python yet.

Phase 2 — Port models, config, and pure policy

Models

  • Define selected package model.
  • Define target/artifact model.
  • Define release destination model.
  • Define preparation plan model.
  • Define stage enum.
  • Define config model.

Configuration

  • Parse current config.toml.
  • Preserve defaults.
  • Implement CLI-over-config precedence.
  • Support custom config path.
  • Validate target/profile/package format settings.

Pure policy

  • Implement expected tag generation.
  • Implement empty/custom tag prefix.
  • Implement archive naming.
  • Implement archive root naming.
  • Implement target-specific binary filename.
  • Implement expected binstall metadata.
  • Implement release URL construction.
  • Implement stage ordering.

Tests

  • Port pure Python tests to Rust.
  • Add tests for non-v tags.
  • Add tests for Windows .exe.
  • Add tests for malformed config.
  • Add tests for CLI precedence.

Gate

  • Rust pure-policy outputs match Python for the fixture matrix.

Phase 3 — Port command execution and redaction

Runner

  • Implement argv-based subprocess runner.
  • Support cwd.
  • Support env additions/removals.
  • Support captured output.
  • Support streaming where useful.
  • Add verbose diagnostics.
  • Add exit-code/error context.

Secret safety

  • Redact GITEA_TOKEN.
  • Redact configured token env variable.
  • Redact credentials in URLs.
  • Ensure child Cargo/Cross build processes do not inherit Gitea token.
  • Test error messages for token leakage.

Gate

  • All runner tests pass.
  • No shell-string execution is used for normal commands.

Phase 4 — Port source acquisition and Git behavior

Local source

  • Accept local paths.
  • Resolve workspace root safely.
  • Never delete/move local source.
  • Read Git origin.
  • Inspect worktree cleanliness.
  • Resolve HEAD commit.

Remote source

  • Accept HTTP/HTTPS Git URLs.
  • Accept SSH URLs.
  • Accept SCP-style URLs.
  • Clone to temporary directory.
  • Checkout requested tag exactly.
  • Implement default cleanup.
  • Implement --keep-workdir.
  • Preserve preparation-mode retained checkout behavior.

Repository URL normalization

  • Normalize .git suffix.
  • Convert supported SSH/SCP repository identity to web/API identity safely.
  • Reject URLs with embedded HTTP credentials for release metadata.
  • Reject query strings where existing behavior does.
  • Support explicit --repository-url.

Tests

  • Port repository URL parsing tests.
  • Test temp cleanup.
  • Test keep-workdir.
  • Test local source remains untouched.
  • Test exact tag checkout.

Gate

  • Fixture acquisition behavior matches Python.

Phase 5 — Port Cargo metadata and package selection

Metadata

  • Execute cargo metadata --format-version=1 --no-deps.
  • Parse package/workspace information.
  • Resolve workspace root.
  • Resolve selected member manifest.
  • Resolve target directory.
  • Resolve inherited package version.
  • Resolve inherited repository.

Selection

  • Standalone package works without --package.
  • Multi-member workspace requires exact package selection when ambiguous.
  • --package NAME selects exact package.
  • Unknown package fails clearly.
  • Library-only package fails clearly.
  • Multi-binary selected package fails clearly.
  • Exactly one binary is accepted.

Tests

  • Port all workspace regression tests.
  • Include unrelated failing workspace member fixture.
  • Ensure selecting the intended package does not build/check unrelated member unnecessarily.

Gate

  • Rust selection decisions match Python for all compatibility fixtures.

Phase 6 — Port manifest validation and repair

Reading/editing

  • Read selected Cargo.toml with toml_edit.
  • Detect missing/incorrect package.repository.
  • Derive repository from Git origin where safe.
  • Validate [package.metadata.binstall].
  • Detect unsupported/conflicting custom binstall options.

Repair

  • Implement proposed-change plan.
  • Implement --fix-metadata.
  • Preserve comments/formatting where practical.
  • Edit only selected package manifest.
  • Make repair idempotent.
  • Report every changed key.

Dry-run

  • Print proposed diff.
  • Never write.

Tests

  • Port metadata validation tests.
  • Port repair tests.
  • Add idempotency test.
  • Add workspace member-only edit test.
  • Add inherited workspace version/repository cases.

Gate

  • Generated metadata matches current release contract.
  • Python and Rust proposed repairs are equivalent for fixtures.

Phase 7 — Port version/tag validation

  • Compute expected tag from selected package version.
  • Apply configured/CLI tag prefix.
  • Validate explicit --tag.
  • Validate local tag points to HEAD where required.
  • Validate remote tag exists and points to expected commit before publication.
  • Preserve preparation-mode distinction: intended tag naming without checking out an existing tag.
  • Never move an existing tag.
  • Never rewrite Cargo package version.

Tests

  • Matching tag.
  • Mismatched tag.
  • Empty prefix.
  • Existing tag at wrong commit.
  • Preparation with intended new tag.
  • Ordinary publication without matching tag.

Gate

  • Tag policy matches Python behavior.

Phase 8 — Port repository preparation

Planning

  • Implement preparation plan/diff.
  • Repair selected Cargo metadata.
  • Add build/artifact ignore entries.
  • Add Cargo.lock inclusion rule as required.
  • Generate Cargo.lock when missing.
  • Preserve existing lockfile.
  • Edit/create Cross.toml.
  • Preserve unrelated Cross.toml settings.
  • Support --cross-image-tag.

Mutation boundaries

  • --prepare-repo alone never commits/tags/pushes.
  • --commit-preparation requires correct clean state.
  • Stage only files belonging to the preparation.
  • Preserve user's Git signing configuration.
  • --create-tag requires commit-preparation workflow as currently specified.
  • Create annotated release tag.
  • Existing correct tag is validated, not moved.
  • --push-preparation requires required predecessor flags.
  • Verify push destination matches release repository.
  • Push branch + tag atomically where current behavior expects it.
  • Never force push.

Dry-run

  • Show file diffs.
  • Show lockfile-generation intention.
  • Show Git commit/tag/push intention.
  • Perform none of them.

Tests

  • Clean preparation.
  • Dirty-worktree refusal.
  • Existing tag safety.
  • Destination mismatch refusal.
  • No implicit Git writes.
  • Cross.toml preservation.
  • Missing lockfile.
  • Existing lockfile.

Gate

  • Rust preparation behavior matches Python fixtures.
  • Disposable repo preparation produces a clean, reviewable result.

Phase 9 — Port prerequisite checks

  • Detect git.
  • Detect cargo.
  • Detect cross.
  • Detect Docker.
  • Detect Podman.
  • Honor CROSS_CONTAINER_ENGINE.
  • Determine usable container backend.
  • Detect cargo-binstall when needed.
  • Report all missing prerequisites before cross build.
  • Dry-run performs only read-only checks.

Gate

  • Failure messages are concise and actionable.

Phase 10 — Port check/test/build pipeline

Host validation

  • Run cargo check for selected package.
  • Run cargo test for selected package.
  • Respect --skip-tests.
  • Preserve selected workspace package scoping.

Cross build

  • Build default Linux x86_64 musl.
  • Build default Linux aarch64 musl.
  • Build default Windows GNU x86_64.
  • Respect repeatable --target.
  • Respect profile.
  • Respect locked/unlocked behavior.
  • Pass selected workspace package correctly.
  • Use fresh target subdirectory for every real release build.
  • Preserve cross image configuration behavior.
  • Do not pass Gitea token to build subprocesses.

Tests

  • Command-construction unit tests.
  • Fake-runner orchestration tests.
  • Real host Cargo fixture test.
  • Real Cross tests behind opt-in environment gate.

Gate

  • Default target matrix builds the known integration fixture in the supported environment.
  • Fresh target directory regression is covered.

Phase 11 — Port packaging and checksums

Packaging

  • Locate built binary.
  • Apply target-specific executable filename.
  • Create standardized archive root.
  • Preserve Unix executable mode.
  • Create .tgz.
  • Exclude unrelated files.
  • Validate archive members against traversal paths.

Checksums

  • Compute SHA-256.
  • Generate deterministic SHA256SUMS.
  • Keep stable asset ordering.

Reproducibility

  • Normalize archive metadata where safe.
  • Document any intentional difference from Python archive bytes.
  • Keep naming/layout identical regardless.

Tests

  • Archive filename.
  • Archive root.
  • Unix binary mode.
  • Windows .exe.
  • SHA-256 generation.
  • SHA256SUMS content.
  • No extra files.
  • Traversal/path safety.

Gate

  • Python and Rust package contracts match for all three default targets.

Phase 12 — Port Gitea API client

Client

  • Parse base instance/repository coordinates.
  • Load token only from configured environment variable.
  • Use HTTPS for authenticated publication.
  • Set useful user-agent.
  • Implement contextual API errors.

Releases

  • Get remote tag.
  • Get release by tag.
  • Create release.
  • Reuse existing release.
  • Preserve draft/prerelease fields.

Assets

  • List release assets once according to current Gitea API behavior.
  • Do not reintroduce the historical repeated pagination bug.
  • Upload assets.
  • Fail on duplicate filename by default.
  • Delete/replace only under --replace-assets.
  • Never touch unrelated assets.

Tests

  • Mock release absence -> create.
  • Mock existing release -> reuse.
  • Asset listing regression test.
  • Collision refusal.
  • Explicit replacement.
  • HTTP failure context.
  • Token redaction.

Gate

  • Mocked Gitea behavior matches Python.

Phase 13 — Port verification

Artifact verification

  • Build expected asset URLs.
  • Download published archives.
  • Prefer anonymous downloads for public assets.
  • Validate SHA256SUMS.
  • Validate archive root.
  • Validate binary filename.
  • Validate Unix executable bit where meaningful.

cargo-binstall

  • Use selected package manifest.
  • Create temporary Cargo home/install root.
  • Install without touching user's normal Cargo bin.
  • Verify all default target contracts where supported.
  • Respect --skip-binstall-test.

Tests

  • Local/mock HTTP asset server integration.
  • Real cargo-binstall integration fixture.
  • Check all three default target artifact layouts.

Gate

  • Existing opt-in cargo-binstall integration test has a Rust equivalent and passes.

Phase 14 — Port orchestration, stages, and dry-run

Pipeline

  • Recreate stage ordering.
  • Implement --stop-after.
  • Ensure each stage stops after successful completion.
  • Preserve preparation as a separate workflow from ordinary publication.

Dry-run

Verify no mutation:

  • no file edits;
  • no lock generation;
  • no compile;
  • no commit;
  • no tag creation;
  • no push;
  • no release creation;
  • no asset upload;
  • no asset deletion.

Verify useful reporting:

  • selected package;
  • version;
  • tag;
  • proposed metadata repair;
  • prerequisites;
  • target matrix;
  • artifact names;
  • destination;
  • planned preparation/Git operations.

Tests

  • Every stop boundary.
  • Dry-run mutation guards.
  • Error propagation.
  • Verbose/non-verbose behavior.

Gate

  • Pipeline tests match Python stage semantics.

Phase 15 — Build a Python-vs-Rust parity harness

Create a migration-only harness/script or test utility.

For each non-mutating fixture:

  • run Python implementation;
  • run Rust implementation;
  • normalize nondeterministic temp paths;
  • compare success/failure;
  • compare selected package;
  • compare version/tag;
  • compare metadata findings;
  • compare planned targets;
  • compare artifact names;
  • compare release destination.

For repair/preparation fixtures:

  • run each in separate disposable copies;
  • compare meaningful TOML values;
  • compare changed-file set;
  • compare generated lockfile presence;
  • compare Cross.toml semantics;
  • compare Git operations planned.

For packaging:

  • compare asset names;
  • compare archive member paths;
  • compare binary names/modes;
  • compare checksum correctness.

Gate

  • No unexplained parity differences remain.

Phase 16 — Real disposable repository validation

Use a repository specifically safe for integration testing.

Preparation

  • Rust tool inspects it successfully.
  • Dry-run is correct.
  • Rust preparation succeeds.
  • Commit creation works when explicitly authorized.
  • Annotated tag creation works when explicitly authorized.
  • Atomic push works when explicitly authorized.

Build/package

  • Cargo check passes.
  • Cargo tests pass.
  • All default cross builds pass.
  • Archives are produced.
  • SHA256SUMS is correct.

Publication

  • Matching remote tag is validated.
  • Release is created or reused.
  • All assets upload.
  • Anonymous downloads work.
  • Checksums/layouts verify.
  • cargo-binstall installs from the live release into a temporary location.

Safety

  • No unrelated repo files modified.
  • No unrelated release assets touched.
  • No token appears in logs.
  • No force push.
  • No tag movement.

Gate

  • One complete real Rust-driven release succeeds end to end.

Phase 17 — Cut over the entry point

Only after the prior gates pass:

  • Make the Rust executable the documented/default tool.
  • If release.sh remains, make it a thin compatibility launcher only.
  • Remove venv checks from the active workflow.
  • Remove requirements.txt from required setup.
  • Remove Python package installation from README.
  • Update examples to invoke the Rust binary.
  • Update CI/Jenkins to build/test Rust.
  • Add release/install instructions for this tool itself if desired.

Gate

  • A clean machine with Rust/runtime prerequisites but no Python environment can use the tool.

Phase 18 — Remove the Python implementation

Do this last.

  • Confirm no README command references Python worker.
  • Confirm no CI job requires Python worker.
  • Confirm no fixture/test depends solely on Python code.
  • Preserve useful behavioral tests in Rust.
  • Delete worker/.
  • Delete Python-only test code.
  • Delete requirements.txt.
  • Simplify/remove obsolete venv release.sh logic.
  • Remove parity harness if it has no long-term value.
  • Keep migration rationale in Git history / docs as appropriate.

Gate

  • git grep finds no accidental active Python-runtime dependency.
  • Rust test suite still passes.

Phase 19 — Final quality pass

Run:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all

Also run the opt-in integration matrix available in the environment.

Check:

  • no normal-path unwrap()/expect() on external/user input;
  • no secret leaks;
  • no shell interpolation hazards;
  • archive path safety;
  • helpful errors;
  • README reflects reality;
  • AGENTS.md reflects final architecture;
  • obsolete migration notes are clearly historical rather than active instructions.

Final definition of done

  • Native Rust CLI replaces Python worker.
  • No venv is required.
  • Existing supported flags/config semantics are preserved.
  • Workspace --package behavior is preserved.
  • Metadata validation/repair is preserved.
  • Preparation + explicit commit/tag/push is preserved.
  • Tag safety is preserved.
  • Fresh-target build behavior is preserved.
  • Default three-target cross build is preserved.
  • .tgz naming/layout is preserved.
  • SHA256SUMS is preserved.
  • Gitea release creation/reuse works.
  • Asset collision/refusal/replacement behavior is preserved.
  • Asset-list pagination regression remains fixed.
  • Anonymous artifact validation works.
  • Real isolated cargo-binstall verification works.
  • Token security/redaction passes.
  • Rust formatting, Clippy, unit, mocked, and integration tests pass.
  • At least one live disposable end-to-end Rust release has succeeded.
  • Python runtime/dependencies are removable with no feature regression.

Historical compatibility notes worth preserving during the rewrite

These are not new tasks; they are reminders of bugs/edge cases already discovered in real use:

  • A previous release-assets implementation incorrectly paginated an endpoint that returned the full attachment list, causing repeated nonempty results. Preserve the regression test.
  • Reused Cargo target directories caused stale build-script Git revision metadata to leak into release binaries. Preserve fresh release target directories.
  • Cross builds may require target-compatible native libraries; do not mask failures such as missing target SQLite.
  • Some repositories use inherited workspace metadata. Use Cargo's resolved package information while editing only the selected member manifest.
  • Existing tags must never be silently moved.
  • Release asset replacement must remain explicitly authorized.