Files

T

José Almeida 0c0c64f5c4 docs: draft homebrew-core formula and submission spec (#904 )

* 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.

2026-05-19 13:52:07 +01:00

3.5 KiB

Raw Blame History

status, created, owner

status	created	owner
draft	2026-05-14	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.

3.5 KiB Raw Blame History

Homebrew Core Submission

Why

What

Scenarios

Out of scope

3.5 KiB

Raw Blame History