pi-microsandbox 0.1.0 → 0.1.1

package/README.md

@@ -46,9 +46,12 @@ same decisions every time you start it.
 
 ## Get started
 
-You'll need Pi, **Node.js 22.19.0+**, and either an Apple Silicon Mac or Linux
-with accessible KVM. Installation also needs Python and a C/C++ build toolchain;
-keep lifecycle scripts and optional dependencies enabled.
+You'll need Pi, **Node.js 22.19.0+**, and one of the supported host targets:
+Apple Silicon macOS (`darwin-arm64`), GNU Linux x86_64
+(`linux-x64-gnu`), or GNU Linux arm64 (`linux-arm64-gnu`). Live sandboxes also
+need host virtualization support. The POSIX lock addon is bundled and installs
+without lifecycle scripts or a compiler; keep npm optional dependencies enabled
+for the Microsandbox platform package.
 [Full requirements and installation help →](docs/getting-started.md)
 
 Install the Microsandbox CLI first:

package/docs/development.md

@@ -12,19 +12,65 @@ To test from source without installing the npm package globally:
 git clone https://github.com/hcohe/pi-microsandbox.git
 cd pi-microsandbox
 
-# fs-ext must compile during installation; do not use --ignore-scripts.
-npm ci
+npm ci --ignore-scripts=true
 npm run typecheck
 npm test
 npm run smoke       # extension-load smoke; no sandbox starts
 npm run check       # all three commands above
 npm audit --omit=dev
