Skip to content

Keen Code Distribution Plan

Goal

Distribute keen through three install channels, backed by GitHub pipeline automation: - Install script (curl | bash) as recommended path - Homebrew as native package manager path - npm as deprecated compatibility path

1. Release Foundations (One-Time)

  • Finalize canonical repo path: github.com/<org>/keen-code.
  • Update go.mod module path from github.com/user/keen-code to actual repo.
  • Standardize binary name as keen.
  • Adopt semantic versioning tags (v0.1.0, v0.2.0, etc.).
  • Define release policy (stable vs prerelease) in README or VERSIONING.md.

2. Build + Package with GoReleaser

  • Add .goreleaser.yaml to build cross-platform artifacts:
  • darwin/amd64, darwin/arm64
  • linux/amd64, linux/arm64
  • optional: windows/amd64
  • Produce:
  • compressed archives (tar.gz/zip)
  • checksums file (checksums.txt)
  • autogenerated changelog
  • Publish assets directly to GitHub Releases on tag pushes.

3. GitHub Actions Pipeline Design

Split CI and release responsibilities.

CI workflow (.github/workflows/go.yml)

  • Trigger: PRs and pushes to main.
  • Keep current checks:
  • go mod verify
  • go build ./...
  • go test -race ./...
  • go vet ./...
  • gofmt check

Release workflow (.github/workflows/release.yml)

  • Trigger: tag push matching v*.
  • Steps:
  • checkout
  • setup Go
  • run tests
  • run GoReleaser
  • Permissions:
  • contents: write to create GitHub Releases
  • Secrets:
  • default GITHUB_TOKEN
  • optional signing keys for artifact signing
  • Create scripts/install.sh that:
  • detects OS + architecture
  • fetches latest or specified version (e.g. -v v1.2.3)
  • downloads archive + checksums.txt from GitHub Releases
  • verifies SHA256 before install
  • installs binary into /usr/local/bin or $HOME/.local/bin
  • Host script at stable URL (raw GitHub or dedicated domain).
  • Document usage:
curl -fsSL https://<host>/install.sh | bash
  • Support pinned-version install for reproducibility:
curl -fsSL https://<host>/install.sh | bash -s -- -v v0.1.0

5. Homebrew Distribution

  • Prefer Homebrew formula (recommended for CLI binaries), not cask.
  • Create tap repository: keen-code/homebrew-tap.
  • Add formula keen.rb containing:
  • release archive URL
  • sha256
  • version
  • Automate formula update on each release (via GoReleaser brews or dedicated workflow).
  • User install flow:
brew tap keen-code/tap
brew install keen
  • If needed later, add cask path as a secondary option.

6. npm Distribution (Deprecated Compatibility)

  • Publish small wrapper package (e.g. @keen-code/cli) that:
  • provides bin command keen
  • downloads matching prebuilt binary during install
  • verifies checksum before activation
  • Mark npm path as deprecated in docs/metadata once script + brew are stable.
  • User command:
npm install -g @keen-code/cli

7. Security + Reliability Controls

  • Add release smoke tests:
  • download produced artifact
  • execute keen --version
  • Add branch protection requiring CI pass before merge/tag.
  • Optional hardening:
  • artifact signing (e.g. cosign)
  • SBOM generation
  • provenance attestations

8. Documentation UX

Update install documentation to this order: 1. Install script (recommended) 2. Homebrew 3. npm (deprecated)

Also include troubleshooting for: - PATH setup - permission issues (sudo-less install) - unsupported architecture - proxy-restricted environments

9. Rollout Sequence

  1. Implement GoReleaser + release workflow.
  2. Implement and validate install.sh.
  3. Stand up Homebrew tap + automation.
  4. Publish npm wrapper package.
  5. Update docs and announce first release (v0.1.0).