@qping/plugin-bus 0.1.0 → 0.3.0

package/dist/webTypes.d.ts

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

package/package.json

@@ -1,36 +1,60 @@
-{
-  "name": "@qping/plugin-bus",
-  "version": "0.1.0",
-  "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
-  "type": "module",
-  "files": [
-    "dist",
-    "src"
-  ],
-  "exports": {
-    "./server": {
-      "types": "./dist/server.d.mts",
-      "import": "./dist/server.mjs",
-      "default": "./dist/server.mjs"
+{
+  "name": "@qping/plugin-bus",
+  "version": "0.3.0",
+  "description": "v3 message-bus runtime for MyTools plugins (named-pipe transport).",
+  "type": "module",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs",
+      "default": "./dist/node.mjs"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.mjs",
+      "default": "./dist/protocol.mjs"
+    },
+    "./bootstrap": {
+      "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"
     },
-    "./protocol": {
-      "types": "./dist/protocol.d.mts",
-      "import": "./dist/protocol.mjs",
-      "default": "./dist/protocol.mjs"
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.mjs",
+      "default": "./dist/search.mjs"
     },
-    "./bootstrap": {
-      "types": "./dist/bootstrap.d.mts",
-      "import": "./dist/bootstrap.mjs",
-      "default": "./dist/bootstrap.mjs"
-    },
-    "./package.json": "./package.json"
-  },
-  "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"
-  }
-}
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "import": "./dist/dev.mjs",
+      "default": "./dist/dev.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",
+    "typescript": "^7.0.2"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,158 @@
+/**
+ * Action registry types.
+ *
+ * A plugin registers its full action set once at startup via `plugin.actions([...])`. Search
+ * items and the detail page only reference actions by id; the parameters an action needs are
+ * produced inside its own `execute`, never carried on the item.
+ */
+
+import type { PluginHostEnv } from "./hostEnv.ts";
+
+/** An i18n message key plus the English fallback the host uses when the key is missing. */
+export type LocalizedText = {
+  key: string;
+  defaultValue: string;
+};
+
+/** Keys the host deliberately permits for action shortcuts. */
+export const Key = {
+  Enter: "Enter", Tab: "Tab", Space: "Space", Delete: "Delete", Backspace: "Backspace",
+  Escape: "Escape", Left: "Left", Right: "Right", Up: "Up", Down: "Down",
+  A: "A", B: "B", C: "C", D: "D", E: "E", F: "F", G: "G", H: "H", I: "I",
+  J: "J", K: "K", L: "L", M: "M", N: "N", O: "O", P: "P", Q: "Q", R: "R",
+  S: "S", T: "T", U: "U", V: "V", W: "W", X: "X", Y: "Y", Z: "Z",
+  D0: "D0", D1: "D1", D2: "D2", D3: "D3", D4: "D4",
+  D5: "D5", D6: "D6", D7: "D7", D8: "D8", D9: "D9",
+  F1: "F1", F2: "F2", F3: "F3", F4: "F4", F5: "F5", F6: "F6",
+  F7: "F7", F8: "F8", F9: "F9", F10: "F10", F11: "F11", F12: "F12",
+} as const;
+
+export type HotkeyKey = (typeof Key)[keyof typeof Key];
+
+/** Permitted modifier combinations, e.g. `Modifiers.ControlShift`. */
+export const Modifiers = {
+  None: 0,
+  Control: 1,
+  Alt: 2,
+  ControlAlt: 3,
+  Shift: 4,
+  ControlShift: 5,
+  AltShift: 6,
+  ControlAltShift: 7,
+} as const;
+
+export type HotkeyModifiers = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export type Hotkey = {
+  key: HotkeyKey;
+  modifiers?: HotkeyModifiers;
+};
+
+/** Actions the host itself can carry out. Anything else belongs in `execute`. */
+export const HostAction = {
+  Copy: "copy",
+  CopyAndPaste: "copyAndPaste",
+  AddClipboardHistory: "addClipboardHistory",
+  Execute: "execute",
+  OpenInExplorer: "openInExplorer",
+  OpenInBrowser: "openInBrowser",
+  OpenPlugin: "openPlugin",
+  Run: "run",
+  Kill: "kill",
+} as const;
+
+export type HostActionKind = (typeof HostAction)[keyof typeof HostAction];
+
+/** Command spec for {@link HostAction.Run}. */
+export type RunSpec = {
+  name?: string;
+  command: string;
+  args?: string;
+  workingDirectory?: string;
+  runAsAdmin?: boolean;
+  isBashScript?: boolean;
+  scripts?: string | string[];
+};
+
+/**
+ * What the host should do, with the parameters that kind actually needs. The discriminated union
+ * is the point: `{ kind: HostAction.Copy, path }` does not compile.
+ */
+export type HostActionRequest =
+  | { kind: typeof HostAction.Copy; text: string }
+  | { kind: typeof HostAction.CopyAndPaste; text: string }
+  | { kind: typeof HostAction.AddClipboardHistory; texts: string[] }
+  | { kind: typeof HostAction.Execute; path: string; args?: string; runAsAdmin?: boolean }
+  | { kind: typeof HostAction.OpenInExplorer; path: string }
+  | { kind: typeof HostAction.OpenInBrowser; url: string | string[] }
+  | { kind: typeof HostAction.OpenPlugin; pluginId: string }
+  | { kind: typeof HostAction.Run; command: RunSpec }
+  | { kind: typeof HostAction.Kill; pid: number };
+
+/** Opens a web detail page. `page` defaults to the entry declared in plugin.json. */
+export type DetailRequest = {
+  page?: string;
+  title?: string;
+  initialState?: unknown;
+};
+
+/**
+ * The result of running an action. Every field is optional and they combine: opening an IDE and
+ * closing the search window is `{ host: {...}, close: true }`.
+ */
+export type ActionOutcome = {
+  /** Run a host-side action (clipboard, process launch, browser, ...). */
+  host?: HostActionRequest;
+  /** Hand off to the detail page; arrives as `host.event.detailAction` with this payload. */
+  web?: { payload?: unknown };
+  /** Open a web detail page. */
+  detail?: DetailRequest;
+  /** Status bar text. */
+  message?: LocalizedText;
+  /** Close the search window afterwards. Defaults to false. */
+  close?: boolean;
+  /** Refresh the current search results afterwards. Defaults to false. */
+  refresh?: boolean;
+};
+
+/**
+ * What an action sees when it runs. `item` is the original object returned by `search()`,
+ * including fields the host never saw — the SDK keeps it so actions do not have to re-derive
+ * their data from the item id.
+ */
+export type ActionContext<TItem = unknown> = PluginHostEnv & {
+  actionId: string;
+  itemId: string;
+  query: string;
+  item?: TItem;
+};
+
+/**
+ * One registered action. `hotkey` is optional: without it the first registered action gets Enter
+ * and the rest are click-only, matching search result items.
+ */
+export type ActionDefinition<TItem = any> = {
+  id: string;
+  title: LocalizedText;
+  description?: LocalizedText;
+  hotkey?: Hotkey;
+  execute: (context: ActionContext<TItem>) => ActionOutcome | void | Promise<ActionOutcome | void>;
+};
+
+/** The registry shape sent to the host in the initialize response (no `execute`). */
+export type ActionManifestEntry = {
+  id: string;
+  title: LocalizedText;
+  description?: LocalizedText;
+  hotkey?: Hotkey;
+};
+
+export function toActionManifest(definition: ActionDefinition): ActionManifestEntry {
+  const entry: ActionManifestEntry = {
+    id: definition.id,
+    title: definition.title,
+  };
+  if (definition.description) entry.description = definition.description;
+  if (definition.hotkey) entry.hotkey = definition.hotkey;
+  return entry;
+}

