@feniix/bridgekit 0.4.0 → 0.6.0

package/README.md

@@ -171,8 +171,9 @@ Use `PortableToolHost<CustomHost>` for values that may be either a built-in host
 - Keep runtime imports in `dependencies`.
 - 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 emitted JavaScript starts with a Node shebang, has executable mode (`chmod +x` or equivalent), and is included by `npm pack --dry-run --json`.
-- If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build for the npm-launched bin and narrow that build to the MCP entrypoint plus shared host-neutral modules.
+- 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 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.
 - Treat `docs/releasing.md` as the future release handoff; this repository is not configured for automated publish yet.

package/dist/src/adapters/mcp-signal.d.ts

@@ -1 +1,9 @@
+/**
+ * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
+ * does not formally type a `signal` on `extra`, so the shape is sniffed
+ * structurally.
+ *
+ * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
+ * major bump in case the cancellation channel moves or gains a typed surface.
+ */
 export declare function signalFromExtra(extra: unknown): AbortSignal | undefined;

package/dist/src/adapters/mcp-signal.js

@@ -1,3 +1,11 @@
+/**
+ * Defensively pulls an `AbortSignal` out of MCP request `extra`. The MCP SDK
+ * does not formally type a `signal` on `extra`, so the shape is sniffed
+ * structurally.
+ *
+ * Validated against `@modelcontextprotocol/sdk` v1.x. Revalidate on any SDK
+ * major bump in case the cancellation channel moves or gains a typed surface.
+ */
 export function signalFromExtra(extra) {
     if (!extra || typeof extra !== "object" || !("signal" in extra)) {
         return undefined;

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

@@ -1,5 +1,5 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolResult } from "../core/define-tool.js";
+import type { PortableTool, PortableToolErrorDetails, PortableToolResult } from "../core/define-tool.js";
 type PiContent = {
     type: "text";
     text: string;
@@ -23,7 +23,7 @@ export type PiToolRegistration = {
     registerTool(tool: PiToolDefinition): unknown;
 };
 export declare class PortableToolExecutionError extends Error {
-    readonly details: Record<string, unknown>;
+    readonly details: PortableToolErrorDetails;
     constructor(result: PortableToolResult);
 }
 export declare function isPortableToolExecutionError(error: unknown): error is PortableToolExecutionError;

package/dist/src/adapters/pi.js

@@ -2,12 +2,23 @@ import { executePortableTool } from "../core/execute-tool.js";
 function toPiDetails(result) {
     return result.structuredContent ?? result.details ?? {};
 }
+function isValidationDetails(source) {
+    return source.kind === "validation" && typeof source.tool === "string" && Array.isArray(source.validationErrors);
+}
+function toPortableToolErrorDetails(result) {
+    const source = toPiDetails(result);
+    if (isValidationDetails(source)) {
+        return source;
+    }
+    const { kind: _ignored, ...rest } = source;
+    return { kind: "domain", ...rest };
+}
 export class PortableToolExecutionError extends Error {
     details;
     constructor(result) {
         super(result.text);
         this.name = "PortableToolExecutionError";
-        this.details = toPiDetails(result);
+        this.details = toPortableToolErrorDetails(result);
     }
 }
 export function isPortableToolExecutionError(error) {

package/dist/src/core/define-tool.d.ts

@@ -1,14 +1,41 @@
 import type { Static, TSchema } from "typebox";
-export interface PortableToolResult {
+export interface PortableToolResult<TStructured extends Record<string, unknown> = Record<string, unknown>> {
     /** Plain text sent back to the model in every host. */
     text: string;
     /** Structured data for hosts that support it. Preferred by both pi and MCP adapters. */
-    structuredContent?: Record<string, unknown>;
-    /** Legacy/adapter debug details used only when structuredContent is absent. */
+    structuredContent?: TStructured;
+    /**
+     * Legacy/adapter debug details used only when `structuredContent` is absent.
+     *
+     * @deprecated Slated for removal in 1.0. Prefer `structuredContent` for
+     * machine-readable data. Both adapters still fall back to this field, but
+     * new tool code should not set it.
+     */
     details?: Record<string, unknown>;
     /** Tool-level error flag. Throw for unexpected adapter/runtime failures. */
     isError?: boolean;
 }
+/**
+ * Discriminated union describing the shape `executePortableTool` puts into a
+ * failure result's `structuredContent`, and that the pi adapter exposes as
+ * `PortableToolExecutionError.details`.
+ *
+ * - `kind: "validation"` — TypeBox rejected the args. Always carries the
+ *   offending tool name and the validation errors.
+ * - `kind: "domain"` — the tool's own handler returned `isError: true`. The
+ *   shape of the rest of the object is whatever the handler chose to expose.
+ */
+export type PortableToolErrorDetails = {
+    kind: "validation";
+    tool: string;
+    validationErrors: PortableValidationError[];
+} | ({
+    kind: "domain";
+} & Record<string, unknown>);
+export interface PortableValidationError {
+    path: string;
+    message: string;
+}
 export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
 export type PortableToolHost<TExtension extends string = never> = PortableToolBuiltInHost | TExtension;
 export interface PortableToolContext<THost extends string = PortableToolBuiltInHost> {

package/dist/src/core/execute-tool.d.ts

@@ -1,15 +1,10 @@
 import type { TSchema } from "typebox";
-import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult } from "./define-tool.js";
-type NoInferPortable<T> = [T][T extends unknown ? 0 : never];
-export interface PortableValidationError {
-    path: string;
-    message: string;
-}
+import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult, PortableValidationError } from "./define-tool.js";
+export type { PortableValidationError };
 export declare function validatePortableToolArgs<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown): {
     ok: true;
 } | {
     ok: false;
     errors: PortableValidationError[];
 };
-export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInferPortable<THost>>): Promise<PortableToolResult>;
-export {};
+export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInfer<THost>>): Promise<PortableToolResult>;

