root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
Download Patch File Download Diff File Expand all files Collapse all files

12
packages/cli/STANDALONE.md
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.

12
packages/cli/src/bin.ts
View File

@@ -15,11 +15,6 @@ import { mkdtempSync, writeFileSync, existsSync } from "node:fs";
import { join, dirname } from "node:path";
import { tmpdir } from "node:os";
// ── Runtime native module resolution patch ───────────────────────────
// This must be imported before any modules that load native binaries (node-pty)
// It sets up paths so the standalone binary can find staged native assets.
import "./runtime/native-patch.js";
// @ts-expect-error -- Bun-only global; undefined in Node
const isBunBinary = typeof Bun !== "undefined" && !!Bun.embeddedFiles;
@@ -119,6 +114,13 @@ async function main() {
try {
switch (command) {
case "dashboard": {
// Initialize native module resolution for Bun binary before starting dashboard
// This sets up the paths so node-pty can find its native assets
if (isBunBinary) {
const { initNativePatch } = await import("./runtime/native-patch.js");
initNativePatch();
}
const portIdx = args.indexOf("--port");
const portIdxShort = args.indexOf("-p");
const pi = portIdx !== -1 ? portIdx : portIdxShort;

188
packages/cli/src/runtime/native-patch.ts
View File

@@ -1,19 +1,20 @@
/**
* Native Module Runtime Resolution Patch
*
* This module creates the directory structure that Bun's compiled binary
* expects for resolving relative paths to native modules.
*
*
* This module sets up the directory structure needed for node-pty to find its native
* modules when running from a Bun-compiled binary.
*
* When Bun compiles a binary, it creates a virtual filesystem at /$bunfs/root/
* where the bundled code runs from. Node-pty tries to load its native module
* using paths relative to this virtual location.
*
* We create a real directory structure at /tmp/kb-bunfs-root/kb/ that mirrors
* the virtual structure, and set up symlinks so the native module can be found.
* where bundled code runs. Node-pty looks for native modules at:
* /$bunfs/root/prebuilds/<platform>-<arch>/pty.node
*
* This module creates a real directory structure at /tmp/kb-bunfs-<pid>/ that mirrors
* the expected structure, then attempts to create a symlink from /$bunfs/root to that
* temp directory (on macOS/Linux) so node-pty can find the native assets.
*/
import { join, dirname, basename } from "node:path";
import { existsSync, copyFileSync, mkdirSync, symlinkSync, rmSync } from "node:fs";
import { join, basename, dirname } from "node:path";
import { existsSync, copyFileSync, mkdirSync, symlinkSync, rmSync, lstatSync, readlinkSync } from "node:fs";
import { tmpdir } from "node:os";
// Detect Bun-compiled binary
@@ -21,24 +22,24 @@ import { tmpdir } from "node:os";
const isBunBinary = typeof Bun !== "undefined" && !!Bun.embeddedFiles;
let initialized = false;
// The virtual root that Bun uses
const BUNFS_ROOT = "/$bunfs/root";
let bunfsSymlinkPath: string | null = null;
function findStagedNativeDir(): string | null {
const platform = process.platform === "darwin" ? "darwin" :
process.platform === "linux" ? "linux" :
const platform = process.platform === "darwin" ? "darwin" :
process.platform === "linux" ? "linux" :
process.platform === "win32" ? "win32" : "unknown";
const arch = process.arch === "arm64" ? "arm64" :
const arch = process.arch === "arm64" ? "arm64" :
process.arch === "x64" ? "x64" : "unknown";
const prebuildName = `${platform}-${arch}`;
// Look next to the executable first
const execDir = dirname(process.execPath);
const nextToBinary = join(execDir, "runtime", prebuildName);
if (existsSync(join(nextToBinary, "pty.node"))) {
return nextToBinary;
}
// Check KB_RUNTIME_DIR env var
if (process.env.KB_RUNTIME_DIR) {
const envPath = join(process.env.KB_RUNTIME_DIR, prebuildName);
if (existsSync(join(envPath, "pty.node"))) {
@@ -50,26 +51,54 @@ function findStagedNativeDir(): string | null {
}
/**
* Create a symlink structure that helps node-pty find its native module.
*
* The idea: Create a temp directory structure that looks like:
* /tmp/kb-bunfs-root/kb/prebuilds/darwin-arm64/pty.node -> <staged>/pty.node
*
* Then we try to influence the module loader to look here.
* Clean up any stale /$bunfs/root symlinks from previous runs.
* This handles cases where a previous process crashed and left a dangling symlink.
*/
function setupNativeResolution(): void {
function cleanupStaleBunfsLinks(): void {
if (process.platform === "win32") return; // Windows doesn't use symlinks for this
const bunfsRoot = "/$bunfs/root";
try {
if (existsSync(bunfsRoot)) {
const stats = lstatSync(bunfsRoot);
if (stats.isSymbolicLink()) {
const target = readlinkSync(bunfsRoot);
// If the target is a temp dir that no longer exists, remove the stale link
if (target.includes("kb-bunfs-") && !existsSync(target)) {
rmSync(bunfsRoot);
console.log("[kb-native-patch] Cleaned up stale /$bunfs/root symlink");
}
}
}
} catch {
// Ignore errors during cleanup
}
}
/**
* Set up the native module resolution structure.
*
* Creates:
* /tmp/kb-bunfs-<pid>/kb/prebuilds/<platform>-<arch>/
* ├── pty.node
* └── spawn-helper (Unix only)
*
* Then attempts to create a symlink at /$bunfs/root pointing to the temp directory
* so that node-pty's relative require() can find the native module.
*/
export function setupNativeResolution(): { success: boolean; nativeDir: string | null } {
const nativeDir = findStagedNativeDir();
if (!nativeDir) {
console.warn("[kb-native-patch] No native assets found, terminal will be unavailable");
return;
return { success: false, nativeDir: null };
}
// Set spawn-helper location
// Set spawn-helper location (Unix platforms)
if (process.platform !== "win32") {
process.env.NODE_PTY_SPAWN_HELPER_DIR = nativeDir;
}
// Store reference
// Store reference for other code to use
process.env.KB_NATIVE_ASSETS_PATH = nativeDir;
// Create the fake bunfs structure
@@ -79,49 +108,116 @@ function setupNativeResolution(): void {
const platformDir = join(prebuildsDir, basename(nativeDir));
try {
// Clean up any previous stale links first
cleanupStaleBunfsLinks();
// Create directory structure
mkdirSync(platformDir, { recursive: true });
// Copy native files to this location
copyFileSync(join(nativeDir, "pty.node"), join(platformDir, "pty.node"));
const ptyNodeDest = join(platformDir, "pty.node");
copyFileSync(join(nativeDir, "pty.node"), ptyNodeDest);
if (existsSync(join(nativeDir, "spawn-helper"))) {
copyFileSync(join(nativeDir, "spawn-helper"), join(platformDir, "spawn-helper"));
}
// Store the path for potential use
process.env.KB_FAKE_BUNFS_ROOT = tmpRoot;
// We can't actually create /$bunfs/root as it's a virtual path
// But we can try to influence NODE_PATH
const nodeModulesAtRoot = join(tmpRoot, "node_modules");
mkdirSync(nodeModulesAtRoot, { recursive: true });
// Prepend to NODE_PATH
const current = process.env.NODE_PATH || "";
const sep = process.platform === "win32" ? ";" : ":";
process.env.NODE_PATH = tmpRoot + sep + current;
console.log("[kb-native-patch] Set up native resolution at:", tmpRoot);
// Try to create symlink from /$bunfs/root to our temp directory
// This allows node-pty's relative require() to find the native module
if (process.platform !== "win32") {
const bunfsRoot = "/$bunfs/root";
try {
// Remove any existing symlink first (in case it was left by a crashed process)
if (existsSync(bunfsRoot)) {
const stats = lstatSync(bunfsRoot);
if (stats.isSymbolicLink()) {
rmSync(bunfsRoot);
}
}
// Create new symlink pointing to our temp kb directory
// We want /$bunfs/root -> /tmp/kb-bunfs-<pid>/kb
// So that /$bunfs/root/prebuilds/<platform>/pty.node resolves correctly
symlinkSync(kbDir, bunfsRoot);
bunfsSymlinkPath = bunfsRoot;
console.log("[kb-native-patch] Created /$bunfs/root symlink for native module resolution");
} catch (symlinkErr) {
// Symlink creation failed (likely permission denied) - not fatal
// The terminal service will try alternative loading methods
console.log("[kb-native-patch] Could not create /$bunfs/root symlink (permissions), using fallback");
}
}
console.log("[kb-native-patch] Native assets staged at:", tmpRoot);
return { success: true, nativeDir };
} catch (err) {
console.error("[kb-native-patch] Failed to setup resolution:", err);
console.error("[kb-native-patch] Failed to setup native resolution:", err);
return { success: false, nativeDir: null };
}
}
export function initNativePatch(): void {
/**
* Clean up the symlink we created (call this on process exit).
*/
export function cleanupNativeResolution(): void {
if (bunfsSymlinkPath && process.platform !== "win32") {
try {
if (existsSync(bunfsSymlinkPath)) {
const stats = lstatSync(bunfsSymlinkPath);
if (stats.isSymbolicLink()) {
rmSync(bunfsSymlinkPath);
}
}
} catch {
// Ignore cleanup errors
}
}
bunfsSymlinkPath = null;
}
/**
* Initialize the native module resolution patch.
* This should be called lazily (e.g., when dashboard starts), not at import time.
*/
export function initNativePatch(): { success: boolean; nativeDir: string | null } {
if (initialized || !isBunBinary) {
return;
return { success: true, nativeDir: process.env.KB_NATIVE_ASSETS_PATH || null };
}
setupNativeResolution();
const result = setupNativeResolution();
initialized = true;
// Register cleanup on exit
process.on("exit", cleanupNativeResolution);
process.on("SIGINT", () => {
cleanupNativeResolution();
process.exit(0);
});
process.on("SIGTERM", () => {
cleanupNativeResolution();
process.exit(0);
});
return result;
}
/**
* Check if terminal functionality is available (native assets found).
*/
export function isTerminalAvailable(): boolean {
if (!isBunBinary) return true;
return findStagedNativeDir() !== null;
}
/**
* Get the path to the staged native assets directory.
*/
export function getNativeDir(): string | null {
return findStagedNativeDir();
}
initNativePatch();
// Note: We do NOT auto-initialize at import time anymore.
// Callers should explicitly call initNativePatch() when needed.

70
packages/dashboard/src/terminal-service.ts
View File

@@ -26,10 +26,10 @@ let ptyLoadError: Error | null = null;
* Looks for runtime/<platform-arch>/ next to the binary.
*/
function findStagedNativeDir(): string | null {
const platform = process.platform === "darwin" ? "darwin" :
process.platform === "linux" ? "linux" :
const platform = process.platform === "darwin" ? "darwin" :
process.platform === "linux" ? "linux" :
process.platform === "win32" ? "win32" : "unknown";
const arch = process.arch === "arm64" ? "arm64" :
const arch = process.arch === "arm64" ? "arm64" :
process.arch === "x64" ? "x64" : "unknown";
const prebuildName = `${platform}-${arch}`;
@@ -60,37 +60,37 @@ async function loadPtyModule(): Promise<typeof import("node-pty")> {
throw ptyLoadError;
}
try {
if (isBunBinary) {
// In Bun-compiled binary, try to load with direct native path
const nativeDir = findStagedNativeDir();
if (nativeDir) {
// Set spawn-helper directory
// For Bun-compiled binary, set up native paths before loading
if (isBunBinary) {
const nativeDir = findStagedNativeDir();
if (nativeDir) {
// Set spawn-helper directory
if (process.platform !== "win32") {
process.env.NODE_PTY_SPAWN_HELPER_DIR = nativeDir;
// Try to load the native module directly first
const nativePath = join(nativeDir, "pty.node");
if (existsSync(nativePath)) {
try {
// Use process.dlopen to load the native module directly
// This bypasses node-pty's internal resolution
const nativeModule = { exports: {} };
(process as any).dlopen(nativeModule, nativePath);
// Now that we have the native module loaded, try importing node-pty
// which should find the already-loaded module
const mod = await import("node-pty");
ptyModule = mod;
return ptyModule as typeof import("node-pty");
} catch (directErr) {
// Direct loading failed, fall through to standard import
console.warn("[terminal] Direct native load failed, trying standard import:", directErr);
}
}
// Store reference for debugging
process.env.KB_NATIVE_ASSETS_PATH = nativeDir;
// Try to pre-load the native module using process.dlopen
// This can help when the normal require() path fails
const nativePath = join(nativeDir, "pty.node");
if (existsSync(nativePath)) {
try {
const nativeModule: { exports?: unknown } = { exports: {} };
// @ts-ignore - process.dlopen is Node internal
process.dlopen(nativeModule, nativePath);
console.log("[terminal] Pre-loaded native module via dlopen");
} catch (dlopenErr) {
// dlopen failed - log but continue, normal import might still work
console.log("[terminal] dlopen pre-load failed (continuing):", dlopenErr);
}
}
}
// Standard import path
}
try {
// Standard import path - the native-patch setup should have created
// the necessary symlink structure for node-pty to find the module
const mod = await import("node-pty");
ptyModule = mod;
return ptyModule as typeof import("node-pty");
@@ -435,7 +435,15 @@ export class TerminalService extends EventEmitter {
console.info(`Creating session ${id} with shell: ${shell} in ${cwd}`);
// Lazy-load node-pty module with proper error handling
const pty = await loadPtyModule();
let pty: typeof import("node-pty");
try {
pty = await loadPtyModule();
} catch (loadErr) {
// Native module couldn't be loaded (common in Bun binaries without proper setup)
// Return null for graceful degradation - routes will return 503
console.error(`[terminal] Failed to load PTY module: ${loadErr}`);
return null;
}
// Build PTY spawn options
const ptyOptions: IPtyForkOptions = {