feat(KB-142): fix CLI native module packaging with lazy loading

- Implement lazy native module loading with graceful degradation for standalone CLI

- Align release workflows with executable payload structure

- Update macOS signing script for single-executable bundles

- Add documentation for standalone CLI packaging (STANDALONE.md)

- Create changeset for patch release
This commit is contained in:
gsxdsm
2026-03-30 23:56:01 -07:00
parent 7eb9bddfd4
commit 9e8cf21058
8 changed files with 242 additions and 89 deletions

View File

@@ -147,6 +147,14 @@ dist/
- `linux-x64/` - Linux x64
- `win32-x64/` - Windows x64
**Important:** When distributing or moving the binary, ensure the `client/` and `runtime/` directories are copied alongside it. Terminal functionality will be unavailable if runtime assets are missing.
**Important:** When distributing or moving the binary, ensure the `client/` and `runtime/` directories are copied alongside it. Terminal functionality will gracefully degrade (return HTTP 503) if runtime assets are missing — the dashboard will continue to work but terminal sessions won't be available.
See the [GitHub repository](https://github.com/dustinbyrne/kb) for platform-specific binaries and build instructions.
**How it works:**
When the dashboard starts from a Bun-compiled binary, it attempts to set up native module resolution so `node-pty` can find its platform-specific `.node` files. This involves:
1. Copying native assets to a temp directory (`/tmp/kb-bunfs-<pid>/kb/prebuilds/<platform>/`)
2. Attempting to create a symlink at `/$bunfs/root` pointing to the temp directory (Unix platforms)
3. If the symlink can't be created (e.g., macOS permissions), pre-loading the native module via `process.dlopen()`
If all resolution methods fail, terminal creation gracefully returns `null`, which the HTTP layer converts to a 503 Service Unavailable response.
**Cross-compilation:** Native assets are staged per-platform during build. When cross-compiling, only the target platform's assets are included. PTY functionality requires running on a platform with matching native assets.