# 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

## 4. Install Script Channel (Recommended)
- 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:

```bash
curl -fsSL https://<host>/install.sh | bash
```

- Support pinned-version install for reproducibility:

```bash
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:

```bash
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:

```bash
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`).
