@adhdev/ghostty-vt-node 0.8.51 → 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# @adhdev/ghostty-vt-node
+
+Native Node binding for `libghostty-vt` — exposes a headless ghostty virtual
+terminal (`createTerminal`) used by daemon-core's `GhosttyVtTerminalBackend`.
+
+## ABI portability (read this first)
+
+The addon is a pure **Node-API (N-API)** binding (it exports
+`napi_register_module_v1`). N-API is **ABI-stable across Node major versions**, so
+a single compiled `.node` loads on every Node runtime that supports the N-API
+version it targets — **independent of `process.versions.modules`**
+(`NODE_MODULE_VERSION`, a.k.a. the "ABI" number: 115 ≈ node20, 127 ≈ node22,
+137 ≈ node24).
+
+Practically: you do **not** need a separate native build per Node version. The
+per-`nodeNNN` directory names under `prebuilt/` are an addressing convenience, not
+a hard requirement — the binaries are byte-identical per platform/arch.
+
+### Why prebuilts are committed
+
+`prebuilt/` is committed to git (only the `*-node137` triplet per platform) so
+that worktree/CI clones load the binding **without a build toolchain**. A clone
+with no committed prebuilt would fall through to compiling from source
+(cmake-js + zig + a `libghostty` fetch); when that toolchain is absent the loader
+throws `ghostty-vt binding unavailable`, which previously surfaced as an
+environment blocker on node24/ABI137 runners.
+
+Shipped triplets:
+
+```
+prebuilt/darwin-arm64-node137/   # macOS Apple Silicon
+prebuilt/linux-x64-node137/      # Linux x64
+prebuilt/win32-x64-node137/      # Windows x64
+```
+
+## Loader resolution order (`index.js`)
+
+1. `ADHDEV_GHOSTTY_VT_PREBUILT_DIR/<triplet>/ghostty_vt_node.node` (explicit override)
+2. `ADHDEV_GHOSTTY_VT_PREBUILT_DIR/ghostty_vt_node.node`
+3. `build/Release` or `build/Debug` (a local compile)
+4. `prebuilt/<exact-triplet>/ghostty_vt_node.node`
+5. **N-API fallback** — any `prebuilt/<platform>-<arch>-node*/ghostty_vt_node.node`
+   for the same platform/arch (this is what makes a brand-new ABI such as a
+   future node26 work without shipping a new directory).
+
+If nothing loads, the thrown error **names the running triplet and the list of
+available prebuilt triplets**, so an environment-blocker report is precise:
+
+```
+Unable to load @adhdev/ghostty-vt-node native binding for running triplet
+"darwin-arm64-node137". Available prebuilt triplets: [darwin-arm64-node137,
+linux-x64-node137, win32-x64-node137]. ...
+```
+
+## Producing / refreshing a prebuilt
+
+Build on the **target platform/arch** (cross-builds are not wired here) with the
+toolchain present (`cmake`, a C/C++ compiler, and `zig` for `libghostty`; set
+`ZIG_EXECUTABLE` if zig is not on `PATH`):
+
+```bash
+# Build for the running platform-arch and emit it into prebuilt/<triplet>/
+ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1 npm run build -w oss/packages/ghostty-vt-node
+
+# Then keep the node137-named dir (per ABI-portability) and commit it:
+#   git add oss/packages/ghostty-vt-node/prebuilt/<platform>-<arch>-node137/
+```
+
+Because the output is ABI-portable, you only need to build **once per
+platform/arch**; rename/keep the directory as the `node137` triplet and the
+runtime fallback covers all other Node versions on that platform.
+
+- macOS arm64 and Linux x64 can be produced on the corresponding native runner.
+- Windows x64 must be built on a Windows runner (MSVC; see the `if(MSVC)` block in
+  `CMakeLists.txt` for the required dynamic-CRT link flags).
+
+## Skipping the native build
+
+Set `ADHDEV_SKIP_GHOSTTY_VT_BUILD=1` to skip compilation when no prebuilt matches
+(useful in environments that intentionally run without the terminal backend).

