App-karr
view release on metacpan or search on metacpan
docs/superpowers/plans/2026-09-14-karr-binary-release.md view on Meta::CPAN
json_mods=()
for m in Cpanel::JSON::XS JSON::XS JSON::PP; do
perl -M"$m" -e1 >/dev/null 2>&1 && json_mods+=("-M" "$m")
done
PAR_VERBATIM=1 pp -o "$OUT" \
-M 'App::karr::**' -M 'App::karr::Cmd::**' \
-M YAML::XS \
-M JSON::MaybeXS "${json_mods[@]}" \
-M Module::Runtime \
-M MooX::Cmd -M 'MooX::Cmd::**' \
-M MooX::Options -M 'MooX::Options::**' \
-M Git::Native -M 'Git::Native::**' \
-M Git::Libgit2 -M 'Git::Libgit2::**' \
-M Alien::Libgit2 \
-M FFI::Platypus -M 'FFI::Platypus::**' -M FFI::CheckLib \
-a "$DISTDIR;lib/auto/share/dist/Alien-Libgit2" \
bin/karr
chmod +x "$OUT"
echo "Built $OUT ($(du -h "$OUT" | cut -f1))"
```
Then: `chmod +x scripts/build-binary.sh`.
- [ ] **Step 3: Build the binary locally**
Run: `KARR_BIN_OUT=/tmp/karrbuild/karr ./scripts/build-binary.sh`
Expected: prints `Built /tmp/karrbuild/karr (~23M)` and exits 0. If it prints the install_type error, reinstall Alien::Libgit2 share into an isolated lib per the pp-recipe preconditions and retry.
- [ ] **Step 4: Sanity-check startup from a fresh cache**
Run: `PAR_GLOBAL_TEMP="$(mktemp -d)" /tmp/karrbuild/karr --version`
Expected: prints the karr version, exit 0. (Full trap coverage is Task 2.) A `did not return a true value` here means `PAR_VERBATIM=1` was dropped.
- [ ] **Step 5: Commit**
```bash
git add scripts/build-binary.sh
git commit -m "build: scripts/build-binary.sh packs karr with pp
Encapsulates the verified pp invocation (PAR_VERBATIM, the dynamic-Cmd-class
and framework globs, the Alien::Libgit2 share dir) so the binary builds the
same way locally and in CI. Refuses a system-build Alien::Libgit2 up front."
```
---
### Task 2: `scripts/verify-binary.sh` â smoke-test both pp traps
**Files:**
- Create: `scripts/verify-binary.sh`
**Interfaces:**
- Consumes: a built binary path (arg 1), produced by `scripts/build-binary.sh`.
- Produces: exit 0 iff every subcommand loads and a real libgit2 board flow succeeds. Task 3's CI job calls this before uploading.
**Notes:** Two traps only surface at runtime â a missing `Cmd::*` class (subcommand dies when first called) and a libgit2/FFI break (any board op dies). The verify must therefore load every subcommand and run one real board flow, in a throwaway rep...
- [ ] **Step 1: Confirm the exact subcommand list and flow signatures**
Run: `/tmp/karrbuild/karr --help` and, for the flow commands, `/tmp/karrbuild/karr create --help`, `move --help`, `handoff --help`, `backup --help`, `destroy --help`.
Expected: note the real flag names (e.g. how `create` reports the new id, the `destroy` confirmation flag). Use these exact forms in Step 2. The command list to load is the "Commands (current)" table in `CLAUDE.md`.
- [ ] **Step 2: Write `scripts/verify-binary.sh`**
```bash
#!/usr/bin/env bash
# Smoke-test a built karr binary against both pp runtime traps.
# Usage: verify-binary.sh <karr-binary>
set -euo pipefail
BIN=$(realpath "${1:?usage: verify-binary.sh <karr-binary>}")
export PAR_GLOBAL_TEMP="$(mktemp -d)"
"$BIN" --version
"$BIN" --help >/dev/null
# Trap 1: force every dynamically-loaded Cmd class to load (no side effects).
for cmd in init create list show move edit delete board dashboard pick unlock \
archive handoff needs metrics log config context agent-name skill \
materialize import repair sync backup restore destroy \
set-refs get-refs disable enable; do
"$BIN" "$cmd" --help >/dev/null || { echo "FAIL: subcommand $cmd" >&2; exit 1; }
done
echo "trap1 (subcommand classes): OK"
# Trap 2: a real libgit2/FFI round trip in a throwaway repo, never the checkout.
work=$(mktemp -d)
(
cd "$work" && git init -q .
"$BIN" init
"$BIN" create "smoke test card" >/dev/null
"$BIN" list --compact
id=$("$BIN" list --compact | awk 'NR==1{gsub(/#/,"",$1); print $1}')
"$BIN" move "$id" in-progress --claim smoke
"$BIN" handoff "$id" --claim smoke --note ok
"$BIN" backup > board.yaml && test -s board.yaml
)
echo "trap2 (libgit2 board flow): OK"
echo "verify: OK"
```
Then: `chmod +x scripts/verify-binary.sh`. Adjust the id-extraction and any flag to match what Step 1 showed.
- [ ] **Step 3: Run the verify against the locally built binary**
Run: `./scripts/verify-binary.sh /tmp/karrbuild/karr`
Expected: prints `trap1 ... OK`, `trap2 ... OK`, `verify: OK`, exit 0. A failure on a single subcommand means that `Cmd::*` class needs its namespace covered by a glob in `build-binary.sh` (it already uses `App::karr::Cmd::**`, so this should pass â...
- [ ] **Step 4: Commit**
```bash
git add scripts/verify-binary.sh
git commit -m "build: scripts/verify-binary.sh smoke-tests the packed binary
Loads every dynamically-resolved subcommand (trap 1) and runs one real
libgit2 board flow in a throwaway repo (trap 2), the two failures a pp build
only shows at runtime. CI gates asset upload on this."
```
---
### Task 3: `.github/workflows/release-binaries.yml` â build the matrix and attach assets
**Files:**
- Create: `.github/workflows/release-binaries.yml`
- Reference: `.github/workflows/ci.yml` (existing patterns â container, checkout, safe.directory)
**Interfaces:**
- Consumes: `scripts/build-binary.sh`, `scripts/verify-binary.sh`, a published release (or a `workflow_dispatch` tag input).
- Produces: four assets per target on the release.
**Notes:** The release event fires because `dzil release` creates the release with the maintainer's PAT, not a workflow `GITHUB_TOKEN`. The build container is the official multi-arch `perl:5.40-bookworm`; its perl is source-built so PAR::Packer's `li...
- [ ] **Step 1: Write the workflow**
```yaml
name: release-binaries
on:
release:
types: [published]
workflow_dispatch:
inputs:
tag:
description: Existing tag to build and attach assets to (dry-run)
required: true
permissions:
contents: write
jobs:
build:
strategy:
fail-fast: false
matrix:
include:
- arch: x86_64
runner: ubuntu-latest
- arch: arm64
runner: ubuntu-24.04-arm
( run in 0.662 second using v1.01-cache-2.11-cpan-99fa8243a42 )