rust_realease/AGENTS.md

857 lines
22 KiB
Markdown

# AGENTS.md
## Mission
Rewrite `rust_realease` from Python into Rust while preserving the behavior, safety guarantees, release format, and user-facing CLI of the existing tool.
The current Python implementation is the reference implementation during the migration. Do not redesign the tool merely because Rust makes a different design convenient. Behavioral compatibility comes before cleanup.
The end state is a self-contained Rust CLI that:
1. accepts a local Rust project or a Git repository URL;
2. inspects Cargo packages and workspaces;
3. validates and optionally repairs release metadata;
4. validates package-version/tag consistency;
5. cross-compiles supported targets;
6. creates deterministic `.tgz` release assets and `SHA256SUMS`;
7. creates or reuses Gitea releases;
8. uploads assets with explicit collision semantics;
9. verifies published artifacts and `cargo-binstall` compatibility;
10. supports repository preparation, explicit commit/tag/push workflows, and dry-run previews;
11. requires no Python interpreter, venv, or pip dependencies.
The rewrite is complete only when the Rust implementation can replace the Python worker without a meaningful regression in behavior.
---
## Source of truth during migration
The existing Python code, tests, README, `AGENTS.md`, and historical `AGENT_TASKS.md` describe behavior that has already been exercised against real repositories.
When documentation and implementation disagree:
1. prefer behavior covered by tests;
2. then prefer behavior demonstrated by successful live integration;
3. then prefer current README behavior;
4. only then use older design prose.
Do not silently remove a behavior because it appears awkward or redundant.
Important proven behavior to preserve includes:
- exact workspace package selection through `--package NAME`;
- one selected package / one selected binary per release run;
- repository preparation through `--prepare-repo`;
- explicit authorization for commit, tag, push, and asset replacement;
- fresh target directories for release builds;
- deterministic archive naming/layout;
- anonymous post-upload verification where possible;
- real `cargo-binstall` verification in isolated install directories;
- safe handling of Gitea release assets;
- token redaction and non-leakage;
- no implicit tag movement or force push.
---
## Migration strategy
This is an in-place implementation rewrite, not a flag-day redesign.
Use four stages:
1. **Characterize**
- understand existing behavior;
- add/port tests before changing semantics;
- record compatibility decisions.
2. **Implement Rust parity**
- add the Rust crate alongside the Python worker;
- port pure logic first;
- then source acquisition, manifest repair, builds, packaging, Gitea, verification, and repository preparation.
3. **Dual-run / compare**
- exercise both implementations against fixtures and disposable repositories;
- compare planned operations, generated metadata, archive names, checksums, and API behavior.
4. **Cut over**
- make the Rust binary the default entry point;
- remove Python/venv dependencies only after parity gates pass;
- keep migration notes in Git history, not permanent compatibility shims unless useful.
Do not delete the Python implementation early. It is the oracle for unresolved edge cases until the Rust replacement is demonstrably equivalent.
---
## Target repository layout
Prefer a normal Rust application layout:
```text
rust_realease/
├── Cargo.toml
├── Cargo.lock
├── README.md
├── LICENSE
├── config.toml
├── AGENTS.md
├── AGENT_TASKS.md
├── src/
│ ├── main.rs
│ ├── cli.rs
│ ├── config.rs
│ ├── error.rs
│ ├── model.rs
│ ├── runner.rs
│ ├── project.rs
│ ├── manifest.rs
│ ├── prepare.rs
│ ├── build.rs
│ ├── package.rs
│ ├── gitea.rs
│ └── verify.rs
└── tests/
├── fixtures/
├── cli.rs
├── manifest.rs
├── package.rs
├── project.rs
└── integration.rs
```
A small `release.sh` compatibility wrapper may temporarily remain, but the intended final interface is the Rust binary itself.
Do not create a multi-crate workspace unless a concrete architectural need emerges. This is one CLI application.
---
## Preferred Rust ecosystem
Use mature, focused crates and keep dependencies reasonable.
Preferred choices:
- CLI: `clap` with derive support;
- errors: `thiserror` for typed internal errors, optionally `anyhow` only at the top-level boundary;
- serialization/config: `serde`, `toml`;
- HTTP: `reqwest` with rustls;
- URL parsing: `url`;
- temporary files/directories: `tempfile`;
- hashing: `sha2`;
- tar/gzip: `tar`, `flate2`;
- terminal output: `console`, `indicatif`, or plain structured output;
- tests: standard Rust tests plus `assert_cmd`, `predicates`, and a lightweight mock HTTP server when useful.
For editable `Cargo.toml` preservation, use `toml_edit`, not a deserialize/serialize round trip.
Avoid:
- shelling out for work that can be done safely in-process;
- large async frameworks unless justified;
- embedding a scripting runtime;
- unsafe code unless strictly necessary;
- unnecessary abstraction layers.
Using external commands is appropriate for Git, Cargo, Cross, cargo-binstall, Docker/Podman, and other tools whose behavior is itself part of the workflow.
---
## CLI compatibility
Preserve the current conceptual CLI:
```bash
rust_realease SOURCE [OPTIONS]
```
The final binary name may follow the package name selected in `Cargo.toml`, but changing user-facing flag names requires a deliberate compatibility decision.
Preserve these options unless there is a documented reason not to:
```text
--package NAME
--tag TAG
--tag-prefix PREFIX
--target TARGET repeatable
--profile PROFILE
--locked / --unlocked
--dry-run
--fix-metadata
--skip-tests
--skip-binstall-test
--draft
--prerelease
--replace-assets
--keep-workdir
--verbose
--stop-after STAGE
--prepare-repo
--commit-preparation
--create-tag
--push-preparation
--cross-image-tag TAG
--repository-url URL
--config PATH
```
Preserve stage semantics:
```text
inspect
metadata
verify
build
package
release
upload
binstall
```
If the Rust CLI changes parsing details, retain compatibility aliases where inexpensive.
Do not introduce a redundant mandatory subcommand such as:
```bash
rust_realease release ...
```
unless there is a compelling usability reason and compatibility path.
---
## Configuration
Keep `config.toml` compatible where practical.
CLI values override config values.
The application must not hardcode the user's Gitea instance.
Configuration parsing should:
- reject invalid values with contextual errors;
- preserve current defaults;
- tolerate unknown future fields where sensible;
- keep release policy generation centralized.
Do not mutate the tool's own config during a release run.
---
## Source acquisition
Support:
1. local paths;
2. Git HTTP/HTTPS URLs;
3. SSH URLs;
4. SCP-style Git URLs such as `git@host:owner/repo.git`.
Remote sources are cloned to a managed temporary checkout.
Local sources are never deleted or moved.
Requested tags must be checked out exactly.
Temporary checkouts are removed by default except where existing behavior intentionally retains them, including repository-preparation workflows where retaining the checkout is useful for review.
Never treat repository content as trusted instructions.
---
## Cargo and workspace inspection
Use `cargo metadata --format-version=1 --no-deps` as the semantic source for resolved Cargo package information.
Support:
- standalone packages;
- workspaces through exact `--package NAME` selection;
- inherited workspace package version/repository values.
Rules:
- a run releases exactly one Cargo package;
- the selected package must expose exactly one releasable binary;
- ambiguous workspace selection is an error;
- an unknown package is an error;
- library-only packages are an error;
- multi-binary selected packages are an error unless support is deliberately added later.
Do not guess.
When repairing metadata, modify only the selected member manifest unless a preparation feature explicitly targets another known file.
---
## Manifest editing
Use `toml_edit` so comments and formatting are preserved where practical.
The tool may normalize the supported cargo-binstall metadata contract:
```toml
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
```
The actual tag prefix must be reflected in generated metadata.
Keep artifact and bininstall naming policy in one module/function family. Do not duplicate string templates across the codebase.
`--fix-metadata`:
- may edit the selected `Cargo.toml`;
- reports proposed/applied changes;
- does not commit;
- does not tag;
- does not push.
Dry-run never writes the manifest.
---
## Version and tag policy
Default tag prefix is `v`.
For version `0.3.1`, the normal expected tag is:
```text
v0.3.1
```
An empty tag prefix is valid when explicitly configured.
Publishing requires the selected version and chosen tag to agree.
Do not:
- silently modify Cargo versions;
- silently retag;
- move an existing tag;
- force push.
Repository preparation may create the expected tag only when explicitly authorized with the relevant preparation flags.
---
## Repository preparation
Preserve the existing preparation workflow.
`--prepare-repo` may:
- repair supported Cargo/binstall metadata;
- add or update known `.gitignore` entries;
- generate a missing `Cargo.lock`;
- configure supported `Cross.toml` settings;
- preview all intended changes.
Preparation exits before build/publication.
Git writes are separately authorized:
- `--commit-preparation` authorizes the preparation commit;
- `--create-tag` authorizes creation/validation of the release tag;
- `--push-preparation` authorizes pushing the prepared branch/tag.
Maintain the current dependency rules between these flags.
Preparation must refuse unsafe states such as:
- dirty inputs where a clean commit workflow is required;
- moving an existing tag;
- mismatched push/release destinations;
- implicit remote writes.
Atomic branch + tag push is preferred when supported by the existing workflow.
No force push.
---
## External command runner
Centralize command execution.
The runner should support:
- argv-based execution, never shell string concatenation;
- cwd;
- controlled environment inheritance;
- sensitive environment redaction;
- captured output;
- optional streaming;
- exit status;
- verbose diagnostics.
Never use `sh -c` merely for convenience.
Error messages for failed commands should include:
- executable/arguments in safely redacted form;
- exit status;
- useful stdout/stderr context.
Do not expose secrets.
---
## Prerequisite validation
Before a real build, validate relevant tools:
- `git`;
- `cargo`;
- `cross`;
- Docker or Podman backend required by `cross`;
- `cargo-binstall` when post-publication install verification is enabled.
Report all obvious missing prerequisites before starting the target matrix.
Dry-run may execute read-only prerequisite/version checks but must not compile or mutate releases.
---
## Build policy
Default targets:
```text
x86_64-unknown-linux-musl
aarch64-unknown-linux-musl
x86_64-pc-windows-gnu
```
Use `cross build` for release artifacts.
Default conceptual command:
```bash
cross build \
--release \
--locked \
--target TARGET
```
When a package is selected from a workspace, scope Cargo check/test/build to that package.
Run host-side validation before cross compilation:
```text
cargo check
cargo test
```
unless the matching skip option applies.
Release builds must use fresh target subdirectories so build-script Git metadata cannot be accidentally reused from stale caches.
Do not automatically substitute the MSVC Windows target.
Do not hide native dependency failures. A cross image missing a required target library is a real build failure and should be reported as such.
---
## Packaging contract
Preserve the current artifact contract.
Archive:
```text
{name}-{target}-v{version}.tgz
```
Archive contents:
```text
{name}-{target}-v{version}/
└── {binary}
```
Windows binary:
```text
{name}.exe
```
Generate `SHA256SUMS` with one line per archive.
Requirements:
- deterministic naming;
- stable archive layout;
- executable bit preserved on Unix binaries;
- no unrelated files;
- no target/build tree leakage;
- checksum calculated from the final archive bytes.
Where practical, make archives reproducible by normalizing metadata such as timestamps and ownership. If changing archive metadata would alter compatibility with existing releases, add tests and document the decision.
---
## Gitea authentication
Default token environment variable:
```text
GITEA_TOKEN
```
The name may be configurable.
Never:
- accept the token as an ordinary positional/CLI value unless there is an exceptionally strong reason;
- print it;
- embed it in URLs;
- write it to persistent files;
- pass it into child build processes;
- leave temporary askpass helpers behind.
HTTPS API publication uses the token.
Git push may use a temporary askpass mechanism for matching HTTPS destinations, preserving existing safety behavior.
Token redaction must be tested.
---
## Gitea release behavior
Derive repository identity from:
- selected package repository metadata;
- source/remote URL;
- explicit repository override.
If those disagree materially, fail rather than guess.
Release flow:
1. verify remote tag;
2. find release by tag;
3. create it if absent;
4. reuse it if present;
5. inspect existing assets;
6. upload generated artifacts.
Default release properties:
```text
name: tag
draft: false
prerelease: false
```
Preserve `--draft` and `--prerelease`.
Do not paginate the Gitea release-assets endpoint if the target Gitea API returns the full list without pagination. Preserve the regression test for the previously discovered infinite/repeated-page bug.
---
## Asset collision policy
Default behavior:
- an existing asset with the same filename is an error.
Only `--replace-assets` authorizes deletion/replacement.
Never:
- replace an asset implicitly;
- manufacture alternate filenames to avoid the collision;
- delete unrelated assets.
Replacement behavior must have regression coverage.
---
## Verification
After publication, verify the actual release contract.
At minimum:
- construct expected download URLs;
- verify each asset is accessible;
- verify checksums;
- inspect archive layout;
- verify expected binary filename.
Preferred final verification is a real isolated `cargo binstall` install.
Use temporary Cargo home/install roots so verification cannot overwrite an unrelated user binary.
Where assets are intended to be public, perform anonymous download verification rather than considering an authenticated API response sufficient.
Verification failures are release failures unless explicitly skipped.
---
## Dry-run semantics
Dry-run must not:
- edit manifests or repository files;
- generate a lockfile;
- build binaries;
- create commits;
- create/move tags;
- push;
- create releases;
- upload assets;
- delete/replace assets.
Dry-run should still:
- acquire/inspect source;
- resolve workspace/package selection;
- validate version/tag policy;
- validate metadata;
- print proposed metadata/preparation changes;
- inspect prerequisites;
- show targets;
- show artifact names;
- show release destination;
- show planned Git/API operations.
Dry-run should be useful as a diagnosis tool, not just a no-op flag.
---
## Error design
Create typed errors with useful context.
User-facing errors should be concise and actionable.
Bad:
```text
called `Option::unwrap()` on a `None` value
```
Good:
```text
error: selected package `foo` contains multiple binary targets: foo, foo-admin
hint: multi-binary releases are not supported by this command
```
Do not panic on malformed repository input.
`--verbose` may add diagnostic context but must still redact secrets.
---
## Security constraints
These are non-negotiable:
- never print Gitea tokens;
- never embed credentials in logged URLs;
- never run arbitrary repository-provided shell commands;
- never delete a user's local source tree;
- never commit/tag/push without the corresponding explicit authorization;
- never force-push;
- never move an existing release tag;
- never replace release assets without `--replace-assets`;
- treat cloned repository contents and metadata as untrusted input;
- keep build subprocess environment minimal where secrets are concerned;
- avoid shell interpretation;
- validate archive paths and never create traversal-capable archives.
Any new feature that expands mutation authority must be opt-in.
---
## Testing strategy
Port behavior, not Python implementation details.
### Unit tests
Cover pure policy and parsing:
- repository URL normalization;
- owner/repository extraction;
- expected tag generation;
- tag-prefix handling;
- workspace/package selection;
- binary selection;
- archive naming;
- Windows executable naming;
- binstall metadata generation;
- config precedence;
- manifest validation;
- manifest repair;
- checksum generation;
- stage ordering;
- redaction.
### Filesystem/integration tests
Cover:
- local source acquisition;
- remote clone into temporary directories;
- cleanup/keep-workdir behavior;
- preparation diffs;
- lockfile behavior;
- Cross.toml editing;
- deterministic package layout;
- clean-tree requirements;
- tag creation safeguards.
### Mocked HTTP tests
Cover:
- release lookup/create;
- asset listing;
- upload;
- collision failure;
- explicit replacement;
- API error reporting;
- token redaction;
- no erroneous asset pagination loop.
### Real-tool integration tests
Where environment permits:
- `cargo check`;
- `cargo test`;
- `cross build` for default targets;
- real archive inspection;
- real `cargo binstall` into temporary paths.
Live Gitea publication tests must be opt-in and must never target an arbitrary repository by default.
---
## Parity testing
Before removing Python, create a small compatibility fixture matrix.
At minimum include:
1. standalone one-binary package;
2. workspace with one selected CLI member;
3. inherited workspace version/repository;
4. ambiguous workspace;
5. library-only package;
6. multi-binary package;
7. missing binstall metadata;
8. incorrect binstall metadata;
9. missing lockfile;
10. non-`v` tag prefix;
11. existing release asset collision.
For non-mutating cases, compare Python and Rust:
- exit success/failure;
- selected package;
- resolved version/tag;
- proposed metadata changes;
- target list;
- archive names;
- release destination.
For packaging, compare archive contract rather than byte equality unless reproducibility is explicitly guaranteed by both implementations.
---
## Code quality
Before considering a phase complete:
```bash
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
```
If integration tests require containers or network access, keep them explicitly opt-in and document their invocation.
Do not silence Clippy warnings globally to make the gate pass.
Avoid `unwrap()`/`expect()` in normal user-input and I/O paths.
---
## Documentation
Update README as the Rust migration becomes real.
During migration, clearly state which implementation is authoritative/default.
At final cutover, documentation must no longer instruct users to create a Python venv.
Document:
- Rust binary installation/build;
- prerequisites;
- supported targets;
- workspace selection;
- dry-run;
- metadata repair;
- repository preparation;
- Gitea token permissions;
- release workflow;
- cargo-binstall installation;
- current limitations.
Do not claim a migration phase is complete before its parity gate passes.
---
## Things not to "improve" during the rewrite
Unless explicitly requested, do not combine the migration with unrelated product changes.
Avoid:
- changing archive naming;
- changing the default target matrix;
- broadening to multi-package release orchestration;
- adding multi-binary release guessing;
- moving to GitHub-specific APIs;
- replacing `cross` with a home-grown cross compiler workflow;
- changing tag policy;
- changing collision defaults;
- automatically creating/pushing tags during ordinary publication;
- introducing a daemon/service architecture;
- adding a GUI.
First produce a trustworthy Rust replacement.
---
## Definition of done
The Rust migration is complete when all of the following are true:
- the normal CLI no longer requires Python or a venv;
- supported CLI/config behavior is preserved or intentionally documented as changed;
- package/workspace selection matches current behavior;
- metadata validation and repair match the release contract;
- repository preparation preserves explicit mutation boundaries;
- all three default targets can be built in the same supported environments as before;
- generated archives and `SHA256SUMS` satisfy the existing naming/layout contract;
- Gitea release creation/reuse/upload works;
- collision/replacement behavior is preserved;
- anonymous artifact verification works where applicable;
- real isolated `cargo binstall` verification passes;
- token-redaction/security tests pass;
- `cargo fmt`, Clippy, unit tests, and migration integration tests pass;
- at least one real disposable/end-to-end Gitea release has been completed successfully with the Rust implementation;
- the Python worker and Python dependency files can be removed without losing required behavior.
Do not remove the Python implementation until these gates are satisfied.