@oh-my-pi/pi-natives 18.17.0 → 18.18.0

package/native/index.js

@@ -1,4 +1,4 @@
-import { loadNative, missingNativeExport } from "./loader-state.js";
+import { loadNative, missingNativeClass, missingNativeExport } from "./loader-state.js";
 import { adaptDesktopSession } from "./desktop-adapter.js";
 
 /**
@@ -23,33 +23,33 @@ import { adaptDesktopSession } from "./desktop-adapter.js";
 const nativeBindings = loadNative();
 // --- generated native exports (do not edit) ---
 // classes
-export const AudioCapture = nativeBindings.AudioCapture;
-export const AudioPlayback = nativeBindings.AudioPlayback;
+export const AudioCapture = nativeBindings.AudioCapture ?? missingNativeClass("AudioCapture");
+export const AudioPlayback = nativeBindings.AudioPlayback ?? missingNativeClass("AudioPlayback");
 export const DesktopSession = adaptDesktopSession(nativeBindings.DesktopSession);
-export const DiffStream = nativeBindings.DiffStream;
-export const EditSession = nativeBindings.EditSession;
-export const EditStore = nativeBindings.EditStore;
-export const FileLock = nativeBindings.FileLock;
-export const HighlightStream = nativeBindings.HighlightStream;
-export const IpcConnection = nativeBindings.IpcConnection;
-export const IpcServer = nativeBindings.IpcServer;
-export const LineMatcher = nativeBindings.LineMatcher;
-export const LiveWebRtcPeer = nativeBindings.LiveWebRtcPeer;
-export const MacAppearanceObserver = nativeBindings.MacAppearanceObserver;
-export const MacOSFrontApp = nativeBindings.MacOSFrontApp;
-export const NativeOAuthCallback = nativeBindings.NativeOAuthCallback;
-export const PipeStreams = nativeBindings.PipeStreams;
-export const PowerAssertion = nativeBindings.PowerAssertion;
-export const Process = nativeBindings.Process;
-export const PtySession = nativeBindings.PtySession;
-export const RunTrace = nativeBindings.RunTrace;
-export const Shell = nativeBindings.Shell;
-export const ShellVisualization = nativeBindings.ShellVisualization;
-export const TextPredictor = nativeBindings.TextPredictor;
-export const TtyWriter = nativeBindings.TtyWriter;
-export const VcsGitRepo = nativeBindings.VcsGitRepo;
-export const VcsJjWorkspace = nativeBindings.VcsJjWorkspace;
-export const VcsRepo = nativeBindings.VcsRepo;
+export const DiffStream = nativeBindings.DiffStream ?? missingNativeClass("DiffStream");
+export const EditSession = nativeBindings.EditSession ?? missingNativeClass("EditSession");
+export const EditStore = nativeBindings.EditStore ?? missingNativeClass("EditStore");
+export const FileLock = nativeBindings.FileLock ?? missingNativeClass("FileLock");
+export const HighlightStream = nativeBindings.HighlightStream ?? missingNativeClass("HighlightStream");
+export const IpcConnection = nativeBindings.IpcConnection ?? missingNativeClass("IpcConnection");
+export const IpcServer = nativeBindings.IpcServer ?? missingNativeClass("IpcServer");
+export const LineMatcher = nativeBindings.LineMatcher ?? missingNativeClass("LineMatcher");
+export const LiveWebRtcPeer = nativeBindings.LiveWebRtcPeer ?? missingNativeClass("LiveWebRtcPeer");
+export const MacAppearanceObserver = nativeBindings.MacAppearanceObserver ?? missingNativeClass("MacAppearanceObserver");
+export const MacOSFrontApp = nativeBindings.MacOSFrontApp ?? missingNativeClass("MacOSFrontApp");
+export const NativeOAuthCallback = nativeBindings.NativeOAuthCallback ?? missingNativeClass("NativeOAuthCallback");
+export const PipeStreams = nativeBindings.PipeStreams ?? missingNativeClass("PipeStreams");
+export const PowerAssertion = nativeBindings.PowerAssertion ?? missingNativeClass("PowerAssertion");
+export const Process = nativeBindings.Process ?? missingNativeClass("Process");
+export const PtySession = nativeBindings.PtySession ?? missingNativeClass("PtySession");
+export const RunTrace = nativeBindings.RunTrace ?? missingNativeClass("RunTrace");
+export const Shell = nativeBindings.Shell ?? missingNativeClass("Shell");
+export const ShellVisualization = nativeBindings.ShellVisualization ?? missingNativeClass("ShellVisualization");
+export const TextPredictor = nativeBindings.TextPredictor ?? missingNativeClass("TextPredictor");
+export const TtyWriter = nativeBindings.TtyWriter ?? missingNativeClass("TtyWriter");
+export const VcsGitRepo = nativeBindings.VcsGitRepo ?? missingNativeClass("VcsGitRepo");
+export const VcsJjWorkspace = nativeBindings.VcsJjWorkspace ?? missingNativeClass("VcsJjWorkspace");
+export const VcsRepo = nativeBindings.VcsRepo ?? missingNativeClass("VcsRepo");
 
 // functions
 export const __ompInstallTokioRuntime = nativeBindings.__ompInstallTokioRuntime ?? missingNativeExport("__ompInstallTokioRuntime");

package/native/loader-state.d.ts

@@ -145,6 +145,29 @@ export function missingNativeExport(
 	addon?: NativeAddonStatus | null,
 ): (() => never) | undefined;
 
+/**
+ * Stub for a class the addon does not provide: `undefined` on a current addon,
+ * a class whose constructor throws on a stale one.
+ */
+export function missingNativeClass(
+	symbolName: string,
+	addon?: NativeAddonStatus | null,
+): (new (...args: unknown[]) => never) | undefined;
+
+/** Notice a workspace tree prints when its addon is from another release. */
+export function staleWorkspaceAddonNotice(addon: NativeAddonStatus): string;
+
+/**
+ * Write {@link staleWorkspaceAddonNotice} once, from the main thread, and only
+ * on a workspace load. The latch is per loaded copy of this module. Returns
+ * whether this call wrote it.
+ */
+export function reportStaleWorkspaceAddon(
+	ctx: { isWorkspaceLoad: boolean },
+	addon: NativeAddonStatus,
+	deps?: { write?: (text: string) => void; state?: { reported: boolean } },
+): boolean;
+
 /** Actionable text for {@link missingNativeExport}. */
 export function missingNativeExportMessage(symbolName: string, addon?: NativeAddonStatus | null): string;
 

