You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d199d52
Browse filesBrowse the repository at this point in the historyBrowse files
fix(build): refuse a Node that cannot produce a distributable release (v1.22.0) (#102)
`npm run build:installers` died on a Homebrew Node with a bare execFileSync
stack trace and no message. The obvious reading is "the Node version is wrong",
and it is not.
`seaBinary` copies process.execPath and injects the app blob into it, so the
Node you build with is the Node you ship. Homebrew's is unsuitable twice over:
its formula passes --disable-single-executable-application, because SEA is
incompatible with their --shared build (nodejs/node#63126), and `otool -L`
shows it linking 22 dylibs under /opt/homebrew that no user has. The SEA
failure was preventing a broken artifact rather than causing one. No Homebrew
Node of any version can work, so neither upgrading nor downgrading is a remedy;
an official build at any current version is.
The build now checks both roles, which are different requirements on possibly
different binaries: the generator (process.execPath) needs SEA compiled in, and
the base (--node, defaulting to process.execPath) is what ships and must be
self-contained. Checking only the first would let a shared-build Node with SEA
enabled through, silently producing an installer that runs on one machine.
Where an official Node exists it recovers instead of complaining:
HYPERGATE_BUILD_NODE, then fnm/nvm/volta/asdf trees newest-first and
/usr/local/bin/node, re-running with the first that passes both checks and
passing the original args through, guarded against recursion. With nothing
usable it exits 1 with the cause and the remedy, printed rather than thrown.
foreignLibs parses the linker's own columns rather than scraping path-shaped
tokens, which had turned @rpath/libnode.147.dylib into /libnode.147.dylib.
CI was never affected: actions/setup-node installs official builds.
Co-authored-by: Claude Opus 5 <[email protected]>
Copy file name to clipboardExpand all lines: SPEC.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -260,6 +260,7 @@ The promise is **one command to a working gateway**: a user installs Hypergate a
260
260
| Merging a bump cuts the release | Since every PR bumps the version but releases were hand-tagged, bumps outran tags (v1.1.0 and v1.2.0 were both bumped and never released). `version-release.yml` watches pushes to `main` that touch `package.json`, and when that version has no tag yet it tags it and dispatches the release. It tags *and* dispatches because a tag pushed with `GITHUB_TOKEN` cannot trigger another workflow, so tagging alone would leave the release unfired and look like a silent success. Before tagging it runs `version:check` and requires `docs/releases/<version>.md`, so a partial bump or missing notes fails while nothing is tagged yet; hand-tagging remains the fallback | shipped | v1.3.0 |
261
261
| CI | Build + unit tests on Node 22 and 24, the HTTP and feature smokes, `cargo fmt`/`clippy`/`test` on Linux, macOS and Windows, the packaged-install smoke, and a standalone-daemon smoke | shipped | v0.9.0 |
262
262
| Runtime-free daemon | The daemon compiles into a single executable via Node's SEA support: the esbuild bundle is injected into a copy of the Node binary, and the UI is resolved relative to `process.execPath`. This is what lets an installer require nothing at all. Chosen over `bun build --compile`, which is less work and cross-compiles, because Bun has no `node:sqlite` and a Bun build would silently drop durable usage history and logs | shipped | v0.9.0 |
263
+
| A release build refuses a Node it cannot ship | `seaBinary` copies the running Node and injects the app blob into it, so **the Node you build with is the Node you ship**. Homebrew's Node is the wrong one twice over: its formula passes `--disable-single-executable-application` (the feature is incompatible with its `--shared` build, nodejs/node#63126), and it links 22 libraries under `/opt/homebrew` that no user has, so even with SEA enabled it would produce an installer that runs only on the machine that built it. `build:standalone` now checks both properties before building anything, and where an official Node is installed (fnm, nvm, volta, asdf, `/usr/local/bin`, or `HYPERGATE_BUILD_NODE`) it re-runs itself with that one instead of failing. Otherwise it exits 1 with the cause and the remedy rather than a stack trace from the middle of the build, and says plainly that the Node *version* is not the problem, since "update Node" is the natural and wrong conclusion. CI was never affected: `actions/setup-node` installs official builds | shipped | v1.22.0 |
263
264
| Native installers | One per platform, each built on its own OS: an NSIS `-setup.exe` for Windows, a drag-to-Applications `.dmg` for macOS (the app bundle carries both binaries and the manager UI; launching it creates per-user CLI links in a writable PATH directory), and `.deb`/`.rpm`/tarball for Linux. All per-user on Windows (no UAC), all carrying the daemon, the CLI, the tray agent and the manager UI. They reuse Hypergate's own commands for the parts that need judgement (`shortcut install`, `autostart on`, `icon`) rather than reimplementing them, and an uninstall deliberately leaves `~/.hypergate` intact. Since the manager window landed, the Linux packages depend on `webkit2gtk-4.1` (alongside GTK, which the tray already required); Windows uses the OS's WebView2 and macOS uses WKWebView, so nothing extra ships or installs there | shipped | v0.9.0 |
264
265
| Build artifacts on demand | The five-way platform matrix is a reusable workflow, so an installer can be built and tested without cutting a release | shipped | v0.9.0 |
265
266
| macOS is Apple silicon only | Intel Macs are not supported. The last Intel macOS runner (`macos-13`) is retired, so an Intel build could only ever be cross-compiled on an Apple silicon runner: nothing in CI could launch it, notarize a run of it, or smoke it, and its disk image job is what failed v1.7.1's release while the Apple silicon one succeeded. Dropping it takes `darwin-x64` out of the build matrix, the npm platform packages, the release assets and the site's download picker; an Intel visitor is told it needs an Apple silicon Mac, and an Intel install that checks for updates is offered none rather than a disk image that will not mount. The remaining Mac disk image is published as `hypergate-macos-apple-silicon.dmg` (the `-arm64` alias is kept, because links to it are published, and the *versioned* file keeps its `-arm64` name so 1.8.x's in-app updater still finds it) | shipped | v1.9.0 |
Copy file name to clipboardExpand all lines: TASKS.md
+38Lines changed: 38 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -623,6 +623,44 @@ Started as listing paperwork and turned up a real defect on the way: the bar the
623
623
- [x] **`build:mcpb` now finds npm when Homebrew installed node**: the same defect `72a9232` fixed in `build-npm.mjs` and `build-standalone.mjs` lived in a third copy of `npmCli()` here, and that commit never reached `main`, so the bundle could not be built on the dev Mac at all (`could not find npm-cli.js near /opt/homebrew/Cellar/node/...`). `npm_execpath` is checked first, with the Homebrew prefix path as a fallback for a direct `node scripts/...` run. · Added: 2026-08-26 · Done: 2026-08-26
624
624
- [x] **Verified**: 319 core + 94 daemon tests pass (2 new gateway assertions: a proxied tool's title and all four hints crossing the hop via a second fixture tool registered with `registerTool`, and a builtin's own title and hints reaching the client), `version:check` agrees across all eight files at 1.18.0, the HTTP smoke is green, `build:mcpb -- --self-signed` ends with the signature block present, and `mcpb validate` passes the manifest schema with the 512x512 icon accepted. · Added: 2026-08-26 · Done: 2026-08-26
625
625
626
+
## Epic 62: a release build that refuses the wrong Node (v1.22.0)
627
+
628
+
Philip, on being told installers cannot be built on his machine: *"is there a better approach then?
629
+
we shouldn't rely on an old version of node"*. He was right, and the honest answer turned out to be
630
+
that the diagnosis behind that sentence was incomplete.
631
+
632
+
- [x] **It was never about the Node version.** `process.config.variables.single_executable_application`
633
+
is `false` on this machine, and Homebrew's formula says why in a comment:
634
+
`--disable-single-executable-application`, because SEA is incompatible with their `--shared`
635
+
build (nodejs/node#63126). No Homebrew Node of any version will ever work, so upgrading is not a
636
+
remedy and neither is downgrading. · Added: 2026-08-26 · Done: 2026-08-26
637
+
- [x] **The more important half: that Node was never shippable anyway.** `seaBinary` copies
638
+
`process.execPath` and injects the blob into it, so the build Node *is* the shipped runtime.
639
+
`otool -L` shows Homebrew's Node linking 22 dylibs under `/opt/homebrew/opt/...`, none of which a
640
+
user has. The SEA failure was preventing a broken artifact rather than causing one, which reframes
641
+
the whole issue: the fix is an official Node, at any current version, not an old one. · Added: 2026-08-26 · Done: 2026-08-26
642
+
- [x] **Guard both roles, because they are different requirements on possibly different binaries.**
643
+
The *generator* (`process.execPath`) needs SEA compiled in; the *base* (`--node`, defaulting to
644
+
`process.execPath`) is what ships and must be self-contained. Checking only the first would let a
645
+
shared-build Node *with* SEA enabled sail through and silently ship an installer that works on one
- **Building the installers locally failed with an unreadable error.** On a machine whose Node came from Homebrew, `npm run build:installers` died with a bare stack trace and no message. The underlying reason is that Homebrew builds Node against shared libraries, which makes it unable to produce a single-file executable and, more importantly, unable to produce one that would run on anyone else's machine.
6
+
7
+
The build now checks for both problems before it starts, uses an official Node automatically if one is installed (fnm, nvm, volta, asdf, or `/usr/local/bin`), and otherwise stops with an explanation and the fix. It also says outright that the Node *version* is not the problem, because "update Node" is the natural conclusion and the wrong one.
8
+
9
+
Published releases were never affected: CI has always built them with official Node.
Copy file name to clipboardExpand all lines: package.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
{
2
2
"name": "hypergate",
3
3
"private": true,
4
-
"version": "1.21.0",
4
+
"version": "1.22.0",
5
5
"description": "Local-first runtime & manager for MCP servers — run servers securely (process sandbox or Docker), supervise them, and expose one gateway endpoint for any agent harness. A ToolHive rival you own.",
0 commit comments