-npm pack --dry-run --json
 ```
 
 The smoke and unit tests do not require KVM, image pulls, or a live sandbox.
 The boot-speed check and live matrix below are explicit VM tests.
 
+### Bundled flock addon
+
+Consumers receive prebuilt lock addons and do not need native build tools. Only
+contributors building or changing the addon need Python, a C compiler, and the
+platform build tools used by node-gyp (`make` on GNU Linux or Xcode command-line
+tools on macOS). On one of the three supported targets, run:
+
+```sh
+npm ci --ignore-scripts=true
+npm run build:flock
+npm run smoke:flock
+npm run check
+```
+
+The build writes
+`native/flock/prebuilds/<target>/flock.node` for the current target. These
+outputs are ignored by Git and must not be committed. CI builds
+`darwin-arm64`, `linux-x64-gnu`, and `linux-arm64-gnu` separately on native
+runners, then loads the same binary under Node 22.19.0 and Node 24.
+
+### Assemble a package from CI artifacts
+
+A complete package needs all three `flock-<target>` artifacts from one CI run.
+Download each artifact into one empty artifact root, create a staging checkout
+from the same commit's Git archive, then give both paths to the assembler:
+
+```sh
+run_id=GITHUB_ACTIONS_RUN_ID
+mkdir -p .tmp
+artifact_root="$(mktemp -d "$PWD/.tmp/flock-artifacts.XXXXXX")"
+staging="$(mktemp -d "$PWD/.tmp/package-staging.XXXXXX")"
+pack_dir="$(mktemp -d "$PWD/.tmp/package-pack.XXXXXX")"
+
+for target in darwin-arm64 linux-x64-gnu linux-arm64-gnu; do
+  gh run download "$run_id" --name "flock-$target" --dir "$artifact_root"
+done
+
+git archive HEAD | tar -x -C "$staging"
+npm run assemble:package -- "$artifact_root" "$staging"
+pack_json="$(npm pack "$staging" --json --pack-destination "$pack_dir")"
+tarball="$(node -e 'const value=JSON.parse(process.argv[1]); const results=Array.isArray(value)?value:Object.values(value); if(results.length!==1) throw new Error(`expected one pack result, got ${results.length}`); process.stdout.write(results[0].filename)' "$pack_json")"
+npm run package-smoke -- "$pack_dir/$tarball"
+```
+
+Use artifacts built from the same commit as `HEAD`. The assembler rejects
+missing, extra, or symlinked artifacts and keeps generated binaries out of the
+source checkout.
+
 ## Boot speed regression test
 
 With [`just`](https://just.systems/) installed, measure the awaited sandbox boot
@@ -98,7 +144,11 @@ canonical changelog. The first npm publication is a human-run local publish of
 the reviewed tarball with interactive npm 2FA. Subsequent releases publish
 directly to npm with OIDC only after a maintainer publishes the matching GitHub
 Release and approves the protected `npm` GitHub Environment. Release automation
-must not use a long-lived npm token.
+must not use a long-lived npm token. Release CI builds every flock artifact from
+the release commit, assembles a temporary staging tree, records each binary's
+SHA-256, smoke-tests the exact tarball on every supported target, and packs only
+once. The publish job downloads and publishes those verified bytes without
+repacking.
 
 The sandbox image workflow publishes all six AMD64 and ARM64 variants to
 `ghcr.io/hcohe/pi-microsandbox`. An `image-vX.Y.Z` Git tag publishes the

package/docs/getting-started.md

@@ -9,28 +9,27 @@ require one of these hosts:
 
 | Host | Architecture | Virtualization requirement |
 | --- | --- | --- |
-| macOS | Apple Silicon (arm64) | Apple virtualization support available to the process |
-| Linux | x86_64 or arm64 (GNU) | KVM enabled, with `/dev/kvm` accessible to the process |
-
-Windows and Intel macOS are not supported by pi-microsandbox. The upstream
-microsandbox runtime has preview Windows support, but this package deliberately
-declares only macOS and Linux. A Linux container or virtual machine also needs
-KVM passthrough or nested virtualization; many hosted environments do not
-provide it. Package loading and non-live tests do not require virtualization.
-
-Installation must run lifecycle scripts and include optional dependencies:
-
-- `fs-ext@2.1.1` compiles a native node-gyp module. Install Python and a working
-  C/C++ build toolchain (`xcode-select --install` on macOS, or a compiler,
-  `make`, and Python 3 on Linux).
-- `microsandbox@0.6.16` installs its matching native addon and runtime binaries
-  through an optional platform package. Do not use `--ignore-scripts` or omit
-  optional dependencies when installing pi-microsandbox.
-
-If the platform package is missing, reinstall with optional dependencies
-enabled, install the matching microsandbox platform package, or set `MSB_PATH`
-to a working `msb` binary. These alternatives do not remove the host
-virtualization requirement.
+| macOS | Apple Silicon (`darwin-arm64`) | Apple virtualization support available to the process |
+| GNU Linux | x86_64 (`linux-x64-gnu`) or arm64 (`linux-arm64-gnu`) | KVM enabled, with `/dev/kvm` accessible to the process |
+
+Windows, Intel macOS, and musl Linux are not supported by pi-microsandbox. The
+upstream microsandbox runtime has preview Windows support, but this package
+deliberately supports only the three targets above. A Linux container or
+virtual machine also needs KVM passthrough or nested virtualization; many hosted
+environments do not provide it. Package loading and non-live tests do not
+require virtualization.
+
+pi-microsandbox includes a prebuilt POSIX lock addon for each supported target.
+It is loaded lazily when an owner lock is first needed. Consumer installation
+does not compile native code or require Python, a C/C++ toolchain, or npm
+lifecycle scripts; installation with scripts disabled is supported.
+
+Keep optional dependencies enabled. `microsandbox@0.6.16` supplies its matching
+native addon and runtime binaries through an optional platform package. If that
+platform package is missing, reinstall with optional dependencies enabled,
+install the matching Microsandbox platform package, or set `MSB_PATH` to a
+working `msb` binary. These alternatives do not remove the host virtualization
+requirement.
 
 ## Install
 

package/docs/safety.md

@@ -19,11 +19,14 @@ The default is fail-closed:
   after a sandbox failure and is shown as `MSB host fallback`.
 - A project cannot replace another process's sandbox: ownership is a
   non-blocking kernel `flock` acquired before any sandbox or volume mutation.
-  Stale sandbox pruning never removes volumes.
-
-The extension entry point does not import the native SDK. Unsupported hosts can
-still load Pi and remain blocked or explicitly off. pi-microsandbox currently supports
-macOS Apple Silicon and Linux with KVM; Windows is not supported.
+  The small bundled POSIX addon is loaded lazily, has no install script, and
+  never falls back to a racy PID check. Stale sandbox pruning never removes
+  volumes.
+
+The extension entry point does not import the native SDK or load the flock
+addon. Unsupported hosts can still load Pi and remain blocked or explicitly
+off. pi-microsandbox supports Apple Silicon macOS and GNU Linux x86_64 or arm64
+with KVM; Windows, Intel macOS, and musl Linux are not supported.
 
 ## Host-read exceptions
 

package/extensions/pi-msb/flock.ts

@@ -0,0 +1,94 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export type FlockOperation = "exnb" | "un";
+export type FlockTarget = "darwin-arm64" | "linux-x64-gnu" | "linux-arm64-gnu";
+
+export interface FlockRuntime {
+  platform: string;
+  arch: string;
+  glibcVersionRuntime?: unknown;
+}
+
+interface NativeFlockBinding {
+  flock(fd: number, operation: FlockOperation): undefined;
+}
+
+export interface LoadFlockOptions {
+  runtime?: FlockRuntime;
+  requireAddon?: (absolutePath: string) => unknown;
+}
+
+const SUPPORTED_TARGETS = "darwin-arm64, linux-x64-gnu, linux-arm64-gnu";
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function currentRuntime(): FlockRuntime {
+  const report = process.platform === "linux"
+    ? process.report?.getReport() as { header?: { glibcVersionRuntime?: unknown } } | undefined
+    : undefined;
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    glibcVersionRuntime: report?.header?.glibcVersionRuntime,
+  };
+}
+
+export function flockTarget(runtime: FlockRuntime): FlockTarget {
+  if (runtime.platform === "darwin" && runtime.arch === "arm64") return "darwin-arm64";
+  if (runtime.platform === "linux" && (runtime.arch === "x64" || runtime.arch === "arm64")) {
+    if (typeof runtime.glibcVersionRuntime !== "string" || runtime.glibcVersionRuntime.length === 0) {
+      throw new Error(
+        `Bundled owner-lock addon requires glibc on Linux; libc is musl or indeterminate for linux-${runtime.arch}; `
+        + `supported targets: ${SUPPORTED_TARGETS}; refusing to use an unsafe fallback`,
+      );
+    }
+    return `linux-${runtime.arch}-gnu`;
+  }
+  throw new Error(
+    `Bundled owner-lock addon does not support ${runtime.platform}-${runtime.arch}; `
+    + `supported targets: ${SUPPORTED_TARGETS}; refusing to use an unsafe fallback`,
+  );
+}
+
+export function flockBinaryPath(target: FlockTarget): string {
+  return fileURLToPath(new URL(`../../native/flock/prebuilds/${target}/flock.node`, import.meta.url));
+}
+
+export function loadFlockBinding(options: LoadFlockOptions = {}): NativeFlockBinding {
+  const target = flockTarget(options.runtime ?? currentRuntime());
+  const relativePath = `native/flock/prebuilds/${target}/flock.node`;
+  const absolutePath = flockBinaryPath(target);
+  const requireAddon = options.requireAddon ?? ((path: string) => createRequire(import.meta.url)(path));
+
+  try {
+    const candidate = requireAddon(absolutePath);
+    if (typeof candidate !== "object" || candidate === null
+      || Object.keys(candidate).length !== 1
+      || typeof (candidate as { flock?: unknown }).flock !== "function") {
+      throw new TypeError("native binding must export only flock() as a callable property");
+    }
+    return candidate as NativeFlockBinding;
+  } catch (error) {
+    throw new Error(
+      `Unable to load bundled owner-lock addon for ${target} from ${relativePath}; `
+      + `refusing to use an unsafe fallback: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+}
+
+let binding: NativeFlockBinding | undefined;
+
+export async function flock(fd: number, operation: FlockOperation): Promise<void> {
+  if (!Number.isInteger(fd) || fd < 0 || fd > 0x7fff_ffff) {
+    throw new TypeError("file descriptor must be a non-negative integer");
+  }
+  if (operation !== "exnb" && operation !== "un") {
+    throw new TypeError('operation must be "exnb" or "un"');
+  }
+  binding ??= loadFlockBinding();
+  binding.flock(fd, operation);
+}

