@qping/plugin-bus 0.1.0

package/dist/server.mjs

@@ -0,0 +1,484 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/framing.ts
+var framing_exports = {};
+__export(framing_exports, {
+  FrameDecoder: () => FrameDecoder,
+  MAX_FRAME_BYTES: () => MAX_FRAME_BYTES,
+  PREFIX_BYTES: () => PREFIX_BYTES,
+  encodeFrame: () => encodeFrame,
+  encodeFrameString: () => encodeFrameString
+});
+function encodeFrame(payload) {
+  const length = payload.length;
+  const frame = Buffer.alloc(PREFIX_BYTES + length);
+  frame[0] = length & 255;
+  frame[1] = length >> 8 & 255;
+  frame[2] = length >> 16 & 255;
+  frame[3] = length >> 24 & 255;
+  payload.copy(frame, PREFIX_BYTES);
+  return frame;
+}
+function encodeFrameString(json) {
+  return encodeFrame(Buffer.from(json, "utf8"));
+}
+var MAX_FRAME_BYTES, PREFIX_BYTES, FrameDecoder;
+var init_framing = __esm({
+  "src/framing.ts"() {
+    MAX_FRAME_BYTES = 4 * 1024 * 1024;
+    PREFIX_BYTES = 4;
+    FrameDecoder = class {
+      prefixBuf = Buffer.alloc(PREFIX_BYTES);
+      prefixFilled = 0;
+      payload = null;
+      payloadFilled = 0;
+      payloadLength = 0;
+      fatal = false;
+      pending = Buffer.alloc(0);
+      feed(chunk) {
+        const empty = { hasFrame: false, payload: Buffer.alloc(0), isFatal: false };
+        if (this.fatal) {
+          return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+        }
+        let current;
+        if (this.pending.length > 0) {
+          current = Buffer.concat([this.pending, chunk]);
+          this.pending = Buffer.alloc(0);
+        } else {
+          current = chunk;
+        }
+        let offset = 0;
+        while (offset < current.length) {
+          if (this.payload === null) {
+            const need = PREFIX_BYTES - this.prefixFilled;
+            const take = Math.min(need, current.length - offset);
+            current.copy(this.prefixBuf, this.prefixFilled, offset, offset + take);
+            this.prefixFilled += take;
+            offset += take;
+            if (this.prefixFilled < PREFIX_BYTES) {
+              return empty;
+            }
+            this.payloadLength = this.prefixBuf[0] | this.prefixBuf[1] << 8 | this.prefixBuf[2] << 16 | this.prefixBuf[3] << 24;
+            if (this.payloadLength < 0 || this.payloadLength > MAX_FRAME_BYTES) {
+              this.fatal = true;
+              return { hasFrame: false, payload: Buffer.alloc(0), isFatal: true };
+            }
+            if (this.payloadLength === 0) {
+              this.reset();
+              this.bufferLeftover(current, offset);
+              return { hasFrame: true, payload: Buffer.alloc(0), isFatal: false };
+            }
+            this.payload = Buffer.alloc(this.payloadLength);
+            this.payloadFilled = 0;
+          }
+          const payloadNeed = this.payloadLength - this.payloadFilled;
+          const payloadTake = Math.min(payloadNeed, current.length - offset);
+          current.copy(this.payload, this.payloadFilled, offset, offset + payloadTake);
+          this.payloadFilled += payloadTake;
+          offset += payloadTake;
+          if (this.payloadFilled >= this.payloadLength) {
+            const out = this.payload;
+            this.reset();
+            this.bufferLeftover(current, offset);
+            return { hasFrame: true, payload: out, isFatal: false };
+          }
+        }
+        return empty;
+      }
+      bufferLeftover(src, offset) {
+        if (offset < src.length) {
+          this.pending = src.subarray(offset);
+        }
+      }
+      reset() {
+        this.prefixFilled = 0;
+        this.payload = null;
+        this.payloadFilled = 0;
+        this.payloadLength = 0;
+      }
+    };
+  }
+});
+
+// src/bootstrap.ts
+import readline from "node:readline/promises";
+
+// src/transport.ts
+init_framing();
+import { connect as netConnect } from "node:net";
+
+// src/protocol.ts
+function canonicalStringify(value) {
+  return JSON.stringify(stripNulls(value));
+}
+function stripNulls(value) {
+  if (value === null || value === void 0) return void 0;
+  if (Array.isArray(value)) return value.map(stripNulls);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      const stripped = stripNulls(v);
+      if (stripped !== void 0) out[k] = stripped;
+    }
+    return out;
+  }
+  return value;
+}
+
+// src/transport.ts
+var NodeTransport = class {
+  socket = null;
+  messageHandlers = /* @__PURE__ */ new Set();
+  disconnectHandlers = /* @__PURE__ */ new Set();
+  closed = false;
+  onMessage(handler) {
+    this.messageHandlers.add(handler);
+  }
+  onDisconnect(handler) {
+    this.disconnectHandlers.add(handler);
+  }
+  get isConnected() {
+    return this.socket !== null && !this.closed;
+  }
+  /** Connects to a Windows named pipe (\\.\pipe\<name>). */
+  async connect(pipePath) {
+    this.socket = netConnect(pipePath);
+    await new Promise((resolve, reject) => {
+      this.socket.once("connect", () => resolve());
+      this.socket.once("error", (err) => reject(err));
+    });
+    const { FrameDecoder: FrameDecoder2 } = await Promise.resolve().then(() => (init_framing(), framing_exports));
+    const decoder = new FrameDecoder2();
+    this.socket.on("data", (chunk) => {
+      let result = decoder.feed(chunk);
+      if (result.isFatal) {
+        this.handleDisconnect();
+        return;
+      }
+      while (result.hasFrame) {
+        try {
+          const env = JSON.parse(result.payload.toString("utf8"));
+          for (const h of this.messageHandlers) h(env);
+        } catch {
+          this.handleDisconnect();
+          return;
+        }
+        result = decoder.feed(Buffer.alloc(0));
+        if (result.isFatal) {
+          this.handleDisconnect();
+          return;
+        }
+      }
+    });
+    this.socket.on("close", () => this.handleDisconnect());
+    this.socket.on("error", () => this.handleDisconnect());
+  }
+  /** Serializes an envelope to a length-prefixed frame and writes it. */
+  send(env) {
+    if (!this.socket || this.closed) {
+      throw new Error("transport is not connected");
+    }
+    this.socket.write(encodeFrameString(canonicalStringify(env)));
+  }
+  async close() {
+    this.closed = true;
+    if (this.socket) {
+      this.socket.end();
+      await new Promise((resolve) => {
+        if (this.socket.destroyed) return resolve();
+        this.socket.once("close", () => resolve());
+      });
+      this.socket = null;
+    }
+  }
+  handleDisconnect() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const h of this.disconnectHandlers) h();
+  }
+};
+
+// src/router.ts
+import { randomBytes } from "node:crypto";
+var HandlerRouter = class {
+  handlers = /* @__PURE__ */ new Map();
+  pendingHostCalls = /* @__PURE__ */ new Map();
+  pluginId = "p";
+  entryId = "e";
+  sessionId = "s";
+  endpointId = "node-main";
+  /** Injected transport send fn; tests can override `router.send` directly. */
+  send;
+  constructor(deps) {
+    this.send = deps.send;
+  }
+  /** Sets the bound identity stamped on outbound messages (after handshake). */
+  setIdentity(ids) {
+    this.pluginId = ids.pluginId;
+    this.entryId = ids.entryId;
+    this.sessionId = ids.sessionId;
+    this.endpointId = ids.endpointId;
+  }
+  handle(route, handler) {
+    this.handlers.set(route, handler);
+  }
+  /** Dispatches an inbound request/response. Returns once handled. */
+  async dispatch(env) {
+    if (env.kind === "response") {
+      this.handleHostResponse(env);
+      return;
+    }
+    if (env.kind !== "request") return;
+    if (env.route === "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`));
+      return;
+    }
+    try {
+      const result = await 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));
+    }
+  }
+  /** Calls a host.call.* capability and resolves with the response payload. */
+  callHost(route, payload, timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      const id = randomBytesHex();
+      const req = {
+        version: "3.0",
+        id,
+        traceId: id,
+        sessionId: this.sessionId,
+        pluginId: this.pluginId,
+        entryId: this.entryId,
+        endpointId: this.endpointId,
+        kind: "request",
+        route,
+        timeoutMs,
+        payload
+      };
+      const pending = { resolve, reject, route };
+      this.pendingHostCalls.set(id, pending);
+      const timer = setTimeout(() => {
+        if (this.pendingHostCalls.has(id)) {
+          this.pendingHostCalls.delete(id);
+          reject(new Error(`host call ${route} timed out after ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+      const origResolve = pending.resolve;
+      const origReject = pending.reject;
+      pending.resolve = (v) => {
+        clearTimeout(timer);
+        origResolve(v);
+      };
+      pending.reject = (e) => {
+        clearTimeout(timer);
+        origReject(e);
+      };
+      this.send(req);
+    });
+  }
+  handleHostResponse(env) {
+    if (!env.correlationId) return;
+    const pending = this.pendingHostCalls.get(env.correlationId);
+    if (!pending) return;
+    this.pendingHostCalls.delete(env.correlationId);
+    if (env.error) {
+      pending.reject(new Error(`${env.error.code}: ${env.error.message}`));
+    } else {
+      pending.resolve(env.payload);
+    }
+  }
+  responseFor(req, payload) {
+    return {
+      version: "3.0",
+      id: randomBytesHex(),
+      correlationId: req.id,
+      traceId: req.traceId,
+      sessionId: req.sessionId,
+      pluginId: req.pluginId,
+      entryId: req.entryId,
+      endpointId: this.endpointId,
+      kind: "response",
+      route: req.route,
+      payload
+    };
+  }
+  errorResponseFor(req, code, message) {
+    return {
+      ...this.responseFor(req, null),
+      payload: void 0,
+      error: { code, message, retryable: false }
+    };
+  }
+};
+function randomBytesHex() {
+  return randomBytes(16).toString("hex");
+}
+
+// src/bootstrap.ts
+async function runPlugin(handlers) {
+  const { pipePath, token } = await readBootstrapLine();
+  const transport = new NodeTransport();
+  await transport.connect(pipePath);
+  const router = new HandlerRouter({ send: (env) => transport.send(env) });
+  transport.onMessage((env) => {
+    router.dispatch(env);
+  });
+  for (const [route, handler] of Object.entries(handlers)) {
+    router.handle(route, handler);
+  }
+  return {
+    transport,
+    router,
+    close: () => transport.close()
+  };
+}
+async function readBootstrapLine() {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  try {
+    const line = await new Promise((resolve, reject) => {
+      rl.once("line", (l) => resolve(l));
+      rl.once("close", () => reject(new Error("stdin closed before bootstrap line")));
+    });
+    const [pipePath, token] = line.split("	");
+    if (!pipePath || !token) {
+      throw new Error(`malformed bootstrap line: ${JSON.stringify(line)}`);
+    }
+    return { pipePath, token };
+  } finally {
+    rl.close();
+  }
+}
+
+// src/server.ts
+var NodeTool = class {
+  #handlers = /* @__PURE__ */ new Map();
+  #searchHandler = null;
+  #actionHandler = null;
+  #initializeHandler = null;
+  #runtime = null;
+  initialize(handler) {
+    this.#initializeHandler = handler;
+    return this;
+  }
+  search(handler) {
+    this.#searchHandler = handler;
+    return this;
+  }
+  action(handler) {
+    this.#actionHandler = handler;
+    return this;
+  }
+  handle(action, handler) {
+    if (!action || typeof action !== "string") {
+      throw new Error("tool.handle requires an action name.");
+    }
+    if (typeof handler !== "function") {
+      throw new Error("tool.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}`;
+    this.#runtime.transport.send({
+      version: "3.0",
+      id: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      traceId: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: "node-main",
+      kind: "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);
+  }
+  /** Connects to the host pipe and begins dispatching. Must be called last. */
+  async start() {
+    const routes = this.buildRoutes();
+    this.#runtime = await runPlugin(routes);
+  }
+  /**
+   * Builds the v3 route map from the fluent registrations. Exposed for unit testing the mapping
+   * without connecting a pipe.
+   */
+  buildRoutes() {
+    const routes = {};
+    if (this.#initializeHandler) {
+      routes["plugin.call.initialize"] = (p) => this.#initializeHandler(p);
+    }
+    if (this.#searchHandler) {
+      routes["plugin.call.search"] = (p) => this.#searchHandler(p);
+    }
+    if (this.#actionHandler) {
+      routes["plugin.call.invokeAction"] = (p) => {
+        return this.#actionHandler({ ...p, itemId: p.itemId, query: p.query });
+      };
+    }
+    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}`;
+      if (!routes[route]) {
+        routes[route] = async (p) => {
+          const ctx = extractContext(p);
+          return handler(p, ctx);
+        };
+      }
+    }
+    return routes;
+  }
+  async stop() {
+    if (this.#runtime) await this.#runtime.close();
+  }
+};
+function extractContext(p) {
+  return {
+    action: p?.action ?? "",
+    itemId: p?.itemId ?? "",
+    query: p?.query ?? "",
+    locale: p?.locale ?? "en-US",
+    fallbackLocale: p?.fallbackLocale ?? "en-US"
+  };
+}
+function createTool() {
+  return new NodeTool();
+}
+export {
+  NodeTool,
+  createTool
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@qping/plugin-bus",
+  "version": "0.1.0",
+  "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.mts",
+      "import": "./dist/server.mjs",
+      "default": "./dist/server.mjs"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.mts",
+      "import": "./dist/protocol.mjs",
+      "default": "./dist/protocol.mjs"
+    },
+    "./bootstrap": {
+      "types": "./dist/bootstrap.d.mts",
+      "import": "./dist/bootstrap.mjs",
+      "default": "./dist/bootstrap.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && node build-sdk.mjs",
+    "check": "node build-sdk.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.8"
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,70 @@
+/**
+ * v3 Node SDK bootstrap entry. Reads the bootstrap line from stdin (pipePath\ttoken), connects to
+ * the named pipe, and starts a HandlerRouter wired to the transport. Plugin authors call
+ * `runPlugin(...)` passing their route handlers; this module owns the connection lifecycle.
+ *
+ * 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.
+ */
+
+import readline from "node:readline/promises";
+import { NodeTransport } from "./transport.ts";
+import { HandlerRouter } from "./router.ts";
+import type { Envelope } from "./protocol.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) and returns a runtime whose
+ * router dispatches inbound plugin.call.* requests to the given handlers. The caller may also use
+ * runtime.router.callHost(...) to invoke host.call.* capabilities.
+ */
+export async function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime> {
+  const { pipePath, token } = await readBootstrapLine();
+
+  const transport = new NodeTransport();
+  await transport.connect(pipePath);
+
+  const router = new HandlerRouter({ send: (env: Envelope) => transport.send(env) });
+
+  // Inbound envelopes from the host arrive on the transport.
+  transport.onMessage((env) => {
+    router.dispatch(env);
+  });
+
+  for (const [route, handler] of Object.entries(handlers)) {
+    router.handle(route, handler);
+  }
+
+  return {
+    transport,
+    router,
+    close: () => transport.close(),
+  };
+}
+
+/** Reads line 1 of stdin: "<pipePath>\t<token>". */
+async function readBootstrapLine(): Promise<{ pipePath: string; token: string }> {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  try {
+    const line = await new Promise<string>((resolve, reject) => {
+      rl.once("line", (l) => resolve(l));
+      rl.once("close", () => reject(new Error("stdin closed before bootstrap line")));
+    });
+    const [pipePath, token] = line.split("\t");
+    if (!pipePath || !token) {
+      throw new Error(`malformed bootstrap line: ${JSON.stringify(line)}`);
+    }
+    return { pipePath, token };
+  } finally {
+    rl.close();
+  }
+}