chore: prepare 0.3.1 release

leehack · leehack · commit bb3c1dada832 · 2026-02-13T12:42:23.000-05:00
Bump version metadata, add tag-triggered trusted pub.dev publishing workflow, and restructure docs with a user-focused README plus separate maintainer guide.
diff --git a/.github/workflows/publish-pubdev.yml b/.github/workflows/publish-pubdev.yml
@@ -0,0 +1,12 @@
+name: Publish pub.dev
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  publish:
+    permissions:
+      id-token: write
+    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,12 @@
+## 0.3.1
+
+- Add installer one-liner smoke tests across Linux/macOS/Windows on `x64` and `arm64`.
+- Expand CI and binary release workflows to include Intel macOS and ARM Linux/Windows.
+- Improve installer workflow reliability with stronger local server startup/readiness checks.
+- Refresh docs/examples with validated signed and unsigned GitHub CLI command examples.
+- Add tag-triggered pub.dev trusted-publishing workflow (`publish-pubdev.yml`) using GitHub OIDC.
+- Refocus README for end users and move maintainer instructions to `doc/maintainers.md`.
+
 ## 0.3.0
 
 - Rename package and CLI naming to `drx`.
@@ -14,8 +23,6 @@
 - Add `--json` output mode for cache and versions commands.
 - Support global utility flags before command verbs (for example `--json versions`).
 - Add GH version-list fallback to repository tags when releases are absent.
-- Add one-liner installer smoke tests across Linux/macOS/Windows.
-- Expand binary build matrix to include Intel macOS and ARM Linux/Windows.
 
 ## 0.1.0
 
diff --git a/README.md b/README.md
@@ -1,221 +1,106 @@
 # drx
 
-`drx` is a Dart-first `npx`/`uvx`-style tool runner.
+`drx` runs CLI tools on demand, similar to `npx` / `uvx`.
 
-- `pub` source: runs Dart package executables.
-- `gh` source: runs precompiled binaries from public GitHub Releases.
-  (language-agnostic: Go/Rust/C/C++/etc. all work)
+- Use `pub.dev` packages when Dart SDK is available.
+- Use GitHub release binaries when Dart SDK is not available.
 
-## Command Forms
+## Install
 
-Default source is `pub`:
-
-```bash
-drx <package[@version]> [--] [args...]
-drx <package:executable[@version]> [--] [args...]
-```
-
-Explicit source:
-
-```bash
-drx --from pub:<package[@version]> <command> [--] [args...]
-drx --from gh:<owner>/<repo[@tag]> <command> [--] [args...]
-drx cache [list|clean|prune] [--json]
-drx versions <package|pub:pkg|gh:owner/repo> [--limit N] [--json]
-```
-
-Examples:
+### With Dart SDK (pub.dev)
 
 ```bash
-drx melos -- --version
-drx mason_cli:mason -- --help
-drx --from pub:very_good_cli very_good -- --help
-drx --from gh:cli/cli@v2.70.0 gh -- version
-drx --from gh:BurntSushi/ripgrep rg -- --version
-drx --from gh:junegunn/fzf fzf -- --version
-drx --from gh:charmbracelet/gum gum -- --version
-drx --allow-unsigned --from gh:sharkdp/fd fd -- --version
-drx --allow-unsigned --from gh:sharkdp/bat bat -- --version
-drx --allow-unsigned --from gh:dandavison/delta delta -- --version
-drx versions melos --limit 5
-drx versions gh:cli/cli --limit 10
-drx cache list
-drx cache prune --max-age-days 30 --max-size-mb 2048
+dart pub global activate drx
+drx --version
 ```
 
-Note: some repositories do not publish checksums. Those require
-`--allow-unsigned` as shown above.
-
-## Cross-Platform Support
-
-- Linux: `x64`, `arm64`
-- macOS: `x64` (Intel), `arm64` (Apple Silicon)
-- Windows: `x64`, `arm64`
-
-`drx` handles Windows executable resolution (`.exe`, `.cmd`, `.bat`) and
-Unix executable permissions for downloaded binaries.
-
-## Flags
-
-- `--runtime auto|jit|aot`: runtime mode for pub executables.
-- `--refresh`: refresh cached artifacts.
-- `--isolated`: use temporary, non-persistent caches.
-- `--asset <name>`: force a specific GitHub asset name.
-- `--allow-unsigned`: allow GH assets without checksum manifests.
-- `--json`: machine-readable output for `cache` and `versions`.
-- `--verbose`: enable verbose logging (currently minimal).
-
-## Cache And Version Commands
-
-- `drx cache list`: show cache location, entry counts, and size.
-- `drx cache clean`: remove all cached artifacts and lock files.
-- `drx cache prune`: remove old cache entries and optionally enforce size limits.
-  - `--max-age-days N`: remove entries older than N days (default: 30 for prune).
-  - `--max-size-mb N`: keep cache under N MB by removing oldest entries.
-  - `--json`: output prune/list/clean results as JSON.
-- `drx versions <target>`: list available versions from pub.dev or GH releases.
-  - falls back to repository tags when GH releases are not present.
-  - `--json`: output version list as JSON.
-  - pub targets: `melos`, `pub:melos`, `mason_cli:mason`
-  - gh targets: `gh:cli/cli`
-
-## Runtime Behavior
-
-- `jit`: uses `dart run package:executable`.
-- `aot`: compiles with `dart compile exe` and runs cached native output.
-- `auto`: prefers AOT, falls back to JIT when AOT is unsupported or fails.
-
-`package:cli_launcher` wrappers (for example, recent `melos`) are not compatible
-with reliable AOT execution in this model. In `auto` mode, drx falls back to JIT.
-
-When run without arguments, `drx` shows the help screen.
-
-Global flags can be placed before utility commands, for example:
+If PATH is not set for pub executables:
 
 ```bash
-drx --json versions gh:cli/cli
-drx --verbose cache list
+dart pub global run drx:drx --version
 ```
 
