From b68ee590d3550a2888ebeece68e03ddbbdad4ece Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 13 Sep 2026 12:06:51 +0200 Subject: [PATCH] First draft to be agent finished --- AGENTS.md | 743 +++++++++++++++++++++++++++++++++++++++++++++ AGENT_TASKS.md | 629 ++++++++++++++++++++++++++++++++++++++ README.md | 24 +- config.toml | 18 ++ release.sh | 131 ++++++++ requirements.txt | 4 + worker/__init__.py | 1 + worker/__main__.py | 5 + worker/cli.py | 192 ++++++++++++ worker/manifest.py | 108 +++++++ worker/models.py | 34 +++ worker/runner.py | 44 +++ 12 files changed, 1932 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 AGENT_TASKS.md create mode 100644 config.toml create mode 100755 release.sh create mode 100644 requirements.txt create mode 100644 worker/__init__.py create mode 100644 worker/__main__.py create mode 100644 worker/cli.py create mode 100644 worker/manifest.py create mode 100644 worker/models.py create mode 100644 worker/runner.py diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..48ccec3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,743 @@ +# AGENT.md + +## Mission + +Finish the `rust-binstall-publisher` proof-of-concept as a small, maintainable release tool for Rust CLI projects. + +The tool must: + +1. refuse to run from the Bash wrapper unless a Python virtual environment is active; +2. offer to create `.venv` when no project venv exists; +3. inspect a local Rust project or clone a Git repository; +4. validate package metadata and `cargo-binstall` metadata; +5. optionally repair missing or incorrect metadata without silently pushing changes; +6. validate that the Git tag matches the Cargo package version; +7. cross-compile release binaries for the default target matrix; +8. package artifacts using a deterministic naming/layout convention; +9. generate SHA-256 checksums; +10. create or reuse a Gitea release; +11. upload release assets; +12. verify that `cargo-binstall` can consume the published artifact metadata. + +The intended default targets are: + +- `x86_64-unknown-linux-musl` +- `aarch64-unknown-linux-musl` +- `x86_64-pc-windows-gnu` + +The tool is initially optimized for a single Cargo package producing a single CLI binary. Multi-package workspaces and multi-binary packages should be detected and reported cleanly rather than guessed at. + +--- + +## Repository layout + +Target layout: + +```text +rust-binstall-publisher/ +├── release.sh +├── requirements.txt +├── config.toml +├── README.md +├── AGENT.md +├── AGENT_TASKS.md +└── worker/ + ├── __init__.py + ├── __main__.py + ├── cli.py + ├── config.py + ├── models.py + ├── runner.py + ├── project.py + ├── manifest.py + ├── build.py + ├── package.py + ├── gitea.py + └── verify.py +``` + +Tests may be added under: + +```text +tests/ +``` + +Do not collapse everything into one large Python file. + +--- + +## User experience + +Preferred final CLI: + +```bash +./release.sh SOURCE [OPTIONS] +``` + +Examples: + +```bash +./release.sh ./my-tool --dry-run +``` + +```bash +./release.sh \ + https://gitea.example.org/user/my-tool.git \ + --tag v0.3.1 \ + --dry-run +``` + +```bash +./release.sh \ + https://gitea.example.org/user/my-tool.git \ + --tag v0.3.1 \ + --fix-metadata +``` + +Avoid requiring a redundant subcommand such as: + +```bash +./release.sh release ... +``` + +unless Typer makes the simpler interface unreasonable. + +--- + +## Bash wrapper requirements + +`release.sh` must be intentionally strict. + +### Without an active venv + +If `.venv` exists: + +- refuse to run the worker; +- print the exact activation command; +- exit non-zero. + +Expected guidance: + +```bash +source .venv/bin/activate +``` + +If `.venv` does not exist and stdin is interactive: + +- ask whether to create it; +- if accepted: + - run `python3 -m venv .venv`; + - install `requirements.txt`; + - report success; + - exit; +- do not attempt to “activate” the environment from inside the script. + +If stdin is non-interactive: + +- fail with a clear message instead of prompting. + +### With an active venv + +If it is the project `.venv`, proceed. + +If another venv is active: + +- warn; +- interactively ask whether to continue; +- in non-interactive mode, fail rather than guessing. + +The wrapper must use: + +```bash +set -euo pipefail +``` + +and finish with: + +```bash +exec python -m worker "$@" +``` + +or the equivalent project-local interpreter invocation. + +--- + +## Python dependencies + +Dependencies are acceptable. + +Use: + +- `tomlkit` for preserving `Cargo.toml` comments and formatting; +- `rich` for readable terminal output; +- `typer` for CLI parsing; +- `httpx` for Gitea HTTP operations. + +Prefer the standard library for everything else. + +Do not add large frameworks. + +--- + +## Configuration + +`config.toml` should provide sane defaults. + +Suggested initial shape: + +```toml +[release] +tag-prefix = "v" + +[build] +targets = [ + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-musl", + "x86_64-pc-windows-gnu", +] +profile = "release" +locked = true + +[package] +format = "tgz" + +[gitea] +token-env = "GITEA_TOKEN" +``` + +CLI options override configuration values. + +Do not hardcode one specific Gitea instance. + +--- + +## Source acquisition + +Support: + +1. a local path; +2. a Git HTTP/HTTPS URL; +3. SSH-style URLs such as `git@host:owner/repo.git`. + +For remote repositories: + +- clone into a temporary directory; +- support checking out a requested tag; +- remove the temporary directory unless `--keep-workdir` is set. + +For local repositories: + +- never delete or move the user’s project; +- do not commit or push changes automatically. + +--- + +## Cargo inspection + +Use: + +```bash +cargo metadata --format-version=1 --no-deps +``` + +to discover: + +- package name; +- package version; +- repository; +- binary target names. + +Also read `Cargo.toml` through `tomlkit` for editable metadata. + +For the first supported release path: + +- exactly one package; +- exactly one binary. + +If multiple binaries or ambiguous workspace packages exist: + +- show what was discovered; +- exit with a clear unsupported-case message. + +Do not guess which binary the user intended. + +--- + +## Version/tag policy + +Default tag prefix: + +```text +v +``` + +For package version: + +```text +0.3.1 +``` + +expected tag: + +```text +v0.3.1 +``` + +If `--tag` is supplied and does not match, fail before building. + +Do not silently retag or rewrite package versions. + +--- + +## cargo-binstall metadata policy + +The tool should standardize artifact naming. + +Preferred archive name: + +```text +{name}-{target}-v{version}.tgz +``` + +Examples: + +```text +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 +``` + +Preferred archive layout: + +```text +mytool-x86_64-unknown-linux-musl-v0.3.1/ +└── mytool +``` + +Windows: + +```text +mytool-x86_64-pc-windows-gnu-v0.3.1/ +└── mytool.exe +``` + +Expected metadata should be generated from the chosen convention rather than duplicated in several modules. + +Suggested metadata: + +```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 }" +``` + +If actual cargo-binstall behavior requires a small adjustment, centralize it in one policy function and document the reason. + +### Modes + +Default: + +```text +check only +``` + +With: + +```bash +--fix-metadata +``` + +the tool may edit the checked-out `Cargo.toml`. + +It must: + +- preserve formatting/comments where practical; +- print what changed; +- not commit; +- not push. + +A future `--commit-metadata` option may be added, but it is not required for this PoC. + +--- + +## Prerequisite validation + +Before a real build, check for: + +- `git` +- `cargo` +- `cross` +- a usable Docker/Podman backend required by `cross` + +Do not discover missing build prerequisites halfway through target 3. + +A dry run should report prerequisite availability but not build anything. + +--- + +## Build policy + +Use `cross build`. + +Default pattern: + +```bash +cross build \ + --release \ + --locked \ + --target TARGET +``` + +Respect config values for: + +- profile; +- locked/unlocked behavior; +- target list. + +If `Cargo.lock` does not exist and locked mode is enabled, fail clearly or require an explicit override. + +Do not switch to `x86_64-pc-windows-msvc` automatically. + +The Windows default for this Linux-hosted PoC is: + +```text +x86_64-pc-windows-gnu +``` + +--- + +## Packaging policy + +Create a local `dist/` staging directory inside the working copy or an explicitly managed temporary location. + +For each target: + +1. locate the compiled binary; +2. copy it into the standardized top-level archive directory; +3. preserve executable mode on Unix binaries; +4. create `.tgz`; +5. compute SHA-256. + +Generate: + +```text +SHA256SUMS +``` + +with one line per archive. + +Do not include build directories or unrelated project files in the archives. + +--- + +## Gitea authentication + +Read the token from an environment variable. + +Default: + +```text +GITEA_TOKEN +``` + +Never require the token as a normal CLI argument. + +Do not log or print the token. + +Support overriding the token environment-variable name through config if easy. + +--- + +## Gitea repository/release handling + +The tool should derive owner/repository from either: + +- the project repository URL; +- the clone source URL; +- explicit CLI options if necessary. + +Do not guess silently if the repository cannot be identified. + +Release behavior: + +1. look up the release by tag; +2. if none exists, create it; +3. if it exists, reuse it; +4. upload artifacts. + +Default release: + +```text +name: same as tag +draft: false +prerelease: false +``` + +Support: + +```bash +--draft +--prerelease +``` + +if straightforward. + +--- + +## Asset collision policy + +Default: + +- if a release already contains an asset with the same filename, fail. + +With: + +```bash +--replace-assets +``` + +the tool may delete/replace matching assets. + +Never silently create duplicate assets with altered filenames. + +--- + +## Verification + +After publishing, verify the release contract. + +At minimum: + +- construct the expected asset URL; +- verify the asset exists; +- download it or otherwise validate that it is accessible; +- verify archive structure; +- verify binary filename. + +Preferred final verification: + +```bash +cargo binstall ... +``` + +using the checked-out manifest or a safe temporary install root. + +Do not overwrite an unrelated user binary during verification. + +Use a temporary Cargo home or bin directory where practical. + +The tool should report verification results per target where feasible. + +--- + +## CLI flags + +Implement or reserve cleanly for: + +```text +--tag TAG +--target TARGET repeatable +--dry-run +--fix-metadata +--skip-tests +--skip-binstall-test +--draft +--prerelease +--replace-assets +--keep-workdir +--verbose +--stop-after STAGE +``` + +Useful stage names: + +```text +inspect +metadata +verify +build +package +release +upload +binstall +``` + +`--stop-after` should stop successfully after the requested completed stage. + +--- + +## Dry-run semantics + +`--dry-run` must not: + +- edit the manifest; +- build binaries; +- create releases; +- upload assets; +- delete assets. + +It should: + +- acquire/inspect the project; +- report package information; +- validate version/tag; +- validate metadata; +- report proposed metadata changes; +- report planned build targets; +- report prerequisites; +- print intended artifact filenames and release destination. + +Dry-run should be useful enough to diagnose most configuration problems. + +--- + +## Error handling + +Prefer clear, short messages. + +Bad: + +```text +KeyError: 'package' +``` + +Good: + +```text +error: Cargo.toml contains no [package] table. +Workspace-only manifests are not supported by this proof-of-concept. +``` + +External command failures should show: + +- command; +- exit status; +- useful stderr. + +Do not expose Python tracebacks by default. + +`--verbose` may expose more detail. + +--- + +## Code organization + +Keep responsibilities separated: + +### `runner.py` +External command execution and streaming. + +### `project.py` +Clone/local-path handling, checkout, cleanup, Git metadata. + +### `manifest.py` +Cargo/TOML inspection and binstall metadata validation/repair. + +### `build.py` +Prerequisites and cross compilation. + +### `package.py` +Artifact staging, archives, hashes. + +### `gitea.py` +HTTP client, release lookup/create, asset lookup/upload/delete. + +### `verify.py` +Published artifact and cargo-binstall verification. + +### `models.py` +Dataclasses shared across modules. + +### `config.py` +Config file parsing and default/CLI merge. + +### `cli.py` +Argument parsing and orchestration only. + +Do not put HTTP logic in `cli.py`. + +Do not put TOML-editing logic in `build.py`. + +--- + +## Testing expectations + +At minimum, add tests for pure logic where practical: + +- repository URL parsing; +- expected tag from version; +- archive naming; +- binary filename per target; +- cargo-binstall metadata generation; +- manifest validation/repair; +- checksum generation. + +Avoid requiring a live Gitea instance for the basic test suite. + +Gitea API calls should be structured so they can be mocked. + +--- + +## Security constraints + +- never print `GITEA_TOKEN`; +- never embed tokens in URLs; +- never push Git changes automatically; +- never delete a user’s local source tree; +- never replace remote assets unless explicitly requested; +- never run arbitrary commands from repository metadata; +- treat repository content as untrusted input; +- avoid `shell=True` in Python subprocess calls. + +--- + +## Documentation expectations + +Update `README.md` as features become real. + +Document: + +- setup; +- venv behavior; +- prerequisites; +- supported targets; +- dry-run; +- metadata repair; +- Gitea token setup; +- example publish command; +- current limitations. + +Do not document unsupported features as if they already work. + +--- + +## Definition of done + +The PoC is complete when this workflow works against a real single-binary Rust CLI project hosted on Gitea: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt + +export GITEA_TOKEN="..." + +./release.sh \ + https://gitea.example.org/owner/tool.git \ + --tag v0.1.0 \ + --fix-metadata +``` + +and the result is: + +- package metadata validated; +- binaries built for all default targets; +- three `.tgz` artifacts produced; +- `SHA256SUMS` produced; +- a Gitea release created or reused; +- all assets uploaded; +- the cargo-binstall URL/layout validated; +- no unrelated files or remote Git history modified. + + diff --git a/AGENT_TASKS.md b/AGENT_TASKS.md new file mode 100644 index 0000000..261e38c --- /dev/null +++ b/AGENT_TASKS.md @@ -0,0 +1,629 @@ +# 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 + +```bash +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: + ```bash + 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: + ```bash + 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 + +```bash +./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: + +```bash +./release.sh ./sample-project --dry-run +``` + +and: + +```bash +./release.sh https://gitea.example.org/user/sample-project.git --dry-run +``` + +--- + +## Phase 5 — Cargo project inspection + +- [ ] Read `Cargo.toml` with `tomlkit`. +- [ ] Run: + ```bash + 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: + +```text +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`: + +```text +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: + ```text + {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: + +```text +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: + +```bash +./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: + +```text +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: + ```bash + 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: + ```bash + 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: + +```text +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 + +```bash +./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: + ```bash + 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: + ```bash + 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`: + +```text +.venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ +dist/ +``` + +--- + +# Final integration test + +Use a real or disposable single-binary Rust project on Gitea. + +## Setup + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt + +export GITEA_TOKEN="..." +``` + +## Inspect + +```bash +./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 + +```bash +./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. + diff --git a/README.md b/README.md index 01bd140..40b9306 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,24 @@ -# rust_realease +# Rust Binstall Publisher +Small release helper for Rust CLI projects. + +Its intended job is to: + +1. acquire a Rust project; +2. inspect and validate its Cargo metadata; +3. ensure cargo-binstall metadata is correct; +4. cross-compile supported targets; +5. package release artifacts; +6. create a Gitea release; +7. upload the artifacts; +8. verify that cargo-binstall can install them. + +## Setup + +The wrapper intentionally refuses to run without an active Python +virtual environment. + +Run: + +```bash +./release.sh --help diff --git a/config.toml b/config.toml new file mode 100644 index 0000000..ceb1efd --- /dev/null +++ b/config.toml @@ -0,0 +1,18 @@ +[release] +tag-prefix = "v" + +[build] +targets = [ + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-musl", + "x86_64-pc-windows-gnu", +] + +profile = "release" +locked = true + +[package] +format = "tgz" + +[gitea] +token-env = "GITEA_TOKEN" diff --git a/release.sh b/release.sh new file mode 100755 index 0000000..4593917 --- /dev/null +++ b/release.sh @@ -0,0 +1,131 @@ +#!/usr/bin/env bash + +set -euo pipefail + +SCRIPT_DIR="$( + cd -- "$(dirname -- "${BASH_SOURCE[0]}")" + pwd +)" + +VENV_DIR="${SCRIPT_DIR}/.venv" +REQUIREMENTS="${SCRIPT_DIR}/requirements.txt" + + +die() { + echo "error: $*" >&2 + exit 1 +} + + +setup_venv() { + command -v python3 >/dev/null 2>&1 || \ + die "python3 is required to create the virtual environment." + + echo + echo "Creating virtual environment:" + echo " ${VENV_DIR}" + echo + + python3 -m venv "${VENV_DIR}" + + echo "Installing worker dependencies..." + "${VENV_DIR}/bin/python" -m pip install --upgrade pip + "${VENV_DIR}/bin/python" -m pip install -r "${REQUIREMENTS}" + + echo + echo "Virtual environment is ready." + echo + echo "Activate it with:" + echo + echo " source .venv/bin/activate" + echo + echo "Then run:" + echo + echo " ./release.sh $*" + echo + + exit 0 +} + + +# --------------------------------------------------------------------------- +# Environment guard +# --------------------------------------------------------------------------- + +if [[ -z "${VIRTUAL_ENV:-}" ]]; then + echo + echo "rust-binstall-publisher requires an active Python virtual environment." + echo + + if [[ -d "${VENV_DIR}" ]]; then + echo "A project virtual environment already exists:" + echo + echo " ${VENV_DIR}" + echo + echo "Activate it first:" + echo + echo " source .venv/bin/activate" + echo + echo "Then rerun this command." + echo + + exit 2 + fi + + echo "No .venv exists yet." + echo + + if [[ -t 0 ]]; then + read -r -p "Create and set up .venv now? [Y/n] " answer + + case "${answer:-Y}" in + y|Y|yes|YES|"") + setup_venv "$@" + ;; + *) + echo + echo "Environment setup cancelled." + echo + echo "Create it manually with:" + echo + echo " python3 -m venv .venv" + echo " source .venv/bin/activate" + echo " pip install -r requirements.txt" + echo + exit 2 + ;; + esac + fi + + die "no virtual environment active and stdin is non-interactive." +fi + + +# --------------------------------------------------------------------------- +# Extra sanity check: +# ensure we're using the project's environment, not some random venv. +# --------------------------------------------------------------------------- + +EXPECTED_VENV="$(cd "${VENV_DIR}" 2>/dev/null && pwd || true)" +ACTIVE_VENV="$(cd "${VIRTUAL_ENV}" 2>/dev/null && pwd || true)" + +if [[ -d "${VENV_DIR}" && "${ACTIVE_VENV}" != "${EXPECTED_VENV}" ]]; then + echo + echo "warning: an environment is active, but it is not this project's .venv:" + echo + echo " active: ${VIRTUAL_ENV}" + echo " expected: ${VENV_DIR}" + echo + read -r -p "Continue anyway? [y/N] " answer + + case "${answer:-N}" in + y|Y|yes|YES) + ;; + *) + exit 2 + ;; + esac +fi + + +exec python -m worker "$@" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ce98fa0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +tomlkit>=0.13,<1 +rich>=14,<15 +typer>=0.16,<1 +httpx>=0.28,<1 diff --git a/worker/__init__.py b/worker/__init__.py new file mode 100644 index 0000000..3dc1f76 --- /dev/null +++ b/worker/__init__.py @@ -0,0 +1 @@ +__version__ = "0.1.0" diff --git a/worker/__main__.py b/worker/__main__.py new file mode 100644 index 0000000..21631a2 --- /dev/null +++ b/worker/__main__.py @@ -0,0 +1,5 @@ +from .cli import app + + +if __name__ == "__main__": + app() diff --git a/worker/cli.py b/worker/cli.py new file mode 100644 index 0000000..f40c38c --- /dev/null +++ b/worker/cli.py @@ -0,0 +1,192 @@ +from __future__ import annotations + +from pathlib import Path + +import typer + +from rich.console import Console +from rich.table import Table + +from . import __version__ +from .project import ( + acquire_project, + cleanup_project, +) +from .manifest import inspect_project + + +app = typer.Typer( + no_args_is_help=True, + pretty_exceptions_enable=False, +) + +console = Console() + + +DEFAULT_TARGETS = [ + "x86_64-unknown-linux-musl", + "aarch64-unknown-linux-musl", + "x86_64-pc-windows-gnu", +] + + +@app.command() +def release( + source: str = typer.Argument( + ..., + help="Git repository URL or local project path.", + ), + tag: str | None = typer.Option( + None, + "--tag", + "-t", + help="Git tag to release.", + ), + target: list[str] | None = typer.Option( + None, + "--target", + help="Build target. May be repeated.", + ), + dry_run: bool = typer.Option( + False, + "--dry-run", + help="Inspect and plan without changing anything.", + ), + keep_workdir: bool = typer.Option( + False, + "--keep-workdir", + help="Keep temporary cloned repositories.", + ), +): + targets = target or DEFAULT_TARGETS + + console.print( + f"[bold]rust-binstall-publisher[/bold] " + f"[dim]v{__version__}[/dim]" + ) + + console.print() + + project_source = acquire_project(source) + + try: + project = inspect_project( + project_source.path + ) + + table = Table( + title="Project", + show_header=False, + ) + + table.add_column("Property") + table.add_column("Value") + + table.add_row( + "Path", + str(project.root), + ) + + table.add_row( + "Package", + project.package_name, + ) + + table.add_row( + "Version", + project.version, + ) + + table.add_row( + "Repository", + project.repository or "[red]missing[/red]", + ) + + table.add_row( + "Binary", + ", ".join(project.binaries), + ) + + table.add_row( + "Commit", + project.commit or "unknown", + ) + + if tag: + table.add_row( + "Requested tag", + tag, + ) + + console.print(table) + console.print() + + target_table = Table( + title="Planned build matrix" + ) + + target_table.add_column("Target") + target_table.add_column("Artifact") + + for triple in targets: + suffix = ".exe" if "windows" in triple else "" + + binary = project.binaries[0] + + target_table.add_row( + triple, + f"{binary}{suffix}", + ) + + console.print(target_table) + + console.print() + + if len(project.binaries) != 1: + console.print( + "[yellow]warning:[/yellow] " + "multiple binaries are not fully supported yet." + ) + + if project.repository is None: + console.print( + "[red]error:[/red] " + "package.repository is required for release publishing." + ) + + raise typer.Exit(1) + + if tag: + expected = f"v{project.version}" + + if tag != expected: + console.print( + f"[red]error:[/red] " + f"tag {tag!r} does not match " + f"package version {project.version!r} " + f"(expected {expected!r})." + ) + + raise typer.Exit(1) + + console.print() + + if dry_run: + console.print( + "[cyan]DRY RUN[/cyan] — " + "no files changed, built, or uploaded." + ) + else: + console.print( + "[yellow]Release execution is not implemented yet.[/yellow]" + ) + + finally: + if project_source.temporary: + if keep_workdir: + console.print( + f"\nTemporary workdir kept at " + f"[bold]{project_source.path}[/bold]" + ) + else: + cleanup_project(project_source) diff --git a/worker/manifest.py b/worker/manifest.py new file mode 100644 index 0000000..a5d7e33 --- /dev/null +++ b/worker/manifest.py @@ -0,0 +1,108 @@ +from __future__ import annotations + +import json + +from pathlib import Path + +import tomlkit + +from .models import RustProject +from .runner import run + + +def inspect_project(root: Path) -> RustProject: + manifest_path = root / "Cargo.toml" + + if not manifest_path.exists(): + raise RuntimeError( + f"Cargo.toml not found: {manifest_path}" + ) + + raw = manifest_path.read_text( + encoding="utf-8" + ) + + document = tomlkit.parse(raw) + + package = document.get("package") + + if package is None: + raise RuntimeError( + "workspace-only Cargo.toml is not supported yet" + ) + + name = package.get("name") + version = package.get("version") + + if not name: + raise RuntimeError( + "package.name is missing" + ) + + if not version: + raise RuntimeError( + "package.version is missing" + ) + + repository = package.get("repository") + + metadata_raw = run( + "cargo", + "metadata", + "--format-version", + "1", + "--no-deps", + cwd=root, + ) + + metadata = json.loads(metadata_raw) + + packages = metadata.get("packages", []) + + matching = [ + pkg + for pkg in packages + if pkg["name"] == name + ] + + if len(matching) != 1: + raise RuntimeError( + f"could not uniquely identify package {name!r}" + ) + + cargo_package = matching[0] + + binaries = [ + target["name"] + for target in cargo_package["targets"] + if "bin" in target["kind"] + ] + + if not binaries: + raise RuntimeError( + "package contains no binary targets" + ) + + commit = None + + try: + commit = run( + "git", + "rev-parse", + "HEAD", + cwd=root, + ) + except Exception: + pass + + return RustProject( + root=root, + manifest=manifest_path, + package_name=name, + version=str(version), + repository=str(repository) + if repository + else None, + binaries=binaries, + commit=commit, + ) diff --git a/worker/models.py b/worker/models.py new file mode 100644 index 0000000..4674fd6 --- /dev/null +++ b/worker/models.py @@ -0,0 +1,34 @@ +from __future__ import annotations + +from dataclasses import dataclass, field +from pathlib import Path + + +@dataclass(slots=True) +class RustProject: + root: Path + manifest: Path + + package_name: str + version: str + + repository: str | None = None + binaries: list[str] = field(default_factory=list) + + commit: str | None = None + tag: str | None = None + + +@dataclass(slots=True) +class BuildTarget: + triple: str + + @property + def is_windows(self) -> bool: + return "windows" in self.triple + + def binary_filename(self, binary: str) -> str: + if self.is_windows: + return f"{binary}.exe" + + return binary diff --git a/worker/runner.py b/worker/runner.py new file mode 100644 index 0000000..7a6570c --- /dev/null +++ b/worker/runner.py @@ -0,0 +1,44 @@ +from __future__ import annotations + +import subprocess +from pathlib import Path + +from rich.console import Console + + +console = Console() + + +class CommandError(RuntimeError): + pass + + +def run( + *args: str, + cwd: Path | None = None, + capture: bool = True, +) -> str: + console.print( + "[dim]$ " + " ".join(args) + "[/dim]" + ) + + proc = subprocess.run( + args, + cwd=cwd, + text=True, + stdout=subprocess.PIPE if capture else None, + stderr=subprocess.PIPE if capture else None, + ) + + if proc.returncode != 0: + stderr = proc.stderr.strip() if proc.stderr else "" + + raise CommandError( + f"command failed ({proc.returncode}): " + f"{' '.join(args)}\n{stderr}" + ) + + if not capture: + return "" + + return proc.stdout.strip()