package/dist/src/core/execute-tool.js

@@ -19,6 +19,7 @@ export async function executePortableTool(tool, args, ctx) {
                 .map((error) => `${error.path} ${error.message}`)
                 .join("; ")}`,
             structuredContent: {
+                kind: "validation",
                 tool: tool.name,
                 validationErrors: validation.errors,
             },

package/dist/src/index.d.ts

@@ -1,2 +1,2 @@
-export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolHost, type PortableToolResult, } from "./core/define-tool.js";
+export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolErrorDetails, type PortableToolHost, type PortableToolResult, } from "./core/define-tool.js";
 export { executePortableTool, type PortableValidationError, validatePortableToolArgs, } from "./core/execute-tool.js";

package/examples/README.md

@@ -20,6 +20,8 @@ Some packages have a host that intentionally loads TypeScript source directly, w
 ```text
 my-pi-extension-package/
   package.json
+  bin/
+    my-tools-mcp.js   # checked-in npm bin wrapper for local/workspace resilience
   extensions/
     tools.ts          # host-neutral portable tools
     index.ts          # source-loaded pi adapter wiring
@@ -177,7 +179,7 @@ In `package.json`:
 }
 ```
 
-For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoint and point only the npm `bin` at emitted JavaScript:
+For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoint and point npm `bin` at a checked-in wrapper rather than directly at generated `dist/` output:
 
 ```json
 {
@@ -186,11 +188,11 @@ For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoin
     "extensions": ["./extensions/index.ts"]
   },
   "bin": {
-    "my-tools-mcp": "./dist/extensions/mcp-server.js"
+    "my-tools-mcp": "./bin/my-tools-mcp.js"
   },
-  "files": ["extensions/", "dist/", "README.md", "LICENSE"],
+  "files": ["bin/", "extensions/", "dist/", "README.md", "LICENSE"],
   "scripts": {
-    "build:mcp": "tsc --project tsconfig.mcp.json && chmod +x dist/extensions/mcp-server.js",
+    "build:mcp": "tsc --project tsconfig.mcp.json",
     "prepack": "npm run build:mcp"
   },
   "engines": {
@@ -203,6 +205,38 @@ For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoin
 }
 ```
 
+The wrapper should resolve the generated MCP server relative to the installed package, build it when missing in local/workspace execution, and preserve build failures:
+
+```js
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const serverPath = join(packageRoot, "dist", "extensions", "mcp-server.js");
+
+if (!existsSync(serverPath)) {
+  const build = spawnSync("npm", ["run", "build:mcp", "--silent"], {
+    cwd: packageRoot,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+    timeout: 60_000,
+  });
+
+  if (build.status !== 0 || !existsSync(serverPath)) {
+    console.error("[my-tools] Failed to build the local MCP server. Run `npm run build:mcp` and try again.");
+    process.exit(build.status && build.status !== 0 ? build.status : 1);
+  }
+}
+
+const { runServer } = await import(pathToFileURL(serverPath).href);
+await runServer();
+```
+
+Commit the wrapper with executable mode (`chmod +x bin/my-tools-mcp.js`) and verify `npm pack --dry-run --json` includes it with executable mode.
+
 MCP behavior:
 
 - `tools/list` exposes TypeBox schemas directly as JSON Schema.
@@ -269,7 +303,8 @@ For publishable tool packages:
 - Declare Node `>=22.19.0` when publishing BridgeKit-powered MCP bins.
 - Avoid `workspace:` or `file:` ranges in publishable package dependencies.
 - Avoid dangling `sourceMappingURL` comments: either publish maps and useful sources, or disable source maps for package builds.
-- Ensure MCP bin output starts with a shebang, is executable (`chmod +x` or equivalent), and appears in `npm pack --dry-run --json` with executable mode.
+- Ensure the npm bin entrypoint starts with a shebang, is executable (`chmod +x` or equivalent), and appears in `npm pack --dry-run --json` with executable mode.
+- When a bin depends on generated output, prefer a checked-in wrapper under `bin/` over pointing directly at `dist/`; test existing output, missing output, failed builds, and successful builds that omit the expected file.
 - If only the MCP bin needs compiled output, narrow its tsconfig to the MCP entrypoint and shared host-neutral modules instead of compiling unrelated host adapters.
 - Add a packed-install smoke test that installs tarballs into a temporary project.
 - For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before release.

package/llms.txt

@@ -91,11 +91,13 @@ Use `PortableToolHost<"custom-host">` when a value may be either a built-in host
 Some hosts, such as pi in source-extension packages, may intentionally load TypeScript source while MCP clients launched from npm need compiled JavaScript. In that case:
 
 - Keep the host source entrypoint if that is the package convention, e.g. `pi.extensions: ["./extensions/index.ts"]`.
-- Add a package-local MCP build whose `bin` points at emitted JavaScript, e.g. `./dist/extensions/mcp-server.js`.
+- 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.
 - 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 built MCP bin is executable (`chmod +x` or equivalent) and verify the mode with `npm pack --dry-run --json`.
+- 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.
 
 ## Anti-patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",
@@ -48,10 +48,9 @@
     "build": "npm run clean && tsc -b tsconfig.json",
     "test": "npm run build && node scripts/run-built-tests.mjs",
     "test:coverage": "npm run build && node scripts/run-built-tests-coverage.mjs",
-    "verify:dist": "node scripts/verify-bridgekit-dist.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "package-smoke": "node scripts/smoke-package.mjs",
-    "prepack": "npm run build && npm run verify:dist"
+    "prepack": "npm run build"
   },
   "files": [
     "dist/**/*.js",