# Homebrew Distribution & Release Guide (Tap-from-Repo)

ArgsBarg provides native, first-class support for packaging, releasing, and distributing command-line binaries and shell autocomplete configurations through Homebrew via a standard **tap-from-repo** model. This is designed to serve as a secure, standard-compliant mechanism for internal enterprise distribution.

---

## 1. Enterprise Distribution Model

Homebrew installs the **binary and shell completions** into the prefix. **Agent artifacts** (skills, MCP, app config) live under the user's home directory and are installed by the app's `configure` command — Homebrew's sandbox does not allow formula hooks to write there.

| Layer | Mechanism | Role in Lifecycle |
| --- | --- | --- |
| **Binary & Autocompletions** | Formula `install` block | Installs compiled binary and registers native shell autocompletions. |
| **Agent artifacts** | `{key} configure install` | User- or script-run after `brew install` / `brew upgrade`; installs skills/MCP and bootstraps `config.json`. |
| **Application Configuration** | `{key} configure install` | Required-config wizard on TTY when `program.appConfig` defines required parameters. |
| **Clean Uninstall** | `{key} configure uninstall` then `brew uninstall` | Removes `~/.agents` artifacts and app config; must run **before** uninstall while the binary is still on PATH. |

*Note: `just install-local` runs both steps for developers. End users see the commands in formula `caveats` and `brew info`.*

---

## 2. Distribution Strategies: Public vs. Private Taps

ArgsBarg supports both open-source public formulas and secure private enterprise distribution. You can configure your repository structure depending on your project type.

### Strategy A: Public Open-Source Taps (Default)

For open-source projects, Homebrew requires zero authentication. Users can tap your public repository and install your application with standard commands out of the box:

```bash
# Tap the public repository
brew tap <org>/<repo>

# Install the application
brew install <tap>/{key}

# Install agent artifacts (skills, MCP, config bootstrap)
{key} configure install
```

The generated Homebrew formula points directly to your public GitHub release asset URL, allowing anyone to install and receive automatic updates securely.

### Strategy B: Private & Proprietary Corporate Taps

For proprietary, inner-source, or internal company tools, security is paramount. ArgsBarg provides a built-in strategy to distribute packages securely from private GitHub repositories without exposing sensitive personal tokens or raw download links in your formula code.

#### 1. End-User Authentication:
Users authenticate locally using the standard GitHub CLI (`gh`), which Homebrew natively integrates with to retrieve download credentials:

```bash
# 1. Install and authenticate with GitHub CLI (if not already done)
brew install gh
gh auth login

# 2. Tap and install your private corporate repository
brew tap <org>/<repo> git@github.com:<org>/<repo>.git
brew install <tap>/{key}

# 3. Install agent artifacts (and required-config wizard on TTY when needed)
{key} configure install
```

#### 2. The Private Release Strategy:
Release formulae generated by ArgsBarg's scripts utilize a custom **`GitHubPrivateReleaseDownloadStrategy`**. This strategy executes the secure asset download through standard GitHub API requests, leveraging the user's local `gh` login credentials securely under the hood:

```ruby
url "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/{key}",
    using: GitHubPrivateReleaseDownloadStrategy
```

---

## 3. Standardized Formula Pattern

ArgsBarg standardizes your Homebrew formulas. A typical generated formula (`Formula/{key}.rb`) is incredibly clean:

```ruby
class Myapp < Formula
  desc "My application description"
  homepage "https://github.com/org/myapp"
  url "https://github.com/org/myapp/releases/download/v1.0.0/myapp.zip"
  sha256 "a1b2c3d4e5f6g7h8..."
  version "1.0.0"

  def install
    bin.install "myapp"
    # Auto-generates shell completions for bash, zsh, and fish directly from the executable
    generate_completions_from_executable(bin/"myapp", "completion", base_name: "myapp")
  end

  def caveats
    <<~EOS
      After install or upgrade:
        myapp configure install

      Before uninstall:
        myapp configure uninstall
        brew uninstall <tap>/myapp
    EOS
  end
end
```

---

## 4. Developer Iteration Workflow

ArgsBarg provides an optimized workflow for developers to build, package, and test their Homebrew installer locally before pushing releases.

### Local Staging Commands:

```bash
# 1. Build the local release binary
just build

# 2. Uninstall any existing formula/tap, stage and install locally, refresh agent artifacts
just install-local

# 3. Swap updated binaries quickly during tight edit cycles (run `just refresh` for skills/MCP)
just reinstall-local

# 4. Remove agent artifacts, uninstall the binary, and untap
just uninstall
```

### Under the Hood:

To ensure you test the exact formula that will be shipped to production, `just install-local` runs:

1.  `just uninstall` — `configure uninstall` (when possible), then remove keg and untap.
2.  `bun scripts/dev-formula.ts install` — Safely backs up your production formula and writes a temporary local dev formula using a `file://` URL pointing to your build directory.
3.  `brew reinstall || brew install --force` — Installs the package locally using Homebrew.
4.  `bun scripts/dev-formula.ts reset` — Automatically restores your production formula on disk.
5.  `{key} configure install` — Installs skills/MCP into `~/.agents` (outside Homebrew's sandbox).

---

## 5. Automated Release Pipeline

ArgsBarg automates the release cycle. A production-ready release is performed using a single command:

```bash
# Performs build, zips binary, updates Formula with new SHA-256, tags git, pushes, and uploads release asset
just release patch   # or minor | major
```

### Release Pipeline Steps:

1.  **Build**: Compiles the binary to `dist/{key}`.
2.  **Archive**: Packages the binary into a compressed `dist/{key}.zip`.
3.  **Integrity Check**: Calculates the cryptographically secure SHA-256 hash of the zip file.
4.  **Formula Sync**: Updates the version number and `sha256` parameter in `Formula/{key}.rb`.
5.  **Tag & Push**: Commits changes, tags the repository with the new version, pushes to GitHub, and publishes the compiled zip to GitHub Releases.

### Older Release Retention & Cleanup:

To keep your storage footprint clean, the pipeline supports purging stale historical release assets while preserving the git tags:

```bash
just release --purge              # Interactive tag purge of older release records
just release --purge --yes        # Silent automated purge (useful in CI/CD)
just release --purge --dry-run    # Preview list of tag deletions
```

---

## 6. Directory Defaults

Applications packaged via ArgsBarg adhere to standard system directories:
*   **Resolved Configuration Path**: `~/.local/lib/<sanitized-key>/config.json`
*   **Agent skill path**: `~/.agents/skills/<key>/`
*   **Auto-Exports**: Developers can import `resolveAppConfigPath` or `displayAppConfigPath` directly from `argsbarg` to display helpful directories in help screens.