gsd-pi 2.10.2 → 2.10.5

package/node_modules/@gsd/pi-coding-agent/src/core/tools/bash-interceptor.test.ts

@@ -0,0 +1,198 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+	checkBashInterception,
+	compileInterceptor,
+	DEFAULT_BASH_INTERCEPTOR_RULES,
+	type BashInterceptorRule,
+} from "./bash-interceptor.js";
+
+const ALL_TOOLS = ["read", "grep", "find", "edit", "write"];
+const NO_TOOLS: string[] = [];
+
+describe("checkBashInterception", () => {
+	describe("read rule (cat/head/tail/less/more)", () => {
+		it("blocks cat with a file argument", () => {
+			const r = checkBashInterception("cat README.md", ALL_TOOLS);
+			assert.equal(r.block, true);
+			assert.equal(r.suggestedTool, "read");
+		});
+
+		it("blocks head and tail", () => {
+			assert.equal(checkBashInterception("head -n 20 file.ts", ALL_TOOLS).block, true);
+			assert.equal(checkBashInterception("tail -f app.log", ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block cat used as heredoc (cat <<EOF)", () => {
+			const r = checkBashInterception("cat <<EOF > file.txt", ALL_TOOLS);
+			assert.notEqual(r.suggestedTool, "read");
+		});
+
+		it("does NOT block when read tool is absent", () => {
+			assert.equal(checkBashInterception("cat README.md", NO_TOOLS).block, false);
+			assert.equal(checkBashInterception("cat README.md", ["grep"]).block, false);
+		});
+	});
+
+	describe("grep rule", () => {
+		it("blocks grep and rg", () => {
+			assert.equal(checkBashInterception("grep foo bar.ts", ALL_TOOLS).block, true);
+			assert.equal(checkBashInterception("rg -r pattern .", ALL_TOOLS).block, true);
+		});
+
+		it("blocks grep with leading whitespace", () => {
+			assert.equal(checkBashInterception("  grep -r foo .", ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block when grep tool is absent", () => {
+			assert.equal(checkBashInterception("grep foo bar", ["read", "edit"]).block, false);
+		});
+	});
+
+	describe("find rule", () => {
+		it("blocks find with -name flag", () => {
+			assert.equal(checkBashInterception('find . -name "*.ts"', ALL_TOOLS).block, true);
+		});
+
+		it("blocks find with -type flag", () => {
+			assert.equal(checkBashInterception("find /tmp -maxdepth 1 -type f", ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block find without name/type flags", () => {
+			assert.equal(checkBashInterception("find /tmp -maxdepth 1", ALL_TOOLS).block, false);
+		});
+
+		it("does NOT block when find tool is absent", () => {
+			assert.equal(checkBashInterception('find . -name "*.ts"', ["read", "grep"]).block, false);
+		});
+	});
+
+	describe("edit rule (sed/perl/awk)", () => {
+		it("blocks sed -i", () => {
+			assert.equal(checkBashInterception("sed -i 's/foo/bar/' file.ts", ALL_TOOLS).block, true);
+			assert.equal(checkBashInterception("sed --in-place 's/x/y/' f", ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block sed without -i (read-only)", () => {
+			assert.equal(checkBashInterception("sed 's/foo/bar/' file.ts", ALL_TOOLS).block, false);
+		});
+
+		it("blocks perl -pi and perl -p -i", () => {
+			assert.equal(checkBashInterception("perl -pi -e 's/foo/bar/' file", ALL_TOOLS).block, true);
+			assert.equal(checkBashInterception("perl -p -i -e 's/x/y/' f", ALL_TOOLS).block, true);
+		});
+
+		it("blocks awk -i inplace", () => {
+			assert.equal(checkBashInterception("awk -i inplace '{print}' file", ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block when edit tool is absent", () => {
+			assert.equal(checkBashInterception("sed -i 's/a/b/' f", ["read", "grep"]).block, false);
+		});
+	});
+
+	describe("write rule (echo/printf/heredoc redirect)", () => {
+		it("blocks echo with > redirect", () => {
+			assert.equal(checkBashInterception("echo hello > file.txt", ALL_TOOLS).block, true);
+		});
+
+		it("blocks printf with > redirect", () => {
+			assert.equal(checkBashInterception('printf "%s" content > out.txt', ALL_TOOLS).block, true);
+		});
+
+		it("does NOT block echo without redirect", () => {
+			assert.equal(checkBashInterception("echo hello", ALL_TOOLS).block, false);
+		});
+
+		it("does NOT block >> append redirect (write tool does not support appending)", () => {
+			assert.equal(checkBashInterception("echo hello >> file.txt", ALL_TOOLS).block, false);
+		});
+
+		it("does NOT block stderr redirect (2>)", () => {
+			assert.equal(checkBashInterception("echo test 2> /dev/null", ALL_TOOLS).block, false);
+		});
+
+		it("does NOT block pipe (echo foo | grep bar)", () => {
+			assert.equal(checkBashInterception("echo foo | grep bar", ALL_TOOLS).block, false);
+		});
+
+		it("does NOT block when write tool is absent", () => {
+			assert.equal(checkBashInterception("echo hello > file.txt", ["read", "grep"]).block, false);
+		});
+	});
+
+	describe("pass-through commands", () => {
+		it("passes npm install", () => {
+			assert.equal(checkBashInterception("npm install", ALL_TOOLS).block, false);
+		});
+
+		it("passes ls > output.txt (not an echo/printf/cat)", () => {
+			assert.equal(checkBashInterception("ls > output.txt", ALL_TOOLS).block, false);
+		});
+
+		it("passes tee file.txt", () => {
+			assert.equal(checkBashInterception("tee file.txt", ALL_TOOLS).block, false);
+		});
+
+		it("passes git log", () => {
+			assert.equal(checkBashInterception("git log --oneline", ALL_TOOLS).block, false);
+		});
+	});
+
+	describe("block message content", () => {
+		it("includes the original command in the block message", () => {
+			const r = checkBashInterception("cat README.md", ALL_TOOLS);
+			assert.ok(r.message?.includes("cat README.md"), "message should contain original command");
+		});
+
+		it("returns block:false with no message when not blocked", () => {
+			const r = checkBashInterception("npm install", ALL_TOOLS);
+			assert.equal(r.block, false);
+			assert.equal(r.message, undefined);
+		});
+	});
+});
+
+describe("compileInterceptor", () => {
+	it("produces same results as checkBashInterception", () => {
+		const interceptor = compileInterceptor(DEFAULT_BASH_INTERCEPTOR_RULES);
+		const cases: [string, string[], boolean][] = [
+			["cat README.md", ALL_TOOLS, true],
+			["npm install", ALL_TOOLS, false],
+			["grep foo bar", ALL_TOOLS, true],
+			["echo hello >> file", ALL_TOOLS, false],
+			["echo test 2> /dev/null", ALL_TOOLS, false],
+		];
+		for (const [cmd, tools, expected] of cases) {
+			assert.equal(
+				interceptor.check(cmd, tools).block,
+				expected,
+				`pre-compiled: "${cmd}" expected block=${expected}`,
+			);
+		}
+	});
+
+	it("silently skips rules with invalid regex patterns", () => {
+		const rules: BashInterceptorRule[] = [
+			{ pattern: "[invalid(", tool: "read", message: "broken" },
+			{ pattern: "^\\s*cat\\s+", tool: "read", message: "valid" },
+		];
+		const interceptor = compileInterceptor(rules);
+		assert.equal(interceptor.check("cat file.txt", ["read"]).block, true);
+	});
+
+	it("returns block:false when available tools list is empty", () => {
+		const interceptor = compileInterceptor(DEFAULT_BASH_INTERCEPTOR_RULES);
+		assert.equal(interceptor.check("cat README.md", []).block, false);
+	});
+
+	it("allows custom rule override", () => {
+		const customRules: BashInterceptorRule[] = [
+			{ pattern: "^\\s*curl\\s+", tool: "fetch", message: "Use fetch tool instead." },
+		];
+		const interceptor = compileInterceptor(customRules);
+		assert.equal(interceptor.check("curl https://example.com", ["fetch"]).block, true);
+		// default rules not active
+		assert.equal(interceptor.check("cat file.txt", ["read"]).block, false);
+	});
+});

package/node_modules/@gsd/pi-coding-agent/src/core/tools/bash-interceptor.ts

@@ -0,0 +1,115 @@
+/**
+ * Bash command interceptor — blocks shell commands that duplicate dedicated tools.
+ *
+ * Each rule defines a regex pattern, a suggested replacement tool, and a message.
+ * A command is only blocked when the suggested tool exists in the session's active tool list.
+ */
+
+export interface BashInterceptorRule {
+	pattern: string;
+	flags?: string;
+	tool: string;
+	message: string;
+}
+
+export const DEFAULT_BASH_INTERCEPTOR_RULES: BashInterceptorRule[] = [
+	{
+		// cat/head/tail for file viewing — excludes heredoc syntax (cat <<)
+		pattern: "^\\s*(cat(?!\\s*<<)|head|tail|less|more)\\s+",
+		tool: "read",
+		message: "Use the read tool to view file contents instead of shell commands.",
+	},
+	{
+		pattern: "^\\s*(grep|rg|ripgrep|ag|ack)\\s+",
+		tool: "grep",
+		message: "Use the grep tool for searching file contents instead of shell commands.",
+	},
+	{
+		pattern: "^\\s*(find|fd|locate)\\s+.*(-name|-iname|-type|--type|-glob)",
+		tool: "find",
+		message: "Use the find tool for locating files by name/type instead of shell commands.",
+	},
+	{
+		pattern: "^\\s*sed\\s+(-i|--in-place)",
+		tool: "edit",
+		message: "Use the edit tool for in-place file modifications instead of sed.",
+	},
+	{
+		pattern: "^\\s*perl\\s+.*-[pn]?i",
+		tool: "edit",
+		message: "Use the edit tool for in-place file modifications instead of perl.",
+	},
+	{
+		pattern: "^\\s*awk\\s+.*-i\\s+inplace",
+		tool: "edit",
+		message: "Use the edit tool for in-place file modifications instead of awk.",
+	},
+	{
+		// echo/printf/heredoc writing to a file via > (not >> append, not 2> stderr redirect)
+		// Matches a single > not preceded by |, >, or a digit (fd redirect like 2>)
+		pattern: "^\\s*(echo|printf|cat\\s*<<)\\s+.*(?<![|>\\d])>(?!>)\\s*\\S",
+		tool: "write",
+		message: "Use the write tool to create/overwrite files instead of shell redirects.",
+	},
+];
+
+export interface InterceptionResult {
+	block: boolean;
+	message?: string;
+	suggestedTool?: string;
+}
+
+export interface CompiledInterceptor {
+	check: (command: string, availableTools: string[]) => InterceptionResult;
+}
+
+/**
+ * Compile rules into an interceptor with pre-built regex objects.
+ * Silently skips rules with invalid patterns.
+ *
+ * Pre-compiling at construction time avoids repeated `new RegExp()` calls
+ * on every bash command invocation.
+ */
+export function compileInterceptor(rules: BashInterceptorRule[]): CompiledInterceptor {
+	const compiled = rules.flatMap((rule) => {
+		try {
+			return [{ regex: new RegExp(rule.pattern, rule.flags), rule }];
+		} catch {
+			return []; // skip invalid regex
+		}
+	});
+
+	return {
+		check(command: string, availableTools: string[]): InterceptionResult {
+			const trimmed = command.trim();
+			for (const { regex, rule } of compiled) {
+				if (regex.test(trimmed) && availableTools.includes(rule.tool)) {
+					return {
+						block: true,
+						message: `Blocked: ${rule.message}\n\nOriginal command: ${command}`,
+						suggestedTool: rule.tool,
+					};
+				}
+			}
+			return { block: false };
+		},
+	};
+}
+
+/**
+ * Check whether a bash command should be intercepted.
+ *
+ * Compiles rules on each call — prefer `compileInterceptor()` for repeated use.
+ *
+ * @param command - The shell command to check
+ * @param availableTools - Tool names present in the current session
+ * @param rules - Override the default rule set (optional)
+ */
+export function checkBashInterception(
+	command: string,
+	availableTools: string[],
+	rules?: BashInterceptorRule[],
+): InterceptionResult {
+	const effectiveRules = rules ?? DEFAULT_BASH_INTERCEPTOR_RULES;
+	return compileInterceptor(effectiveRules).check(command, availableTools);
+}

package/node_modules/@gsd/pi-coding-agent/src/core/tools/bash.ts

@@ -7,6 +7,7 @@ import type { AgentTool } from "@gsd/pi-agent-core";
 import { type Static, Type } from "@sinclair/typebox";
 import { spawn } from "child_process";
 import { getShellConfig, getShellEnv, killProcessTree, sanitizeCommand } from "../../utils/shell.js";
+import { type BashInterceptorRule, compileInterceptor, DEFAULT_BASH_INTERCEPTOR_RULES } from "./bash-interceptor.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateTail } from "./truncate.js";
 import type { ArtifactManager } from "../artifact-manager.js";
 
@@ -191,6 +192,13 @@ export interface BashToolOptions {
 	spawnHook?: BashSpawnHook;
 	/** Session-scoped artifact storage. When provided, spills to artifact files instead of temp files. */
 	artifactManager?: ArtifactManager;
+	/** Bash interceptor configuration — blocks commands that duplicate dedicated tools */
+	interceptor?: {
+		enabled: boolean;
+		rules?: BashInterceptorRule[];
+	};
+	/** Tool names available in the session, used by the interceptor to check if replacement tools exist */
+	availableToolNames?: string[] | (() => string[]);
 }
 
 export function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {
@@ -199,6 +207,12 @@ export function createBashTool(cwd: string, options?: BashToolOptions): AgentToo
 	const spawnHook = options?.spawnHook;
 	const artifactManager = options?.artifactManager;
 
+	// Pre-compile interceptor rules once at construction time
+	const interceptorInstance =
+		options?.interceptor?.enabled
+			? compileInterceptor(options.interceptor.rules ?? DEFAULT_BASH_INTERCEPTOR_RULES)
+			: null;
+
 	return {
 		name: "bash",
 		label: "bash",
@@ -210,6 +224,21 @@ export function createBashTool(cwd: string, options?: BashToolOptions): AgentToo
 			signal?: AbortSignal,
 			onUpdate?,
 		) => {
+			// Check bash interceptor — block commands that duplicate dedicated tools
+			if (interceptorInstance) {
+				const toolNames =
+					typeof options!.availableToolNames === "function"
+						? options!.availableToolNames()
+						: options!.availableToolNames ?? [];
+				const interception = interceptorInstance.check(command, toolNames);
+				if (interception.block) {
+					return {
+						content: [{ type: "text" as const, text: interception.message ?? "Command blocked by interceptor" }],
+						details: undefined,
+					};
+				}
+			}
+
 			// Apply command prefix if configured (e.g., "shopt -s expand_aliases" for alias support)
 			const resolvedCommand = sanitizeCommand(commandPrefix ? `${commandPrefix}\n${command}` : command);
 			const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook);

package/node_modules/@gsd/pi-coding-agent/src/core/tools/index.ts

@@ -8,6 +8,14 @@ export {
 	bashTool,
 	createBashTool,
 } from "./bash.js";
+export {
+	type BashInterceptorRule,
+	checkBashInterception,
+	type CompiledInterceptor,
+	compileInterceptor,
+	DEFAULT_BASH_INTERCEPTOR_RULES,
+	type InterceptionResult,
+} from "./bash-interceptor.js";
 export {
 	createEditTool,
 	type EditOperations,

package/node_modules/@gsd/pi-coding-agent/src/index.ts

@@ -202,6 +202,7 @@ export {
 export { BlobStore, isBlobRef, parseBlobRef, externalizeImageData, resolveImageData } from "./core/blob-store.js";
 export { ArtifactManager } from "./core/artifact-manager.js";
 export {
+	type AsyncSettings,
 	type CompactionSettings,
 	type ImageSettings,
 	type PackageSource,
@@ -220,6 +221,7 @@ export {
 } from "./core/skills.js";
 // Tools
 export {
+	type BashInterceptorRule,
 	type BashOperations,
 	type BashSpawnContext,
 	type BashSpawnHook,
@@ -227,6 +229,10 @@ export {
 	type BashToolInput,
 	type BashToolOptions,
 	bashTool,
+	checkBashInterception,
+	type CompiledInterceptor,
+	compileInterceptor,
+	DEFAULT_BASH_INTERCEPTOR_RULES,
 	codingTools,
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,

package/node_modules/@gsd/pi-coding-agent/src/modes/interactive/interactive-mode.ts

@@ -175,7 +175,7 @@ export class InteractiveMode {
 	private pendingTools = new Map<string, ToolExecutionComponent>();
 
 	// Tool output expansion state
-	private toolOutputExpanded = true;
+	private toolOutputExpanded = false;
 
 	// Thinking block visibility state
 	private hideThinkingBlock = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.10.2",
+  "version": "2.10.5",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,8 @@
     "pi:install-global": "node scripts/install-pi-global.js",
     "pi:uninstall-global": "node scripts/uninstall-pi-global.js",
     "sync-pkg-version": "node scripts/sync-pkg-version.cjs",
-    "prepublishOnly": "npm run sync-pkg-version && npm run build"
+    "sync-platform-versions": "node native/scripts/sync-platform-versions.cjs",
+    "prepublishOnly": "npm run sync-pkg-version && npm run sync-platform-versions && npm run build"
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
@@ -81,6 +82,11 @@
     "typescript": "^5.4.0"
   },
   "optionalDependencies": {
+    "@gsd-build/engine-darwin-arm64": "2.10.5",
+    "@gsd-build/engine-darwin-x64": "2.10.5",
+    "@gsd-build/engine-linux-x64-gnu": "2.10.5",
+    "@gsd-build/engine-linux-arm64-gnu": "2.10.5",
+    "@gsd-build/engine-win32-x64-msvc": "2.10.5",
     "fsevents": "~2.3.3"
   },
   "overrides": {

package/packages/native/dist/hasher/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Native BLAKE3 content hashing — Rust implementation via napi-rs.
+ *
+ * Provides ultra-fast content hashing (~GB/s) using BLAKE3 with automatic
+ * SIMD acceleration (AVX2, SSE4.1, NEON). All hashes are lowercase hex,
+ * 64 characters (256-bit).
+ */
+export interface HashDirectoryOptions {
+    /** Glob pattern to filter files (e.g. "**\/*.ts"). Defaults to all files. */
+    glob?: string;
+    /** Whether to respect .gitignore rules. Defaults to true. */
+    gitignore?: boolean;
+}
+/** BLAKE3 hash of a UTF-8 string, returned as lowercase 64-char hex. */
+export declare function hashString(text: string): string;
+/** BLAKE3 hash of a file's contents, returned as lowercase 64-char hex. */
+export declare function hashFile(path: string): string;
+/**
+ * BLAKE3 hash of multiple files in parallel.
+ * Returns a map of path -> hex hash. Silently skips unreadable files.
+ */
+export declare function hashFiles(paths: string[]): Record<string, string>;
+/**
+ * BLAKE3 hash all files in a directory, optionally filtered by glob.
+ * Returns a map of relative path -> hex hash.
+ */
+export declare function hashDirectory(dirPath: string, options?: HashDirectoryOptions): Record<string, string>;
+/**
+ * Given previous hashes (path -> hex), re-hash each file and return
+ * paths whose content changed or no longer exist.
+ */
+export declare function didFilesChange(hashes: Record<string, string>): string[];

package/packages/native/dist/hasher/index.js

@@ -0,0 +1,37 @@
+/**
+ * Native BLAKE3 content hashing — Rust implementation via napi-rs.
+ *
+ * Provides ultra-fast content hashing (~GB/s) using BLAKE3 with automatic
+ * SIMD acceleration (AVX2, SSE4.1, NEON). All hashes are lowercase hex,
+ * 64 characters (256-bit).
+ */
+import { native } from "../native.js";
+/** BLAKE3 hash of a UTF-8 string, returned as lowercase 64-char hex. */
+export function hashString(text) {
+    return native.hashString(text);
+}
+/** BLAKE3 hash of a file's contents, returned as lowercase 64-char hex. */
+export function hashFile(path) {
+    return native.hashFile(path);
+}
+/**
+ * BLAKE3 hash of multiple files in parallel.
+ * Returns a map of path -> hex hash. Silently skips unreadable files.
+ */
+export function hashFiles(paths) {
+    return native.hashFiles(paths);
+}
+/**
+ * BLAKE3 hash all files in a directory, optionally filtered by glob.
+ * Returns a map of relative path -> hex hash.
+ */
+export function hashDirectory(dirPath, options) {
+    return native.hashDirectory(dirPath, options);
+}
+/**
+ * Given previous hashes (path -> hex), re-hash each file and return
+ * paths whose content changed or no longer exist.
+ */
+export function didFilesChange(hashes) {
+    return native.didFilesChange(hashes);
+}

package/packages/native/dist/native.d.ts

@@ -2,7 +2,10 @@
  * Native addon loader.
  *
  * Locates and loads the compiled Rust N-API addon (`.node` file).
- * Tries platform-tagged release builds first, then falls back to dev builds.
+ * Resolution order:
+ *   1. @gsd-build/engine-{platform} npm optional dependency (production install)
+ *   2. native/addon/gsd_engine.{platform}.node (local release build)
+ *   3. native/addon/gsd_engine.dev.node (local debug build)
  */
 export declare const native: {
     search: (content: Buffer | Uint8Array, options: unknown) => unknown;

package/packages/native/dist/native.js

@@ -2,7 +2,10 @@
  * Native addon loader.
  *
  * Locates and loads the compiled Rust N-API addon (`.node` file).
- * Tries platform-tagged release builds first, then falls back to dev builds.
+ * Resolution order:
+ *   1. @gsd-build/engine-{platform} npm optional dependency (production install)
+ *   2. native/addon/gsd_engine.{platform}.node (local release build)
+ *   3. native/addon/gsd_engine.dev.node (local debug build)
  */
 import { createRequire } from "node:module";
 import * as path from "node:path";
@@ -11,24 +14,51 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 const addonDir = path.resolve(__dirname, "..", "..", "..", "native", "addon");
 const platformTag = `${process.platform}-${process.arch}`;
-const candidates = [
-    path.join(addonDir, `gsd_engine.${platformTag}.node`),
-    path.join(addonDir, "gsd_engine.dev.node"),
-];
+/** Map Node.js platform/arch to the npm package suffix */
+const platformPackageMap = {
+    "darwin-arm64": "darwin-arm64",
+    "darwin-x64": "darwin-x64",
+    "linux-x64": "linux-x64-gnu",
+    "linux-arm64": "linux-arm64-gnu",
+    "win32-x64": "win32-x64-msvc",
+};
 function loadNative() {
     const errors = [];
-    for (const candidate of candidates) {
+    // 1. Try the platform-specific npm optional dependency
+    const packageSuffix = platformPackageMap[platformTag];
+    if (packageSuffix) {
         try {
-            return require(candidate);
+            return require(`@gsd-build/engine-${packageSuffix}`);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            errors.push(`${candidate}: ${message}`);
+            errors.push(`@gsd-build/engine-${packageSuffix}: ${message}`);
         }
     }
+    // 2. Try local release build (native/addon/gsd_engine.{platform}.node)
+    const releasePath = path.join(addonDir, `gsd_engine.${platformTag}.node`);
+    try {
+        return require(releasePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`${releasePath}: ${message}`);
+    }
+    // 3. Try local dev build (native/addon/gsd_engine.dev.node)
+    const devPath = path.join(addonDir, "gsd_engine.dev.node");
+    try {
+        return require(devPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`${devPath}: ${message}`);
+    }
     const details = errors.map((e) => `  - ${e}`).join("\n");
+    const supportedPlatforms = Object.keys(platformPackageMap);
     throw new Error(`Failed to load gsd_engine native addon for ${platformTag}.\n\n` +
         `Tried:\n${details}\n\n` +
-        `Build with: npm run build:native -w @gsd/native`);
+        `Supported platforms: ${supportedPlatforms.join(", ")}\n` +
+        `If your platform is listed, try reinstalling: npm i -g gsd-pi\n` +
+        `Otherwise, please open an issue: https://github.com/gsd-build/gsd-2/issues`);
 }
 export const native = loadNative();

package/packages/native/dist/xxhash/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Native xxHash32 — Rust implementation via napi-rs.
+ *
+ * Drop-in replacement for the pure-JS xxHash32 in hashline.ts.
+ * Hashes the UTF-8 representation of the input string with the given seed.
+ */
+/**
+ * Compute xxHash32 of a UTF-8 string.
+ *
+ * @param input  The string to hash (encoded as UTF-8 internally).
+ * @param seed   32-bit seed value.
+ * @returns      32-bit unsigned hash.
+ */
+export declare function xxHash32(input: string, seed: number): number;

package/packages/native/dist/xxhash/index.js

@@ -0,0 +1,17 @@
+/**
+ * Native xxHash32 — Rust implementation via napi-rs.
+ *
+ * Drop-in replacement for the pure-JS xxHash32 in hashline.ts.
+ * Hashes the UTF-8 representation of the input string with the given seed.
+ */
+import { native } from "../native.js";
+/**
+ * Compute xxHash32 of a UTF-8 string.
+ *
+ * @param input  The string to hash (encoded as UTF-8 internally).
+ * @param seed   32-bit seed value.
+ * @returns      32-bit unsigned hash.
+ */
+export function xxHash32(input, seed) {
+    return native.xxHash32(input, seed);
+}