@qping/plugin-bus 0.1.0 → 0.3.0

package/src/router.ts

@@ -1,149 +1,199 @@
-/**
- * Handler router for the Node SDK v3. Dispatches inbound plugin.call.* requests to registered
- * handlers, auto-replies to bus.ping, and provides callHost() to invoke host.call.* capabilities
- * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
- */
-
-import { randomBytes } from "node:crypto";
-import type { Envelope, BusError } from "./protocol.ts";
-
-type Handler = (payload: unknown) => Promise<unknown> | unknown;
-type Sender = (env: Envelope) => void;
-
-interface PendingHostCall {
-  resolve: (value: unknown) => void;
-  reject: (err: Error) => void;
-  route: string;
-}
-
-export class HandlerRouter {
-  private handlers = new Map<string, Handler>();
-  private pendingHostCalls = new Map<string, PendingHostCall>();
-  private pluginId = "p";
-  private entryId = "e";
-  private sessionId = "s";
-  private endpointId = "node-main";
-
-  /** Injected transport send fn; tests can override `router.send` directly. */
-  send: Sender;
-
-  constructor(deps: { send: Sender }) {
-    this.send = deps.send;
-  }
-
-  /** Sets the bound identity stamped on outbound messages (after handshake). */
-  setIdentity(ids: { pluginId: string; entryId: string; sessionId: string; endpointId: string }): void {
-    this.pluginId = ids.pluginId;
-    this.entryId = ids.entryId;
-    this.sessionId = ids.sessionId;
-    this.endpointId = ids.endpointId;
-  }
-
-  handle(route: string, handler: Handler): void {
-    this.handlers.set(route, handler);
-  }
-
-  /** Dispatches an inbound request/response. Returns once handled. */
-  async dispatch(env: Envelope): Promise<void> {
-    if (env.kind === "response") {
-      this.handleHostResponse(env);
-      return;
-    }
-    if (env.kind !== "request") return;
-
-    // bus.ping is always auto-replied; it does not occupy a handler slot.
-    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: string, payload: unknown, timeoutMs = 30000): Promise<unknown> {
-    return new Promise((resolve, reject) => {
-      const id = randomBytesHex();
-      const req: Envelope = {
-        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: PendingHostCall = { 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);
-      // Clear the timer when settled.
-      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);
-    });
-  }
-
-  private handleHostResponse(env: Envelope): void {
-    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);
-    }
-  }
-
-  private responseFor(req: Envelope, payload: unknown): Envelope {
-    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,
-    };
-  }
-
-  private errorResponseFor(req: Envelope, code: string, message: string): Envelope {
-    return {
-      ...this.responseFor(req, null),
-      payload: undefined,
-      error: { code, message, retryable: false } as BusError,
-    };
-  }
-}
-
-function randomBytesHex(): string {
-  // 16 random bytes -> 32 hex chars, matching the C# GuidIdGenerator format.
-  return randomBytes(16).toString("hex");
-}
+/**
+ * Handler router for the Node SDK v3. Dispatches inbound plugin.call.* requests to registered
+ * handlers, auto-replies to bus.ping, and provides callHost() to invoke host.call.* capabilities
+ * and correlate their responses. Mirrors the C# MessageBus routing rules on the Node side.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+import {
+  type Envelope,
+  type BusError,
+  EndpointIds,
+  ErrorCode,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+} from "./protocol.ts";
+
+type Handler = (payload: unknown, context: { sessionId: string }) => Promise<unknown> | unknown;
+type Sender = (env: Envelope) => void;
+
+interface PendingHostCall {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  route: string;
+}
+
+type RequestScope = { deadlineMs: number | null };
+
+const requestScope = new AsyncLocalStorage<RequestScope>();
+
+export const DefaultHostCallTimeoutMs = 30_000;
+
+/** Remaining ms of the inbound plugin.call timeout, if currently inside a request. */
+export function remainingTimeoutMs(): number | undefined {
+  const scope = requestScope.getStore();
+  if (!scope || scope.deadlineMs == null) {
+    return undefined;
+  }
+
+  return scope.deadlineMs - Date.now();
+}
+
+export function resolveHostCallTimeoutMs(explicit?: number): number {
+  const remaining = remainingTimeoutMs();
+  if (explicit != null) {
+    return remaining == null ? explicit : Math.min(explicit, remaining);
+  }
+
+  return remaining ?? DefaultHostCallTimeoutMs;
+}
+
+function deadlineFromTimeoutMs(timeoutMs: number | null | undefined): number | null {
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    return null;
+  }
+
+  return Date.now() + timeoutMs;
+}
+
+export class HandlerRouter {
+  private handlers = new Map<string, Handler>();
+  private pendingHostCalls = new Map<string, PendingHostCall>();
+  private pluginId = "p";
+  private entryId = "e";
+  private sessionId = "s";
+  private endpointId: string = EndpointIds.NodeMain;
+
+  /** Injected transport send fn; tests can override `router.send` directly. */
+  send: Sender;
+
+  constructor(deps: { send: Sender }) {
+    this.send = deps.send;
+  }
+
+  /** Sets the bound identity stamped on outbound messages (after handshake). */
+  setIdentity(ids: { pluginId: string; entryId: string; sessionId: string; endpointId: string }): void {
+    this.pluginId = ids.pluginId;
+    this.entryId = ids.entryId;
+    this.sessionId = ids.sessionId;
+    this.endpointId = ids.endpointId;
+  }
+
+  handle(route: string, handler: Handler): void {
+    this.handlers.set(route, handler);
+  }
+
+  /** Dispatches an inbound request/response. Returns once handled. */
+  async dispatch(env: Envelope): Promise<void> {
+    if (env.kind === MessageKind.Response) {
+      this.handleHostResponse(env);
+      return;
+    }
+    if (env.kind !== MessageKind.Request) return;
+
+    // bus.ping is always auto-replied; it does not occupy a handler slot.
+    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, ErrorCode.RouteNotFound, `route '${env.route}' has no handler`));
+      return;
+    }
+
+    const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
+    try {
+      const result = await requestScope.run(
+        { deadlineMs },
+        () => handler(env.payload, { sessionId: env.sessionId }),
+      );
+      this.send(this.responseFor(env, result ?? {}));
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.send(this.errorResponseFor(env, ErrorCode.InternalError, message));
+    }
+  }
+
+  /** Calls a host.call.* capability and resolves with the response payload. */
+  callHost(route: string, payload: unknown, timeoutMs?: number): Promise<unknown> {
+    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: Envelope = {
+        version: ProtocolVersion,
+        id,
+        traceId: id,
+        sessionId: this.sessionId,
+        pluginId: this.pluginId,
+        entryId: this.entryId,
+        endpointId: this.endpointId,
+        kind: MessageKind.Request,
+        route,
+        timeoutMs: effectiveTimeoutMs,
+        payload,
+      };
+      const pending: PendingHostCall = { 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 ${effectiveTimeoutMs}ms`));
+        }
+      }, effectiveTimeoutMs);
+      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);
+    });
+  }
+
+  private handleHostResponse(env: Envelope): void {
+    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);
+    }
+  }
+
+  private responseFor(req: Envelope, payload: unknown): Envelope {
+    return {
+      version: ProtocolVersion,
+      id: randomBytesHex(),
+      correlationId: req.id,
+      traceId: req.traceId,
+      sessionId: req.sessionId,
+      pluginId: req.pluginId,
+      entryId: req.entryId,
+      endpointId: this.endpointId,
+      kind: MessageKind.Response,
+      route: req.route,
+      payload,
+    };
+  }
+
+  private errorResponseFor(req: Envelope, code: BusError["code"], message: string): Envelope {
+    return {
+      ...this.responseFor(req, null),
+      payload: undefined,
+      error: { code, message, retryable: false } as BusError,
+    };
+  }
+}
+
+function randomBytesHex(): string {
+  // 16 random bytes -> 32 hex chars, matching the C# GuidIdGenerator format.
+  return randomBytes(16).toString("hex");
+}

package/src/search.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns whether every character in `pattern` occurs in `target` in the same order.
+ * Matching is case-insensitive and characters do not need to be adjacent.
+ *
+ * @example isSubsequence("gthb", "GitHub") // true
+ */
+export function isSubsequence(pattern: string, target: string): boolean {
+  if (!pattern) return true;
+  if (!target) return false;
+
+  const needle = pattern.toLowerCase();
+  const haystack = target.toLowerCase();
+  let patternIndex = 0;
+
+  for (let targetIndex = 0; targetIndex < haystack.length && patternIndex < needle.length; targetIndex += 1) {
+    if (haystack[targetIndex] === needle[patternIndex]) {
+      patternIndex += 1;
+    }
+  }
+
+  return patternIndex === needle.length;
+}

package/src/transport.ts

@@ -17,8 +17,9 @@ export class NodeTransport {
   private disconnectHandlers = new Set<DisconnectHandler>();
   private closed = false;
 
-  onMessage(handler: MessageHandler): void {
+  onMessage(handler: MessageHandler): () => void {
     this.messageHandlers.add(handler);
+    return () => { this.messageHandlers.delete(handler); };
   }
 
   onDisconnect(handler: DisconnectHandler): void {

package/src/webClient.ts

@@ -0,0 +1,288 @@
+/**
+ * v3 Web SDK: speaks protocol envelopes over chrome.webview.postMessage.
+ * Host stamps identity; the page does not supply plugin/entry/session ids.
+ *
+ * Connections start with bus.handshake. Subsequent plugin.call.* envelopes use the
+ * negotiated version. call("refresh") is sent as plugin.call.refresh.
+ */
+
+import { mytoolsI18n } from "./i18n.ts";
+import {
+  type Envelope,
+  type BusError,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+  pluginCallRoute,
+} from "./protocol.ts";
+import type { MyToolsThemePayload } from "./webTypes.ts";
+
+export { mytoolsI18n } from "./i18n.ts";
+export { renderHotkeyKeycaps } from "./hotkeyKeycaps.ts";
+export { HostEvents } from "./webTypes.ts";
+export type {
+  MyToolsHostActionDefinition,
+  MyToolsHostDetailActionPayload,
+  MyToolsHostInitializePayload,
+  MyToolsHostKeyPayload,
+  MyToolsHostSearchPayload,
+  MyToolsInputActionCapturedPayload,
+  MyToolsLanguageChangedPayload,
+  MyToolsThemeChangedPayload,
+  MyToolsThemePayload,
+} from "./webTypes.ts";
+
+type Pending = {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+};
+
+export interface WebBusClient {
+  /** Sends plugin.call.<method>. Bare names are prefixed; full routes are left as-is. */
+  call<T = unknown>(method: string, payload?: unknown, timeoutMs?: number): Promise<T>;
+  on<T = unknown>(route: string, handler: (payload: T) => void): () => void;
+  i18n: typeof mytoolsI18n;
+  theme: typeof mytoolsTheme;
+  close(): void;
+}
+
+const HandshakeTimeoutMs = 8_000;
+
+const mytoolsTheme = {
+  current: "dark",
+  apply(payload: MyToolsThemePayload): void {
+    if (typeof payload.theme === "string") {
+      this.current = payload.theme;
+    }
+    const root = typeof document !== "undefined" ? document.documentElement : null;
+    if (!root) {
+      return;
+    }
+    if (typeof payload.theme === "string") {
+      root.setAttribute("data-theme", payload.theme);
+      root.style.colorScheme = payload.theme;
+    }
+    if (payload.themeTokens) {
+      for (const [key, value] of Object.entries(payload.themeTokens)) {
+        if (typeof value === "string") {
+          root.style.setProperty(key, value);
+        }
+      }
+    }
+  },
+};
+
+function hasWebView(): boolean {
+  return !!(typeof window !== "undefined" && (window as any).chrome?.webview);
+}
+
+function post(env: Envelope): void {
+  if (!hasWebView()) throw new Error("chrome.webview is not available");
+  (window as any).chrome.webview.postMessage(env);
+}
+
+function randomId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+function parseMessage(data: unknown): Envelope | null {
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!data || typeof data !== "object") return null;
+  const env = data as Envelope;
+  if (typeof env.kind !== "string" || typeof env.route !== "string") return null;
+  return env;
+}
+
+function applyHostSideEffects(env: Envelope): void {
+  const payload = env.payload;
+  if (!payload || typeof payload !== "object") return;
+  if (env.route === Routes.HostEvent.Initialize) {
+    mytoolsI18n.configure(payload);
+    mytoolsI18n.apply();
+    mytoolsTheme.apply(payload as MyToolsThemePayload);
+  } else if (env.route === Routes.HostEvent.LanguageChanged) {
+    mytoolsI18n.configure(payload);
+    mytoolsI18n.apply();
+  } else if (env.route === Routes.HostEvent.ThemeChanged) {
+    mytoolsTheme.apply(payload as MyToolsThemePayload);
+  }
+}
+
+function negotiatedVersionFrom(payload: unknown): string {
+  if (payload && typeof payload === "object" && "negotiatedVersion" in payload) {
+    const value = (payload as { negotiatedVersion?: unknown }).negotiatedVersion;
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return ProtocolVersion;
+}
+
+/**
+ * Creates a Web bus client. Registers the message listener immediately so host
+ * events that arrive before `on()` are buffered and replayed.
+ *
+ * Handshake is required before call(). Page scripts are bundled as IIFE, so this
+ * function is synchronous; handshake runs in the background and gates call().
+ */
+export function createWebBusClient(options?: {
+  timeoutMs?: number;
+}): WebBusClient {
+  const pending = new Map<string, Pending>();
+  const eventHandlers = new Set<(env: Envelope) => void>();
+  const lastByRoute = new Map<string, Envelope>();
+  const defaultTimeout = options?.timeoutMs ?? 30_000;
+  let wireVersion = ProtocolVersion;
+  let handshakeError: Error | null = null;
+
+  const onMessage = (event: MessageEvent) => {
+    const env = parseMessage(event.data);
+    if (!env) return;
+    if (env.kind === MessageKind.Response && env.correlationId) {
+      const p = pending.get(env.correlationId);
+      if (!p) return;
+      pending.delete(env.correlationId);
+      if (env.error) {
+        p.reject(new Error(`${(env.error as BusError).code}: ${(env.error as BusError).message}`));
+      } else {
+        p.resolve(env.payload);
+      }
+      return;
+    }
+    if (env.kind === MessageKind.Event) {
+      lastByRoute.set(env.route, env);
+      applyHostSideEffects(env);
+      for (const h of eventHandlers) h(env);
+    }
+  };
+
+  let handshakeDone: Promise<void> = Promise.resolve();
+  if (hasWebView()) {
+    (window as any).chrome.webview.addEventListener("message", onMessage);
+    handshakeDone = handshake(HandshakeTimeoutMs)
+      .then((version) => {
+        wireVersion = version;
+      })
+      .catch((err: unknown) => {
+        handshakeError = err instanceof Error ? err : new Error(String(err));
+        throw handshakeError;
+      });
+  }
+
+  function ensureHandshaken(): Promise<void> {
+    if (handshakeError) return Promise.reject(handshakeError);
+    return handshakeDone.then(() => {
+      if (handshakeError) throw handshakeError;
+    });
+  }
+
+  function call<T = unknown>(method: string, payload?: unknown, timeoutMs = defaultTimeout): Promise<T> {
+    const route = pluginCallRoute(method);
+    return ensureHandshaken().then(
+      () =>
+        new Promise<T>((resolve, reject) => {
+          const id = randomId();
+          const timer = window.setTimeout(() => {
+            pending.delete(id);
+            reject(new Error(`request timed out: ${route}`));
+          }, timeoutMs);
+          pending.set(id, {
+            resolve: (v) => {
+              window.clearTimeout(timer);
+              resolve(v as T);
+            },
+            reject: (e) => {
+              window.clearTimeout(timer);
+              reject(e);
+            },
+          });
+          post({
+            version: wireVersion,
+            id,
+            traceId: id,
+            sessionId: "",
+            pluginId: "",
+            entryId: "",
+            endpointId: "",
+            kind: MessageKind.Request,
+            route,
+            timeoutMs,
+            payload: payload ?? {},
+          });
+        }),
+    );
+  }
+
+  function subscribe(handler: (env: Envelope) => void): () => void {
+    eventHandlers.add(handler);
+    for (const env of lastByRoute.values()) handler(env);
+    return () => {
+      eventHandlers.delete(handler);
+    };
+  }
+
+  return {
+    call,
+    on: (route, handler) =>
+      subscribe((env) => {
+        if (env.route === route) handler((env.payload ?? {}) as never);
+      }),
+    i18n: mytoolsI18n,
+    theme: mytoolsTheme,
+    close: () => {
+      if (hasWebView()) {
+        (window as any).chrome.webview.removeEventListener("message", onMessage);
+      }
+      pending.clear();
+      eventHandlers.clear();
+      lastByRoute.clear();
+    },
+  };
+}
+
+function handshake(timeoutMs: number): Promise<string> {
+  const id = randomId();
+  return new Promise((resolve, reject) => {
+    const timer = window.setTimeout(() => {
+      cleanup();
+      reject(new Error("bus.handshake timed out"));
+    }, timeoutMs);
+
+    const onMessage = (event: MessageEvent) => {
+      const env = parseMessage(event.data);
+      if (!env || env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      cleanup();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+      } else {
+        resolve(negotiatedVersionFrom(env.payload));
+      }
+    };
+
+    const cleanup = () => {
+      window.clearTimeout(timer);
+      (window as any).chrome.webview.removeEventListener("message", onMessage);
+    };
+
+    (window as any).chrome.webview.addEventListener("message", onMessage);
+    post({
+      version: ProtocolVersion,
+      id,
+      traceId: id,
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: "web",
+      kind: MessageKind.Request,
+      route: Routes.Bus.Handshake,
+      timeoutMs,
+      payload: { version: ProtocolVersion, supportedVersions: [ProtocolVersion] },
+    });
+  });
+}