feat: add GitHub release tarball workflow

[ThomasK33]

Summary

• add a hand-curated GitHub release workflow that packages a verified tarball, checksum, and metadata artifact before publishing a GitHub Release
• add a reusable scripts/pack-release.mjs seam and wire install smoke through it so future npm publication can reuse the same verified artifact preparation stage
• update install/release docs and add a dogfood proof bundle for the local tarball pack/install/verify flow

Behavior changes

• hosted prerelease/private installation is now documented around GitHub Release tarball assets instead of npm publication
• maintainers get a dedicated Release workflow with prepare-release and publish-github-release jobs plus explicit tag/package validation
• packaging smoke now shares the release tarball packer that emits checksum + metadata for automation reuse

Validation

• npm run verify
• local proof bundle under dogfood/20260410-release-tarball/

Proof / review artifacts

• dogfood/20260410-release-tarball/README.md
• dogfood/20260410-release-tarball/screenshots/01-release-proof.png
• dogfood/20260410-release-tarball/videos/release-proof.webm
• dogfood/20260410-release-tarball/recordings/release-proof.cast

Notes

• no design-doc deviations beyond documenting the new release process
• the hosted GitHub Actions release run was not executed from this workspace because that requires real remote tag/release context and repository credentials; the checked-in workflow and local artifact path were validated here

---

📋 Implementation Plan

Plan: GitHub release tarball workflow with npm-publish-ready seams

Goal

Add a hand-curated release workflow that produces a validated .tgz package on GitHub Releases, makes that asset the preferred private/prerelease install path, and keeps the implementation easy to extend with a future npm-publish job without over-engineering the first cut.

Evidence from the current repo

• .github/workflows/ci.yml already runs the quality bar and install smoke, but there is no release or publish workflow.
• package.json already has the core packaging hooks we can reuse:
  • build
  • pack:private
  • smoke:install
  • prepublishOnly
• scripts/smoke-install.mjs already validates the important packaging contract end to end:
  • npm pack --json --ignore-scripts --pack-destination <dir>
  • install the resulting tarball into an isolated prefix
  • run version --json and doctor --json from the installed CLI
• README.md already treats the built tarball as the guaranteed prerelease/private install route and the git install route as best-effort only.
• docs/RELEASE-PROCESS.md has validation and proof expectations but does not yet document GitHub release asset creation or npm publish steps.
• Important future constraint: the repo currently uses name: "agent-terminal", and the explore report found that name already exists on npm. The new workflow should therefore stay generic around package metadata and not assume the final npm publish target is settled.

Proposed implementation

Phase 1 — Add reusable release-artifact plumbing

Files: package.json, scripts/pack-release.mjs (new), optionally a small focused test if the script gains nontrivial logic.

1. Add a small repo-local packaging script dedicated to release artifacts instead of pushing JSON parsing and checksum logic into workflow YAML.
2. The script should:
   • optionally assume build already ran (preferred for CI),
   • call npm pack --json --ignore-scripts --pack-destination <dir>,
   • parse the returned metadata defensively,
   • assert the tarball exists and is non-empty,
   • derive package name/version/filename from the metadata instead of hardcoding agent-terminal,
   • emit machine-readable metadata (stdout JSON and/or metadata file) including tarball filename, package name, version, output path, and checksum.
3. Keep the existing private-pack flow working by either:
   • adding a new script such as pack:release, while leaving pack:private intact, or
   • refactoring pack:private to call the new script without changing user-facing behavior.
4. Keep the implementation minimal; only add a dedicated test if the new script contains enough logic to justify it. Otherwise rely on the existing install smoke plus targeted local invocation.

Quality gate after Phase 1

• Run the local packaging path into a temp directory.
• Confirm the metadata reports the expected tarball.
• Install the produced .tgz into an isolated prefix and verify version --json and doctor --json still succeed.

Phase 2 — Add a dedicated GitHub release workflow

Files: .github/workflows/release.yml (new), possibly package.json if helper scripts/commands are added.

1. Add a separate hand-curated release workflow rather than modifying the existing CI workflow.
2. Structure the workflow in jobs so the future npm-publish step can depend on the same verified release artifact:
   • prepare-release job
     • checkout source,
     • install/setup tooling the same way CI does,
     • validate release inputs/ref,
     • run the repo quality bar (mise run ci or the current equivalent),
     • run the new pack script into a stable output directory,
     • upload the tarball + checksum as workflow artifacts,
     • expose outputs such as package_name, package_version, tarball_filename, and checksum filename.
   • publish-github-release job
     • depend on prepare-release,
     • create or update the GitHub Release,
     • upload the .tgz and checksum asset,
     • include an install hint in the release body pointing users to the tarball asset rather than github:owner/repo.
3. Keep the workflow generic and future-proof:
   • derive filenames from script outputs rather than hardcoding agent-terminal-*.tgz,
   • keep GitHub release publishing isolated in its own job,
   • leave a clear seam for a later publish-npm job to depend on prepare-release.
