Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat(homebrew): provide a managed service and safe upgrade path

Open
  • Is something wrong?
#1,357 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
70/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
documentation, release

Research direction

Start with the GoReleaser release config (.goreleaser.yml/.goreleaser.yaml) browsers→brews section for the engram formula and add an opt-in service do stanza using opt_bin/"engram" with serve, keep_alive true and log paths. Then update the installation/upgrade documentation (the Homebrew section) to cover the one-time unmanaged-daemon transition, brew services start/restart gentleman-programming/tap/engram, and the Brewfile restart_service: :changed route, explicitly warning that plain brew upgrade does not restart a running process. Done looks like: a rendered formula containing the service block plus a release-config regression check (e.g. a test asserting the service block survives generation).

Written by the indexing model from the issue text.

Description

priority:medium status:needs-review type:feature
🔍 Problem Description

The GoReleaser-generated Homebrew formula for engram has no service do stanza. An unmanaged engram serve can survive a binary upgrade in the old, now-unlinked Cellar path and keep port 7437 occupied indefinitely. I reproduced this after upgrading 1.20.0 to 2.0.0: lsof showed the listener still executing /opt/homebrew/Cellar/engram/1.20.0/bin/engram, although engram --version on PATH reported 2.0.0. The Pi adapter on npm latest then refused memory operations with an opaque ownership-mismatch error.

This is distinct from #279 (daemon status plus a manual launchd template), #1255 (client diagnostic, fixed on main), and #1346 (that diagnostic not yet published). The formula still provides no standard managed-service path, and plain brew upgrade engram does not restart an unmanaged daemon.

💡 Proposed Solution
  1. Add an opt-in Homebrew service definition in the upstream GoReleaser brews configuration (the generated tap formula must not be hand-edited). Use opt_bin/"engram" with serve, keep_alive true, and standard log paths. Do not auto-start the service at install time or terminate a listener whose ownership cannot be established.
  2. Document the one-time transition from an unmanaged daemon (stop the old listener only after verifying it), brew services start gentleman-programming/tap/engram, and verification through /health/CLI. Document that plain brew upgrade engram may leave a still-running old process; the supported post-upgrade path should explicitly brew services restart ..., or use a Brewfile with restart_service: :changed and brew bundle to automate restarts. Do not imply that KeepAlive replaces a still-running process automatically.
  3. Add a deterministic release-config/formula-render regression check, if practical, so future generated formulas retain the service block.

I'd like to prepare a focused PR if the maintainers approve the approach. An alternative would be a dedicated engram upgrade command, but that is a much larger and more dangerous change to process ownership.

📦 Affected Area

Other (Homebrew release configuration and installation documentation)

🔄 Alternatives Considered
  • #279's manual launchd recipe works, but isn't integrated with brew services and is easy to miss.
  • Killing the listener automatically from Pi or a post-install hook is unsafe: a port occupant without a matching instance ID must be treated as untrusted.
  • KeepAlive by itself cannot reload a process that stays alive during brew upgrade; document an explicit managed restart path instead.
📎 Additional Context

The engram 2.0.0 formula in Gentleman-Programming/homebrew-tap/Formula/engram.rb is GoReleaser-generated and contains no service do block. The old server's pre-v2 /health response lacks an instance_id; its version field is hardcoded 0.1.0, so it is not a reliable running-binary version indicator. Verify the process image path when diagnosing this case. Related: #279, #1255, #1346.

Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
11h 17m
Merged PRs (30d)
334

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.