package/src/bootstrap.ts

@@ -1,70 +1,159 @@
-/**
- * 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.
- *
- * 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.
- */
-
-import readline from "node:readline/promises";
-import { NodeTransport } from "./transport.ts";
-import { HandlerRouter } from "./router.ts";
-import type { Envelope } from "./protocol.ts";
-
-export interface PluginHandlers {
-  [route: string]: (payload: any) => Promise<any> | any;
-}
-
-export interface PluginRuntime {
-  transport: NodeTransport;
-  router: HandlerRouter;
-  close(): Promise<void>;
-}
-
-/**
- * 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.
- */
-export async function runPlugin(handlers: PluginHandlers): Promise<PluginRuntime> {
-  const { pipePath, token } = await readBootstrapLine();
-
-  const transport = new NodeTransport();
-  await transport.connect(pipePath);
-
-  const router = new HandlerRouter({ send: (env: Envelope) => transport.send(env) });
-
-  // Inbound envelopes from the host arrive on the transport.
-  transport.onMessage((env) => {
-    router.dispatch(env);
-  });
-
-  for (const [route, handler] of Object.entries(handlers)) {
-    router.handle(route, handler);
-  }
-
-  return {
-    transport,
-    router,
-    close: () => transport.close(),
-  };
-}
-
-/** Reads line 1 of stdin: "<pipePath>\t<token>". */
-async function readBootstrapLine(): Promise<{ pipePath: string; token: string }> {
-  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
-  try {
-    const line = await new Promise<string>((resolve, reject) => {
-      rl.once("line", (l) => resolve(l));
-      rl.once("close", () => reject(new Error("stdin closed before bootstrap line")));
-    });
-    const [pipePath, token] = line.split("\t");
-    if (!pipePath || !token) {
-      throw new Error(`malformed bootstrap line: ${JSON.stringify(line)}`);
-    }
-    return { pipePath, token };
-  } finally {
-    rl.close();
-  }
-}
+/**
+ * v3 Node SDK bootstrap entry. Reads the bootstrap line from stdin (pipePath\ttoken), connects to
+ * 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
+ * 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,
+  EndpointIds,
+  MessageKind,
+  ProtocolVersion,
+  Routes,
+} from "./protocol.ts";
+
+export interface PluginHandlers {
+  [route: string]: (payload: any, context: { sessionId: string }) => Promise<any> | any;
+}
+
+export interface PluginRuntime {
+  transport: NodeTransport;
+  router: HandlerRouter;
+  close(): Promise<void>;
+}
+
+const SUPPORTED_VERSIONS = [ProtocolVersion];
+
+/**
+ * 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();
+
+  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);
+  });
+
+  transport.onMessage((env) => {
+    if (env.route === Routes.Bus.Ping) lastPingAt = Date.now();
+    router.dispatch(env);
+  });
+
+  for (const [route, handler] of Object.entries(handlers)) {
+    router.handle(route, handler);
+  }
+
+  return {
+    transport,
+    router,
+    close: async () => {
+      clearInterval(watchdog);
+      await transport.close();
+    },
+  };
+}
+
+/** Reads line 1 of stdin: "<pipePath>\t<token>". */
+async function readBootstrapLine(): Promise<{ pipePath: string; token: string }> {
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  try {
+    const line = await new Promise<string>((resolve, reject) => {
+      rl.once("line", (l) => resolve(l));
+      rl.once("close", () => reject(new Error("stdin closed before bootstrap line")));
+    });
+    const [pipePath, token] = line.split("\t");
+    if (!pipePath || !token) {
+      throw new Error(`malformed bootstrap line: ${JSON.stringify(line)}`);
+    }
+    return { pipePath, token };
+  } finally {
+    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/dev.ts

@@ -0,0 +1,14 @@
+/**
+ * Development-time helpers for MyTools plugins.
+ *
+ * This entry point is intended for build and watch scripts, not plugin runtime code.
+ */
+import { requestDevelopmentPluginRefreshWithOptions } from "./developmentRefresh.ts";
+
+/**
+ * Notifies a running MyTools instance that a development plugin was rebuilt.
+ * The request is retried once after a short delay when the pipe is not yet available.
+ */
+export function requestDevelopmentPluginRefresh(pluginId: string): Promise<void> {
+  return requestDevelopmentPluginRefreshWithOptions(pluginId);
+}

package/src/developmentRefresh.ts

@@ -0,0 +1,95 @@
+import { createConnection } from "node:net";
+
+export const DEVELOPMENT_REFRESH_PIPE_PATH = "\\\\.\\pipe\\MyTools.DevelopmentPlugins.Refresh";
+
+const DEFAULT_RETRY_DELAY_MS = 250;
+const DEFAULT_MAX_ATTEMPTS = 2;
+const DEFAULT_REQUEST_TIMEOUT_MS = 2_000;
+const VALID_PLUGIN_ID = /^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$/;
+
+export type DevelopmentRefreshRequestOptions = {
+  pipePath?: string;
+  retryDelayMs?: number;
+  maxAttempts?: number;
+  requestTimeoutMs?: number;
+};
+
+/** Internal implementation with injectable timing and endpoint for protocol tests. */
+export async function requestDevelopmentPluginRefreshWithOptions(
+  pluginId: string,
+  options: DevelopmentRefreshRequestOptions = {},
+): Promise<void> {
+  if (!VALID_PLUGIN_ID.test(pluginId)) {
+    throw new TypeError(`Invalid MyTools plugin ID: ${pluginId}`);
+  }
+
+  const pipePath = options.pipePath ?? DEVELOPMENT_REFRESH_PIPE_PATH;
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError("maxAttempts must be a positive integer");
+  }
+  if (!Number.isFinite(retryDelayMs) || retryDelayMs < 0) {
+    throw new RangeError("retryDelayMs must be a non-negative number");
+  }
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+    throw new RangeError("requestTimeoutMs must be a positive number");
+  }
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      await sendRefreshRequest(pipePath, pluginId, requestTimeoutMs);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxAttempts) {
+        await delay(retryDelayMs);
+      }
+    }
+  }
+
+  throw new Error(
+    `Failed to request MyTools refresh for ${pluginId} after ${maxAttempts} attempts`,
+    { cause: lastError },
+  );
+}
+
+function sendRefreshRequest(
+  pipePath: string,
+  pluginId: string,
+  requestTimeoutMs: number,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(pipePath);
+    let settled = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+
+    const settle = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve();
+    };
+
+    socket.once("connect", () => {
+      socket.end(`${pluginId}\n`, () => {
+        settle();
+      });
+    });
+    socket.once("error", (error) => {
+      socket.destroy();
+      settle(error);
+    });
+    timeout = setTimeout(() => {
+      socket.destroy();
+      settle(new Error(`Development refresh request timed out after ${requestTimeoutMs}ms`));
+    }, requestTimeoutMs);
+  });
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/src/hostEnv.ts

@@ -0,0 +1,21 @@
+/** Environment the host stamps onto every plugin.call payload. */
+
+export type PluginTheme = "light" | "dark";
+
+export type PluginHostEnv = {
+  locale: string;
+  fallbackLocale: string;
+  theme: PluginTheme;
+};
+
+export function asTheme(value: unknown): PluginTheme {
+  return value === "light" ? "light" : "dark";
+}
+
+export function asHostEnv(payload: any): PluginHostEnv {
+  return {
+    locale: typeof payload?.locale === "string" ? payload.locale : "en-US",
+    fallbackLocale: typeof payload?.fallbackLocale === "string" ? payload.fallbackLocale : "en-US",
+    theme: asTheme(payload?.theme),
+  };
+}