@qping/plugin-bus 0.1.0 → 0.2.0

package/dist/node.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Node-side plugin SDK: fluent `createPlugin()` over the v3 named-pipe message bus.
+ *
+ * Method names map to v3 routes:
+ *   initialize -> plugin.call.initialize
+ *   search     -> plugin.call.search
+ *   action     -> plugin.call.invokeAction
+ *   handle(name) -> plugin.call.<name>
+ *   publish    -> plugin.event.<subjectId>
+ *   hostCall   -> host.call.<method>
+ */
+export type PluginTheme = "light" | "dark";
+export type PluginHostEnv = {
+    locale: string;
+    fallbackLocale: string;
+    theme: PluginTheme;
+};
+export type PluginContext = PluginHostEnv & {
+    action: string;
+    itemId: string;
+    query: string;
+};
+/** Payload of plugin.call.initialize. Host sends locale, theme, and the resolved message bag. */
+export type PluginInitializeParams = PluginHostEnv & {
+    messages: Record<string, string>;
+};
+/** Payload of plugin.call.search. */
+export type PluginSearchParams = PluginHostEnv & {
+    query: string;
+    mode: "global" | "plugin";
+};
+/** Payload of plugin.call.invokeAction. */
+export type PluginActionParams = PluginHostEnv & {
+    itemId: string;
+    actionId: string;
+    query: string;
+};
+type PluginInitializeHandler = (params: PluginInitializeParams) => unknown | Promise<unknown>;
+type PluginSearchHandler = (params: PluginSearchParams) => unknown | Promise<unknown>;
+type PluginActionHandler = (params: PluginActionParams) => unknown | Promise<unknown>;
+type PluginHandler = (payload: any, context: PluginContext) => unknown | Promise<unknown>;
+export declare class Plugin {
+    #private;
+    initialize(handler: PluginInitializeHandler): this;
+    search(handler: PluginSearchHandler): this;
+    action(handler: PluginActionHandler): this;
+    handle(action: string, handler: PluginHandler): this;
+    /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
+    publish(subjectId: string, payload?: unknown): void;
+    /** Calls a host.call.<method> capability and awaits the response.
+     *  `timeoutMs` defaults to the remaining timeout of the inbound plugin.call
+     *  (from a page `bus.call`) when inside a handler; otherwise 30s.
+     */
+    hostCall(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    /** Connects to the host pipe and begins dispatching. Must be called last. */
+    start(): Promise<void>;
+    /**
+     * Builds the v3 route map from the fluent registrations. Exposed for unit testing the mapping
+     * without connecting a pipe.
+     */
+    buildRoutes(): Record<string, (payload: any) => unknown | Promise<unknown>>;
+    stop(): Promise<void>;
+}
+export declare function createPlugin(): Plugin;
+export {};

package/dist/{server.mjs → node.mjs}

@@ -110,12 +110,77 @@ var init_framing = __esm({
 
 // src/bootstrap.ts
 import readline from "node:readline/promises";
+import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/transport.ts
 init_framing();
 import { connect as netConnect } from "node:net";
 
 // src/protocol.ts
+var MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event"
+};
+var ErrorCode = {
+  ProtocolMismatch: "ProtocolMismatch",
+  HandshakeFailed: "HandshakeFailed",
+  CapabilityNotDeclared: "CapabilityNotDeclared",
+  CapabilityDenied: "CapabilityDenied",
+  InvalidPayload: "InvalidPayload",
+  MessageTooLarge: "MessageTooLarge",
+  RouteNotFound: "RouteNotFound",
+  RequestTimeout: "RequestTimeout",
+  TooManyRequests: "TooManyRequests",
+  TransportDisconnected: "TransportDisconnected",
+  PluginUnavailable: "PluginUnavailable",
+  InternalError: "InternalError",
+  Cancelled: "Cancelled",
+  RateLimited: "RateLimited"
+};
+var ProtocolVersion = "3.0";
+var EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host"
+};
+var Routes = {
+  Bus: {
+    Handshake: "bus.handshake",
+    Ping: "bus.ping",
+    Cancel: "bus.cancel",
+    Subscribe: "bus.subscribe",
+    Unsubscribe: "bus.unsubscribe"
+  },
+  Prefix: {
+    PluginCall: "plugin.call.",
+    HostCall: "host.call.",
+    PluginEvent: "plugin.event.",
+    HostEvent: "host.event.",
+    Diagnostics: "diagnostics."
+  },
+  PluginCall: {
+    Initialize: "plugin.call.initialize",
+    Search: "plugin.call.search",
+    InvokeAction: "plugin.call.invokeAction"
+  },
+  HostEvent: {
+    Initialize: "host.event.initialize",
+    Search: "host.event.search",
+    Key: "host.event.key",
+    LanguageChanged: "host.event.languageChanged",
+    ThemeChanged: "host.event.themeChanged",
+    InputActionCaptured: "host.event.inputActionCaptured"
+  }
+};
+function pluginCallRoute(method) {
+  return method.startsWith(Routes.Prefix.PluginCall) ? method : `${Routes.Prefix.PluginCall}${method}`;
+}
+function hostCallRoute(method) {
+  return method.startsWith(Routes.Prefix.HostCall) ? method : `${Routes.Prefix.HostCall}${method}`;
+}
+function pluginEventRoute(subjectId) {
+  return subjectId.startsWith(Routes.Prefix.PluginEvent) ? subjectId : `${Routes.Prefix.PluginEvent}${subjectId}`;
+}
 function canonicalStringify(value) {
   return JSON.stringify(stripNulls(value));
 }
@@ -141,6 +206,9 @@ var NodeTransport = class {
   closed = false;
   onMessage(handler) {
     this.messageHandlers.add(handler);
+    return () => {
+      this.messageHandlers.delete(handler);
+    };
   }
   onDisconnect(handler) {
     this.disconnectHandlers.add(handler);
@@ -207,14 +275,37 @@ var NodeTransport = class {
 };
 
 // src/router.ts
+import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
+var requestScope = new AsyncLocalStorage();
+var DefaultHostCallTimeoutMs = 3e4;
+function remainingTimeoutMs() {
+  const scope = requestScope.getStore();
+  if (!scope || scope.deadlineMs == null) {
+    return void 0;
+  }
+  return scope.deadlineMs - Date.now();
+}
+function resolveHostCallTimeoutMs(explicit) {
+  const remaining = remainingTimeoutMs();
+  if (explicit != null) {
+    return remaining == null ? explicit : Math.min(explicit, remaining);
+  }
+  return remaining ?? DefaultHostCallTimeoutMs;
+}
+function deadlineFromTimeoutMs(timeoutMs) {
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    return null;
+  }
+  return Date.now() + timeoutMs;
+}
 var HandlerRouter = class {
   handlers = /* @__PURE__ */ new Map();
   pendingHostCalls = /* @__PURE__ */ new Map();
   pluginId = "p";
   entryId = "e";
   sessionId = "s";
-  endpointId = "node-main";
+  endpointId = EndpointIds.NodeMain;
   /** Injected transport send fn; tests can override `router.send` directly. */
   send;
   constructor(deps) {
@@ -232,43 +323,48 @@ var HandlerRouter = class {
   }
   /** Dispatches an inbound request/response. Returns once handled. */
   async dispatch(env) {
-    if (env.kind === "response") {
+    if (env.kind === MessageKind.Response) {
       this.handleHostResponse(env);
       return;
     }
-    if (env.kind !== "request") return;
-    if (env.route === "bus.ping") {
+    if (env.kind !== MessageKind.Request) return;
+    if (env.route === Routes.Bus.Ping) {
       this.send(this.responseFor(env, { ok: true }));
       return;
     }
     const handler = this.handlers.get(env.route);
     if (!handler) {
-      this.send(this.errorResponseFor(env, "RouteNotFound", `route '${env.route}' has no handler`));
+      this.send(this.errorResponseFor(env, ErrorCode.RouteNotFound, `route '${env.route}' has no handler`));
       return;
     }
+    const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
     try {
-      const result = await handler(env.payload);
+      const result = await requestScope.run({ deadlineMs }, () => handler(env.payload));
       this.send(this.responseFor(env, result ?? {}));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      this.send(this.errorResponseFor(env, "InternalError", message));
+      this.send(this.errorResponseFor(env, ErrorCode.InternalError, message));
     }
   }
   /** Calls a host.call.* capability and resolves with the response payload. */
-  callHost(route, payload, timeoutMs = 3e4) {
+  callHost(route, payload, timeoutMs) {
+    const effectiveTimeoutMs = resolveHostCallTimeoutMs(timeoutMs);
+    if (effectiveTimeoutMs <= 0) {
+      return Promise.reject(new Error(`host call ${route} timed out (no time remaining)`));
+    }
     return new Promise((resolve, reject) => {
       const id = randomBytesHex();
       const req = {
-        version: "3.0",
+        version: ProtocolVersion,
         id,
         traceId: id,
         sessionId: this.sessionId,
         pluginId: this.pluginId,
         entryId: this.entryId,
         endpointId: this.endpointId,
-        kind: "request",
+        kind: MessageKind.Request,
         route,
-        timeoutMs,
+        timeoutMs: effectiveTimeoutMs,
         payload
       };
       const pending = { resolve, reject, route };
@@ -276,9 +372,9 @@ var HandlerRouter = class {
       const timer = setTimeout(() => {
         if (this.pendingHostCalls.has(id)) {
           this.pendingHostCalls.delete(id);
-          reject(new Error(`host call ${route} timed out after ${timeoutMs}ms`));
+          reject(new Error(`host call ${route} timed out after ${effectiveTimeoutMs}ms`));
         }
-      }, timeoutMs);
+      }, effectiveTimeoutMs);
       const origResolve = pending.resolve;
       const origReject = pending.reject;
       pending.resolve = (v) => {
@@ -305,7 +401,7 @@ var HandlerRouter = class {
   }
   responseFor(req, payload) {
     return {
-      version: "3.0",
+      version: ProtocolVersion,
       id: randomBytesHex(),
       correlationId: req.id,
       traceId: req.traceId,
@@ -313,7 +409,7 @@ var HandlerRouter = class {
       pluginId: req.pluginId,
       entryId: req.entryId,
       endpointId: this.endpointId,
-      kind: "response",
+      kind: MessageKind.Response,
       route: req.route,
       payload
     };
@@ -331,12 +427,29 @@ function randomBytesHex() {
 }
 
 // src/bootstrap.ts
+var SUPPORTED_VERSIONS = [ProtocolVersion];
 async function runPlugin(handlers) {
   const { pipePath, token } = await readBootstrapLine();
   const transport = new NodeTransport();
   await transport.connect(pipePath);
+  const identity = await completeHandshake(transport, token);
   const router = new HandlerRouter({ send: (env) => transport.send(env) });
+  router.setIdentity(identity);
+  const HOST_LOST_MS = 15e3;
+  let lastPingAt = Date.now();
+  const watchdog = setInterval(() => {
+    if (Date.now() - lastPingAt > HOST_LOST_MS) {
+      clearInterval(watchdog);
+      process.exit(1);
+    }
+  }, 1e3);
+  watchdog.unref?.();
+  transport.onDisconnect(() => {
+    clearInterval(watchdog);
+    process.exit(1);
+  });
   transport.onMessage((env) => {
+    if (env.route === Routes.Bus.Ping) lastPingAt = Date.now();
     router.dispatch(env);
   });
   for (const [route, handler] of Object.entries(handlers)) {
@@ -345,7 +458,10 @@ async function runPlugin(handlers) {
   return {
     transport,
     router,
-    close: () => transport.close()
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    }
   };
 }
 async function readBootstrapLine() {
@@ -364,9 +480,55 @@ async function readBootstrapLine() {
     rl.close();
   }
 }
+async function completeHandshake(transport, token, timeoutMs = 1e4) {
+  const id = randomBytes2(16).toString("hex");
+  const req = {
+    version: ProtocolVersion,
+    id,
+    traceId: id,
+    sessionId: "",
+    pluginId: "",
+    entryId: "",
+    endpointId: EndpointIds.NodeMain,
+    kind: MessageKind.Request,
+    route: Routes.Bus.Handshake,
+    timeoutMs,
+    payload: {
+      version: ProtocolVersion,
+      supportedVersions: SUPPORTED_VERSIONS,
+      token
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`bus.handshake timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    const unsubscribe = transport.onMessage((env) => {
+      if (env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      clearTimeout(timer);
+      unsubscribe();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+        return;
+      }
+      const p = env.payload ?? {};
+      const pluginId = String(p.pluginId ?? "");
+      const entryId = String(p.entryId ?? "");
+      const sessionId = String(p.sessionId ?? "");
+      const endpointId = String(p.endpointId ?? EndpointIds.NodeMain);
+      if (!pluginId || !entryId || !sessionId) {
+        reject(new Error("bus.handshake success response missing bound identity"));
+        return;
+      }
+      resolve({ pluginId, entryId, sessionId, endpointId });
+    });
+    transport.send(req);
+  });
+}
 
-// src/server.ts
-var NodeTool = class {
+// src/node.ts
+var Plugin = class {
   #handlers = /* @__PURE__ */ new Map();
   #searchHandler = null;
   #actionHandler = null;
@@ -386,35 +548,38 @@ var NodeTool = class {
   }
   handle(action, handler) {
     if (!action || typeof action !== "string") {
-      throw new Error("tool.handle requires an action name.");
+      throw new Error("plugin.handle requires an action name.");
     }
     if (typeof handler !== "function") {
-      throw new Error("tool.handle requires a handler.");
+      throw new Error("plugin.handle requires a handler.");
     }
     this.#handlers.set(action, handler);
     return this;
   }
   /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
   publish(subjectId, payload = {}) {
-    if (!this.#runtime) throw new Error("tool not started");
-    const route = subjectId.startsWith("plugin.event.") ? subjectId : `plugin.event.${subjectId}`;
+    if (!this.#runtime) throw new Error("plugin not started");
+    const route = pluginEventRoute(subjectId);
     this.#runtime.transport.send({
-      version: "3.0",
+      version: ProtocolVersion,
       id: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
       traceId: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
       sessionId: "",
       pluginId: "",
       entryId: "",
-      endpointId: "node-main",
-      kind: "event",
+      endpointId: EndpointIds.NodeMain,
+      kind: MessageKind.Event,
       route,
       payload
     });
   }
-  /** Calls a host.call.<method> capability and awaits the response. */
-  hostCall(method, params = {}) {
-    if (!this.#runtime) return Promise.reject(new Error("tool not started"));
-    return this.#runtime.router.callHost(`host.call.${method}`, params);
+  /** Calls a host.call.<method> capability and awaits the response.
+   *  `timeoutMs` defaults to the remaining timeout of the inbound plugin.call
+   *  (from a page `bus.call`) when inside a handler; otherwise 30s.
+   */
+  hostCall(method, params = {}, timeoutMs) {
+    if (!this.#runtime) return Promise.reject(new Error("plugin not started"));
+    return this.#runtime.router.callHost(hostCallRoute(method), params, timeoutMs);
   }
   /** Connects to the host pipe and begins dispatching. Must be called last. */
   async start() {
@@ -428,35 +593,20 @@ var NodeTool = class {
   buildRoutes() {
     const routes = {};
     if (this.#initializeHandler) {
-      routes["plugin.call.initialize"] = (p) => this.#initializeHandler(p);
+      routes[Routes.PluginCall.Initialize] = (p) => this.#initializeHandler(asInitializeParams(p));
     }
     if (this.#searchHandler) {
-      routes["plugin.call.search"] = (p) => this.#searchHandler(p);
+      routes[Routes.PluginCall.Search] = (p) => this.#searchHandler(asSearchParams(p));
     }
     if (this.#actionHandler) {
-      routes["plugin.call.invokeAction"] = (p) => {
-        return this.#actionHandler({ ...p, itemId: p.itemId, query: p.query });
-      };
+      routes[Routes.PluginCall.InvokeAction] = (p) => this.#actionHandler(asActionParams(p));
     }
-    routes["plugin.call.detailCall"] = async (p) => {
-      const action = p?.action ?? "";
-      const handler = this.#handlers.get(action);
-      if (!handler) {
-        throw new Error(`no handler registered for action '${action}'`);
-      }
-      const ctx = extractContext(p);
-      const result = await handler(p?.payload ?? {}, ctx);
-      return { result: result ?? {} };
-    };
-    routes["plugin.call.detailEvent"] = async (p) => {
-      return { state: p?.payload ?? {} };
-    };
     for (const [action, handler] of this.#handlers) {
-      const route = `plugin.call.${action}`;
+      const route = pluginCallRoute(action);
       if (!routes[route]) {
         routes[route] = async (p) => {
-          const ctx = extractContext(p);
-          return handler(p, ctx);
+          const ctx = extractContext(p, action);
+          return handler(p ?? {}, ctx);
         };
       }
     }
@@ -466,19 +616,53 @@ var NodeTool = class {
     if (this.#runtime) await this.#runtime.close();
   }
 };
-function extractContext(p) {
+function asHostEnv(p) {
+  return {
+    locale: typeof p?.locale === "string" ? p.locale : "en-US",
+    fallbackLocale: typeof p?.fallbackLocale === "string" ? p.fallbackLocale : "en-US",
+    theme: asTheme(p?.theme)
+  };
+}
+function asInitializeParams(p) {
+  const messages = p?.messages;
+  return {
+    ...asHostEnv(p),
+    messages: isStringRecord(messages) ? messages : {}
+  };
+}
+function asSearchParams(p) {
+  return {
+    ...asHostEnv(p),
+    query: typeof p?.query === "string" ? p.query : "",
+    mode: p?.mode === "plugin" ? "plugin" : "global"
+  };
+}
+function asActionParams(p) {
+  return {
+    ...asHostEnv(p),
+    itemId: typeof p?.itemId === "string" ? p.itemId : "",
+    actionId: typeof p?.actionId === "string" ? p.actionId : "",
+    query: typeof p?.query === "string" ? p.query : ""
+  };
+}
+function asTheme(value) {
+  return value === "light" ? "light" : "dark";
+}
+function isStringRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((v) => typeof v === "string");
+}
+function extractContext(p, action) {
   return {
-    action: p?.action ?? "",
-    itemId: p?.itemId ?? "",
-    query: p?.query ?? "",
-    locale: p?.locale ?? "en-US",
-    fallbackLocale: p?.fallbackLocale ?? "en-US"
+    ...asHostEnv(p),
+    action,
+    itemId: typeof p?.itemId === "string" ? p.itemId : "",
+    query: typeof p?.query === "string" ? p.query : ""
   };
 }
-function createTool() {
-  return new NodeTool();
+function createPlugin() {
+  return new Plugin();
 }
 export {
-  NodeTool,
-  createTool
+  Plugin,
+  createPlugin
 };

package/dist/protocol.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Hand-written TypeScript protocol types for the plugin message bus v3. These MUST stay
+ * byte-for-byte aligned with the C# types in MyTools.Protocol (see the canonical fixtures in
+ * MyTools.Protocol.Test/Fixtures/*.json). The drift-prevention self-check
+ * (fixtures-selfcheck.mjs) encodes/decodes those fixtures through these types.
+ *
+ * Field names are camelCase on the wire (System.Text.Json camelCase policy on the C# side).
+ * Null fields are omitted on the wire (WhenWritingNull).
+ *
+ * Runtime constants mirror MyTools.Protocol (MessageKindWire, Routes, EndpointIds,
+ * ProtocolVersion.CurrentWire). Do not re-hardcode those strings in SDK source.
+ */
+export declare const MessageKind: {
+    readonly Request: "request";
+    readonly Response: "response";
+    readonly Event: "event";
+};
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+export declare const ErrorCode: {
+    readonly ProtocolMismatch: "ProtocolMismatch";
+    readonly HandshakeFailed: "HandshakeFailed";
+    readonly CapabilityNotDeclared: "CapabilityNotDeclared";
+    readonly CapabilityDenied: "CapabilityDenied";
+    readonly InvalidPayload: "InvalidPayload";
+    readonly MessageTooLarge: "MessageTooLarge";
+    readonly RouteNotFound: "RouteNotFound";
+    readonly RequestTimeout: "RequestTimeout";
+    readonly TooManyRequests: "TooManyRequests";
+    readonly TransportDisconnected: "TransportDisconnected";
+    readonly PluginUnavailable: "PluginUnavailable";
+    readonly InternalError: "InternalError";
+    readonly Cancelled: "Cancelled";
+    readonly RateLimited: "RateLimited";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export declare const ProtocolVersion = "3.0";
+export declare const EndpointIds: {
+    readonly NodeMain: "node-main";
+    readonly Host: "host";
+};
+export declare const Routes: {
+    readonly Bus: {
+        readonly Handshake: "bus.handshake";
+        readonly Ping: "bus.ping";
+        readonly Cancel: "bus.cancel";
+        readonly Subscribe: "bus.subscribe";
+        readonly Unsubscribe: "bus.unsubscribe";
+    };
+    readonly Prefix: {
+        readonly PluginCall: "plugin.call.";
+        readonly HostCall: "host.call.";
+        readonly PluginEvent: "plugin.event.";
+        readonly HostEvent: "host.event.";
+        readonly Diagnostics: "diagnostics.";
+    };
+    readonly PluginCall: {
+        readonly Initialize: "plugin.call.initialize";
+        readonly Search: "plugin.call.search";
+        readonly InvokeAction: "plugin.call.invokeAction";
+    };
+    readonly HostEvent: {
+        readonly Initialize: "host.event.initialize";
+        readonly Search: "host.event.search";
+        readonly Key: "host.event.key";
+        readonly LanguageChanged: "host.event.languageChanged";
+        readonly ThemeChanged: "host.event.themeChanged";
+        readonly InputActionCaptured: "host.event.inputActionCaptured";
+    };
+};
+export declare function pluginCallRoute(method: string): string;
+export declare function hostCallRoute(method: string): string;
+export declare function pluginEventRoute(subjectId: string): string;
+export interface BusError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    details?: unknown;
+}
+/**
+ * The frozen Phase-1 envelope. All fields except correlationId/timeoutMs/error/payload are
+ * required; the optional ones are omitted on the wire when null.
+ */
+export interface Envelope {
+    version: string;
+    id: string;
+    correlationId?: string | null;
+    traceId: string;
+    sessionId: string;
+    pluginId: string;
+    entryId: string;
+    endpointId: string;
+    kind: MessageKind;
+    route: string;
+    timeoutMs?: number | null;
+    payload?: unknown;
+    error?: BusError | null;
+}
+/** Omit null/undefined-valued keys to match the C# WhenWritingNull behavior. */
+export declare function canonicalStringify(value: unknown): string;
+/** Parse + re-canonicalize, returning the canonical JSON string (stable key order via JSON.stringify). */
+export declare function canonicalize(json: string): string;