@feniix/bridgekit 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to `@feniix/bridgekit` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.13.0] - 2026-05-27
+
+### Added
+
+- New `buildStdio` option on `BinWrapperOptions`
+  (`@feniix/bridgekit/bin-wrapper`). Default `"inherit"` preserves
+  existing behavior. **MCP stdio server bins should pass
+  `["ignore", "inherit", "inherit"]`** — the build subprocess's stdout
+  otherwise contaminates the parent's JSON-RPC framing on its own
+  stdout. The default-`"inherit"` behavior was a latent risk for the
+  two current consumers that adopted `runBinWrapper` (works today only
+  because `npm run <script> --silent` happens to be quiet under tsc) and
+  an active blocker for `pi-exa`, which could not migrate from its
+  hand-rolled wrapper. Resolves
+  [#59](https://github.com/feniix/bridgekit/issues/59).
+
+### Changed
+
+- `PiToolDefinition.promptGuidelines` (the internal tool-shape declared
+  in `src/adapters/pi.ts` and exposed via
+  `PiToolRegistration["registerTool"]`'s parameter) widened from
+  `readonly string[]` to `string[]` to close a contravariance gap with
+  pi-coding-agent's `ExtensionAPI`. The runtime contract is unchanged —
+  `registerPiTools` has spread-copied the source array into a fresh
+  `string[]` before handing it to `pi.registerTool` since 0.9.1
+  (PR #48); only the type declaration catches up to reality. Consumers
+  (`pi-exa`, `pi-code-reasoning`, `pi-sequential-thinking`) can drop
+  the `pi as unknown as PiToolRegistration` cast at their
+  `registerPiTools` call sites.
+  `PortableTool.hostExtras.pi.promptGuidelines` (the consumer-facing
+  metadata type) stays `readonly string[]` — that's the right contract
+  for immutable consumer-owned data that bridgekit reads. Resolves
+  [#60](https://github.com/feniix/bridgekit/issues/60).
+
 ## [0.12.0] - 2026-05-27
 
 ### Documentation

package/README.md

@@ -255,6 +255,7 @@ Options:
 - `buildScript` (required): npm script to invoke when the entry is missing (e.g. `"build:mcp"`).
 - `buildTimeoutMs` (optional, default `60_000`): timeout for the build subprocess. Distinct "Build timed out…" diagnostic fires when exceeded.
 - `logPrefix` (optional, default `"bridgekit-bin"`): prefix on the "Failed to build…" diagnostic.
+- `buildStdio` (optional, default `"inherit"`): `stdio` mode passed to `spawnSync` when the build script runs. **MCP stdio server bins should pass `["ignore", "inherit", "inherit"]`** so the build subprocess's stdout cannot contaminate the parent's JSON-RPC framing channel (`process.stdout`). stderr stays inherited so build diagnostics remain visible.
 
 The MCP entry module must export `async function runServer(): Promise<void>`. Consumers with a different export name can alias on export.
 

package/dist/src/adapters/pi.d.ts

@@ -20,7 +20,7 @@ type PiToolDefinition = {
     parameters: TSchema;
     execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: (update: PiToolUpdate) => void, ctx?: unknown): Promise<PiToolResult>;
     promptSnippet?: string;
-    promptGuidelines?: readonly string[];
+    promptGuidelines?: string[];
 };
 export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;

package/dist/src/bin-wrapper-internal.d.ts

@@ -30,6 +30,20 @@ export interface BinWrapperOptions {
     buildScript: string;
     buildTimeoutMs?: number;
     logPrefix?: string;
+    /**
+     * stdio mode passed to `spawnSync` when the build script runs. Defaults to
+     * `"inherit"`.
+     *
+     * **MCP stdio server bins must override this.** `process.stdout` IS the
+     * JSON-RPC channel for an MCP stdio server; any output the build subprocess
+     * emits to stdout (npm warnings, postinstall scripts, tsc diagnostics) flows
+     * directly into the parent's stdout via `stdio: "inherit"` and contaminates
+     * JSON-RPC framing. Pass `["ignore", "inherit", "inherit"]` to route the
+     * build's stdout to `/dev/null` while keeping stderr visible.
+     *
+     * @default "inherit"
+     */
+    buildStdio?: SpawnSyncOptions["stdio"];
 }
 export interface BinWrapperDeps {
     spawnSync: BinWrapperSpawnSync;

package/dist/src/bin-wrapper-internal.js

@@ -20,7 +20,7 @@ export async function runBinWrapperWithDeps(options, deps) {
         const timeoutMs = options.buildTimeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS;
         const build = deps.spawnSync("npm", ["run", options.buildScript, "--silent"], {
             cwd: packageRoot,
-            stdio: "inherit",
+            stdio: options.buildStdio ?? "inherit",
             shell: process.platform === "win32",
             timeout: timeoutMs,
         });

package/llms.txt

@@ -113,10 +113,13 @@ Some hosts, such as pi in source-extension packages, may intentionally load Type
     metaUrl: import.meta.url,
     mcpEntry: "dist/extensions/mcp-server.js",
     buildScript: "build:mcp",
+    // MCP stdio bins: route the build subprocess's stdout to /dev/null so it
+    // cannot contaminate the parent's JSON-RPC framing on process.stdout.
+    buildStdio: ["ignore", "inherit", "inherit"],
   });
   ```
 
-  `mcpEntry` and `buildScript` must be literal strings — sourcing them from CLI args or env vars opens arbitrary-file import and Windows command injection. The MCP entry module must export `async function runServer(): Promise<void>`.
+  `mcpEntry` and `buildScript` must be literal strings — sourcing them from CLI args or env vars opens arbitrary-file import and Windows command injection. The MCP entry module must export `async function runServer(): Promise<void>`. `buildStdio` defaults to `"inherit"`; MCP stdio server bins should override to `["ignore", "inherit", "inherit"]` (since 0.13.0) because `process.stdout` is the JSON-RPC channel and the build subprocess otherwise contaminates framing.
 - Narrow the MCP build to the MCP entrypoint and shared host-neutral modules; avoid compiling pi adapter entrypoints into the standalone MCP path.
 - Put runtime imports used by the compiled MCP bin in `dependencies`, not only peers or dev dependencies.
 - Declare BridgeKit's Node engine requirement in the downstream package (`>=22.19.0`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",