@kb-labs/adapters 0.5.0

package/packages/adapters-eventbus-cache/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * @module @kb-labs/adapters-eventbus-cache
+ * EventBus adapter using ICache for persistent event storage.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-eventbus-cache';
+ * import { MemoryCache } from '@kb-labs/core-platform/noop';
+ *
+ * // When loaded by platform, deps are injected automatically.
+ * // For manual usage:
+ * const cache = new MemoryCache();
+ * const eventBus = createAdapter(
+ *   { pollIntervalMs: 500, eventTtlMs: 3600000 },
+ *   { cache }
+ * );
+ *
+ * // Subscribe to events
+ * const unsubscribe = eventBus.subscribe('user.created', async (event) => {
+ *   console.log('User created:', event);
+ * });
+ *
+ * // Publish event
+ * await eventBus.publish('user.created', { id: '123', name: 'Alice' });
+ *
+ * // Cleanup
+ * unsubscribe();
+ * eventBus.disconnect();
+ * ```
+ */
+
+import { randomUUID } from 'node:crypto';
+import type { IEventBus, ICache, EventHandler, Unsubscribe } from '@kb-labs/core-platform';
+import type { CacheEventBusConfig, StoredEvent, Subscription, CacheEventBusDeps } from './types.js';
+
+// Re-export manifest and types
+export { manifest } from './manifest.js';
+export type { CacheEventBusConfig, StoredEvent, CacheEventBusDeps } from './types.js';
+
+/**
+ * EventBus implementation using ICache for persistent storage.
+ *
+ * Features:
+ * - Persistent events survive restarts (if cache is persistent)
+ * - Distributed across processes (if cache is Redis)
+ * - Automatic cleanup of old events via TTL
+ * - Polling-based subscription mechanism
+ */
+export class CacheEventBusAdapter implements IEventBus {
+  private readonly cache: ICache;
+  private readonly config: Required<CacheEventBusConfig>;
+  private readonly subscriptions = new Map<string, Subscription>();
+
+  constructor(cache: ICache, config: CacheEventBusConfig = {}) {
+    this.cache = cache;
+    this.config = {
+      pollIntervalMs: config.pollIntervalMs ?? 1000,
+      eventTtlMs: config.eventTtlMs ?? 86400000, // 24 hours
+      keyPrefix: config.keyPrefix ?? 'eventbus:',
+    };
+  }
+
+  /**
+   * Publish an event to a topic.
+   * Events are stored in a sorted set with timestamp as score.
+   */
+  async publish<T>(topic: string, event: T): Promise<void> {
+    const storedEvent: StoredEvent<T> = {
+      id: randomUUID(),
+      topic,
+      data: event,
+      timestamp: Date.now(),
+    };
+
+    const key = `${this.config.keyPrefix}${topic}`;
+
+    // Add to sorted set with timestamp as score
+    await this.cache.zadd(key, storedEvent.timestamp, JSON.stringify(storedEvent));
+  }
+
+  /**
+   * Subscribe to events on a topic.
+   * Uses polling to check for new events at configurable intervals.
+   */
+  subscribe<T>(topic: string, handler: EventHandler<T>): Unsubscribe {
+    const subscriberId = randomUUID();
+    const key = `${this.config.keyPrefix}${topic}`;
+
+    const subscription: Subscription = {
+      topic,
+      handler: handler as (event: unknown) => Promise<void>,
+      timer: null,
+      subscriberId,
+      lastTimestamp: Date.now(),
+      seenIds: new Set(),
+    };
+
+    // Polling function
+    const poll = async (): Promise<void> => {
+      try {
+        const now = Date.now();
+
+        // Get events from lastTimestamp (inclusive) to catch events with same ms timestamp
+        const events = await this.cache.zrangebyscore(
+          key,
+          subscription.lastTimestamp,
+          now
+        );
+
+        let maxTimestamp = subscription.lastTimestamp;
+
+        // Process events sequentially to preserve order.
+        for (const eventJson of events) {
+          try {
+            const storedEvent = JSON.parse(eventJson) as StoredEvent<T>;
+
+            // Skip already-delivered events (dedup by ID)
+            if (subscription.seenIds.has(storedEvent.id)) {continue;}
+
+            subscription.seenIds.add(storedEvent.id);
+            await handler(storedEvent.data);
+
+            if (storedEvent.timestamp > maxTimestamp) {
+              maxTimestamp = storedEvent.timestamp;
+            }
+          } catch (err) {
+            console.error(`[CacheEventBus] Handler error for topic "${topic}":`, err);
+          }
+        }
+
+        // Advance cursor — purge seenIds for timestamps we've moved past
+        if (maxTimestamp > subscription.lastTimestamp) {
+          subscription.seenIds.clear();
+          // Re-add IDs at the new maxTimestamp boundary (they may repeat next poll)
+          for (const eventJson of events) {
+            try {
+              const ev = JSON.parse(eventJson) as StoredEvent<T>;
+              if (ev.timestamp === maxTimestamp) {
+                subscription.seenIds.add(ev.id);
+              }
+            } catch { /* ignore parse errors */ }
+          }
+          subscription.lastTimestamp = maxTimestamp;
+        }
+
+        // Cleanup old events (older than TTL)
+        await this.cleanupOldEvents(key);
+      } catch (err) {
+        console.error(`[CacheEventBus] Poll error for topic "${topic}":`, err);
+      }
+    };
+
+    // Start polling timer
+    subscription.timer = setInterval(() => void poll(), this.config.pollIntervalMs);
+    this.subscriptions.set(subscriberId, subscription);
+
+    // Return unsubscribe function
+    return () => {
+      const sub = this.subscriptions.get(subscriberId);
+      if (sub?.timer) {
+        clearInterval(sub.timer);
+      }
+      this.subscriptions.delete(subscriberId);
+    };
+  }
+
+  /**
+   * Remove events older than TTL from a topic.
+   */
+  private async cleanupOldEvents(key: string): Promise<void> {
+    const cutoff = Date.now() - this.config.eventTtlMs;
+    const oldEvents = await this.cache.zrangebyscore(key, 0, cutoff);
+
+    // Cleanup old events
+    await Promise.all(oldEvents.map(oldEvent => this.cache.zrem(key, oldEvent)));
+  }
+
+  /**
+   * Stop all subscriptions and cleanup.
+   * Call this on shutdown to prevent memory leaks.
+   */
+  disconnect(): void {
+    for (const sub of this.subscriptions.values()) {
+      if (sub.timer) {
+        clearInterval(sub.timer);
+      }
+    }
+    this.subscriptions.clear();
+  }
+
+  /**
+   * Get the number of active subscriptions (for testing/debugging).
+   */
+  get subscriptionCount(): number {
+    return this.subscriptions.size;
+  }
+}
+
+/**
+ * Factory function for adapter loading.
+ * Called by initPlatform() when loading adapters from config.
+ *
+ * @param config - EventBus configuration
+ * @param deps - Required dependencies (cache)
+ * @returns CacheEventBusAdapter instance
+ */
+export function createAdapter(
+  config: CacheEventBusConfig = {},
+  deps: CacheEventBusDeps,
+): CacheEventBusAdapter {
+  return new CacheEventBusAdapter(deps.cache, config);
+}
+
+// Default export for direct import
+export default createAdapter;

package/packages/adapters-eventbus-cache/src/manifest.ts

@@ -0,0 +1,50 @@
+/**
+ * @module @kb-labs/adapters-eventbus-cache/manifest
+ * Adapter manifest for Cache-backed EventBus.
+ */
+
+import type { AdapterManifest } from '@kb-labs/core-platform';
+
+/**
+ * Adapter manifest for Cache-backed EventBus.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: '1.0.0',
+  id: 'eventbus-cache',
+  name: 'Cache-backed EventBus',
+  version: '1.0.0',
+  description: 'EventBus using ICache for persistent event storage with polling-based subscriptions',
+  author: 'KB Labs Team',
+  license: 'KBPL-1.1',
+  type: 'core',
+  implements: 'IEventBus',
+  requires: {
+    adapters: [{ id: 'cache', alias: 'cache' }],
+    platform: '>= 1.0.0',
+  },
+  capabilities: {
+    custom: {
+      persistence: true,
+      distributed: true,
+      ttl: true,
+      polling: true,
+    },
+  },
+  configSchema: {
+    pollIntervalMs: {
+      type: 'number',
+      default: 1000,
+      description: 'Polling interval in milliseconds',
+    },
+    eventTtlMs: {
+      type: 'number',
+      default: 86400000,
+      description: 'Event TTL in milliseconds (default: 24 hours)',
+    },
+    keyPrefix: {
+      type: 'string',
+      default: 'eventbus:',
+      description: 'Prefix for all cache keys',
+    },
+  },
+};

package/packages/adapters-eventbus-cache/src/types.ts

@@ -0,0 +1,58 @@
+/**
+ * @module @kb-labs/adapters-eventbus-cache/types
+ * Type definitions for Cache-backed EventBus adapter.
+ */
+
+import type { ICache } from '@kb-labs/core-platform';
+
+/**
+ * Dependencies for Cache-backed EventBus adapter.
+ * Matches manifest.requires.adapters: [{ id: 'cache', alias: 'cache' }]
+ */
+export interface CacheEventBusDeps {
+  cache: ICache;
+}
+
+/**
+ * Configuration for Cache-backed EventBus adapter.
+ */
+export interface CacheEventBusConfig {
+  /** Polling interval in milliseconds (default: 1000) */
+  pollIntervalMs?: number;
+  /** Event TTL in milliseconds (default: 24 hours) */
+  eventTtlMs?: number;
+  /** Key prefix for cache keys (default: "eventbus:") */
+  keyPrefix?: string;
+}
+
+/**
+ * Stored event structure in cache.
+ */
+export interface StoredEvent<T = unknown> {
+  /** Unique event ID */
+  id: string;
+  /** Event topic */
+  topic: string;
+  /** Event payload */
+  data: T;
+  /** Event timestamp (ms since epoch) */
+  timestamp: number;
+}
+
+/**
+ * Internal subscription tracking.
+ */
+export interface Subscription {
+  /** Topic name */
+  topic: string;
+  /** Event handler function */
+  handler: (event: unknown) => Promise<void>;
+  /** Polling timer reference */
+  timer: ReturnType<typeof setInterval> | null;
+  /** Unique subscriber ID */
+  subscriberId: string;
+  /** Last processed event timestamp */
+  lastTimestamp: number;
+  /** IDs of events already delivered (for dedup within same timestamp) */
+  seenIds: Set<string>;
+}

package/packages/adapters-eventbus-cache/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-eventbus-cache/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-eventbus-cache/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  dts: true,
+});

package/packages/adapters-fs/README.md

@@ -0,0 +1,171 @@
+# @kb-labs/adapters-fs
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+Filesystem storage adapter for local file operations with path security and glob pattern support.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `IStorage` |
+| **Type** | `core` |
+| **Requires** | None |
+| **Category** | Storage |
+
+## Features
+
+- **Path Security** - Sandboxed file access within configured base directory
+- **Streaming Support** - Efficient large file handling with streams
+- **Glob Patterns** - Find files using glob patterns
+- **Metadata Access** - Get file stats, size, modification time
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-fs
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "storage": "@kb-labs/adapters-fs"
+    },
+    "adapterOptions": {
+      "storage": {
+        "baseDir": ".kb/data"
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseDir` | `string` | `process.cwd()` | Base directory for all file operations |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Read file
+const content = await platform.storage.read('config.json');
+
+// Write file
+await platform.storage.write('output.txt', 'Hello, World!');
+
+// List files with glob
+const files = await platform.storage.glob('**/*.ts');
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-fs';
+
+const storage = createAdapter({ baseDir: '/path/to/data' });
+
+await storage.write('test.txt', 'content');
+const content = await storage.read('test.txt');
+```
+
+## How It Works
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│  FS Adapter │────▶│ File System │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          │
+                    Path Validation
+                    (stays in baseDir)
+```
+
+The adapter validates all paths to ensure they stay within the configured `baseDir`, preventing path traversal attacks (e.g., `../../../etc/passwd`).
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'fs-storage',
+  name: 'Filesystem Storage',
+  version: '1.0.0',
+  implements: 'IStorage',
+  capabilities: {
+    streaming: true,
+    custom: {
+      glob: true,
+      metadata: true,
+    },
+  },
+}
+```
+
+## Performance Considerations
+
+- **Memory**: Uses streams for large files to avoid memory issues
+- **Latency**: Depends on disk I/O, SSD recommended for production
+- **Throughput**: Limited by disk speed and OS file system cache
+
+## FAQ
+
+<details>
+<summary><strong>Q: Can I use this adapter outside KB Labs platform?</strong></summary>
+
+No. This adapter is designed specifically for KB Labs ecosystem and depends on platform interfaces and contracts. Use `createAdapter()` for standalone testing only.
+</details>
+
+<details>
+<summary><strong>Q: How do I prevent path traversal attacks?</strong></summary>
+
+The adapter automatically validates all paths. Any attempt to access files outside `baseDir` will throw an error. You don't need to do anything extra.
+</details>
+
+<details>
+<summary><strong>Q: Can I use absolute paths?</strong></summary>
+
+No. All paths are relative to `baseDir`. This is by design for security.
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-analytics-file` | File-based analytics storage |
+
+## Troubleshooting
+
+### Error: EACCES permission denied
+
+**Cause**: The process doesn't have write permissions to the target directory.
+
+**Solution**: Check directory permissions or choose a different `baseDir`:
+
+```bash
+chmod 755 /path/to/your/baseDir
+```
+
+### Error: Path outside base directory
+
+**Cause**: Attempted to access a file outside the sandboxed `baseDir`.
+
+**Solution**: Use relative paths only. Don't use `..` to escape the directory.
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-fs/allowed.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/conflict.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/dest.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/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-fs/exists.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/not-allowed.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/other.txt

@@ -0,0 +1 @@
+c

package/packages/adapters-fs/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kb-labs/adapters-fs",
+  "version": "0.5.0",
+  "description": "Filesystem adapter implementing IStorage interface",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./secure-storage": {
+      "import": "./dist/secure-storage.js",
+      "types": "./dist/secure-storage.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.2",
+    "fs-extra": "^11.0.0"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/fs-extra": "^11.0.0",
+    "@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"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-fs/public/file1.txt

@@ -0,0 +1 @@
+1

package/packages/adapters-fs/public/file2.txt

@@ -0,0 +1 @@
+2

package/packages/adapters-fs/secret.txt

@@ -0,0 +1 @@
+content

package/packages/adapters-fs/secrets/key.txt

@@ -0,0 +1 @@
+secret