@qping/plugin-bus 0.1.0 → 0.2.0

package/dist/webTypes.d.ts

@@ -0,0 +1,50 @@
+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>;
+    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;
+}
+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 declare const HostEvents: {
+    readonly Initialize: "host.event.initialize";
+    readonly Search: "host.event.search";
+    readonly Key: "host.event.key";
+    readonly LanguageChanged: "host.event.languageChanged";
+    readonly ThemeChanged: "host.event.themeChanged";
+    readonly InputActionCaptured: "host.event.inputActionCaptured";
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qping/plugin-bus",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
   "type": "module",
   "files": [
@@ -8,29 +8,43 @@
     "src"
   ],
   "exports": {
-    "./server": {
-      "types": "./dist/server.d.mts",
-      "import": "./dist/server.mjs",
-      "default": "./dist/server.mjs"
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs",
+      "default": "./dist/node.mjs"
     },
     "./protocol": {
-      "types": "./dist/protocol.d.mts",
+      "types": "./dist/protocol.d.ts",
       "import": "./dist/protocol.mjs",
       "default": "./dist/protocol.mjs"
     },
     "./bootstrap": {
-      "types": "./dist/bootstrap.d.mts",
+      "types": "./dist/bootstrap.d.ts",
       "import": "./dist/bootstrap.mjs",
       "default": "./dist/bootstrap.mjs"
     },
+    "./web": {
+      "types": "./dist/webClient.d.ts",
+      "import": "./dist/webClient.mjs",
+      "default": "./dist/webClient.mjs"
+    },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.mjs",
+      "default": "./dist/i18n.mjs"
+    },
     "./package.json": "./package.json"
   },
+  "dependencies": {
+    "i18next": "^25.3.2"
+  },
   "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"
+    "esbuild": "^0.25.8",
+    "typescript": "^7.0.2"
   }
 }

package/src/bootstrap.ts

@@ -1,16 +1,24 @@
 /**
  * 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.
+ * the named pipe, completes bus.handshake (presenting the token and receiving bound identity),
+ * and starts a HandlerRouter stamped with that identity.
  *
  * 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.
+ * Node process's stdin — "<pipePath>\t<token>" — then waits for the Node side to connect the pipe
+ * and complete handshake before promoting the session to Ready.
  */
 
 import readline from "node:readline/promises";
+import { randomBytes } from "node:crypto";
 import { NodeTransport } from "./transport.ts";
 import { HandlerRouter } from "./router.ts";
-import type { Envelope } from "./protocol.ts";
+import {
+  type Envelope,
+  EndpointIds,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+} from "./protocol.ts";
 
 export interface PluginHandlers {
   [route: string]: (payload: any) => Promise<any> | any;
@@ -22,10 +30,11 @@ export interface PluginRuntime {
   close(): Promise<void>;
 }
 
+const SUPPORTED_VERSIONS = [ProtocolVersion];
+
 /**
- * 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.
+ * Connects to the host pipe (reading the bootstrap line from stdin), completes handshake, and
+ * returns a runtime whose router dispatches inbound plugin.call.* requests to the given handlers.
  */
 export async function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime> {
   const { pipePath, token } = await readBootstrapLine();
@@ -33,10 +42,29 @@ export async function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime
   const transport = new NodeTransport();
   await transport.connect(pipePath);
 
+  const identity = await completeHandshake(transport, token);
   const router = new HandlerRouter({ send: (env: Envelope) => transport.send(env) });
+  router.setIdentity(identity);
+
+  // Passive host-liveness watchdog: exit if Host stops sending bus.ping (orphan process).
+  // Threshold is well above the host ping interval (~2s) to tolerate brief host stalls.
+  const HOST_LOST_MS = 15_000;
+  let lastPingAt = Date.now();
+  const watchdog = setInterval(() => {
+    if (Date.now() - lastPingAt > HOST_LOST_MS) {
+      clearInterval(watchdog);
+      process.exit(1);
+    }
+  }, 1_000);
+  watchdog.unref?.();
+
+  transport.onDisconnect(() => {
+    clearInterval(watchdog);
+    process.exit(1);
+  });
 
-  // Inbound envelopes from the host arrive on the transport.
   transport.onMessage((env) => {
+    if (env.route === Routes.Bus.Ping) lastPingAt = Date.now();
     router.dispatch(env);
   });
 
@@ -47,7 +75,10 @@ export async function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime
   return {
     transport,
     router,
-    close: () => transport.close(),
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    },
   };
 }
 
@@ -68,3 +99,61 @@ async function readBootstrapLine(): Promise<{ pipePath: string; token: string }>
     rl.close();
   }
 }
