@qping/plugin-bus 0.1.0 → 0.3.0

package/src/hotkeyKeycaps.ts

@@ -0,0 +1,28 @@
+/** Render a host-formatted shortcut as the same sequence of keycaps used by the desktop action bar. */
+export function renderHotkeyKeycaps(element: HTMLElement, hotkey: string): void {
+  const normalized = hotkey.trim();
+  element.hidden = normalized.length === 0;
+  element.setAttribute("aria-label", normalized);
+  element.classList.add("hotkey-keycaps");
+
+  const keycaps = normalized.length === 0
+    ? []
+    : normalized.split("+").map((token) => createKeycap(token.trim()));
+  element.replaceChildren(...keycaps);
+}
+
+function createKeycap(token: string): HTMLSpanElement {
+  const keycap = document.createElement("span");
+  keycap.className = "hotkey-keycap";
+  keycap.setAttribute("aria-hidden", "true");
+
+  if (token.toLowerCase() === "enter" || token.toLowerCase() === "return") {
+    keycap.classList.add("hotkey-keycap-enter");
+    keycap.textContent = "↵";
+    keycap.title = "Enter";
+  } else {
+    keycap.textContent = token;
+  }
+
+  return keycap;
+}

package/src/i18n.ts

@@ -0,0 +1,120 @@
+import i18next, { type i18n } from "i18next";
+
+export type TranslationValues = Record<string, unknown>;
+
+export type TranslationOptions = TranslationValues & {
+  defaultValue: string;
+  translatorComment?: string;
+};
+
+type LocalizationPayload = {
+  locale?: string;
+  fallbackLocale?: string;
+  messages?: Record<string, string>;
+};
+
+class MyToolsI18n {
+  readonly #instance: i18n = i18next.createInstance();
+  #locale = "en-US";
+  #fallbackLocale = "en-US";
+  #messages: Record<string, string> = {};
+
+  get language(): string {
+    return this.#locale;
+  }
+
+  configure(payload: LocalizationPayload | Record<string, unknown> | null | undefined): void {
+    if (!payload || typeof payload !== "object") {
+      return;
+    }
+    this.#locale = typeof payload.locale === "string" ? payload.locale : this.#locale;
+    this.#fallbackLocale = typeof payload.fallbackLocale === "string"
+      ? payload.fallbackLocale
+      : this.#fallbackLocale;
+    this.#messages = isRecord(payload.messages)
+      ? Object.fromEntries(Object.entries(payload.messages).filter((entry): entry is [string, string] => typeof entry[1] === "string"))
+      : {};
+    if (this.#instance.isInitialized) {
+      this.#instance.addResourceBundle(this.#locale, "translation", this.#messages, true, true);
+      void this.#instance.changeLanguage(this.#locale);
+      return;
+    }
+
+    void this.#instance.init({
+      lng: this.#locale,
+      fallbackLng: this.#fallbackLocale,
+      initImmediate: false,
+      debug: false,
+      showSupportNotice: false,
+      keySeparator: false,
+      nsSeparator: false,
+      interpolation: { escapeValue: false },
+      resources: {
+        [this.#locale]: { translation: this.#messages }
+      }
+    });
+  }
+
+  t(key: string, options: TranslationOptions): string {
+    if (!key || typeof key !== "string") {
+      throw new Error("i18n.t requires a stable key.");
+    }
+    if (!options || typeof options.defaultValue !== "string") {
+      throw new Error("i18n.t requires a string defaultValue.");
+    }
+
+    const { translatorComment: _, ...runtimeOptions } = options;
+    if (!this.#instance.isInitialized) {
+      return options.defaultValue.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.-]*)\s*\}\}/g, (placeholder, name: string) => {
+        const value = options[name];
+        return value === undefined || value === null ? placeholder : String(value);
+      });
+    }
+    return this.#instance.t(key, runtimeOptions);
+  }
+
+  apply(root?: ParentNode): void {
+    if (typeof document === "undefined") {
+      return;
+    }
+    const target = root ?? document;
+    target.querySelectorAll<HTMLElement>("[data-i18n]").forEach((element) => {
+      const descriptor = element.dataset.i18n ?? "";
+      const parsed = parseDescriptor(descriptor);
+      const defaultValue = element.dataset.i18nDefaultValue ?? element.textContent ?? parsed.key;
+      const value = this.t(parsed.key, { defaultValue });
+      parsed.attributes.forEach((attribute) => {
+        if (attribute === "text") {
+          element.textContent = value;
+        } else {
+          element.setAttribute(attribute, value);
+        }
+      });
+    });
+    document.documentElement.lang = this.#locale;
+  }
+}
+
+function parseDescriptor(descriptor: string): { attributes: string[]; key: string } {
+  const attributes: string[] = [];
+  let key = descriptor;
+  while (key.startsWith("[")) {
+    const closingBracket = key.indexOf("]");
+    if (closingBracket <= 1) {
+      break;
+    }
+
+    attributes.push(key.slice(1, closingBracket));
+    key = key.slice(closingBracket + 1);
+  }
+
+  return key
+    ? { attributes: attributes.length > 0 ? attributes : ["text"], key }
+    : { attributes: ["text"], key: descriptor };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export const mytoolsI18n = new MyToolsI18n();

package/src/node.ts

@@ -0,0 +1,332 @@
+/**
+ * Node-side plugin SDK: fluent `createPlugin()` over the v3 named-pipe message bus.
+ *
+ * Method names map to v3 routes:
+ *   initialize -> plugin.call.initialize
+ *   search     -> plugin.call.search
+ *   actions    -> plugin.call.invokeAction (dispatched by action id)
+ *   handle(name) -> plugin.call.<name>
+ *   publish    -> plugin.event.<subjectId>
+ *   hostCall   -> host.call.<method>
+ */
+
+import { runPlugin, type PluginRuntime } from "./bootstrap.ts";
+import { asHostEnv, type PluginHostEnv, type PluginTheme } from "./hostEnv.ts";
+import { toActionManifest, type ActionDefinition, type ActionOutcome } from "./actions.ts";
+import {
+  EndpointIds,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+  hostCallRoute,
+  pluginCallRoute,
+  pluginEventRoute,
+} from "./protocol.ts";
+
+export type { PluginHostEnv, PluginTheme } from "./hostEnv.ts";
+export {
+  HostAction,
+  Key,
+  Modifiers,
+  type ActionContext,
+  type ActionDefinition,
+  type ActionOutcome,
+  type DetailRequest,
+  type HostActionKind,
+  type HostActionRequest,
+  type Hotkey,
+  type HotkeyKey,
+  type HotkeyModifiers,
+  type LocalizedText,
+  type RunSpec,
+} from "./actions.ts";
+
+export type PluginContext = PluginHostEnv & {
+  action: string;
+  itemId: string;
+  query: string;
+};
+
+/** Payload of plugin.call.initialize. Host sends locale, theme, and the resolved message bag. */
+export type PluginInitializeParams = PluginHostEnv & {
+  messages: Record<string, string>;
+};
+
+/** Payload of plugin.call.search. */
+export type PluginSearchParams = PluginHostEnv & {
+  query: string;
+  mode: "global" | "plugin";
+};
+
+export type SearchIcon = {
+  kind: string;
+  value: string;
+};
+
+/**
+ * A search result row. Only `id`/`title`/`subtitle`/`priority`/`icon`/`actions` reach the host;
+ * any other field stays on the Node side and comes back as `context.item` when an action runs.
+ */
+export type SearchItem = {
+  id: string;
+  title: string;
+  subtitle?: string;
+  priority?: number;
+  icon?: SearchIcon;
+  /** Ids of registered actions, in display order. The first one is bound to Enter. */
+  actions?: string[];
+  [extra: string]: unknown;
+};
+
+export type SearchResult = {
+  items: SearchItem[];
+};
+
+/** Keeps `context.item` available without letting a long-lived session grow without bound. */
+const ItemCacheLimit = 1000;
+const SessionCacheLimit = 8;
+
+type PluginInitializeHandler = (params: PluginInitializeParams) => unknown | Promise<unknown>;
+type PluginSearchHandler = (params: PluginSearchParams) => SearchResult | Promise<SearchResult>;
+type PluginHandler = (payload: any, context: PluginContext) => unknown | Promise<unknown>;
+
+export class Plugin {
+  #handlers = new Map<string, PluginHandler>();
+  #actions = new Map<string, ActionDefinition<any>>();
+  #searchHandler: PluginSearchHandler | null = null;
+  #initializeHandler: PluginInitializeHandler | null = null;
+  #runtime: PluginRuntime | null = null;
+  #itemsBySession = new Map<string, Map<string, unknown>>();
+
+  initialize(handler: PluginInitializeHandler): this {
+    this.#initializeHandler = handler;
+    return this;
+  }
+
+  search(handler: PluginSearchHandler): this {
+    this.#searchHandler = handler;
+    return this;
+  }
+
+  /**
+   * Registers every action this plugin offers. The list is sent to the host in the initialize
+   * response, so the host knows the ids, labels and hotkeys before any search runs; search items
+   * and the detail page then reference them by id only.
+   */
+  actions<TItem = any>(definitions: ActionDefinition<TItem>[]): this {
+    if (!Array.isArray(definitions)) {
+      throw new Error("plugin.actions requires an array of action definitions.");
+    }
+    for (const definition of definitions) {
+      if (!definition?.id) {
+        throw new Error("plugin.actions requires every action to have an id.");
+      }
+      if (this.#actions.has(definition.id)) {
+        throw new Error(`plugin.actions has a duplicate action id: ${definition.id}`);
+      }
+      if (typeof definition.execute !== "function") {
+        throw new Error(`plugin.actions requires an execute function for action: ${definition.id}`);
+      }
+      this.#actions.set(definition.id, definition);
+    }
+    return this;
+  }
+
+  handle(action: string, handler: PluginHandler): this {
+    if (!action || typeof action !== "string") {
+      throw new Error("plugin.handle requires an action name.");
+    }
+    if (typeof handler !== "function") {
+      throw new Error("plugin.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: string, payload: unknown = {}): void {
+    if (!this.#runtime) throw new Error("plugin not started");
+    const route = pluginEventRoute(subjectId);
+    this.#runtime.transport.send({
+      version: ProtocolVersion,
+      id: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      traceId: crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+      sessionId: "",
+      pluginId: "",
+      entryId: "",
+      endpointId: EndpointIds.NodeMain,
+      kind: MessageKind.Event,
+      route,
+      payload,
+    });
+  }
+
+  /** Calls a host.call.<method> capability and awaits the response.
+   *  `timeoutMs` defaults to the remaining timeout of the inbound plugin.call
+   *  (from a page `bus.call`) when inside a handler; otherwise 30s.
+   */
+  hostCall(method: string, params: Record<string, unknown> = {}, timeoutMs?: number): Promise<unknown> {
+    if (!this.#runtime) return Promise.reject(new Error("plugin not started"));
+    return this.#runtime.router.callHost(hostCallRoute(method), params, timeoutMs);
+  }
+
+  /** Connects to the host pipe and begins dispatching. Must be called last. */
+  async start(): Promise<void> {
+    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(): Record<
+    string,
+    (payload: any, context?: { sessionId: string }) => unknown | Promise<unknown>
+  > {
+    const routes: Record<
+      string,
+      (payload: any, context?: { sessionId: string }) => unknown | Promise<unknown>
+    > = {};
+
+    // initialize always answers, even without a handler, because the host reads the action
+    // registry out of this response.
+    routes[Routes.PluginCall.Initialize] = async (p) => {
+      const result = this.#initializeHandler
+        ? await this.#initializeHandler(asInitializeParams(p))
+        : {};
+      const body = result && typeof result === "object" ? { ...(result as object) } : {};
+      return { ...body, actions: [...this.#actions.values()].map(toActionManifest) };
+    };
+
+    if (this.#searchHandler) {
+      routes[Routes.PluginCall.Search] = async (p, request) => {
+        const result = await this.#searchHandler!(asSearchParams(p));
+        return { items: this.#trackItems(request?.sessionId ?? "default", result?.items ?? []) };
+      };
+    }
+
+    if (this.#actions.size > 0) {
+      routes[Routes.PluginCall.InvokeAction] = (p, request) =>
+        this.#invokeAction(request?.sessionId ?? "default", p);
+    }
+
+    for (const [action, handler] of this.#handlers) {
+      const route = pluginCallRoute(action);
+      if (!routes[route]) {
+        routes[route] = async (p) => {
+          const ctx = extractContext(p, action);
+          return handler(p ?? {}, ctx);
+        };
+      }
+    }
+    return routes;
+  }
+
+  async stop(): Promise<void> {
+    if (this.#runtime) await this.#runtime.close();
+  }
+
+  /** Remembers the full items and returns the trimmed rows the host actually renders. */
+  #trackItems(sessionId: string, items: SearchItem[]): Record<string, unknown>[] {
+    const sessionItems = this.#sessionItems(sessionId);
+    const wire: Record<string, unknown>[] = [];
+    for (const item of items) {
+      if (!item || typeof item !== "object") continue;
+      const id = typeof item.id === "string" ? item.id : "";
+      if (id) {
+        sessionItems.delete(id);
+        sessionItems.set(id, item);
+      }
+      wire.push(toWireItem(item));
+    }
+    while (sessionItems.size > ItemCacheLimit) {
+      const oldest = sessionItems.keys().next();
+      if (oldest.done) break;
+      sessionItems.delete(oldest.value);
+    }
+    return wire;
+  }
+
+  async #invokeAction(sessionId: string, payload: any): Promise<ActionOutcome> {
+    const env = asHostEnv(payload);
+    const actionId = typeof payload?.actionId === "string" ? payload.actionId : "";
+    const itemId = typeof payload?.itemId === "string" ? payload.itemId : "";
+    const query = typeof payload?.query === "string" ? payload.query : "";
+
+    const definition = this.#actions.get(actionId);
+    if (!definition) {
+      throw new Error(`unknown action: ${actionId}`);
+    }
+
+    const outcome = (await definition.execute({
+      ...env,
+      actionId,
+      itemId,
+      query,
+      item: this.#itemsBySession.get(sessionId)?.get(itemId),
+    })) as ActionOutcome | undefined;
+    return outcome ?? {};
+  }
+
+  #sessionItems(sessionId: string): Map<string, unknown> {
+    const key = sessionId || "default";
+    let items = this.#itemsBySession.get(key);
+    if (!items) {
+      items = new Map<string, unknown>();
+      this.#itemsBySession.set(key, items);
+      while (this.#itemsBySession.size > SessionCacheLimit) {
+        const oldest = this.#itemsBySession.keys().next();
+        if (oldest.done) break;
+        this.#itemsBySession.delete(oldest.value);
+      }
+    }
+    return items;
+  }
+}
+
+function toWireItem(item: SearchItem): Record<string, unknown> {
+  const wire: Record<string, unknown> = {
+    id: item.id,
+    title: item.title,
+  };
+  if (typeof item.subtitle === "string") wire.subtitle = item.subtitle;
+  if (typeof item.priority === "number") wire.priority = item.priority;
+  if (item.icon) wire.icon = item.icon;
+  if (Array.isArray(item.actions)) wire.actions = item.actions.filter((id) => typeof id === "string");
+  return wire;
+}
+
+function asInitializeParams(p: any): PluginInitializeParams {
+  const messages = p?.messages;
+  return {
+    ...asHostEnv(p),
+    messages: isStringRecord(messages) ? messages : {},
+  };
+}
+
+function asSearchParams(p: any): PluginSearchParams {
+  return {
+    ...asHostEnv(p),
+    query: typeof p?.query === "string" ? p.query : "",
+    mode: p?.mode === "plugin" ? "plugin" : "global",
+  };
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return !!value && typeof value === "object" && !Array.isArray(value)
+    && Object.values(value).every((v) => typeof v === "string");
+}
+
+function extractContext(p: any, action: string): PluginContext {
+  return {
+    ...asHostEnv(p),
+    action,
+    itemId: typeof p?.itemId === "string" ? p.itemId : "",
+    query: typeof p?.query === "string" ? p.query : "",
+  };
+}
+
+export function createPlugin(): Plugin {
+  return new Plugin();
+}

package/src/protocol.ts

@@ -6,25 +6,91 @@
  *
  * Field names are camelCase on the wire (System.Text.Json camelCase policy on the C# side).
  * Null fields are omitted on the wire (WhenWritingNull).
+ *
+ * Runtime constants mirror MyTools.Protocol (MessageKindWire, Routes, EndpointIds,
+ * ProtocolVersion.CurrentWire). Do not re-hardcode those strings in SDK source.
  */
 
-export type MessageKind = "request" | "response" | "event";
+export const MessageKind = {
+  Request: "request",
+  Response: "response",
+  Event: "event",
+} as const;
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+
+export const 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",
+} as const;
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export const ProtocolVersion = "3.0";
+
+export const EndpointIds = {
+  NodeMain: "node-main",
+  Host: "host",
+} as const;
+
+export const 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",
+    DetailAction: "host.event.detailAction",
+    LanguageChanged: "host.event.languageChanged",
+    ThemeChanged: "host.event.themeChanged",
+    InputActionCaptured: "host.event.inputActionCaptured",
+  },
+} as const;
 
-export type ErrorCode =
-  | "ProtocolMismatch"
-  | "HandshakeFailed"
-  | "CapabilityNotDeclared"
-  | "CapabilityDenied"
-  | "InvalidPayload"
-  | "MessageTooLarge"
-  | "RouteNotFound"
-  | "RequestTimeout"
-  | "TooManyRequests"
-  | "TransportDisconnected"
-  | "PluginUnavailable"
-  | "InternalError"
-  | "Cancelled"
-  | "RateLimited";
+export function pluginCallRoute(method: string): string {
+  return method.startsWith(Routes.Prefix.PluginCall)
+    ? method
+    : `${Routes.Prefix.PluginCall}${method}`;
+}
+
+export function hostCallRoute(method: string): string {
+  return method.startsWith(Routes.Prefix.HostCall)
+    ? method
+    : `${Routes.Prefix.HostCall}${method}`;
+}
+
+export function pluginEventRoute(subjectId: string): string {
+  return subjectId.startsWith(Routes.Prefix.PluginEvent)
+    ? subjectId
+    : `${Routes.Prefix.PluginEvent}${subjectId}`;
+}
 
 export interface BusError {
   code: ErrorCode;
@@ -38,7 +104,7 @@ export interface BusError {
  * required; the optional ones are omitted on the wire when null.
  */
 export interface Envelope {
-  version: string; // e.g. "3.0"
+  version: string; // e.g. ProtocolVersion
   id: string;
   correlationId?: string | null;
   traceId: string;