José Almeida
0c0c64f5c4
* docs: draft homebrew-core formula and submission spec
Adds a source-build Formula/kandev.rb (parallel to the binary-install
formula in kdlbs/homebrew-kandev), plus spec.md + submission-checklist.md
under docs/specs/homebrew-core/.
* fix(homebrew): add uses_from_macos sqlite, drop head stanza
Address Greptile review on PR #904: declare sqlite as a build-time dep
for the cgo go-sqlite3 link, and drop the head stanza since
homebrew-core typically asks new formulae to omit it.
* chore(homebrew): bump formula pin to v0.49.0 for local preflight
* fix(homebrew): switch livecheck to git strategy with version regex
GithubLatest hits GitHub's API and is reserved for formulae that
consume release assets or where git tag inspection can't identify
the latest version. Ours uses the auto-generated tag archive and
publishes clean vX.Y.Z tags, so the default git strategy is the
right choice per docs.brew.sh/Brew-Livecheck.
* fix(release): replace rsync with cp -RL for cross-environment portability
Linuxbrew CI ships without rsync, which broke the homebrew-core
formula build. cp -RL provides the same dereference-symlinks behavior
on both BSD and GNU coreutils, no extra dependency required.
* Revert "fix(release): replace rsync with cp -RL for cross-environment portability"
This reverts commit 5599817f4f.
* fix(homebrew): add rsync as build dep
Linuxbrew CI ships without rsync, and package-web.sh uses
rsync --copy-links --safe-links to dereference pnpm's symlinks
while tolerating broken absolute symlinks from the content-addressed
store. Adding rsync as a build dep keeps the script unchanged.
* fix(homebrew): address maintainer review feedback
Apply review from SMillerDev on homebrew-core/pull/283241:
- Use std_go_args helper for both go build calls
- Invoke release scripts directly (rely on shebang) instead of bash
- Extract bundle assembly into scripts/release/package-bundle.sh
- Replace --version/--help test block with a functional health check
that boots the Go backend with an isolated data dir, polls
/api/v1/system/health, and shuts down cleanly
* fix(homebrew): address PR #904 review feedback
- spec.md: fix "no tap-tap" typo
- submission-checklist.md: bump stale v0.41.0 references to v0.49.0
- test block: rescue Errno::ESRCH/ECHILD in ensure so original failure
diagnostic isn't masked when the backend crashes early
* chore(homebrew): drop submission-checklist.md from PR
* docs(homebrew): align spec.md with current formula
- Add rsync to build deps list and note uses_from_macos sqlite
- Update livecheck snippet to match the regex form actually shipped
- Replace --help/--version test description with the health-check
block currently in Formula/kandev.rb
* fix(homebrew): move rsync to uses_from_macos
cubic flagged on PR #904: depends_on "rsync" trips
brew audit --new-formula because rsync ships with macOS.
uses_from_macos "rsync" => :build uses system rsync on
macOS and installs Homebrew's on Linux, which matches the
intent.
* fix(release): drop redundant chmod in package-bundle.sh
package-cli.sh:41 already runs chmod +x on cli.js when it creates
the file, so re-running chmod here is pure noise.
40 lines
3.5 KiB
Markdown
40 lines
3.5 KiB
Markdown
---
|
|
status: draft
|
|
created: 2026-05-14
|
|
owner: tbd
|
|
---
|
|
|
|
# Homebrew Core Submission
|
|
|
|
## Why
|
|
|
|
Kandev is currently installable via `brew install kdlbs/kandev/kandev` from the `kdlbs/homebrew-kandev` tap. The tap formula downloads pre-built release tarballs, which works for end users but is rejected by `homebrew/homebrew-core` policy. Landing in homebrew-core means:
|
|
|
|
- `brew install kandev` (no tap required) — lower friction discovery.
|
|
- Bottles are built and signed by Homebrew's CI, eliminating per-platform GH-release tarballs as the install path.
|
|
- Automated version bumps via `brew bump-formula-pr` once `livecheck` is wired up.
|
|
|
|
## What
|
|
|
|
- Author a homebrew-core-compliant `Formula/kandev.rb` that **builds entirely from source** — Go backend (cgo + sqlite via `mattn/go-sqlite3`), Next.js standalone web bundle, and the TypeScript CLI esbuild bundle.
|
|
- Source comes from the GitHub-generated tag archive (`https://github.com/kdlbs/kandev/archive/refs/tags/vX.Y.Z.tar.gz`); per-release sha256 is captured at submission/bump time.
|
|
- Build deps: `go => :build`, `pnpm => :build`. Runtime dep: `node` (CLI launcher + Next.js standalone server). `uses_from_macos "rsync" => :build` (used by `scripts/release/package-web.sh` to dereference symlinks in the Next.js standalone output) and `uses_from_macos "sqlite"` (cgo sqlite3 link) — both ship with macOS, only installed via Homebrew on Linux.
|
|
- Install layout: `libexec/{bin,web,cli}` plus a single `bin/kandev` wrapper produced by `write_env_script`, setting `KANDEV_BUNDLE_DIR=<libexec>` and `KANDEV_VERSION=<version>`. This is the contract `apps/cli/src/runtime.ts` already honors.
|
|
- `livecheck do; url :stable; regex(/^v?(\d+(?:\.\d+)+)$/i); end` — Git strategy (the default for `url :stable`) checks tags directly and avoids the GitHub API rate limit.
|
|
- Test block: spawns `libexec/bin/kandev` with an isolated `KANDEV_HOME_DIR` and random `KANDEV_SERVER_PORT`, polls `/api/v1/system/health` until the response contains `"healthy"` (60s timeout), then shuts the backend down. Also asserts the formula `version` appears in `bin/kandev --version`.
|
|
- Tap (`kdlbs/homebrew-kandev`) and its update script (`scripts/release/update-homebrew-tap.sh`) stay untouched — it remains the binary-install fast path; the homebrew-core formula is a parallel, source-built distribution.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** the homebrew-core PR is merged, **WHEN** a macOS user runs `brew install kandev`, **THEN** Homebrew downloads the source tarball, compiles the Go binaries, builds the Next.js + CLI bundles, installs them under `Cellar/kandev/X.Y.Z/{bin,libexec}`, and `kandev --help` prints "kandev launcher".
|
|
- **GIVEN** a new kandev release `vX.Y.Z` is tagged, **WHEN** Homebrew's auto-bump worker runs, **THEN** `livecheck` resolves the new tag from GitHub Releases and a bump PR is opened against the formula.
|
|
- **GIVEN** a maintainer reviews the PR, **WHEN** they run `brew install --build-from-source kandev` locally, **THEN** the build completes without network or sandbox failures and `brew test kandev` passes.
|
|
|
|
## Out of scope
|
|
|
|
- Migrating users from `kdlbs/homebrew-kandev` to homebrew-core (both can coexist; users opt in by switching tap reference).
|
|
- Linuxbrew bottle parity beyond what homebrew-core's CI provides by default.
|
|
- Vendoring JS dependencies via `resource` blocks — falls back here only if maintainers reject network-during-install.
|
|
- Changes to `.github/workflows/release.yml` or `scripts/release/update-homebrew-tap.sh`.
|
|
- Notability lobbying — submission goes in as-is; maintainers decide.
|