+
+/**
+ * Sends bus.handshake with the bootstrap token and waits for the host response that binds
+ * plugin/entry/session/endpoint identity. Rejects on HandshakeFailed / ProtocolMismatch / timeout.
+ */
+export async function completeHandshake(
+  transport: NodeTransport,
+  token: string,
+  timeoutMs = 10000,
+): Promise<{ pluginId: string; entryId: string; sessionId: string; endpointId: string }> {
+  const id = randomBytes(16).toString("hex");
+  const req: Envelope = {
+    version: ProtocolVersion,
+    id,
+    traceId: id,
+    sessionId: "",
+    pluginId: "",
+    entryId: "",
+    endpointId: EndpointIds.NodeMain,
+    kind: MessageKind.Request,
+    route: Routes.Bus.Handshake,
+    timeoutMs,
+    payload: {
+      version: ProtocolVersion,
+      supportedVersions: SUPPORTED_VERSIONS,
+      token,
+    },
+  };
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`bus.handshake timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const unsubscribe = transport.onMessage((env: Envelope) => {
+      if (env.kind !== MessageKind.Response || env.correlationId !== id) return;
+      clearTimeout(timer);
+      unsubscribe();
+      if (env.error) {
+        reject(new Error(`${env.error.code}: ${env.error.message}`));
+        return;
+      }
+      const p = (env.payload ?? {}) as Record<string, unknown>;
+      const pluginId = String(p.pluginId ?? "");
+      const entryId = String(p.entryId ?? "");
+      const sessionId = String(p.sessionId ?? "");
+      const endpointId = String(p.endpointId ?? EndpointIds.NodeMain);
+      if (!pluginId || !entryId || !sessionId) {
+        reject(new Error("bus.handshake success response missing bound identity"));
+        return;
+      }
+      resolve({ pluginId, entryId, sessionId, endpointId });
+    });
+
+    transport.send(req);
+  });
+}

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,213 @@
+/**
+ * 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
+ *   action     -> plugin.call.invokeAction
+ *   handle(name) -> plugin.call.<name>
+ *   publish    -> plugin.event.<subjectId>
+ *   hostCall   -> host.call.<method>
+ */
+
+import { runPlugin, type PluginRuntime } from "./bootstrap.ts";
+import {
+  EndpointIds,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+  hostCallRoute,
+  pluginCallRoute,
+  pluginEventRoute,
+} from "./protocol.ts";
+
+export type PluginTheme = "light" | "dark";
+
+export type PluginHostEnv = {
+  locale: string;
+  fallbackLocale: string;
+  theme: PluginTheme;
+};
+
+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";
+};
+
+/** Payload of plugin.call.invokeAction. */
+export type PluginActionParams = PluginHostEnv & {
+  itemId: string;
+  actionId: string;
+  query: string;
+};
+
+type PluginInitializeHandler = (params: PluginInitializeParams) => unknown | Promise<unknown>;
+type PluginSearchHandler = (params: PluginSearchParams) => unknown | Promise<unknown>;
+type PluginActionHandler = (params: PluginActionParams) => unknown | Promise<unknown>;
+type PluginHandler = (payload: any, context: PluginContext) => unknown | Promise<unknown>;
+
+export class Plugin {
+  #handlers = new Map<string, PluginHandler>();
+  #searchHandler: PluginSearchHandler | null = null;
+  #actionHandler: PluginActionHandler | null = null;
+  #initializeHandler: PluginInitializeHandler | null = null;
+  #runtime: PluginRuntime | null = null;
+
+  initialize(handler: PluginInitializeHandler): this {
+    this.#initializeHandler = handler;
+    return this;
+  }
+
+  search(handler: PluginSearchHandler): this {
+    this.#searchHandler = handler;
+    return this;
+  }
+
+  action(handler: PluginActionHandler): this {
+    this.#actionHandler = handler;
+    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) => unknown | Promise<unknown>> {
+    const routes: Record<string, (payload: any) => unknown | Promise<unknown>> = {};
+
+    if (this.#initializeHandler) {
+      routes[Routes.PluginCall.Initialize] = (p) => this.#initializeHandler!(asInitializeParams(p));
+    }
+    if (this.#searchHandler) {
+      routes[Routes.PluginCall.Search] = (p) => this.#searchHandler!(asSearchParams(p));
+    }
+    if (this.#actionHandler) {
+      routes[Routes.PluginCall.InvokeAction] = (p) => this.#actionHandler!(asActionParams(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();
+  }
+}
+
+function asHostEnv(p: any): PluginHostEnv {
+  return {
+    locale: typeof p?.locale === "string" ? p.locale : "en-US",
+    fallbackLocale: typeof p?.fallbackLocale === "string" ? p.fallbackLocale : "en-US",
+    theme: asTheme(p?.theme),
+  };
+}
+
+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 asActionParams(p: any): PluginActionParams {
+  return {
+    ...asHostEnv(p),
+    itemId: typeof p?.itemId === "string" ? p.itemId : "",
+    actionId: typeof p?.actionId === "string" ? p.actionId : "",
+    query: typeof p?.query === "string" ? p.query : "",
+  };
+}
+
+function asTheme(value: unknown): PluginTheme {
+  return value === "light" ? "light" : "dark";
+}
+
+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();
+}