23 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.
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.