@feniix/bridgekit 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ 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
+
+- `README.md` gets a full `bin-wrapper` adapter section under "API
+  reference" — usage example, options breakdown, `runServer`
+  contract, trusted-literal security note, and the missing-entry
+  behavior matrix. Previously the subpath had a single line in the
+  entrypoint table and zero body documentation. Closes the largest
+  gap surfaced by the post-0.11.0 doc audit.
+- `README.md` "Why" bullet and "Packaging" section updated for the
+  four-entrypoint shape and the `runBinWrapper` recommendation
+  (replaces the pre-0.11.0 manual checked-in-wrapper recipe).
+- `llms.txt` rewrites the "Mixed source-loaded hosts and compiled
+  MCP bins" section to lead with `runBinWrapper`. The 8-bullet
+  manual-wrapper recipe is demoted to a fallback bullet for
+  authors writing their own wrapper.
+- `dist/src/bin-wrapper.d.ts` added to the published-declarations
+  lists in `README.md` and `llms.txt`.
+- `docs/README.md` lists `docs/rfc-host-extras.md` in the
+  maintainer-docs catalog. The RFC is JSDoc-linked from
+  `src/core/define-tool.ts` and was missing from the catalog.
+- `src/adapters/mcp.typecheck.ts` fixes a wrong version stamp on
+  the `signalFromExtra` adversarial-pin comment (was `0.10.0 (#3)`,
+  should be `0.11.0 (#3)`). The pin's code is correct; only the
+  comment was wrong.
+
+No API or behavior changes.
+
 ## [0.11.0] - 2026-05-27
 
 ### Added

package/README.md

@@ -66,7 +66,7 @@ This package is ESM-only and supports Node.js 22.19.0 or newer. Published module
 - Define a tool once; ship it to pi and MCP without per-host forks.
 - Host-neutral tool files: no pi or MCP SDK imports in the tool definition itself.
 - TypeBox schemas pass through to MCP `inputSchema` directly — no JSON Schema conversion step.
-- Import-passive, `sideEffects: false`, three-entrypoint split (`.`, `./pi`, `./mcp`) so pi-only consumers do not pull the MCP SDK and vice versa.
+- Import-passive, `sideEffects: false`, four-entrypoint split (`.`, `./pi`, `./mcp`, `./bin-wrapper`) so pi-only consumers do not pull the MCP SDK and vice versa.
 - Conformance-tested public surface: a packed-install smoke test enforces the runtime export set, deep-import rejection, and type-level strictness against the installed declarations.
 
 ## API reference
@@ -233,6 +233,42 @@ Portable validation failures and portable `isError: true` results return `CallTo
 
 The two adapters now read in parallel: invalid args and portable `isError` results return `{ isError: true }` from both hosts by default, and the same result-guard helpers (`isValidationFailure`, `isDomainFailure`) narrow them on either side.
 
+### bin-wrapper (since 0.11.0)
+
+The `bin-wrapper` subpath ships a helper for npm `bin` scripts that load a compiled MCP entrypoint and build it on first invocation when the compiled output is missing. Replaces the ~25-line "resolve dist path → spawn build if missing → import and run" boilerplate that downstream consumers with mixed source-loaded pi + compiled MCP packages previously hand-rolled.
+
+```js
+#!/usr/bin/env node
+import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
+
+await runBinWrapper({
+  metaUrl: import.meta.url,
+  mcpEntry: "dist/extensions/mcp-server.js",
+  buildScript: "build:mcp",
+});
+```
+
+Options:
+
+- `metaUrl` (required): `import.meta.url` of the bin script. Used to locate the package root (the bin's parent directory).
+- `mcpEntry` (required): path to the compiled MCP entry, relative to the package root (e.g. `"dist/extensions/mcp-server.js"`).
+- `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.
+
+**Security: `mcpEntry` and `buildScript` must be literal strings in the caller's source.** The helper joins `mcpEntry` onto the resolved package root and dynamically `import()`s it, and it passes `buildScript` to `spawnSync` (with `shell: true` on Windows where `&`, `|`, and `^` are shell metacharacters). Sourcing either from CLI args or environment variables exposes arbitrary-file import and Windows command injection.
+
+Behavior on missing entry:
+
+- Build emits the entry → import and call `runServer()`.
+- Build exits non-zero but the entry exists → recover (import and call `runServer()`).
+- Build exits 0 but the entry is still missing → exit with code 1, generic "Failed to build…" diagnostic.
+- Build exits non-zero with entry missing → exit with the build's status code, generic diagnostic.
+- Build killed by timeout (SIGTERM) → exit 1, distinct timeout diagnostic naming `buildTimeoutMs`.
+
 ## Best practices
 
 Tool definition best practices:
