#73: Add Homebrew-compatible packaging draft

[sandsower]

Summary

• Add a draft Homebrew formula at packaging/homebrew/beislid.rb.
• Add CLI runtime-layout validation before sourcing installer code.
• Support packaged layouts through BEISLID_HOME when bin/beislid is separated from the runtime root.
• Document that this is packaging validation only; full Homebrew support remains tracked in Add full Homebrew support for Beislið CLI #67.
• Add installer tests for packaged CLI fallback, invalid runtime layout errors, synthetic Homebrew symlink layout, and formula runtime subset coverage.

Verification

• python3 scripts/validate_skills.py
• bash scripts/test_install.sh — 55 passed
• ruby -c packaging/homebrew/beislid.rb
• git diff --check

Review notes

• Cross-host smoke skipped by request because this Phase 4 change is packaging/docs/test focused.
• Local review found an invalid BEISLID_HOME error-path gap; fixed and retested.
• Fresh-eyes recheck found no remaining Critical or Important issues.
• Untracked .codex and RELEASE_NOTES.md were left unstaged and are not part of this PR.

Summary by CodeRabbit

• New Features

  • CLI now validates runtime layout at startup and shows clear guidance when required runtime pieces are missing.
  • Draft Homebrew packaging that installs a runtime subset and exposes the CLI.
  • Support for BEISLID_HOME to locate the runtime when binaries are relocated.

• Documentation

  • README and docs updated with Homebrew packaging draft and packaged-layout guidance.

• Tests

  • Added packaged-CLI tests covering Homebrew-style layouts and validation behaviors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 17c179d1-7e84-4eeb-b95a-06a759005467

📥 Commits

Reviewing files that changed from the base of the PR and between 3ad46d4 and cdb6a45.

📒 Files selected for processing (1)

• bin/beislid

🚧 Files skipped from review as they are similar to previous changes (1)

• bin/beislid

---

📝 Walkthrough

Walkthrough

Adds a draft Homebrew formula and docs, expands the CLI entrypoint to validate required runtime layout (supports overridable BEISLID_HOME), and adds packaged-layout tests and a test helper to exercise Homebrew-style installs and failure messaging.

Changes

Homebrew packaging and packaged runtime support

Layer / File(s)	Summary
Runtime layout validation and BEISLID_HOME resolution bin/beislid	Broadens BEISLID_ROOT repointing to use BEISLID_HOME when the initially resolved root lacks required runtime components; adds _validate_runtime_layout(root) that checks for scripts/install_lib.sh, skills/, and install.sh and exits with an error listing missing items before sourcing installer code.
Homebrew formula definition packaging/homebrew/beislid.rb	New draft Homebrew formula installs runtime assets under libexec, exposes bin/beislid via a symlink to libexec/bin/beislid, includes caveats about draft status and BEISLID_HOME, and provides CLI tests for help and status.
Packaged layout test helpers and cases scripts/test_install.sh	Adds run_packaged_cli() helper and tests covering BEISLID_HOME fallback, incomplete runtime-layout error reporting, invalid BEISLID_HOME handling, and Homebrew-style libexec/bin symlink layouts; registers tests in the main suite.
User documentation docs/configuration.md, docs/how-to-use.md, README.md	Adds notes documenting the draft Homebrew formula location and status, packaged layout expectations, the CLI’s runtime-layout validation behavior, and guidance to use BEISLID_HOME when the binary is separated from the runtime root.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• [#51 Phase 4] Add Homebrew-compatible packaging draft #73: Implements the draft Homebrew formula and CLI runtime-layout validation described in the issue.
• Add full Homebrew support for Beislið CLI #67: Adds and exercises Homebrew packaging support and BEISLID_HOME guidance tracked by this issue.

Possibly related PRs

• sandsower/beislid#74: Modifies the same CLI entrypoint; this PR builds validation and BEISLID_HOME handling on top of that work.

Poem

🐰 In libexec and bottles I hop with glee,

bin finds home where the scripts ought to be,
BEISLID_HOME points the cozy way,
Tests nod approval, docs light the day,
A tiny formula, packaged merrily ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: adding a Homebrew-compatible packaging draft, which aligns with the primary objectives of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase-4-homebrew-packaging-draft

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bin/beislid`:
- Around line 22-28: The current conditional only falls back to BEISLID_HOME
when scripts/install_lib.sh is missing; expand it to detect any incomplete
runtime layout by checking all required entries (e.g., scripts/install_lib.sh,
skills/ directory, install.sh) before refusing the current BEISLID_ROOT. Update
the conditional that references BEISLID_ROOT and BEISLID_HOME so it triggers
when BEISLID_HOME is set and any of the required files/dirs are absent (use -f
for files, -d for directories), then preserve the existing logic that sets
BEISLID_ROOT="$(cd "$BEISLID_HOME" && pwd)" if BEISLID_HOME is a directory or
assigns BEISLID_ROOT="$BEISLID_HOME" otherwise.

🪄 Autofix (Beta)

✅ Autofix completed

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0dc5f2cd-9980-4de7-96ba-38043f38d1c5

📥 Commits

Reviewing files that changed from the base of the PR and between bee7081 and 643a56a.

📒 Files selected for processing (6)

• README.md
• bin/beislid
• docs/configuration.md
• docs/how-to-use.md
• packaging/homebrew/beislid.rb
• scripts/test_install.sh

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Fixes Applied Successfully

Fixed 1 file(s) based on 1 unresolved review comment.

Files modified:

• bin/beislid

Commit: 3ad46d47c0d09b41100ab149e669e2f50b0f75ab

The changes have been pushed to the phase-4-homebrew-packaging-draft branch.

Time taken: 1m 40s