-## Security Policy
-
-- GH asset checksum verification is required by default.
-- If no checksum manifest is present, execution is blocked.
-- `--allow-unsigned` explicitly bypasses that block.
-
-## Make Your Tool drx-Compatible
-
-See the maintainer guide:
-[`doc/compatibility.md`](https://github.com/leehack/drx/blob/main/doc/compatibility.md).
-
-It covers:
-
-- pub.dev executable compatibility requirements
-- GitHub Releases binary compatibility requirements
-- checksum formats and naming conventions
-- validation commands for both `pub` and `gh` sources
-
-## Publish To pub.dev
+### Without Dart SDK (precompiled binary)
 
-Dry-run validation:
+Linux / macOS:
 
 ```bash
-dart pub publish --dry-run
+curl -fsSL "https://raw.githubusercontent.com/leehack/drx/main/tool/install.sh" | DRX_REPO=leehack/drx sh
 ```
 
-Publish:
+Windows (PowerShell):
 
-```bash
-dart pub publish
+```powershell
+$env:DRX_REPO = "leehack/drx"
+iwr "https://raw.githubusercontent.com/leehack/drx/main/tool/install.ps1" -UseBasicParsing | iex
 ```
 
-`drx` is intended as the publish name on pub.dev.
+Both installers verify checksums before installing.
 
-## Install With Dart SDK (pub.dev)
+## Quick Usage
 
-Install globally with pub:
+Default source is `pub`:
 
 ```bash
-dart pub global activate drx
+drx <package[@version]> [--] [args...]
+drx <package:executable[@version]> [--] [args...]
 ```
 
-Install a specific version:
+Explicit source selection:
 
 ```bash
-dart pub global activate drx 0.3.0
+drx --from pub:<package[@version]> <command> [--] [args...]
+drx --from gh:<owner>/<repo[@tag]> <command> [--] [args...]
 ```
 
-Run it:
+Examples:
 
 ```bash
-drx --version
-```
+drx melos -- --version
+drx mason_cli:mason -- --help
+drx --from pub:very_good_cli very_good -- --help
 
-If your PATH is not configured for pub global executables:
+drx --from gh:cli/cli@v2.70.0 gh -- version
+drx --from gh:BurntSushi/ripgrep rg -- --version
+drx --from gh:junegunn/fzf fzf -- --version
+drx --from gh:charmbracelet/gum gum -- --version
 
-```bash
-dart pub global run drx:drx --version
+# Some repos do not publish checksums:
+drx --allow-unsigned --from gh:sharkdp/fd fd -- --version
 ```
 
-Uninstall:
+## Useful Commands
 
 ```bash
-dart pub global deactivate drx
-```
-
-## Install Without Dart SDK (Binary Options)
-
-For users without Dart installed, publish precompiled binaries in GitHub
-Releases and provide platform-specific one-liner installers.
-
-Recommended options:
-
-1. `curl | sh` installer for Linux/macOS
-2. PowerShell installer for Windows
-3. Package managers (Homebrew tap, Scoop, winget, apt/rpm) as follow-ups
-
-Typical one-liner patterns:
+drx cache list
+drx cache clean
+drx cache prune --max-age-days 30 --max-size-mb 2048
 
-```bash
-# Linux/macOS
-curl -fsSL "https://raw.githubusercontent.com/leehack/drx/main/tool/install.sh" | DRX_REPO=leehack/drx sh
-```
+drx versions melos --limit 5
+drx versions gh:cli/cli --limit 10
 
-```powershell
-# Windows PowerShell
-$env:DRX_REPO = "leehack/drx"
-iwr "https://raw.githubusercontent.com/leehack/drx/main/tool/install.ps1" -UseBasicParsing | iex
+drx --json versions gh:cli/cli
+drx --json cache list
 ```
 
-Install scripts download and verify the matching `.sha256` checksum before
-installing binaries.
+## Runtime Modes (pub source)
 
-The repository includes ready workflows for CI and binary release publishing:
+- `--runtime auto` (default): prefer AOT, fallback to JIT
+- `--runtime jit`: `dart run`
+- `--runtime aot`: compile and run native executable
 
-- `.github/workflows/ci.yml`
-- `.github/workflows/installer-smoke.yml`
-- `.github/workflows/release-binaries.yml`
+## Security Defaults
 
-`release-binaries.yml` runs on pushed tags (`v*`) and also supports manual
-dispatch with a required `tag` input.
+- GitHub assets require checksum verification by default.
+- Unsigned assets are blocked unless you pass `--allow-unsigned`.
 
-`installer-smoke.yml` validates one-liner install scripts on Linux/macOS/Windows
-across `x64` and `arm64` runners.
-
-## Development
-
-```bash
-dart pub get
-dart analyze
-dart test
-```
+## Platform Support
 
-### Coverage
+- Linux: `x64`, `arm64`
+- macOS: `x64` (Intel), `arm64` (Apple Silicon)
+- Windows: `x64`, `arm64`
 
-```bash
-dart test --coverage=coverage
-dart run coverage:format_coverage --packages=.dart_tool/package_config.json --report-on=lib --in=coverage --out=coverage/lcov.info --lcov --fail-under=80
-dart run tool/check_coverage.dart 80 coverage/lcov.info
-```
+## More Docs
 
-The repository enforces 80%+ line coverage for `lib/`.
+- Tool maintainer compatibility guide: [`doc/compatibility.md`](https://github.com/leehack/drx/blob/main/doc/compatibility.md)
+- Project maintenance / release notes: [`doc/maintainers.md`](https://github.com/leehack/drx/blob/main/doc/maintainers.md)
diff --git a/doc/maintainers.md b/doc/maintainers.md
@@ -0,0 +1,76 @@
+# drx Maintainer Guide
+
+This document is for project maintainers and contributors.
+
+## Local Development
+
+```bash
+dart pub get
+dart analyze
+dart test
+```
+
+Coverage check:
+
+```bash
+dart test --coverage=coverage
+dart run coverage:format_coverage --packages=.dart_tool/package_config.json --report-on=lib --in=coverage --out=coverage/lcov.info --lcov --fail-under=80
+dart run tool/check_coverage.dart 80 coverage/lcov.info
+```
+
+## CI and Release Workflows
+
+- `/.github/workflows/ci.yml`
+  - analyze + tests on Linux/macOS/Windows (`x64`, `arm64`) and coverage gate.
+- `/.github/workflows/installer-smoke.yml`
+  - validates one-liner install scripts on Linux/macOS/Windows (`x64`, `arm64`).
+- `/.github/workflows/publish-pubdev.yml`
+  - publishes to pub.dev when a tag like `vX.Y.Z` is pushed.
+- `/.github/workflows/release-binaries.yml`
+  - builds and uploads release binaries/checksums for `v*` tags.
+
+## pub.dev Trusted Publishing Setup
+
+Configure once on pub.dev package admin page:
+
+1. Enable **Automated publishing from GitHub Actions**.
+2. Repository: `leehack/drx`.
+3. Tag pattern: `v{{version}}`.
+
+No `PUB_TOKEN` is required when trusted publishing is configured correctly.
+
+## Release Checklist
+
+1. Update version in:
+   - `pubspec.yaml`
+   - `lib/src/engine.dart`
+2. Add release notes to `CHANGELOG.md`.
+3. Validate:
+   - `dart analyze`
+   - `dart test`
+   - `dart pub publish --dry-run`
+4. Commit and push `main`.
+5. Create and push tag:
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Tag push triggers:
+
+- pub.dev publish (`publish-pubdev.yml`)
+- binary release (`release-binaries.yml`)
+
+## Manual Binary Rebuild for Existing Tag
+
+Use workflow dispatch on `Release Binaries` with input tag, for example `v0.3.1`.
+
+This is useful if a previous binary job failed and source code fixes were applied
+without changing the package version.
+
+## Installer Smoke Testing Notes
+
+- Installer scripts support `DRX_DOWNLOAD_BASE` override for local/test payloads.
+- This is used by installer smoke workflow to test the one-liner flow end-to-end
+  without depending on external GitHub release artifacts.
diff --git a/lib/src/engine.dart b/lib/src/engine.dart
@@ -14,7 +14,7 @@ import 'pub_runner.dart';
 import 'version_lister.dart';
 
 /// Current drx CLI version.
-const String drxVersion = '0.3.0';
+const String drxVersion = '0.3.1';
 
 /// Command engine that coordinates parsing, resolution, and execution.
 final class DrxEngine {
diff --git a/pubspec.yaml b/pubspec.yaml
