@vitest-agent/sidecar 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @vitest-agent/sidecar
+
+[![npm](https://img.shields.io/npm/v/@vitest-agent/sidecar?label=npm&color=cb3837)](https://www.npmjs.com/package/@vitest-agent/sidecar)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+> **Part of the [vitest-agent](https://vitest-agent.dev) ecosystem.** Most users want **[@vitest-agent/plugin](https://www.npmjs.com/package/@vitest-agent/plugin)**, which pulls this package in automatically (it installs automatically with the CLI; you rarely add it directly).
+
+A Node Single Executable Application (SEA) binary for the per-Bash-call `inject-env` hot path. Every Bash tool call from a Claude Code agent fires the plugin's `pre-tool-use/bash.sh` hook, which detects Vitest invocations and prepends the canonical `VITEST_AGENT_*` env prefix. Running that through the full `vitest-agent` CLI pays Node cold-start latency on every call; this binary runs the same logic with a fraction of the startup cost.
+
+## Features
+
+- **Native binary** — Node SEA wrapping the same `inject-env` TypeScript that ships in `@vitest-agent/cli`; JS fallback and binary stay byte-identical
+- **Per-platform sub-packages** — `@vitest-agent/sidecar-darwin-arm64`, `@vitest-agent/sidecar-linux-arm64`, `@vitest-agent/sidecar-linux-x64`, `@vitest-agent/sidecar-win32-x64` as `optionalDependencies`; only the matching one installs
+- **`resolveSidecarBinaryPath()`** — exported function that returns the absolute path of the installed binary, or `null` on unsupported platforms
+
+## Install
+
+```bash
+npm install --save-dev @vitest-agent/plugin
+# @vitest-agent/sidecar arrives transitively through @vitest-agent/cli
+```
+
+The plugin's SessionStart hook resolves the binary path once per session via `vitest-agent agent sidecar-path` and exports `VITEST_AGENT_SIDECAR_BIN`. The PreToolUse Bash hook reads that env var and execs the binary directly — no PATH lookup, no Node startup. On unsupported platforms the hook falls back to the `vitest-agent` JS CLI automatically.
+
+## Documentation
+
+Package reference at [vitest-agent.dev/sidecar](https://vitest-agent.dev/sidecar).
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,47 @@
+//#region src/resolve-sidecar-binary-path.d.ts
+/**
+ * \@vitest-agent/sidecar
+ *
+ * Resolves the absolute path of the platform-specific sidecar binary
+ * by using `require.resolve` on the optional platform package's bin entry.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Platform and architecture resolver options for dependency injection in tests.
+ *
+ * @public
+ */
+interface ResolveSidecarBinaryPathOptions {
+  /** Override the platform (defaults to `process.platform`). */
+  readonly platform?: NodeJS.Platform;
+  /** Override the architecture (defaults to `process.arch`). */
+  readonly arch?: string;
+  /** Override the module resolver (defaults to `createRequire`-backed resolver). */
+  readonly resolver?: (path: string) => string;
+}
+/**
+ * Resolve the absolute path of the platform-specific sidecar binary.
+ *
+ * The four platform packages that ship SEA binaries are:
+ *   - `@vitest-agent/sidecar-darwin-arm64`  → `bin/vitest-agent-sidecar`
+ *   - `@vitest-agent/sidecar-linux-arm64`   → `bin/vitest-agent-sidecar`
+ *   - `@vitest-agent/sidecar-linux-x64`     → `bin/vitest-agent-sidecar`
+ *   - `@vitest-agent/sidecar-win32-x64`     → `bin/vitest-agent-sidecar.exe`
+ *
+ * The binary path is resolved via `require.resolve` of the platform package's
+ * bin entry (not discovered on PATH), so transitive optional dependencies that
+ * are never hoisted to `node_modules/.bin/` are still found correctly.
+ *
+ * Returns `null` when:
+ *   - The platform/arch combination has no matching package (e.g. darwin-x64).
+ *   - The matching optional dependency was not installed (MODULE_NOT_FOUND).
+ *
+ * @param options - Optional overrides for platform, arch, and resolver (for testing).
+ * @returns The absolute path to the binary, or `null` when not resolvable.
+ * @public
+ */
+declare function resolveSidecarBinaryPath(options?: ResolveSidecarBinaryPathOptions): string | null;
+//#endregion
+export { type ResolveSidecarBinaryPathOptions, resolveSidecarBinaryPath };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,3 @@
+import { resolveSidecarBinaryPath } from "./resolve-sidecar-binary-path.js";
+
+export { resolveSidecarBinaryPath };

package/package.json

@@ -0,0 +1,45 @@
+{
+	"name": "@vitest-agent/sidecar",
+	"version": "1.0.0",
+	"private": false,
+	"description": "Fast-path native binary for vitest-agent. Ships a Node SEA executable that handles the per-Bash-call inject-env hot path.",
+	"keywords": [
+		"vitest",
+		"agent",
+		"sidecar",
+		"sea",
+		"binary"
+	],
+	"homepage": "https://github.com/spencerbeggs/vitest-agent#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/vitest-agent/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/vitest-agent.git",
+		"directory": "packages/sidecar"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"optionalDependencies": {
+		"@vitest-agent/sidecar-darwin-arm64": "1.0.0",
+		"@vitest-agent/sidecar-linux-arm64": "1.0.0",
+		"@vitest-agent/sidecar-linux-x64": "1.0.0",
+		"@vitest-agent/sidecar-win32-x64": "1.0.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/resolve-sidecar-binary-path.js

@@ -0,0 +1,57 @@
+import { createRequire } from "node:module";
+
+//#region src/resolve-sidecar-binary-path.ts
+/**
+* \@vitest-agent/sidecar
+*
+* Resolves the absolute path of the platform-specific sidecar binary
+* by using `require.resolve` on the optional platform package's bin entry.
+*
+* @packageDocumentation
+*/
+/**
+* The four platform/arch combinations that have a matching sidecar package.
+* darwin-x64 is intentionally absent — there is no such package.
+*/
+const SUPPORTED_PLATFORMS = /* @__PURE__ */ new Map([
+	["darwin-arm64", "@vitest-agent/sidecar-darwin-arm64"],
+	["linux-arm64", "@vitest-agent/sidecar-linux-arm64"],
+	["linux-x64", "@vitest-agent/sidecar-linux-x64"],
+	["win32-x64", "@vitest-agent/sidecar-win32-x64"]
+]);
+/**
+* Resolve the absolute path of the platform-specific sidecar binary.
+*
+* The four platform packages that ship SEA binaries are:
+*   - `@vitest-agent/sidecar-darwin-arm64`  → `bin/vitest-agent-sidecar`
+*   - `@vitest-agent/sidecar-linux-arm64`   → `bin/vitest-agent-sidecar`
+*   - `@vitest-agent/sidecar-linux-x64`     → `bin/vitest-agent-sidecar`
+*   - `@vitest-agent/sidecar-win32-x64`     → `bin/vitest-agent-sidecar.exe`
+*
+* The binary path is resolved via `require.resolve` of the platform package's
+* bin entry (not discovered on PATH), so transitive optional dependencies that
+* are never hoisted to `node_modules/.bin/` are still found correctly.
+*
+* Returns `null` when:
+*   - The platform/arch combination has no matching package (e.g. darwin-x64).
+*   - The matching optional dependency was not installed (MODULE_NOT_FOUND).
+*
+* @param options - Optional overrides for platform, arch, and resolver (for testing).
+* @returns The absolute path to the binary, or `null` when not resolvable.
+* @public
+*/
+function resolveSidecarBinaryPath(options = {}) {
+	const key = `${options.platform ?? process.platform}-${options.arch ?? process.arch}`;
+	const packageName = SUPPORTED_PLATFORMS.get(key);
+	if (packageName === void 0) return null;
+	const resolve = options.resolver ?? createRequire(import.meta.url).resolve;
+	try {
+		return resolve(packageName);
+	} catch (err) {
+		if (err.code === "MODULE_NOT_FOUND") return null;
+		throw err;
+	}
+}
+
+//#endregion
+export { resolveSidecarBinaryPath };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}