@qping/plugin-bus 0.2.0 → 0.4.0

package/dist/actions.d.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 declare const Key: {
+    readonly Enter: "Enter";
+    readonly Tab: "Tab";
+    readonly Space: "Space";
+    readonly Delete: "Delete";
+    readonly Backspace: "Backspace";
+    readonly Escape: "Escape";
+    readonly Left: "Left";
+    readonly Right: "Right";
+    readonly Up: "Up";
+    readonly Down: "Down";
+    readonly A: "A";
+    readonly B: "B";
+    readonly C: "C";
+    readonly D: "D";
+    readonly E: "E";
+    readonly F: "F";
+    readonly G: "G";
+    readonly H: "H";
+    readonly I: "I";
+    readonly J: "J";
+    readonly K: "K";
+    readonly L: "L";
+    readonly M: "M";
+    readonly N: "N";
+    readonly O: "O";
+    readonly P: "P";
+    readonly Q: "Q";
+    readonly R: "R";
+    readonly S: "S";
+    readonly T: "T";
+    readonly U: "U";
+    readonly V: "V";
+    readonly W: "W";
+    readonly X: "X";
+    readonly Y: "Y";
+    readonly Z: "Z";
+    readonly D0: "D0";
+    readonly D1: "D1";
+    readonly D2: "D2";
+    readonly D3: "D3";
+    readonly D4: "D4";
+    readonly D5: "D5";
+    readonly D6: "D6";
+    readonly D7: "D7";
+    readonly D8: "D8";
+    readonly D9: "D9";
+    readonly F1: "F1";
+    readonly F2: "F2";
+    readonly F3: "F3";
+    readonly F4: "F4";
+    readonly F5: "F5";
+    readonly F6: "F6";
+    readonly F7: "F7";
+    readonly F8: "F8";
+    readonly F9: "F9";
+    readonly F10: "F10";
+    readonly F11: "F11";
+    readonly F12: "F12";
+};
+export type HotkeyKey = (typeof Key)[keyof typeof Key];
+/** Permitted modifier combinations, e.g. `Modifiers.ControlShift`. */
+export declare const Modifiers: {
+    readonly None: 0;
+    readonly Control: 1;
+    readonly Alt: 2;
+    readonly ControlAlt: 3;
+    readonly Shift: 4;
+    readonly ControlShift: 5;
+    readonly AltShift: 6;
+    readonly ControlAltShift: 7;
+};
+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 declare const HostAction: {
+    readonly Copy: "copy";
+    readonly CopyAndPaste: "copyAndPaste";
+    readonly AddClipboardHistory: "addClipboardHistory";
+    readonly Execute: "execute";
+    readonly OpenInExplorer: "openInExplorer";
+    readonly OpenInBrowser: "openInBrowser";
+    readonly OpenPlugin: "openPlugin";
+    readonly Run: "run";
+    readonly Kill: "kill";
+};
+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 declare function toActionManifest(definition: ActionDefinition): ActionManifestEntry;
+export {};

package/dist/bootstrap.d.ts

