@qping/plugin-bus 0.2.0 → 0.3.0

package/src/router.ts

@@ -1,196 +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 { 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) => 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));
-      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");
-}
+/**
+ * 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/webClient.ts

@@ -18,8 +18,11 @@ import {
 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,

package/src/webTypes.ts

@@ -1,5 +1,13 @@
 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;
@@ -12,6 +20,7 @@ export interface MyToolsHostInitializePayload {
   fallbackLocale: string;
   translationRevision: string;
   messages: Record<string, string>;
+  actions: MyToolsHostActionDefinition[];
   theme?: string;
   themeTokens?: Record<string, string>;
 }
@@ -36,6 +45,13 @@ 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;