@qping/plugin-bus 0.2.0 → 0.4.0

package/src/actions.ts

@@ -0,0 +1,164 @@
+/**
+ * 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;
+};
+
+export type ActionTarget =
+  /** Run one privileged host-side action (clipboard, process launch, browser, ...). */
+  | { kind: "host"; action: HostActionRequest }
+  /** Hand off to the currently active detail page as host.event.detailAction. */
+  | { kind: "web"; payload?: unknown }
+  /** Open a new web detail page. */
+  | ({ kind: "detail" } & DetailRequest);
+
+export type ActionAfter = "keep" | "close" | "refresh";
+
+type ActionOutcomeBase = {
+  /** Status bar text. */
+  message?: LocalizedText;
+};
+
+/**
+ * The result of running an action. An action selects at most one execution target. Host targets
+ * may choose a follow-up lifecycle action; web and detail targets keep their current surface alive.
+ */
+export type ActionOutcome = ActionOutcomeBase & (
+  | { target?: undefined; after?: ActionAfter }
+  | { target: Extract<ActionTarget, { kind: "host" }>; after?: ActionAfter }
+  | { target: Exclude<ActionTarget, { kind: "host" }>; after?: "keep" }
+);
+
+/**
+ * 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,159 +1,159 @@
-/**
- * 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) => 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);
-  });
-}
+/**
+ * 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),
+  };
+}

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;
+}