@@ -10,7 +10,9 @@
 import { NodeTransport } from "./transport.ts";
 import { HandlerRouter } from "./router.ts";
 export interface PluginHandlers {
-    [route: string]: (payload: any) => Promise<any> | any;
+    [route: string]: (payload: any, context: {
+        sessionId: string;
+    }) => Promise<any> | any;
 }
 export interface PluginRuntime {
     transport: NodeTransport;

package/dist/bootstrap.mjs

@@ -167,6 +167,7 @@ var Routes = {
     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"
@@ -330,7 +331,10 @@ var HandlerRouter = class {
     }
     const deadlineMs = deadlineFromTimeoutMs(env.timeoutMs);
     try {
-      const result = await requestScope.run({ deadlineMs }, () => handler(env.payload));
+      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);

package/dist/dev.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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 declare function requestDevelopmentPluginRefresh(pluginId: string): Promise<void>;

package/dist/dev.mjs

@@ -0,0 +1,80 @@
+// src/developmentRefresh.ts
+import { createConnection } from "node:net";
+var DEVELOPMENT_REFRESH_PIPE_PATH = "\\\\.\\pipe\\MyTools.DevelopmentPlugins.Refresh";
+var DEFAULT_RETRY_DELAY_MS = 250;
+var DEFAULT_MAX_ATTEMPTS = 2;
+var DEFAULT_REQUEST_TIMEOUT_MS = 2e3;
+var VALID_PLUGIN_ID = /^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$/;
+async function requestDevelopmentPluginRefreshWithOptions(pluginId, options = {}) {
+  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;
+  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, pluginId, requestTimeoutMs) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(pipePath);
+    let settled = false;
+    let timeout;
+    const settle = (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve();
+    };
+    socket.once("connect", () => {
+      socket.end(`${pluginId}
+`, () => {
+        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) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+// src/dev.ts
+function requestDevelopmentPluginRefresh(pluginId) {
+  return requestDevelopmentPluginRefreshWithOptions(pluginId);
+}
+export {
+  requestDevelopmentPluginRefresh
+};

package/dist/developmentRefresh.d.ts

@@ -0,0 +1,9 @@
+export declare const DEVELOPMENT_REFRESH_PIPE_PATH = "\\\\.\\pipe\\MyTools.DevelopmentPlugins.Refresh";
+export type DevelopmentRefreshRequestOptions = {
+    pipePath?: string;
+    retryDelayMs?: number;
+    maxAttempts?: number;
+    requestTimeoutMs?: number;
+};
+/** Internal implementation with injectable timing and endpoint for protocol tests. */
+export declare function requestDevelopmentPluginRefreshWithOptions(pluginId: string, options?: DevelopmentRefreshRequestOptions): Promise<void>;

package/dist/hostEnv.d.ts

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

package/dist/hotkeyKeycaps.d.ts

@@ -0,0 +1,2 @@
+/** Render a host-formatted shortcut as the same sequence of keycaps used by the desktop action bar. */
+export declare function renderHotkeyKeycaps(element: HTMLElement, hotkey: string): void;

package/dist/node.d.ts

@@ -4,17 +4,15 @@
  * Method names map to v3 routes:
  *   initialize -> plugin.call.initialize
  *   search     -> plugin.call.search
- *   action     -> plugin.call.invokeAction
+ *   actions    -> plugin.call.invokeAction (dispatched by action id)
  *   handle(name) -> plugin.call.<name>
  *   publish    -> plugin.event.<subjectId>
  *   hostCall   -> host.call.<method>
  */
-export type PluginTheme = "light" | "dark";
-export type PluginHostEnv = {
-    locale: string;
-    fallbackLocale: string;
-    theme: PluginTheme;
-};
+import { type PluginHostEnv } from "./hostEnv.ts";
+import { type ActionDefinition } from "./actions.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;
@@ -29,21 +27,40 @@ export type PluginSearchParams = PluginHostEnv & {
     query: string;
     mode: "global" | "plugin";
 };
-/** Payload of plugin.call.invokeAction. */
-export type PluginActionParams = PluginHostEnv & {
-    itemId: string;
-    actionId: string;
-    query: string;
+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[];
 };
 type PluginInitializeHandler = (params: PluginInitializeParams) => unknown | Promise<unknown>;
-type PluginSearchHandler = (params: PluginSearchParams) => unknown | Promise<unknown>;
-type PluginActionHandler = (params: PluginActionParams) => unknown | Promise<unknown>;
+type PluginSearchHandler = (params: PluginSearchParams) => SearchResult | Promise<SearchResult>;
 type PluginHandler = (payload: any, context: PluginContext) => unknown | Promise<unknown>;
 export declare class Plugin {
     #private;
     initialize(handler: PluginInitializeHandler): this;
     search(handler: PluginSearchHandler): this;
-    action(handler: PluginActionHandler): 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;
     handle(action: string, handler: PluginHandler): this;
     /** Publishes a plugin.event.<subjectId> event to all webviews in the session. */
     publish(subjectId: string, payload?: unknown): void;
@@ -58,8 +75,9 @@ export declare class Plugin {
      * 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>>;
+    buildRoutes(): Record<string, (payload: any, context?: {
+        sessionId: string;
+    }) => unknown | Promise<unknown>>;
     stop(): Promise<void>;
 }
 export declare function createPlugin(): Plugin;
-export {};