package/index.js

@@ -1,20 +1,93 @@
+const fs = require('node:fs');
 const path = require('node:path');
 
+const ADDON_FILE = 'ghostty_vt_node.node';
+const PREBUILT_ROOT = path.join(__dirname, 'prebuilt');
+
 function getTriplet() {
     return `${process.platform}-${process.arch}-node${process.versions.modules}`;
 }
 
+// The addon is a pure Node-API (N-API) binding (it exports
+// `napi_register_module_v1`). N-API is ABI-stable across Node major versions, so
+// a single compiled `.node` loads on every Node runtime that supports the N-API
+// version it targets — regardless of `process.versions.modules`
+// (NODE_MODULE_VERSION / "ABI"). The per-`nodeNNN` prebuilt directories are
+// therefore an addressing convenience, not a hard ABI requirement: the binaries
+// inside them are byte-identical per platform/arch.
+//
+// Consequently the loader resolves in three tiers:
+//   1. an explicit override dir (ADHDEV_GHOSTTY_VT_PREBUILT_DIR),
+//   2. a locally compiled build/ output,
+//   3. an exact `platform-arch-nodeABI` prebuilt, and finally
+//   4. ANY prebuilt for the same `platform-arch` (N-API portability fallback).
+// Tier 4 is what makes a brand-new Node ABI (e.g. a future node26) work without
+// shipping a new directory — the previous failure mode where node137 runtimes
+// hit "binding unavailable" purely because no `node137` directory existed.
+
+function listAvailablePrebuiltTriplets() {
+    try {
+        return fs
+            .readdirSync(PREBUILT_ROOT, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((name) => fs.existsSync(path.join(PREBUILT_ROOT, name, ADDON_FILE)))
+            .sort();
+    } catch {
+        return [];
+    }
+}
+
+function samePlatformArchTriplets(triplet) {
+    // triplet === `${platform}-${arch}-node${abi}` → prefix is `${platform}-${arch}-`
+    const prefix = `${process.platform}-${process.arch}-`;
+    return listAvailablePrebuiltTriplets().filter(
+        (name) => name.startsWith(prefix) && name !== triplet,
+    );
+}
+
+// Last-resort: every other installed prebuilt, regardless of platform/arch.
+// Requiring a foreign-OS `.node` throws a load error (ELF/PE mismatch,
+// "invalid ELF header", "not a valid Win32 application"), which loadBinding()
+// simply skips — so this tier is inert on a correctly-addressed runtime. Its
+// sole purpose is test isolation: suites that mock `process.platform` (e.g.
+// win32 PTY-write / submit driver coverage) corrupt getTriplet() into an
+// address for which no loadable binary exists on the CI runner; walking the
+// remaining triplets lets the real host binary (the one that actually loads)
+// still resolve, instead of the whole ProviderCliAdapter construction throwing.
+function otherInstalledTriplets(triplet, alreadyTried) {
+    return listAvailablePrebuiltTriplets().filter(
+        (name) => name !== triplet && !alreadyTried.has(name),
+    );
+}
+
 function loadBinding() {
     const triplet = getTriplet();
     const explicitPrebuiltDir = process.env.ADHDEV_GHOSTTY_VT_PREBUILT_DIR
         ? path.resolve(process.env.ADHDEV_GHOSTTY_VT_PREBUILT_DIR)
         : null;
+
     const candidates = [
-        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, triplet, 'ghostty_vt_node.node') : null,
-        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, 'ghostty_vt_node.node') : null,
-        path.join(__dirname, 'build', 'Release', 'ghostty_vt_node.node'),
-        path.join(__dirname, 'build', 'Debug', 'ghostty_vt_node.node'),
-        path.join(__dirname, 'prebuilt', triplet, 'ghostty_vt_node.node'),
+        // 1. explicit override
+        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, triplet, ADDON_FILE) : null,
+        explicitPrebuiltDir ? path.join(explicitPrebuiltDir, ADDON_FILE) : null,
+        // 2. locally compiled output
+        path.join(__dirname, 'build', 'Release', ADDON_FILE),
+        path.join(__dirname, 'build', 'Debug', ADDON_FILE),
+        // 3. exact-ABI prebuilt
+        path.join(PREBUILT_ROOT, triplet, ADDON_FILE),
+        // 4. N-API portability fallback: any same platform-arch prebuilt
+        ...samePlatformArchTriplets(triplet).map((name) =>
+            path.join(PREBUILT_ROOT, name, ADDON_FILE),
+        ),
+        // 5. test-isolation fallback: any remaining installed triplet (see
+        //    otherInstalledTriplets). Foreign-OS binaries throw on require and
+        //    are skipped; the real host binary still resolves under a mocked
+        //    process.platform.
+        ...otherInstalledTriplets(
+            triplet,
+            new Set([triplet, ...samePlatformArchTriplets(triplet)]),
+        ).map((name) => path.join(PREBUILT_ROOT, name, ADDON_FILE)),
     ].filter(Boolean);
 
     const errors = [];
