Story (Required)

As a macOS user, trying to install the `tektoncd-pac` command-line tool, I want the installation to complete successfully using Homebrew so that I can easily set up my development environment.

This story addresses a bug that prevents users on macOS from installing the `tektoncd-pac` binary via the official Homebrew tap. Fixing this improves the developer experience and removes a significant barrier to entry for macOS users who rely on Homebrew for package management.

Background (Required)

A user reported that they are unable to install `tektoncd-pac` using the Homebrew Cask on macOS. The installation fails with a specific error related to the Cask definition file. This prevents users from using the simplest and most common installation method on this platform.

The user was on macOS version 15.5 and ran the following command:

brew install --cask openshift-pipelines/pipelines-as-code/tektoncd-pac

The process fails with the following errors:

Error: Unexpected method 'bin' called during preflight on Cask tektoncd-pac.
...
Error: undefined method 'install' for nil
/opt/homebrew/Library/Taps/openshift-pipelines/homebrew-pipelines-as-code/Casks/tektoncd-pac.rb:34:in `block (2 levels) in Cask::CaskLoader::FromPathLoader#load'

The user confirmed they were able to use the binary after building it manually, indicating the issue lies with the Homebrew Cask formula and not the binary itself.

The original issue was reported in GitHub: https://github.com/openshift-pipelines/pipelines-as-code/issues/2182

Out of scope

• Changes to the `tektoncd-pac` binary itself.
• Fixing installation methods for other operating systems (e.g., Linux, Windows).
• Changes to the core Homebrew Cask functionality.

Approach (Required)

The error message `Unexpected method 'bin' called during preflight` and the stack trace pointing to the `tektoncd-pac.rb` file strongly suggest an issue with the Ruby DSL (Domain Specific Language) used in the Homebrew Cask definition.

1. *Analyze the Cask File*: Inspect the `Casks/tektoncd-pac.rb` file located in the `openshift-pipelines/homebrew-pipelines-as-code` repository.
2. *Correct the Syntax*: The `bin` stanza in a Homebrew Cask is used to link binaries. Its usage inside a `preflight` block is incorrect. The fix will likely involve moving the `binary` definition to the top level of the Cask block, as per Homebrew Cask documentation.
3. *Local Testing*: Test the corrected Cask file locally on a macOS machine. This involves:

• Tapping the local, modified version of the formula.
• Running `brew install --cask tektoncd-pac` to verify the fix.
• Running `brew uninstall tektoncd-pac` to ensure clean uninstallation.
  4. *Submit PR*: Create a Pull Request with the fix to the `openshift-pipelines/homebrew-pipelines-as-code` repository.

Dependencies

• Access to a macOS environment is required for testing the fix.

Acceptance Criteria (Mandatory)

• Given a user on a standard macOS environment with Homebrew installed,
• When the user runs `brew tap openshift-pipelines/pipelines-as-code`.
• And then runs `brew install --cask tektoncd-pac`.
• Then the installation must complete successfully without any errors.
• And the `tkn-pac` binary must be correctly installed and available in the system's PATH.
• And running `tkn-pac --version` should execute and display the correct version information.
• And running `brew uninstall tektoncd-pac` must successfully remove the application and its symlinks.

INVEST Checklist

Dependencies identified
Blockers noted and expected delivery timelines set
Design is implementable
Acceptance criteria agreed upon
Story estimated

Legend

Unknown
Verified
Unsatisfied

Done Checklist

• [ ] Code is completed, reviewed, documented and checked in
• [ ] Unit and integration test automation have been delivered and running cleanly in continuous integration/staging/canary environment
• [ ] Continuous Delivery pipeline(s) is able to proceed with new code included
• [ ] Customer facing documentation, API docs etc. are produced/updated, reviewed and published
• [ ] Acceptance criteria are met