package/native/loader-state.js

@@ -693,6 +693,48 @@ export function missingNativeExport(symbolName, addon = loadedAddon) {
 	};
 }
 
+/**
+ * Static reads a {@link missingNativeClass} stand-in answers normally rather
+ * than throwing: the function-object intrinsics every caller and inspector
+ * touches, and `then`, so an accidental `await` on the export resolves to the
+ * class instead of exploding somewhere unrelated.
+ */
+const CLASS_STUB_PLAIN_STATICS = new Set(["prototype", "name", "length", "constructor", "then"]);
+
+/**
+ * Class counterpart of {@link missingNativeExport}: a stand-in that fails with
+ * the addon's identity attached instead of as a bare `undefined` export, which
+ * surfaces as `undefined is not a constructor` at the callsite and names
+ * nothing.
+ *
+ * Same staleness rule as the function stub: only a stale addon gets a
+ * stand-in, so `typeof native.Thing === "function"` capability probes against
+ * a current addon keep their meaning.
+ *
+ * Several of these classes are entered through a static rather than a
+ * constructor — `FileLock.tryAcquire`, `IpcServer.listen`, `Process.fromPid`,
+ * `PowerAssertion.start` — so the stand-in answers any other static read with
+ * the same diagnostic. Only a stale addon reaches it, and only for a class
+ * that addon does not carry, so nothing on a healthy tree meets a proxy.
+ * @param {string} symbolName
+ * @param {ReturnType<typeof nativeAddonStatus>} [addon]
+ * @returns {(new (...args: unknown[]) => never) | undefined}
+ */
+export function missingNativeClass(symbolName, addon = loadedAddon) {
+	if (!addon?.stale) return undefined;
+	const stub = class MissingNativeClass {
+		constructor() {
+			throw new Error(missingNativeExportMessage(symbolName, addon));
+		}
+	};
+	return new Proxy(stub, {
+		get(target, key, receiver) {
+			if (typeof key === "symbol" || CLASS_STUB_PLAIN_STATICS.has(key)) return Reflect.get(target, key, receiver);
+			throw new Error(missingNativeExportMessage(`${symbolName}.${key}`, addon));
+		},
+	});
+}
+
 /**
  * Actionable text for {@link missingNativeExport}. `addon` is injectable so the
  * wording can be pinned without a stale `.node` on disk.
@@ -715,6 +757,106 @@ export function missingNativeExportMessage(symbolName, addon = loadedAddon) {
 	);
 }
 
+/**
+ * One-line notice for a workspace tree running an addon from another release.
+ *
+ * The missing-symbol stubs only speak when a caller touches a symbol the addon
+ * does not carry. A symbol it does carry runs that release's behaviour — an
+ * older shell, an older grep — with no marker at all, so this notice is the
+ * only provenance those failures get.
+ *
+ * `stale` is any release difference, so the wording must not assume the addon
+ * is the older side.
+ * @param {NonNullable<ReturnType<typeof nativeAddonStatus>>} addon
+ * @returns {string}
+ */
+export function staleWorkspaceAddonNotice(addon) {
+	const loaded = addon.version ? `@oh-my-pi/pi-natives@${addon.version}` : "an addon without a release stamp";
+	return (
+		`[pi-natives] ${addon.path} is ${loaded}, but this checkout is @${addon.packageVersion}. ` +
+		"Symbols this checkout expects may be missing and shared ones may behave differently; " +
+		"run `bun run build:native` before trusting results from this tree.\n"
+	);
+}
+
+/**
+ * Whether the copy of this module running on the current thread has already
+ * written the mismatched-addon notice. One per loaded copy, which is one per
+ * main thread in every shape this package ships; the write itself is confined
+ * to the main thread by {@link onMainThread}.
+ */
+const staleNoticeState = { reported: false };
+
+/** Memoized answer from {@link onMainThread}; `undefined` until first asked. */
+let mainThreadAnswer;
+
+/**
+ * True on a process's main thread, false inside a worker thread.
+ *
+ * Resolved through `createRequire` on first use rather than imported at module
+ * scope: `packages/coding-agent/src/cli.ts` keeps `node:worker_threads` out of
+ * ordinary startup on purpose, and this module is reached statically from
+ * `sqlite-locks` on launches that never load an addon. Asking only when a
+ * mismatch has already been found keeps that boundary. A runtime without the
+ * builtin answers "main thread", which is the safe side: the notice prints.
+ * @returns {boolean}
+ */
+function onMainThread() {
+	if (mainThreadAnswer === undefined) {
+		try {
+			mainThreadAnswer = createRequire(import.meta.url)("node:worker_threads").isMainThread !== false;
+		} catch {
+			mainThreadAnswer = true;
+		}
+	}
+	return mainThreadAnswer;
+}
+
+/**
+ * Write {@link staleWorkspaceAddonNotice} once, from the main thread, when a
+ * workspace tree loads an addon of another release.
+ *
+ * Three guards, each load-bearing.
+ *
+ * Main thread only, because fd 2 is shared and a worker reaches `loadNative()`
+ * long after interactive mode owns the terminal — the subagent, JS-eval and
+ * tab workers all start then, so a per-worker write paints into a rendered
+ * frame. The main thread has already said it at startup; a worker repeating it
+ * adds nothing and costs the display. A worker *process* keeps the notice: it
+ * has its own main thread, and `subprocess/worker-client.ts` captures its
+ * stderr to a file rather than the terminal.
+ *
+ * Latched, because `loadNative()` is not a startup-only call: the lazy
+ * entrypoints in `clipboard.js` and friends call it on every invocation.
+ *
+ * Workspace loads only, because {@link validateLoadedBindings} has a second
+ * success path — it accepts a pre-sentinel addon on an installed load
+ * (`isCompatiblePreSentinelNativeAddon`), which reports no release and so
+ * counts as `stale`. That user has no repository to build.
+ *
+ * The write is a synchronous `fs.writeSync` to fd 2 for the same reason as
+ * {@link startupMarker}: it must survive a crash that follows it. `write` and
+ * `state` are injectable so a test can exercise the guards without consuming
+ * this copy's latch.
+ * @param {{ isWorkspaceLoad: boolean }} ctx
+ * @param {NonNullable<ReturnType<typeof nativeAddonStatus>>} addon
+ * @param {{ write?: (text: string) => void; state?: { reported: boolean } }} [deps]
+ * @returns {boolean} whether this call wrote the notice
+ */
+export function reportStaleWorkspaceAddon(ctx, addon, deps = {}) {
+	const state = deps.state ?? staleNoticeState;
+	// Thread identity last: the three cheap gates reject every ordinary launch
+	// before `node:worker_threads` is resolved at all.
+	if (!ctx.isWorkspaceLoad || !addon.stale || state.reported || !onMainThread()) return false;
+	state.reported = true;
+	try {
+		(deps.write ?? (text => fs.writeSync(2, text)))(staleWorkspaceAddonNotice(addon));
+	} catch {
+		// stderr unavailable; the notice is best-effort, the stubs still speak
+	}
+	return true;
+}
+
 /**
  * Install the addon's bounded Tokio runtime now that `dlopen` has returned and
  * the dynamic-loader lock is released. The Rust `#[module_init]` deliberately
@@ -881,6 +1023,7 @@ export function loadNative() {
 			installNativeTokioRuntime(bindings);
 			configureGrammarDir(bindings, ctx.nativesDir);
 			loadedAddon = describeLoadedAddon(bindings, candidate, ctx);
+			reportStaleWorkspaceAddon(ctx, loadedAddon);
 	        cleanupStaleNativeVersions({ nativesDir: ctx.nativesDir, currentVersion: ctx.packageVersion });
 			startupMarker("native:loadNative:done");
 			return bindings;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "18.17.0",
+	"version": "18.18.0",
 	"description": "Native Rust bindings for PDF conversion, audio, WebRTC, grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
 	"type": "module",
 	"homepage": "https://omp.sh",
@@ -120,11 +120,11 @@
 		}
 	},
 	"optionalDependencies": {
-		"@oh-my-pi/pi-natives-linux-x64": "18.17.0",
-		"@oh-my-pi/pi-natives-linux-arm64": "18.17.0",
-		"@oh-my-pi/pi-natives-darwin-x64": "18.17.0",
-		"@oh-my-pi/pi-natives-darwin-arm64": "18.17.0",
-		"@oh-my-pi/pi-natives-win32-x64": "18.17.0",
-		"@oh-my-pi/pi-natives-win32-arm64": "18.17.0"
+		"@oh-my-pi/pi-natives-linux-x64": "18.18.0",
+		"@oh-my-pi/pi-natives-linux-arm64": "18.18.0",
+		"@oh-my-pi/pi-natives-darwin-x64": "18.18.0",
+		"@oh-my-pi/pi-natives-darwin-arm64": "18.18.0",
+		"@oh-my-pi/pi-natives-win32-x64": "18.18.0",
+		"@oh-my-pi/pi-natives-win32-arm64": "18.18.0"
 	}
 }