4. Fail fast with explicit validation before doing release work:
   • assert the release tag/ref matches package.json version (for example, v1.2.3 ↔ 1.2.3),
   • fail if required assets are missing,
   • fail if the quality bar or smoke install fails.
5. Prefer a low-dependency release upload path (for example gh release create/upload or an equivalent maintained approach) so the workflow stays easy to audit and extend.

Suggested workflow shape

on:
  workflow_dispatch:
    inputs:
      tag:
        required: true
  push:
    tags:
      - 'v*'

jobs:
  prepare-release:
    outputs:
      package_name: ...
      package_version: ...
      tarball_filename: ...
      checksum_filename: ...

  publish-github-release:
    needs: prepare-release

  # Future follow-up:
  # publish-npm:
  #   needs: prepare-release

Quality gate after Phase 2

• Run the new workflow on a scratch tag/release.
• Verify the workflow publishes the .tgz and checksum assets.
• Download the hosted tarball and confirm it installs successfully into a fresh isolated prefix.

Phase 3 — Update install and release-process documentation

Files: README.md, docs/RELEASE-PROCESS.md, and only any additional docs that directly reference the old prerelease install path.

1. Update README.md installation guidance so the preferred hosted prerelease path is the GitHub Release tarball asset.
2. Keep the source/git install route documented as an explicit build-from-source path with caveats, not the recommended install story.
3. Document both release-asset consumption modes where relevant:
   • direct npm install -g <release-asset-url> for environments where the asset URL is accessible,
   • authenticated download followed by npm install -g ./agent-terminal-<version>.tgz for private-release environments.
4. Update docs/RELEASE-PROCESS.md with:
   • release prerequisites,
   • version/tag expectations,
   • workflow trigger steps,
   • release asset verification steps,
   • the fact that npm publish is intentionally not wired yet.
5. If any docs currently imply npm publication is already available for this repo, tighten the language so it reflects the new GitHub-release-tarball reality and the future npm-publish follow-up.

Quality gate after Phase 3

• Follow the updated README steps verbatim in a clean environment.
• Confirm the documented release workflow steps match the implemented workflow names/inputs.

Future npm-publish seam

This change should stop short of publishing to npm, but the structure should make the follow-up small:

• the release workflow should already surface verified package metadata and artifact names,
• a future publish-npm job should be able to depend on prepare-release instead of rebuilding the package from scratch,
• docs should explicitly call out that npm publication depends on a separate registry/name decision,
• because the package name may change before npm publication, the workflow and scripts should always read package metadata dynamically.

Risks and decision points

• npm name conflict: the explore report indicates agent-terminal already exists on npm; future publish may require a scoped or renamed package. Do not bake the current name into workflow logic beyond reading it from package.json.
• Private release auth: private GitHub release assets may not support the same frictionless install flow as public assets. The docs should include an authenticated download fallback rather than promising a raw URL install everywhere.
• Versioning strategy: this plan assumes version bumps remain manual for now and the workflow validates tag/version alignment instead of mutating repo state.
• Scope control: avoid broad refactors of scripts/smoke-install.mjs unless reuse is clearly worth the extra surface area.

Acceptance criteria

• A new GitHub Actions release workflow can produce a validated npm tarball and attach it to a GitHub Release.
• The release workflow fails fast on version/ref mismatch and on any failed quality gate.
• The tarball asset remains installable with npm in an isolated prefix.
• The implementation exposes enough structured metadata/outputs that a future npm-publish job can reuse the verified release preparation stage.
• README and release-process docs reflect the GitHub-release-tarball flow and clearly separate it from the git install path.

Dogfooding and proof plan

Local CLI proof

1. Use isolated temp directories for the tarball output, install prefix, and AGENT_TERMINAL_HOME.
2. Run the release-pack command locally and install the resulting .tgz into the isolated prefix.
3. Run:
   • agent-terminal version --json
   • agent-terminal --home "$AGENT_TERMINAL_HOME" doctor --json
4. Capture:
   • at least one terminal screenshot showing the produced tarball and successful install,
   • one screen recording covering pack → install → version/doctor verification.

Hosted GitHub proof

1. Trigger the release workflow on a scratch tag/release.
2. Use the agent-browser skill to inspect the GitHub Actions run and the resulting Release page.
3. Capture:
   • a screenshot of the successful workflow run,
   • a screenshot of the Release page showing the .tgz and checksum assets,
   • a screen recording of downloading the asset and installing it in a fresh environment.
4. If the repo/release is private, verify the authenticated download + local install path rather than assuming a public direct-URL install.

Proof bundle expectations

• Store reviewer-facing evidence under a new dogfood/ bundle for this feature.
• Include the exact commands used, screenshots, and video files.
• In Exec mode, attach the key screenshots/videos in the final handoff so reviewers can confirm the workflow and install path visually.

---

Generated with mux • Model: openai:gpt-5.4 • Thinking: xhigh