Skip to content

Commit d199d52

Browse files
ermishclaude
andauthored
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]>
1 parent 1a0a3df commit d199d52

12 files changed

Lines changed: 206 additions & 10 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
"source": "./plugins/hypergate",
1414
"displayName": "Hypergate",
1515
"description": "Every MCP server Hypergate runs on this machine, through one local gateway.",
16-
"version": "1.21.0",
16+
"version": "1.22.0",
1717
"author": { "name": "Nekko Labs", "url": "https://hypergate.app" },
1818
"homepage": "https://hypergate.app",
1919
"repository": "https://github.com/nekko-labs/hypergate",

‎SPEC.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,7 @@ The promise is **one command to a working gateway**: a user installs Hypergate a
260260
| 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 |
261261
| 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 |
262262
| 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 |
263264
| 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 |
264265
| 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 |
265266
| 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 |

‎TASKS.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -623,6 +623,44 @@ Started as listing paperwork and turned up a real defect on the way: the bar the
623623
- [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
624624
- [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
625625

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
646+
machine. · [spec](SPEC.md#312-distribution-shipped) · Added: 2026-08-26 · Done: 2026-08-26
647+
- [x] **Recover rather than just complain**: `HYPERGATE_BUILD_NODE`, then fnm/nvm/volta/asdf trees
648+
(newest version first) and `/usr/local/bin/node`, re-running the script with the first Node that
649+
passes both checks and passing the original args through, guarded against recursion by
650+
`HYPERGATE_NODE_CHECKED`. With nothing usable it exits 1 with the cause and the remedy, printed
651+
rather than thrown: a machine-configuration problem with a known fix is only buried by a stack
652+
trace through the build script. · Added: 2026-08-26 · Done: 2026-08-26
653+
- [x] **`foreignLibs` parses the linker's own columns**, not anything path-shaped in the output. The
654+
first cut scraped `/`-prefixed tokens and turned `@rpath/libnode.147.dylib` into
655+
`/libnode.147.dylib`, which reads like a system path and is not one. Now `otool`'s
656+
`<name> (compatibility ...)` column and `ldd`'s `=> <path>`. · Added: 2026-08-26 · Done: 2026-08-26
657+
- [x] **Verified every branch on this machine**, including the ones with no real Node to test
658+
against: both detectors against Homebrew's Node (22 foreign libs, SEA false) *and* against
659+
`/bin/ls` and `/usr/bin/curl` as controls that must look self-contained (0 each, so no false
660+
positives); discovery, re-exec, argument passthrough and the recursion guard against a stand-in
661+
Node laid out the way nvm does; the `HYPERGATE_BUILD_NODE` override; and an unusable override
662+
failing exactly once rather than looping. Exit code 1, no stack trace. · Added: 2026-08-26 · Done: 2026-08-26
663+
626664
## Epic 61: a prompt that says who is actually asking (v1.21.0)
627665

628666
Philip, after a stray Touch ID prompt: *"it says 'hypergate is trying to reveal smoke token'. can we

‎apps/daemon/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@hypergate/daemon",
3-
"version": "1.21.0",
3+
"version": "1.22.0",
44
"private": true,
55
"type": "module",
66
"main": "dist/index.js",

‎apps/daemon/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ const TOKEN_KEY = 'bearerToken';
174174
// otherwise get a daemon on 7777 that the CLI then looks for somewhere else.
175175
const PORT = Number(process.env.HYPERGATE_PORT ?? process.env.PORT ?? 7777);
176176
const LISTEN_HOST = '127.0.0.1';
177-
const VERSION = '1.21.0';
177+
const VERSION = '1.22.0';
178178
/**
179179
* `--stdio` is a transient spawn by an agent harness, not the resident daemon.
180180
* It deliberately does NOT open the durable store: the rolled-up aggregates are

‎apps/shell/Cargo.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎apps/shell/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[package]
22
name = "hypergate-shell"
3-
version = "1.21.0"
3+
version = "1.22.0"
44
edition = "2024"
55
description = "Hypergate desktop shell: tray agent, CLI, and sandbox launcher"
66
license = "MIT"

‎docs/releases/1.22.0.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Building a release tells you when it cannot
2+
3+
### Bug fixes
4+
5+
- **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.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "hypergate",
33
"private": true,
4-
"version": "1.21.0",
4+
"version": "1.22.0",
55
"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.",
66
"license": "MIT",
77
"type": "module",

‎plugins/hypergate/.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
33
"name": "hypergate",
44
"displayName": "Hypergate",
5-
"version": "1.21.0",
5+
"version": "1.22.0",
66
"description": "Every MCP server Hypergate runs on this machine, through one local gateway.",
77
"author": { "name": "Nekko Labs", "url": "https://hypergate.app" },
88
"homepage": "https://hypergate.app",

0 commit comments

Comments
 (0)