package/extensions/pi-msb/locks.ts

@@ -1,13 +1,14 @@
 import { chmod, mkdir, open, readFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 
+import { flock as bundledFlock } from "./flock.ts";
 import { LOCKFILE_VERSION, resourceId } from "./types.ts";
 import type { LockHandle, LockInfo, LocksPort } from "./types.ts";
 
 /**
  * The hooks are deliberately part of the options shape so unit tests can exercise
  * the lifecycle without loading the native addon. Production callers leave them
- * unset and use fs-ext below.
+ * unset and use the lazy bundled binding.
  */
 export type FlockFn = (fd: number, operation: "exnb" | "un") => Promise<void>;
 
@@ -18,25 +19,6 @@ export interface LocksOptions {
   unlock?: (fd: number) => Promise<void>;
 }
 
-type FsExtCallback = (
-  fd: number,
-  operation: string,
-  callback: (error?: unknown) => void,
-) => void;
-type FsExtUnlockCallback = (fd: number, callback: (error?: unknown) => void) => void;
-type FsExtModule = {
-  flock?: FsExtCallback;
-  unlock?: FsExtUnlockCallback;
-};
-
-let fsExtPromise: Promise<FsExtModule> | undefined;
-
-// Keep the native dependency genuinely lazy and let extension-load/type-only
-// environments operate without resolving the optional native module.
-function importNativeModule(specifier: string): Promise<unknown> {
-  return import(specifier);
-}
-
 function errorCode(error: unknown): string | undefined {
   if (typeof error === "object" && error !== null && "code" in error) {
     const code = (error as { code?: unknown }).code;
@@ -49,77 +31,16 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function unsupportedPlatformError(): Error {
-  return new Error(
-    "pi-microsandbox owner locks require POSIX flock(2) via fs-ext; this platform is unsupported (Windows LockFileEx is not implemented)",
-  );
-}
-
-async function loadFsExt(): Promise<FsExtModule> {
-  if (process.platform === "win32") throw unsupportedPlatformError();
-  fsExtPromise ??= importNativeModule("fs-ext").then((module) => {
-    const defaultExport = (module as unknown as { default?: unknown }).default;
-    const candidate = (defaultExport ?? module) as FsExtModule;
-    if (typeof candidate.flock !== "function") {
-      throw new Error("fs-ext loaded without flock(); refusing to use a racy PID fallback");
-    }
-    return candidate;
-  });
-  return fsExtPromise;
-}
-
-function callbackFlock(flock: FsExtCallback, fd: number, operation: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    try {
-      flock(fd, operation, (error) => (error ? reject(error) : resolve()));
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-function callbackUnlock(unlock: FsExtUnlockCallback, fd: number): Promise<void> {
-  return new Promise((resolve, reject) => {
-    try {
-      unlock(fd, (error) => (error ? reject(error) : resolve()));
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
 interface LockOperations {
   flock(fd: number): Promise<void>;
   unlock(fd: number): Promise<void>;
 }
 
 async function lockOperations(opts: LocksOptions): Promise<LockOperations> {
-  if (opts.flock) {
-    return {
-      flock: (fd) => opts.flock!(fd, "exnb"),
-      unlock: (fd) => opts.unlock ? opts.unlock(fd) : opts.flock!(fd, "un"),
-    };
-  }
-
-  let module: FsExtModule;
-  try {
-    module = await loadFsExt();
-  } catch (error) {
-    throw new Error(
-      `Unable to load fs-ext for owner locks; refusing to use a racy PID fallback: ${errorMessage(error)}`,
-      { cause: error },
-    );
-  }
-  const flock = module.flock;
-  if (!flock) {
-    throw new Error("fs-ext does not provide flock(); refusing to use a racy PID fallback");
-  }
-  const unlock = module.unlock;
+  const flock = opts.flock ?? bundledFlock;
   return {
-    flock: (fd) => callbackFlock(flock, fd, "exnb"),
-    unlock: (fd) => unlock
-      ? callbackUnlock(unlock, fd)
-      : callbackFlock(flock, fd, "un"),
+    flock: (fd) => flock(fd, "exnb"),
+    unlock: (fd) => opts.unlock ? opts.unlock(fd) : flock(fd, "un"),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-microsandbox",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Microsandbox-backed isolation for Pi coding tools",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,10 @@
     "SECURITY.md",
     "docs/*.md",
     "extensions/pi-msb/*.ts",
-    "!extensions/pi-msb/*.test.ts"
+    "!extensions/pi-msb/*.test.ts",
+    "native/flock/prebuilds/darwin-arm64/flock.node",
+    "native/flock/prebuilds/linux-x64-gnu/flock.node",
+    "native/flock/prebuilds/linux-arm64-gnu/flock.node"
   ],
   "pi": {
     "extensions": [
@@ -41,16 +44,17 @@
     ]
   },
   "scripts": {
+    "build:flock": "node ./scripts/build-flock-addon.mjs",
+    "smoke:flock": "node ./scripts/smoke-flock-addon.mjs",
+    "assemble:package": "node ./scripts/assemble-package.mjs",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --import ./test/setup.ts --test extensions/pi-msb/*.test.ts",
     "smoke": "pi --no-extensions -e . --offline --list-models __pi_msb_smoke__",
     "check": "npm run typecheck && npm test && npm run smoke",
     "package-smoke": "./scripts/package-smoke.sh",
-    "release-check": "npm run check && npm run package-smoke && npm audit --omit=dev",
-    "prepublishOnly": "npm run release-check"
+    "release-check": "npm run check && npm audit --omit=dev"
   },
   "dependencies": {
-    "fs-ext": "2.1.1",
     "microsandbox": "0.6.16"
   },
   "peerDependencies": {
@@ -61,13 +65,12 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.4",
     "@earendil-works/pi-tui": "0.84.4",
-    "@types/fs-ext": "^2.0.3",
     "@types/node": "^22.10.0",
+    "node-gyp": "12.1.0",
     "typebox": "1.3.23",
     "typescript": "^7.0.2"
   },
   "allowScripts": {
-    "fs-ext@2.1.1": true,
     "@google/genai": false,
     "protobufjs": false
   }