@@ -26,8 +99,12 @@ function loadBinding() {
         }
     }
 
+    const available = listAvailablePrebuiltTriplets();
     throw new Error(
-        `Unable to load @adhdev/ghostty-vt-node native binding for ${triplet}. Provide a prebuilt via ADHDEV_GHOSTTY_VT_PREBUILT_DIR or build it with "npm run build -w packages/ghostty-vt-node". ${errors.join(' | ')}`,
+        `Unable to load @adhdev/ghostty-vt-node native binding for running triplet "${triplet}". ` +
+            `Available prebuilt triplets: [${available.join(', ') || 'none'}]. ` +
+            `Provide a prebuilt via ADHDEV_GHOSTTY_VT_PREBUILT_DIR or build it with ` +
+            `"npm run build -w oss/packages/ghostty-vt-node". Attempts: ${errors.join(' | ')}`,
     );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/ghostty-vt-node",
-  "version": "0.8.51",
+  "version": "1.0.0",
   "description": "Native Node binding for libghostty-vt",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,7 +10,8 @@
     "prebuilt",
     "scripts",
     "CMakeLists.txt",
-    "src"
+    "src",
+    "README.md"
   ],
   "scripts": {
     "build": "node ./scripts/build-or-use-prebuilt.mjs",

package/scripts/build-or-use-prebuilt.mjs

@@ -83,4 +83,27 @@ if (result.error) {
   console.error(`[ghostty-vt-node] failed to launch native build for ${triplet}:`, result.error);
 }
 
+// Mirror a successful local build into prebuilt/<triplet>/ so CI (or a developer)
+// can produce a shippable prebuilt reproducibly: build once on the target
+// platform, then commit prebuilt/<triplet>/. Set ADHDEV_GHOSTTY_VT_EMIT_PREBUILT=1
+// to enable (off by default so ordinary `npm run build` does not churn the dir).
+// The binding is Node-API (ABI-stable), so a single emitted triplet is enough for
+// the running platform-arch; the runtime loader (index.js) falls back across ABIs.
+if ((result.status ?? 1) === 0 && process.env.ADHDEV_GHOSTTY_VT_EMIT_PREBUILT === '1') {
+  try {
+    const prebuiltDir = path.join(packageDir, 'prebuilt', triplet);
+    fs.mkdirSync(prebuiltDir, { recursive: true });
+    for (const entry of fs.readdirSync(outputDir)) {
+      // Ship the addon plus its co-located runtime libs (.dylib/.so/.dll),
+      // skip intermediate build artifacts.
+      if (/\.(node|dylib|so|so\.\d.*|dll)$/.test(entry)) {
+        fs.copyFileSync(path.join(outputDir, entry), path.join(prebuiltDir, entry));
+      }
+    }
+    console.log(`[ghostty-vt-node] emitted prebuilt for ${triplet} → ${prebuiltDir}`);
+  } catch (emitError) {
+    console.error(`[ghostty-vt-node] failed to emit prebuilt for ${triplet}:`, emitError);
+  }
+}
+
 process.exit(result.status ?? 1);