SocketDev · Mikola Lysenko (mikolalysenko) · Sep 26, 2026 · Sep 26, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -74,6 +74,38 @@ jobs:
             exit 1
           fi
 
+  # The napi addon is only ever loaded by Node, so cargo's own tests never
+  # exercise its JS loader or the engine/provider boundary.
+  node-addon:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install Rust
+        run: rustup show
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
+        with:
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '20.20.2'
+
+      - name: Build addon
+        env:
+          SOCKET_PATCH_NODE_CARGO_PROFILE: dev
+        run: node crates/socket-patch-node/npm/scripts/build-addon.mjs
+
+      - name: Smoke-test addon
+        run: node --test crates/socket-patch-node/npm/test/smoke.mjs
+
   # Lint the out-of-workspace packaging artifacts: the RubyGems CLI launcher
   # gem + the Bundler plugin gem (Ruby), and the curl|sh installer. Ruby is
   # pre-installed on the ubuntu-latest runner.

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -175,11 +175,11 @@ jobs:
 
       - name: Build (cargo)
         if: matrix.build-tool == 'cargo'
-        run: cargo build --release --target ${{ matrix.target }}
+        run: cargo build --release -p socket-patch-cli --target ${{ matrix.target }}
 
       - name: Build (cross)
         if: matrix.build-tool == 'cross'
-        run: cross build --release --target ${{ matrix.target }}
+        run: cross build --release -p socket-patch-cli --target ${{ matrix.target }}
 
       - name: Package (unix)
         if: matrix.archive == 'tar.gz'

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -2,6 +2,13 @@
 members = [
     "crates/socket-patch-core",
     "crates/socket-patch-cli",
+    "crates/socket-patch-node",
+]
+# Bare `cargo build` (release.yml's per-target builds) skips the Node addon,
+# which no release artifact ships; `--workspace` and `-p` still build it.
+default-members = [
+    "crates/socket-patch-core",
+    "crates/socket-patch-cli",
 ]
 resolver = "2"
 
@@ -21,6 +28,7 @@ sha1 = "=0.10.6"
 hex = "=0.4.3"
 reqwest = { version = "=0.12.28", features = ["rustls-tls", "json"], default-features = false }
 tokio = { version = "=1.50.0", features = ["full"] }
+tokio-util = "=0.7.18"
 futures-util = { version = "=0.3.32", default-features = false, features = ["std"] }
 thiserror = "=2.0.18"
 walkdir = "=2.5.0"
@@ -48,6 +56,9 @@ wiremock = "=0.6.5"
 portable-pty = "=0.9.0"
 base64 = "=0.22.1"
 serial_test = "=3.4.0"
+napi = { version = "=3.13.0", features = ["napi8", "tokio_rt"] }
+napi-derive = "=3.6.9"
+napi-build = "=2.5.0"
 
 [profile.release]
 strip = true
@@ -65,6 +76,12 @@ inherits = "release"
 lto = false
 strip = "none" # unstripped test binaries => usable backtraces on failure
 
+# The Node addon (crates/socket-patch-node) for hosts that load it
+# in-process: release semantics without the slow full-LTO link.
+[profile.addon]
+inherits = "release"
+lto = "thin"
+
 # Test-execution speed: `cargo test` builds dependencies with the dev
 # profile; at opt-level 0 the hash/compression/bsdiff hot loops are 10-100x
 # slower (the self_update fixture family measured 403s debug vs ~2s release

diff --git a/crates/socket-patch-cli/CLI_CONTRACT.md b/crates/socket-patch-cli/CLI_CONTRACT.md
@@ -27,6 +27,8 @@ This document defines the **public surface** of the `socket-patch` binary. Anyth
 
 **Root `--update` flag.** `socket-patch --update [VERSION]` updates the binary itself from GitHub Releases. It is a root flag, not a subcommand: argv is rewritten (the same mechanism as the bare-UUID fallback) onto an internal hidden subcommand whose name carries no stability guarantee — script the flag, never the internal name. Combining the flag with a subcommand (`socket-patch --update scan`) is a usage error (exit 2). Full contract: [Self-update contract](#self-update-contract-socket-patch---update).
 
+**Internal `hosted-bundle` subcommand.** `socket-patch hosted-bundle` is a hidden, INTERNAL parity/debug harness for the in-memory hosted engine (`src/hosted_memory/`, the engine the Node addon embeds): it reads a JSON bundle `{"files": {path: text}, "binaryFiles"?: {path: base64}, "presentOnly"?: [path], "symlinks"?: [path], "projectRoots"?: [dir], "pipenvMajor"?: n, "batchSize"?: n}` on stdin, queries the authenticated org API built from `--api-url` / `--api-token` / `--org` only (both of the latter are required; no public-proxy fallback), and prints the engine result — or `{"status":"error","error":{"code","message"}}` with exit 1 (exit 2 for unusable input or missing credentials). It never touches the filesystem. Its name, input and output carry NO stability guarantee; do not script it.
+
 ## Global arguments
 
 In v3.0 every subcommand accepts the same set of "global" flags via a single shared `GlobalArgs` struct that's `#[command(flatten)]`-ed into each per-command struct (`crates/socket-patch-cli/src/args.rs`). Subcommands that don't actually consume a given flag accept it silently — e.g. `list --global` parses fine and is a no-op. Every flag also has an environment-variable binding; precedence is **CLI arg > env var > default** — and for exactly three keys (`--api-token`, `--org`, `--api-url`) the JS socket-cli's persisted login sits between env var and default: **CLI arg > env var (canonical, then `SOCKET_CLI_*` alias) > socket-cli `config.json` > default**. See "Persisted configuration" under Environment variables.

diff --git a/crates/socket-patch-cli/Cargo.toml b/crates/socket-patch-cli/Cargo.toml
@@ -22,6 +22,8 @@ clap = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 tokio = { workspace = true }
+tokio-util = { workspace = true }
+base64 = { workspace = true }
 futures-util = { workspace = true }
 console = { workspace = true }
 dialoguer = { workspace = true }