build: add release packaging script

Author: rexleimo

.gitignore

@@ -1,5 +1,6 @@
 # Rust
 /target/
+/dist/
 **/*.rs.bk
 
 # RexOS runtime

docs/plans/2026-03-01-github-release-binaries.md

@@ -0,0 +1,143 @@
+# GitHub Release Binaries Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Publish prebuilt `rexos` CLI binaries to GitHub Releases so end users can download/run without cloning the repo, and add CI to validate changes with `cargo test`.
+
+**Architecture:** Add two GitHub Actions workflows:
+- `CI` workflow runs `cargo test` on PRs/pushes.
+- `Release` workflow (tag-triggered) builds `rexos` across a small OS matrix, packages archives, and uploads them to a GitHub Release.
+
+Use a small Python (stdlib-only) packaging script to produce consistent `.tar.gz`/`.zip` archives and `.sha256` checksums across platforms.
+
+**Tech Stack:** GitHub Actions, Rust (cargo), Python 3 (stdlib: `tarfile`, `zipfile`, `hashlib`, `argparse`).
+
+---
+
+### Task 1: Add a cross-platform release packager
+
+**Files:**
+- Create: `scripts/package_release.py`
+
+**Step 1: Write a minimal “packager smoke” command (manual test)**
+
+Run (local):
+```bash
+cargo build --release -p rexos-cli
+python3 scripts/package_release.py --version v0.0.0 --target local --bin target/release/rexos --out-dir dist
+ls -la dist
+```
+
+Expected:
+- `dist/rexos-v0.0.0-local.tar.gz`
+- `dist/rexos-v0.0.0-local.tar.gz.sha256`
+
+**Step 2: Implement the packaging script**
+
+Requirements:
+- Create a staging directory `dist/rexos-<version>-<target>/`
+- Copy the built binary into the staging directory (`rexos` or `rexos.exe`)
+- Optionally include `README.md` (and `LICENSE` if present)
+- Produce:
+  - `.zip` for Windows targets
+  - `.tar.gz` for everything else
+- Write `<archive>.sha256` (SHA-256 hex + two spaces + filename)
+
+**Step 3: Re-run the smoke command**
+
+Expected: archive + checksum created, and the binary is present inside the archive.
+
+**Step 4: Commit**
+
+```bash
+git add scripts/package_release.py
+git commit -m "build: add release packaging script"
+```
+
+---
+
+### Task 2: Add CI workflow (tests)
+
+**Files:**
+- Create: `.github/workflows/ci.yml`
+
+**Step 1: Implement CI**
+
+Requirements:
+- Trigger on `pull_request` and `push` to `main`
+- Run `cargo test` (workspace) on a small OS matrix (Linux/macOS/Windows)
+- Use Rust cache (`Swatinem/rust-cache`) for speed
+
+**Step 2: Validate locally**
+
+Run:
+```bash
+cargo test
+```
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "ci: add github actions test workflow"
+```
+
+---
+
+### Task 3: Add Release workflow (tagged builds → GitHub Releases)
+
+**Files:**
+- Create: `.github/workflows/release.yml`
+
+**Step 1: Implement build matrix**
+
+Matrix (initial):
+- `ubuntu-latest` → `x86_64-unknown-linux-gnu`
+- `macos-13` → `x86_64-apple-darwin`
+- `macos-14` → `aarch64-apple-darwin`
+- `windows-latest` → `x86_64-pc-windows-msvc`
+
+Each build job:
+- `cargo build --release -p rexos-cli --locked`
+- `python scripts/package_release.py --version $TAG --target $TARGET ...`
+- Upload `dist/*` as workflow artifacts
+
+Release job:
+- Download all artifacts into `dist/`
+- Create/update GitHub Release for the tag and upload `dist/*` as assets
+
+**Step 2: Document release process**
+
+Update `README.md` with:
+- Download-from-Releases instructions for end users
+- Maintainer instructions: `git tag vX.Y.Z && git push origin vX.Y.Z` triggers the workflow
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/release.yml README.md
+git commit -m "release: build and upload binaries on tags"
+```
+
+---
+
+### Task 4: Final verification
+
+**Step 1: Run tests**
+
+Run:
+```bash
+cargo test
+```
+
+Expected: all tests pass.
+
+**Step 2: Ensure worktree is clean**
+
+Run:
+```bash
+git status -sb
+```
+
+Expected: no uncommitted changes.
+

scripts/package_release.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import shutil
+import sys
+import tarfile
+import zipfile
+from pathlib import Path
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def should_zip(target: str, bin_path: Path) -> bool:
+    if bin_path.suffix.lower() == ".exe":
+        return True
+    t = target.lower()
+    return ("windows" in t) or t.endswith("msvc")
+
+
+def create_tar_gz(archive_path: Path, stage_dir: Path) -> None:
+    with tarfile.open(archive_path, "w:gz") as tf:
+        tf.add(stage_dir, arcname=stage_dir.name)
+
+
+def create_zip(archive_path: Path, stage_dir: Path) -> None:
+    with zipfile.ZipFile(archive_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in stage_dir.rglob("*"):
+            if p.is_dir():
+                continue
+            zf.write(p, arcname=str(p.relative_to(stage_dir.parent)))
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description="Package a rexos release archive + sha256 file.")
+    parser.add_argument("--version", required=True, help="Version string, e.g. v0.1.0")
+    parser.add_argument("--target", required=True, help="Target triple or label, e.g. x86_64-unknown-linux-gnu")
+    parser.add_argument("--bin", required=True, help="Path to built rexos binary (rexos or rexos.exe)")
+    parser.add_argument("--out-dir", default="dist", help="Output directory (default: dist)")
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        help="Optional file to include in the archive (repeatable)",
+    )
+    args = parser.parse_args(argv)
+
+    repo_root = Path.cwd()
+    out_dir = (repo_root / args.out_dir).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    bin_path = (repo_root / args.bin).resolve()
+    if not bin_path.exists():
+        print(f"error: --bin does not exist: {bin_path}", file=sys.stderr)
+        return 2
+
+    if not bin_path.is_file():
+        print(f"error: --bin is not a file: {bin_path}", file=sys.stderr)
+        return 2
+
+    base_name = f"rexos-{args.version}-{args.target}"
+    stage_dir = out_dir / base_name
+    if stage_dir.exists():
+        shutil.rmtree(stage_dir)
+    stage_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy binary (keep its original filename; on Windows it's usually rexos.exe).
+    dest_bin = stage_dir / bin_path.name
+    shutil.copy2(bin_path, dest_bin)
+    if dest_bin.suffix.lower() != ".exe":
+        os.chmod(dest_bin, 0o755)
+
+    # Default include set if present.
+    default_includes = ["README.md", "LICENSE", "LICENSE.txt"]
+    includes: list[Path] = []
+    for rel in default_includes:
+        p = (repo_root / rel)
+        if p.exists() and p.is_file():
+            includes.append(p)
+    for user_inc in args.include:
+        p = (repo_root / user_inc)
+        if p.exists() and p.is_file():
+            includes.append(p)
+
+    seen: set[Path] = set()
+    for p in includes:
+        rp = p.resolve()
+        if rp in seen:
+            continue
+        seen.add(rp)
+        shutil.copy2(rp, stage_dir / p.name)
+
+    if should_zip(args.target, bin_path):
+        archive_path = out_dir / f"{base_name}.zip"
+        create_zip(archive_path, stage_dir)
+    else:
+        archive_path = out_dir / f"{base_name}.tar.gz"
+        create_tar_gz(archive_path, stage_dir)
+
+    digest = sha256_file(archive_path)
+    sha_path = archive_path.with_suffix(archive_path.suffix + ".sha256")
+    sha_path.write_text(f"{digest}  {archive_path.name}\n", encoding="utf-8")
+
+    print(str(archive_path))
+    print(str(sha_path))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+