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_projectsubmodule 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 NAMEbehavior. - 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-afterbehavior. - 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.rsconfig.rserror.rsmodel.rsrunner.rsproject.rsmanifest.rsprepare.rsbuild.rspackage.rsgitea.rsverify.rs
- Add test fixture directory.
- Add
cargo fmt --checkgate. - Add strict Clippy gate.
- Add
cargo test --allgate.
Suggested dependencies:
clapserdetomltoml_editthiserrorreqwestwith rustlsurltempfilesha2tarflate2
Test-only as useful:
assert_cmdpredicates- mock HTTP server crate
Gate
- Rust binary builds.
--helpworks.- 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-
vtags. - 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
.gitsuffix. - 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 NAMEselects 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.tomlwithtoml_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-repoalone never commits/tags/pushes.--commit-preparationrequires correct clean state.- Stage only files belonging to the preparation.
- Preserve user's Git signing configuration.
--create-tagrequires commit-preparation workflow as currently specified.- Create annotated release tag.
- Existing correct tag is validated, not moved.
--push-preparationrequires 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-binstallwhen 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 checkfor selected package. - Run
cargo testfor 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.shremains, make it a thin compatibility launcher only. - Remove venv checks from the active workflow.
- Remove
requirements.txtfrom 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.shlogic. - Remove parity harness if it has no long-term value.
- Keep migration rationale in Git history / docs as appropriate.
Gate
git grepfinds 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.mdreflects 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
--packagebehavior 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.
.tgznaming/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.