@qping/plugin-bus 0.1.0 → 0.3.0

package/src/webTypes.ts

@@ -0,0 +1,68 @@
+import { Routes } from "./protocol.ts";
+
+export interface MyToolsHostActionDefinition {
+  id: string;
+  /** Host-localized action display name. */
+  name: string;
+  /** Host-validated display form, for example `Ctrl+H`; absent means click-only. */
+  hotkey?: string | null;
+}
+
+export interface MyToolsHostInitializePayload {
+  protocolVersion: string;
+  pluginId: string;
+  version?: string;
+  itemId: string;
+  query: string;
+  keyword: string;
+  initialState: unknown;
+  locale: string;
+  fallbackLocale: string;
+  translationRevision: string;
+  messages: Record<string, string>;
+  actions: MyToolsHostActionDefinition[];
+  theme?: string;
+  themeTokens?: Record<string, string>;
+}
+
+export interface MyToolsLanguageChangedPayload {
+  locale: string;
+  fallbackLocale: string;
+  translationRevision: string;
+  messages: Record<string, string>;
+}
+
+export interface MyToolsThemeChangedPayload {
+  theme: string;
+  themeTokens: Record<string, string>;
+}
+
+export interface MyToolsHostSearchPayload {
+  query: string;
+}
+
+export interface MyToolsHostKeyPayload {
+  key: string;
+}
+
+/** Payload explicitly returned in an action outcome's `web.payload`. */
+export interface MyToolsHostDetailActionPayload {
+  actionId?: string;
+  action?: string;
+  [key: string]: unknown;
+}
+
+export interface MyToolsInputActionCapturedPayload {
+  requestId: string;
+  cancelled?: boolean;
+  kind?: "hotkey" | "mouse";
+  hotKey?: string | null;
+  mouseButton?: string | null;
+}
+
+export interface MyToolsThemePayload {
+  theme?: string;
+  themeTokens?: Record<string, string>;
+}
+
+export const HostEvents = Routes.HostEvent;

package/dist/bootstrap.d.mts

@@ -1 +0,0 @@
-export * from "../src/bootstrap.ts";

package/dist/protocol.d.mts

@@ -1 +0,0 @@
-export * from "../src/protocol.ts";

package/dist/server.d.mts

@@ -1 +0,0 @@
-export * from "../src/server.ts";

package/dist/server.mjs

@@ -1,484 +0,0 @@
-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
-};