@qping/plugin-bus 0.1.0 → 0.2.0

package/dist/bootstrap.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v3 Node SDK bootstrap entry. Reads the bootstrap line from stdin (pipePath\ttoken), connects to
+ * the named pipe, completes bus.handshake (presenting the token and receiving bound identity),
+ * and starts a HandlerRouter stamped with that identity.
+ *
+ * This mirrors the C# NodeProcessController's spawn contract: the host writes one line to the
+ * Node process's stdin — "<pipePath>\t<token>" — then waits for the Node side to connect the pipe
+ * and complete handshake before promoting the session to Ready.
+ */
+import { NodeTransport } from "./transport.ts";
+import { HandlerRouter } from "./router.ts";
+export interface PluginHandlers {
+    [route: string]: (payload: any) => Promise<any> | any;
+}
+export interface PluginRuntime {
+    transport: NodeTransport;
+    router: HandlerRouter;
+    close(): Promise<void>;
+}
+/**
+ * Connects to the host pipe (reading the bootstrap line from stdin), completes handshake, and
+ * returns a runtime whose router dispatches inbound plugin.call.* requests to the given handlers.
+ */
+export declare function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime>;
+/**
+ * Sends bus.handshake with the bootstrap token and waits for the host response that binds
+ * plugin/entry/session/endpoint identity. Rejects on HandshakeFailed / ProtocolMismatch / timeout.
+ */
+export declare function completeHandshake(transport: NodeTransport, token: string, timeoutMs?: number): Promise<{
+    pluginId: string;
+    entryId: string;
+    sessionId: string;
+    endpointId: string;
+}>;

package/dist/bootstrap.mjs

@@ -110,12 +110,68 @@ 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 canonicalStringify(value) {
   return JSON.stringify(stripNulls(value));
 }
@@ -141,6 +197,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 +266,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 +314,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 +363,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 +392,7 @@ var HandlerRouter = class {
   }
   responseFor(req, payload) {
     return {
-      version: "3.0",
+      version: ProtocolVersion,
       id: randomBytesHex(),
       correlationId: req.id,
       traceId: req.traceId,
@@ -313,7 +400,7 @@ var HandlerRouter = class {
       pluginId: req.pluginId,
       entryId: req.entryId,
       endpointId: this.endpointId,
-      kind: "response",
+      kind: MessageKind.Response,
       route: req.route,
       payload
     };
@@ -331,12 +418,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 +449,10 @@ async function runPlugin(handlers) {
   return {
     transport,
     router,
-    close: () => transport.close()
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    }
   };
 }
 async function readBootstrapLine() {
@@ -364,6 +471,53 @@ 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);
+  });
+}
 export {
+  completeHandshake,
   runPlugin
 };

package/dist/framing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Length-prefixed framing for the v3 named-pipe transport, mirroring the C# FrameCodec/FrameDecoder.
+ * Wire format: [4-byte little-endian unsigned length][UTF-8 JSON payload].
+ *
+ * The incremental decoder handles fragmented, sticky and truncated streams, and rejects an oversize
+ * length prefix as fatal *before* allocating the payload buffer (so a malicious/buggy peer cannot
+ * force a huge allocation). After a fatal error the decoder stays dead.
+ */
+export declare const MAX_FRAME_BYTES: number;
+export declare const PREFIX_BYTES = 4;
+/** Encodes a raw payload buffer into a length-prefixed frame. */
+export declare function encodeFrame(payload: Buffer): Buffer;
+/** Encodes a UTF-8 JSON string into a length-prefixed frame. */
+export declare function encodeFrameString(json: string): Buffer;
+export interface FrameFeedResult {
+    hasFrame: boolean;
+    payload: Buffer;
+    isFatal: boolean;
+}
+/**
+ * Incremental length-prefixed frame decoder. Feed byte chunks (fragmented/sticky/partial) and get
+ * back one complete payload at a time. Leftover bytes from a chunk that contained more than one
+ * frame are buffered internally and surfaced by subsequent feeds (including an empty buffer).
+ */
+export declare class FrameDecoder {
+    private prefixBuf;
+    private prefixFilled;
+    private payload;
+    private payloadFilled;
+    private payloadLength;
+    private fatal;
+    private pending;
+    feed(chunk: Buffer): FrameFeedResult;
+    private bufferLeftover;
+    private reset;
+}

package/dist/i18n.d.ts

@@ -0,0 +1,19 @@
+export type TranslationValues = Record<string, unknown>;
+export type TranslationOptions = TranslationValues & {
+    defaultValue: string;
+    translatorComment?: string;
+};
+type LocalizationPayload = {
+    locale?: string;
+    fallbackLocale?: string;
+    messages?: Record<string, string>;
+};
+declare class MyToolsI18n {
+    #private;
+    get language(): string;
+    configure(payload: LocalizationPayload | Record<string, unknown> | null | undefined): void;
+    t(key: string, options: TranslationOptions): string;
+    apply(root?: ParentNode): void;
+}
+export declare const mytoolsI18n: MyToolsI18n;
+export {};