@@ -258,7 +294,7 @@ Package and release checklist:
 - Avoid `workspace:` or `file:` dependency ranges in publishable packages.
 - Avoid dangling `sourceMappingURL` comments: publish maps and useful sources together, or disable source maps for package builds.
 - For MCP stdio bins, ensure the executable entrypoint starts with a Node shebang, has executable mode (`chmod +x` or equivalent), and is included by `npm pack --dry-run --json`.
-- If an npm-launched bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing `bin` directly at `dist/`; the wrapper should resolve the package-local generated file and may run the package-local build for workspace/local execution.
+- If an npm-launched bin depends on generated output, use `runBinWrapper` from `@feniix/bridgekit/bin-wrapper` (since 0.11.0) — it resolves the package-local generated entry, runs the package-local build when output is missing in workspace/local execution, preserves build failures, and distinguishes timeout from build error in its diagnostic. The bin script becomes a three-line invocation; no hand-rolled wrapper needed.
 - If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build behind that wrapper and narrow the build to the MCP entrypoint plus shared host-neutral modules.
 - Declare a compatible Node engine (`>=22.19.0`) in downstream packages that expose BridgeKit-powered MCP bins.
 - Run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before publishing.
@@ -272,5 +308,5 @@ Read these files in order:
 
 1. `README.md` — public API, contracts, and best practices.
 2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
-3. `examples/README.md` — copyable layouts for shared tools, pi extensions, MCP stdio servers, and per-host metadata via `hostExtras`.
-4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain the same implementation context.
+3. `examples/README.md` — copyable layouts for shared tools, pi extensions, MCP stdio servers, per-host metadata via `hostExtras`, and bin wrappers via `runBinWrapper`.
+4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, `dist/src/mcp.d.ts`, and `dist/src/bin-wrapper.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain the same implementation context.

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

@@ -7,7 +7,7 @@ Use this package when you need to define a tool once and expose it through both
 1. `README.md` — public API, contracts, best practices, packaging notes.
 2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
 3. `examples/README.md` — copyable end-to-end layouts for shared tools, pi extension wiring, MCP stdio server wiring, and per-host metadata via `hostExtras`.
-4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain implementation context.
+4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, `dist/src/mcp.d.ts`, and `dist/src/bin-wrapper.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain implementation context.
 
 ## Import map
 
@@ -104,12 +104,27 @@ Some hosts, such as pi in source-extension packages, may intentionally load Type
 
 - Keep the host source entrypoint if that is the package convention, e.g. `pi.extensions: ["./extensions/index.ts"]`.
 - Add a package-local MCP build and point npm `bin` at a checked-in wrapper under `bin/`, not directly at generated `dist/` output.
-- The wrapper should resolve the package-local generated MCP server, run the package-local build when output is missing in workspace/local execution, and preserve non-zero build failures.
+- **Use the built-in `runBinWrapper` helper** (since 0.11.0) instead of a hand-rolled wrapper. It resolves the package-local generated entry, runs the package-local build when output is missing in workspace/local execution, preserves non-zero build failures, recovers when the build emits the entry despite a non-zero exit, and emits a distinct timeout diagnostic when `spawnSync` is killed by `buildTimeoutMs`:
+
+  ```js
+  #!/usr/bin/env node
+  import { runBinWrapper } from "@feniix/bridgekit/bin-wrapper";
+  await runBinWrapper({
+    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>`. `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`).
-- Ensure the checked-in wrapper is executable (`chmod +x` or equivalent) and verify the mode with `npm pack --dry-run --json`.
-- Test wrapper behavior for existing output, missing output, failed builds, and builds that exit successfully without creating the expected file.
+- Ensure the bin script is executable (`chmod +x` or equivalent) and verify the mode with `npm pack --dry-run --json`.
+- If you write your own wrapper instead of using `runBinWrapper`, test the four behavior modes: existing output, missing output that the build creates, failed builds (non-zero exit), and builds that exit successfully without creating the expected file.
 
 ## Anti-patterns
 

package/package.json

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