@isdk/tool-electron 1.0.0

package/docs/README.md

@@ -0,0 +1,465 @@
+**@isdk/tool-electron**
+
+***
+
+# @isdk/tool-electron
+
+> ✨ **Electron-native IPC Transport for the `ToolFunc` Framework**
+> Build decoupled, type-safe, real-time Electron apps with RPC tools and Pub/Sub events over IPC.
+
+[🇨🇳 中文文档](_media/README.cn.md) | 🌐 English
+
+[![npm version](https://img.shields.io/npm/v/@isdk/tool-electron.svg?style=flat-square)](https://www.npmjs.com/package/@isdk/tool-electron)
+[![Vitest Tests](https://img.shields.io/badge/tests-vitest-green?style=flat-square)](https://vitest.dev/)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-purple?style=flat-square)](LICENSE)
+
+```bash
+npm install @isdk/tool-electron
+```
+
+Built on [`@isdk/tool-func`](https://github.com/isdk/ai-tools) — Define reusable, self-documenting functions.
+
+## 🌟 Features
+
+Designed to pair with `@isdk/tool-rpc` / `@isdk/tool-event`. Define your business logic once as tools, then call them from the renderer like local methods — no HTTP required.
+
+* ✅ **Zero network overhead** — uses Electron IPC
+* ✅ **RPC Tools over IPC** — Call server-defined functions from renderer
+* ✅ **Real-time Event Bus** — Bidirectional Pub/Sub with auto session management
+* ✅ **Unified error model** via `@isdk/common-error`
+* ✅ **AbortSignal support** — cancel waiting on the client
+* ✅ **Safe Preload Bridge** — Securely expose APIs via `contextBridge` with injectable `Bridge`, `ServerIpcMain`, `PubSubBridge`, and `ServerPubSubIpcMain` types
+* ✅ **Dynamic Namespaces** — Run multiple isolated tool/event buses via URI scheme (`electron://my-app`)
+* ✅ **URI Scheme Routing** — `apiUrl` follows URI convention; `electron://` routes to IPC, `http://` routes to HTTP; auto-registered with `RpcTransportManager`
+
+---
+
+## 🔒 Secure Bridge Pattern
+
+When `contextIsolation` is enabled (the default since Electron 12), the renderer process has no direct access to Node.js or Electron APIs. The recommended approach is to:
+
+1. **Preload** — Expose a minimal `invoke`-only bridge via `contextBridge`
+2. **Main process** — Optionally inject a custom `ipcMain`-like object for testing or custom setups
+3. **Renderer** — Create transport instances with the injected bridge
+
+### 1. Main Process (Server)
+
+```ts
+// main.ts
+import { ServerTools } from '@isdk/tool-rpc';
+import { EventServer } from '@isdk/tool-event';
+import {
+  IpcServerToolTransport,
+  ElectronServerPubSubTransport,
+} from '@isdk/tool-electron';
+
+// Register a tool
+ServerTools.register({
+  name: 'getUser',
+  func: async ({ id }: { id: string }) => ({ id, name: 'Alice' }),
+});
+
+// Mount RPC with the URI 'electron://my-app'
+const server = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+server.addDiscoveryHandler('electron://my-app', () => ServerTools.toJSON());
+server.addRpcHandler('electron://my-app');
+await server.start();
+
+// Setup event bus
+EventServer.setPubSubTransport(
+  new ElectronServerPubSubTransport('my-app-events'),
+);
+EventServer.get()?.register();
+```
+
+> **Testing tip:** Pass a mock `ipcMain` object via the `ipcMain` option:
+>
+> ```ts
+> import { IpcServerToolTransport } from '@isdk/tool-electron';
+> const server = new IpcServerToolTransport({
+>   apiUrl: 'electron://test',
+>   // Works with any test framework — wrap with vi.fn() / jest.fn() / sinon.spy() as needed
+>   ipcMain: { handle: () => {}, removeHandler: () => {} },
+> });
+> ```
+
+---
+
+### 2. Preload Script (Secure Bridge)
+
+The preload script is the **only** place with access to `ipcRenderer`. Expose only what's needed:
+
+```ts
+// preload.ts
+import { contextBridge, ipcRenderer } from 'electron';
+
+// Expose a minimal invoke bridge to the renderer
+export type ElectronIpcBridge = {
+  invoke: (channel: string, ...args: any[]) => Promise<any>;
+};
+
+contextBridge.exposeInMainWorld('electronIpc', {
+  invoke: (channel: string, ...args: any[]) =>
+    ipcRenderer.invoke(channel, ...args),
+} satisfies ElectronIpcBridge);
+```
+
+---
+
+### 3. Renderer Process (Client)
+
+In the renderer, create the transport using the bridge exposed by the preload:
+
+```ts
+// renderer.ts
+import {
+  IpcClientToolTransport,
+  type Bridge,
+} from '@isdk/tool-electron';
+
+// The bridge exposed by preload.ts
+const bridge: Bridge = (window as any).electronIpc;
+
+// Create the transport with the injectable bridge
+const transport = new IpcClientToolTransport('electron://my-app', { bridge });
+
+// Mount and load tool definitions
+await transport.loadApis();
+
+// Call a remote tool
+const result = await transport._fetch('getUser', { id: '42' });
+console.log(result); // { id: '42', name: 'Alice' }
+```
+
+---
+
+### ⚡ Full Preload + Pub/Sub Example
+
+Here's a complete end-to-end example showing both RPC and Pub/Sub with the injectable bridge types:
+
+**main.ts (server)**
+
+```ts
+import { ServerTools } from '@isdk/tool-rpc';
+import {
+  IpcServerToolTransport,
+  ElectronServerPubSubTransport,
+} from '@isdk/tool-electron';
+
+// Register a tool
+ServerTools.register({
+  name: 'getUser',
+  func: async ({ id }: { id: string }) => ({ id, name: 'Alice' }),
+});
+
+// RPC transport
+const rpcServer = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+rpcServer.addDiscoveryHandler('electron://my-app', () => ServerTools.toJSON());
+rpcServer.addRpcHandler('electron://my-app');
+await rpcServer.start();
+
+// Pub/Sub transport
+const pubSubServer = new ElectronServerPubSubTransport('electron://my-app-events');
+pubSubServer.listen();
+
+// 💡 Testing: inject a mock ipcMain via ServerPubSubIpcMain
+// import type { ServerPubSubIpcMain } from '@isdk/tool-electron';
+// const mockIpcMain: ServerPubSubIpcMain = {
+//   on: () => {},
+//   removeAllListeners: () => {},
+// };
+// const pubSubServer = new ElectronServerPubSubTransport('electron://test', { ipcMain: mockIpcMain });
+```
+
+**preload.ts**
+
+```ts
+import { contextBridge, ipcRenderer } from 'electron';
+
+const electronIpc = {
+  invoke: (ch: string, ...args: any[]) => ipcRenderer.invoke(ch, ...args),
+  on: (ch: string, listener: (event: any, ...args: any[]) => void) => {
+    ipcRenderer.on(ch, listener);
+  },
+  off: (ch: string, listener: (event: any, ...args: any[]) => void) => {
+    ipcRenderer.removeListener(ch, listener);
+  },
+  send: (ch: string, ...args: any[]) => ipcRenderer.send(ch, ...args),
+};
+
+contextBridge.exposeInMainWorld('electronIpc', electronIpc);
+```
+
+**renderer.ts**
+
+```ts
+import {
+  IpcClientToolTransport,
+  ElectronClientPubSubTransport,
+  type Bridge,
+  type PubSubBridge,
+} from '@isdk/tool-electron';
+
+const bridge: Bridge = (window as any).electronIpc;
+const pubsubBridge: PubSubBridge = (window as any).electronIpc;
+
+// Create RPC transport
+const rpc = new IpcClientToolTransport('electron://my-app', { bridge });
+await rpc.loadApis();
+
+// Create Pub/Sub transport with the same bridge
+const pubsub = new ElectronClientPubSubTransport('electron://my-app-events', {
+  bridge: pubsubBridge,
+});
+const stream = pubsub.connect('electron://my-app-events');
+
+stream.on('server-event', (data) => {
+  console.log('Received:', data);
+});
+```
+
+---
+
+## 🚀 Quick Start (Simple Setup)
+
+If you don't need `contextIsolation` or want a minimal setup:
+
+### 1. Main Process
+
+```ts
+// main.ts
+import { ServerTools } from '@isdk/tool-rpc';
+import {
+  IpcServerToolTransport,
+} from '@isdk/tool-electron';
+
+ServerTools.register({
+  name: 'greet',
+  func: async ({ name }: { name: string }) => `Hello, ${name}!`,
+});
+
+const server = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+server.addDiscoveryHandler('electron://my-app', () => ServerTools.toJSON());
+server.addRpcHandler('electron://my-app');
+await server.start();
+```
+
+### 2. Preload Script
+
+Use the same preload script as the [Secure Bridge Pattern](#2-preload-script-secure-bridge) above:
+
+```ts
+// preload.ts — same as the Secure Bridge Pattern example
+import { contextBridge, ipcRenderer } from 'electron';
+
+contextBridge.exposeInMainWorld('electronIpc', {
+  invoke: (ch: string, ...args: any[]) => ipcRenderer.invoke(ch, ...args),
+});
+```
+
+### 3. Renderer Process
+
+```ts
+// renderer.ts
+import { IpcClientToolTransport } from '@isdk/tool-electron';
+
+const transport = new IpcClientToolTransport('electron://my-app', {
+  bridge: (window as any).electronIpc,
+});
+const defs = await transport.loadApis();
+const result = await transport._fetch('greet', { name: 'World' });
+console.log(result); // "Hello, World!"
+```
+
+---
+
+## 🔄 Architecture
+
+```mermaid
+graph LR
+    subgraph "Main Process"
+        A[ServerTools] --> B[IpcServer]
+        C[EventServer] --> D[PubSub Server]
+        B -->|ipcMain.handle| E[(IPC Channel)]
+        D -->|ipcMain.on/send| E
+    end
+
+    subgraph "Preload (contextBridge)"
+        P["electronIpc.invoke"] -->|ipcRenderer.invoke| E
+    end
+
+    subgraph "Renderer Process"
+        F[IpcClientToolTransport] -->|bridge.invoke| P
+        G[ElectronClientPubSubTransport] -->|ipcRenderer.on/send| E
+    end
+```
+
+The preload script acts as a security boundary — the renderer never imports `electron` directly.
+
+---
+
+## ⚙️ Advanced
+
+### Custom ServerIpcMain (Testing / Custom IPC)
+
+Inject a mock or custom `ipcMain`-like object for testing:
+
+```ts
+import { IpcServerToolTransport, type ServerIpcMain } from '@isdk/tool-electron';
+
+// Plain no-op mocks — wrap with vitest/jest/sinon spies for assertions
+const mockIpcMain: ServerIpcMain = {
+  handle: (_channel, _handler) => {},
+  removeHandler: (_channel) => {},
+};
+
+const server = new IpcServerToolTransport({
+  apiUrl: 'electron://test',
+  ipcMain: mockIpcMain,
+});
+```
+
+### Error Handling
+
+`_fetch` throws a `CommonError` directly when the server returns an error response. No need to call `toObject()` first — errors are thrown immediately:
+
+```ts
+import { CommonError } from '@isdk/common-error';
+
+try {
+  const result = await transport._fetch('getUser', { id: 'invalid' });
+} catch (err: any) {
+  if (err instanceof CommonError) {
+    console.error(`Error [${err.code}]: ${err.message}`, err.data);
+  }
+}
+```
+
+> **Note:** The `toObject()` method is still available for backward compatibility, but when used on a successful response it simply passes the data through. For new code, just use `await transport._fetch(...)` directly.
+
+### Timeout & Cancellation
+
+```ts
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 5000);
+
+try {
+  const result = await transport._fetch('slowTool', params, undefined, undefined, {
+    signal: ctrl.signal,
+  });
+} catch (err: any) {
+  if (err.name === 'AbortError') {
+    console.log('Cancelled or timed out');
+  }
+}
+```
+
+### Dynamic Namespaces
+
+```ts
+// Switch to a different namespace at runtime
+transport.setApiUrl('electron://my-app-v2');
+await transport.loadApis();
+```
+
+---
+
+## 📦 API
+
+### API URL Convention
+
+All IPC transports use URI-formatted `apiUrl` values with the `electron://` scheme:
+
+```ts
+// Server: options object
+const server = new IpcServerToolTransport({ apiUrl: 'electron://my-app' });
+
+// Client: first argument
+const client = new IpcClientToolTransport('electron://my-app', { bridge });
+
+// PubSub: constructor argument
+const pubsub = new ElectronServerPubSubTransport('electron://my-app');
+```
+
+The `electron` scheme is auto-registered with `RpcTransportManager` on import,
+so `RpcTransportManager.instance.getClient('electron://my-app')` works automatically.
+The host component is extracted as the IPC channel namespace:
+`'electron://my-app'` → channels `my-app:discover`, `pubsub-downstream:my-app`, etc.
+
+### Exported Types (Bridge Pattern)
+
+| Type | Description | Methods | Used By |
+|------|-------------|---------|---------|
+| `Bridge` | Client-side RPC bridge. Inject into `IpcClientToolTransport`. | `invoke(channel, ...args): Promise<any>` | `IpcClientToolTransport` |
+| `ServerIpcMain` | Server-side RPC bridge. Inject into `IpcServerToolTransport`. | `handle(channel, handler)`, `removeHandler(channel)` | `IpcServerToolTransport` |
+| `PubSubBridge` | Client-side Pub/Sub bridge. Inject into `ElectronClientPubSubTransport`. | `on(channel, listener)`, `off(channel, listener)`, `send(channel, ...args)` | `ElectronClientPubSubTransport` |
+| `ServerPubSubIpcMain` | Server-side Pub/Sub bridge. Inject into `ElectronServerPubSubTransport`. | `on(channel, listener)`, `removeAllListeners(channel?)` | `ElectronServerPubSubTransport` |
+
+All four types are exported from the package root:
+
+```ts
+import {
+  type Bridge,
+  type ServerIpcMain,
+  type PubSubBridge,
+  type ServerPubSubIpcMain,
+} from '@isdk/tool-electron';
+```
+
+### Exported Classes
+
+| Class | Process | Purpose |
+|-------|---------|---------|
+| `IpcClientToolTransport` | Renderer | RPC transport for calling server tools |
+| `IpcServerToolTransport` | Main | RPC transport for registering and serving tools |
+| `ElectronClientPubSubTransport` | Renderer | Pub/Sub transport for receiving/sending events |
+| `ElectronServerPubSubTransport` | Main | Pub/Sub transport for broadcasting events |
+| `ServerTools` | Main | Tool registry (re-exported from `@isdk/tool-rpc`) |
+| `EventServer` | Main | Event server (re-exported from `@isdk/tool-event`) |
+
+---
+
+## 🧪 Testing
+
+Run unit tests with mocked Electron IPC:
+
+```bash
+npm test           # run once
+npm run test:watch # dev mode
+npm run coverage   # generate report
+```
+
+Mocks: `test/mocks/electron.ts`
+
+---
+
+## 📚 Docs
+
+- [ToolFunc Core](https://github.com/isdk/ai-tools/tree/main/packages/tool-func)
+- [RPC Transports Guide](https://github.com/isdk/ai-tools/tree/main/packages/tool-rpc)
+- [Events Guide](https://github.com/isdk/ai-tools/tree/main/packages/tool-event)
+
+---
+
+## 🤝 Contributing
+
+We ❤️ contributions!
+
+1. Fork → `git clone`
+2. Create branch → `git checkout -b feat/your-feature`
+3. Commit → `git commit -m 'feat: add XYZ'`
+4. Push → `git push origin feat/your-feature`
+5. Open PR 🎉
+
+Please ensure tests pass and types are clean.
+
+---
+
+## 📜 License
+
+MIT © [ISDK](https://github.com/isdk) — See [LICENSE](LICENSE)
+
+---
+
+> 💡 **Pro Tip**: Use `EventServer.forward([...events])` to auto-relay global events to all connected clients!