@kb-labs/adapters 0.5.0

package/packages/adapters-transport/README.md

@@ -0,0 +1,170 @@
+# @kb-labs/adapters-transport
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+Transport layer for inter-process communication between parent and child processes. Supports IPC and Unix Sockets.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `ITransport` |
+| **Type** | Infrastructure |
+| **Requires** | None |
+| **Category** | IPC / Networking |
+
+## Features
+
+- **Multiple Transports** - IPC, Unix Sockets, or auto-select
+- **Serialization** - Handle Buffer, Date, Error, and complex objects
+- **Auto-Reconnect** - Automatic reconnection for Unix sockets
+- **Timeout Support** - Configurable request timeouts
+- **Protocol Versioning** - Backward-compatible protocol
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-transport
+```
+
+## Configuration
+
+### Auto Mode (Recommended)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-transport';
+
+// Auto-select best transport (Unix Socket with IPC fallback)
+const transport = createAdapter({ type: 'auto' });
+```
+
+### IPC Transport
+
+```typescript
+// Force IPC (legacy compatibility)
+const transport = createAdapter({
+  type: 'ipc',
+  timeout: 30000
+});
+```
+
+### Unix Socket Transport
+
+```typescript
+// Force Unix Socket (max performance)
+const transport = createAdapter({
+  type: 'unix-socket',
+  socketPath: '/tmp/kb-ipc.sock',
+  timeout: 30000,
+  autoReconnect: true
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `'ipc' \| 'unix-socket' \| 'auto'` | - | Transport type |
+| `socketPath` | `string` | `'/tmp/kb-ipc.sock'` | Unix socket path |
+| `timeout` | `number` | `30000` | Request timeout in ms |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect (Unix socket only) |
+
+## Usage
+
+### Sending Adapter Calls
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-transport';
+import type { AdapterCall, AdapterResponse } from '@kb-labs/adapters-transport';
+
+const transport = createAdapter({ type: 'auto' });
+
+// Connect
+await transport.connect();
+
+// Send call
+const call: AdapterCall = {
+  version: 2,
+  type: 'adapter:call',
+  requestId: 'req-123',
+  adapter: 'cache',
+  method: 'get',
+  args: ['key'],
+  timeout: 5000
+};
+
+const response: AdapterResponse = await transport.send(call);
+
+// Disconnect
+await transport.disconnect();
+```
+
+### Unix Socket Server
+
+```typescript
+import { UnixSocketServer } from '@kb-labs/adapters-transport';
+
+const server = new UnixSocketServer({
+  socketPath: '/tmp/kb-ipc.sock'
+});
+
+server.on('call', async (call, respond) => {
+  // Handle adapter call
+  const result = await processCall(call);
+  respond({ type: 'adapter:response', requestId: call.requestId, result });
+});
+
+await server.start();
+```
+
+## Serializable Types
+
+The transport layer handles special types:
+
+```typescript
+// Buffer
+{ __type: 'Buffer', data: 'base64-encoded' }
+
+// Date
+{ __type: 'Date', iso: '2024-01-01T00:00:00.000Z' }
+
+// Error
+{ __type: 'Error', name: 'Error', message: 'Something failed', stack: '...' }
+```
+
+## Transport Comparison
+
+| Feature | IPC | Unix Socket |
+|---------|-----|-------------|
+| **Performance** | Good | Better |
+| **Streaming** | Limited | Full support |
+| **Cross-process** | Child only | Any process |
+| **Reconnection** | No | Yes |
+| **Platform** | All | Unix/macOS |
+
+## FAQ
+
+<details>
+<summary><strong>Q: When should I use IPC vs Unix Socket?</strong></summary>
+
+- Use **IPC** when spawning child processes with `child_process.fork()`
+- Use **Unix Socket** for daemon processes or higher throughput
+- Use **auto** to let the system choose the best option
+</details>
+
+<details>
+<summary><strong>Q: What happens if the server disconnects?</strong></summary>
+
+With `autoReconnect: true`, Unix Socket transport will automatically reconnect when the server becomes available again.
+</details>
+
+## Related Packages
+
+| Package | Use Case |
+|---------|----------|
+| `@kb-labs/core-runtime` | Uses transport for plugin sandbox IPC |
+| `@kb-labs/plugin-execution` | Plugin execution with transport layer |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-transport/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-transport/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kb-labs/adapters-transport",
+  "version": "0.5.0",
+  "description": "Transport adapters for inter-process communication (IPC, Unix Sockets)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@kb-labs/core-runtime": "link:../../../../platform/kb-labs-core/packages/core-runtime"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "keywords": [
+    "kb-labs",
+    "transport",
+    "ipc",
+    "unix-socket"
+  ],
+  "author": "KB Labs",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}