@kb-labs/adapters 0.5.0

package/packages/adapters-pino/src/index.ts

@@ -0,0 +1,322 @@
+/**
+ * @module @kb-labs/adapters-pino
+ * Pino adapter implementing ILogger interface.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-pino';
+ *
+ * const logger = createAdapter({
+ *   level: 'info',
+ *   pretty: true,
+ * });
+ *
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Failed to connect', new Error('Connection timeout'));
+ *
+ * const childLogger = logger.child({ service: 'api' });
+ * childLogger.debug('Request received');
+ * ```
+ */
+
+import pino, { type Logger as PinoLoggerInstance } from "pino";
+import type { ILogger, ILogBuffer, LogRecord } from "@kb-labs/core-platform";
+import { generateLogId } from "@kb-labs/core-platform/adapters";
+import { LogRingBuffer } from "./log-ring-buffer";
+
+// Re-export manifest
+export { manifest } from "./manifest.js";
+
+/**
+ * Configuration for log streaming/buffering
+ */
+export interface StreamingConfig {
+  /** Enable log buffering for streaming (default: false) */
+  enabled: boolean;
+  /** Maximum buffer size (number of log records, default: 1000) */
+  bufferSize?: number;
+  /** Maximum age of logs in buffer (milliseconds, default: 3600000 = 1 hour) */
+  bufferMaxAge?: number;
+}
+
+/**
+ * Configuration for Pino logger adapter.
+ */
+export interface PinoLoggerConfig {
+  /** Log level (default: 'info') */
+  level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+  /** Enable pretty printing for development (default: false) */
+  pretty?: boolean;
+  /** Streaming configuration (optional) */
+  streaming?: StreamingConfig;
+  /** Additional pino options */
+  options?: pino.LoggerOptions;
+}
+
+/**
+ * Pino implementation of ILogger interface.
+ */
+export class PinoLoggerAdapter implements ILogger {
+  private pino: PinoLoggerInstance;
+  private logBuffer?: LogRingBuffer;
+  private logCallbacks = new Set<(record: LogRecord) => void>();
+  private bindings: Record<string, unknown> = {};
+
+  constructor(config: PinoLoggerConfig = {}) {
+    // Resolve log level with priority: ENV var > config.level > 'info'
+    // This allows overriding via KB_LOG_LEVEL or LOG_LEVEL environment variables
+    const resolvedLevel =
+      (process.env.KB_LOG_LEVEL as PinoLoggerConfig["level"]) ??
+      (process.env.LOG_LEVEL as PinoLoggerConfig["level"]) ??
+      config.level ??
+      "info";
+
+    // Initialize log buffer if streaming is enabled
+    if (config.streaming?.enabled) {
+      this.logBuffer = new LogRingBuffer(
+        config.streaming.bufferSize ?? 1000,
+        config.streaming.bufferMaxAge ?? 3600000,
+      );
+    }
+
+    const transport = config.pretty
+      ? {
+          target: "pino-pretty",
+          options: {
+            colorize: true,
+            translateTime: "SYS:standard",
+            ignore: "pid,hostname",
+          },
+        }
+      : undefined;
+
+    // Merge options, but transport from config.options takes precedence
+    const finalTransport = config.options?.transport ?? transport;
+
+    // Always use single pino instance (no multistream)
+    // LogRingBuffer is fed directly in log methods, not via Pino stream
+    this.pino = pino({
+      level: resolvedLevel,
+      ...config.options,
+      transport: finalTransport,
+    });
+  }
+
+  /**
+   * Emit log record to all registered callbacks (extensions).
+   * Fire-and-forget - errors in callbacks don't block logging.
+   */
+  private emitLog(record: LogRecord): void {
+    if (this.logCallbacks.size === 0) {
+      return;
+    }
+
+    for (const callback of this.logCallbacks) {
+      try {
+        callback(record);
+      } catch (error) {
+        console.error("[PinoLogger] Error in onLog callback:", error);
+      }
+    }
+  }
+
+  /**
+   * Internal constructor for child loggers.
+   */
+  private constructor_child(pinoInstance: PinoLoggerInstance, bindings: Record<string, unknown>) {
+    const instance = Object.create(PinoLoggerAdapter.prototype);
+    instance.pino = pinoInstance;
+    instance.logCallbacks = this.logCallbacks; // Share callbacks with parent
+    instance.logBuffer = this.logBuffer; // Share buffer with parent
+    instance.bindings = bindings;
+    return instance;
+  }
+
+  private mergeBindings(meta?: Record<string, unknown>): Record<string, unknown> {
+    if (!meta) {
+      return { ...this.bindings };
+    }
+    return { ...this.bindings, ...meta };
+  }
+
+  info(message: string, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    this.pino.info(meta ?? {}, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "info",
+      message,
+      fields: mergedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  warn(message: string, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    this.pino.warn(meta ?? {}, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "warn",
+      message,
+      fields: mergedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  error(message: string, error?: Error, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    const enrichedMeta = {
+      ...mergedMeta,
+      ...(error && {
+        error: {
+          message: error.message,
+          stack: error.stack,
+          name: error.name,
+        },
+      }),
+    };
+
+    this.pino.error(enrichedMeta, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "error",
+      message,
+      fields: enrichedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  fatal(message: string, error?: Error, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    const enrichedMeta = {
+      ...mergedMeta,
+      ...(error && {
+        error: {
+          message: error.message,
+          stack: error.stack,
+          name: error.name,
+        },
+      }),
+    };
+
+    this.pino.fatal(enrichedMeta, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "fatal",
+      message,
+      fields: enrichedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  debug(message: string, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    this.pino.debug(meta ?? {}, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "debug",
+      message,
+      fields: mergedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  trace(message: string, meta?: Record<string, unknown>): void {
+    const logId = generateLogId();
+    const timestamp = Date.now();
+    const mergedMeta = this.mergeBindings(meta);
+
+    this.pino.trace(meta ?? {}, message);
+
+    const record: LogRecord = {
+      id: logId,
+      timestamp,
+      level: "trace",
+      message,
+      fields: mergedMeta,
+      source: (mergedMeta.source as string) ?? "unknown",
+    };
+
+    this.logBuffer?.append(record);
+    this.emitLog(record);
+  }
+
+  child(bindings: Record<string, unknown>): ILogger {
+    const mergedBindings = { ...this.bindings, ...bindings };
+    const childPino = this.pino.child(bindings);
+    return this.constructor_child(childPino, mergedBindings);
+  }
+
+  /**
+   * Get log buffer for streaming/querying (ILogger optional method)
+   */
+  getLogBuffer(): ILogBuffer | undefined {
+    return this.logBuffer;
+  }
+
+  /**
+   * Register callback for every log event (ILogger optional method).
+   * Used by platform to connect logger extensions (ring buffer, persistence).
+   *
+   * @param callback - Function to call on each log event
+   * @returns Unsubscribe function to remove the callback
+   */
+  onLog(callback: (record: LogRecord) => void): () => void {
+    this.logCallbacks.add(callback);
+    return () => this.logCallbacks.delete(callback);
+  }
+}
+
+/**
+ * Create Pino logger adapter.
+ * This is the factory function called by initPlatform() when loading adapters.
+ */
+export function createAdapter(config?: PinoLoggerConfig): PinoLoggerAdapter {
+  return new PinoLoggerAdapter(config);
+}
+
+// Default export for direct import
+export default createAdapter;
+
+// Export buffer class
+export { LogRingBuffer } from "./log-ring-buffer";

package/packages/adapters-pino/src/log-ring-buffer.ts

@@ -0,0 +1,142 @@
+/**
+ * @module @kb-labs/adapters-pino/log-ring-buffer
+ * Ring buffer for in-memory log storage with real-time streaming
+ */
+
+import type {
+  LogRecord,
+  LogQuery,
+  ILogBuffer,
+  LogLevel,
+} from "@kb-labs/core-platform";
+
+/**
+ * Ring buffer implementation for log storage
+ */
+export class LogRingBuffer implements ILogBuffer {
+  private buffer: LogRecord[] = [];
+  private subscribers: Set<(record: LogRecord) => void> = new Set();
+  private readonly maxSize: number;
+  private readonly maxAge: number;
+
+  constructor(maxSize: number = 1000, maxAge: number = 3600000) {
+    this.maxSize = maxSize;
+    this.maxAge = maxAge; // milliseconds
+  }
+
+  /**
+   * Append log record to buffer
+   */
+  append(record: LogRecord): void {
+    // Add to buffer
+    this.buffer.push(record);
+
+    // Evict old entries by size
+    if (this.buffer.length > this.maxSize) {
+      this.buffer.shift();
+    }
+
+    // Evict old entries by age
+    const now = Date.now();
+    const cutoff = now - this.maxAge;
+    while (this.buffer.length > 0 && this.buffer[0]!.timestamp < cutoff) {
+      this.buffer.shift();
+    }
+
+    // Notify subscribers
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber(record);
+      } catch (error) {
+        // Ignore subscriber errors
+        console.error("[LogRingBuffer] Subscriber error:", error);
+      }
+    }
+  }
+
+  /**
+   * Query logs with filters
+   */
+  query(query?: LogQuery): LogRecord[] {
+    let results = [...this.buffer];
+
+    if (!query) {
+      return results;
+    }
+
+    // Filter by time range
+    if (query.from !== undefined) {
+      results = results.filter((r) => r.timestamp >= query.from!);
+    }
+    if (query.to !== undefined) {
+      results = results.filter((r) => r.timestamp <= query.to!);
+    }
+
+    // Filter by source
+    if (query.source !== undefined) {
+      results = results.filter((r) => r.source === query.source);
+    }
+
+    // Filter by level (minimum level)
+    if (query.level !== undefined) {
+      const levels: LogLevel[] = [
+        "trace",
+        "debug",
+        "info",
+        "warn",
+        "error",
+        "fatal",
+      ];
+      const minLevelIndex = levels.indexOf(query.level);
+      results = results.filter((r) => {
+        const recordLevelIndex = levels.indexOf(r.level);
+        return recordLevelIndex >= minLevelIndex;
+      });
+    }
+
+    // Apply limit
+    if (query.limit !== undefined && query.limit > 0) {
+      results = results.slice(-query.limit); // Take most recent N
+    }
+
+    return results;
+  }
+
+  /**
+   * Subscribe to real-time log stream
+   */
+  subscribe(callback: (record: LogRecord) => void): () => void {
+    this.subscribers.add(callback);
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+
+  /**
+   * Find log by ID in buffer
+   */
+  findById(id: string): LogRecord | undefined {
+    return this.buffer.find((record) => record.id === id);
+  }
+
+  /**
+   * Get buffer statistics
+   */
+  getStats(): {
+    total: number;
+    bufferSize: number;
+    oldestTimestamp: number | null;
+    newestTimestamp: number | null;
+  } {
+    return {
+      total: this.buffer.length,
+      bufferSize: this.maxSize,
+      oldestTimestamp:
+        this.buffer.length > 0 ? this.buffer[0]!.timestamp : null,
+      newestTimestamp:
+        this.buffer.length > 0
+          ? this.buffer[this.buffer.length - 1]!.timestamp
+          : null,
+    };
+  }
+}

package/packages/adapters-pino/src/manifest.ts

@@ -0,0 +1,49 @@
+/**
+ * @module @kb-labs/adapters-pino/manifest
+ * Adapter manifest for Pino logger.
+ */
+
+import type { AdapterManifest } from "@kb-labs/core-platform";
+
+/**
+ * Adapter manifest for Pino logger.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: "1.0.0",
+  id: "pino-logger",
+  name: "Pino Logger",
+  version: "1.0.0",
+  description: "Production-ready structured logger based on Pino",
+  author: "KB Labs Team",
+  license: "KBPL-1.1",
+  type: "core",
+  implements: "ILogger",
+  optional: {
+    adapters: ["analytics"],
+  },
+  capabilities: {
+    streaming: true,
+  },
+  configSchema: {
+    level: {
+      type: "string",
+      enum: ["trace", "debug", "info", "warn", "error", "fatal"],
+      default: "info",
+      description: "Minimum log level",
+    },
+    pretty: {
+      type: "boolean",
+      default: false,
+      description: "Enable pretty printing for development",
+    },
+    streaming: {
+      type: "object",
+      description: "Log streaming/buffering configuration",
+      properties: {
+        enabled: { type: "boolean", default: false },
+        bufferSize: { type: "number", default: 1000 },
+        bufferMaxAge: { type: "number", default: 3600000 },
+      },
+    },
+  },
+};

package/packages/adapters-pino/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-pino/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-pino/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-pino-http/README.md

@@ -0,0 +1,141 @@
+# @kb-labs/adapters-pino-http
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+Pino HTTP transport for streaming logs to KB Labs REST API.
+
+## Features
+
+- ✅ **Batching** - Configurable batch size and flush interval
+- ✅ **Retry Logic** - Exponential backoff on HTTP failures
+- ✅ **Graceful Shutdown** - Flushes pending logs before exit
+- ✅ **Error Handling** - Logs to stderr if HTTP fails
+- ✅ **Lightweight** - Minimal dependencies, uses native `fetch`
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-pino-http
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  transport: {
+    target: '@kb-labs/adapters-pino-http',
+    options: {
+      url: 'http://localhost:5050/api/v1/logs/ingest',
+      batchSize: 50,
+      flushIntervalMs: 3000,
+    },
+  },
+});
+
+logger.info('Hello from Pino HTTP Transport!');
+```
+
+### With Platform DI (Recommended)
+
+Configure in `.kb/kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "logger": "@kb-labs/adapters-pino"
+    },
+    "adapterOptions": {
+      "logger": {
+        "level": "info",
+        "options": {
+          "transport": {
+            "target": "@kb-labs/adapters-pino-http",
+            "options": {
+              "url": "http://localhost:5050/api/v1/logs/ingest",
+              "batchSize": 50,
+              "flushIntervalMs": 3000
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Then use in code:
+
+```typescript
+import { initPlatform } from '@kb-labs/core-platform';
+
+const platform = await initPlatform();
+
+platform.logger.info('This log will be sent to REST API!', {
+  plugin: 'my-plugin',
+  executionId: 'exec-123',
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | `http://localhost:5050/api/v1/logs/ingest` | REST API endpoint for log ingestion |
+| `batchSize` | `number` | `50` | Number of logs to batch before sending |
+| `flushIntervalMs` | `number` | `3000` | Max time in ms to wait before flushing batch |
+| `retryAttempts` | `number` | `3` | Number of retry attempts on HTTP failure |
+| `retryDelayMs` | `number` | `1000` | Initial retry delay in ms (exponential backoff) |
+| `headers` | `Record<string, string>` | `{}` | Custom HTTP headers (e.g., for authentication) |
+| `debug` | `boolean` | `false` | Enable debug logging to stderr |
+
+## How It Works
+
+1. **Pino logs** are written to the transport stream
+2. **Batch accumulation** - Logs are collected into a batch
+3. **Flush trigger** - Batch is sent when:
+   - Batch size reaches `batchSize` (immediate flush)
+   - `flushIntervalMs` timer expires (delayed flush)
+   - Process exits (graceful shutdown)
+4. **HTTP POST** - Batch is sent to REST API with retry logic
+5. **Retry on failure** - Exponential backoff (1s → 2s → 4s)
+6. **Error logging** - Failures are logged to stderr
+
+## Performance
+
+- **Batching reduces HTTP overhead**: 50 logs/request vs 50 requests
+- **Non-blocking**: Uses async `fetch`, doesn't block Pino
+- **Memory-safe**: Ring buffer in REST API prevents OOM
+
+## Debugging
+
+Enable debug mode to see transport activity:
+
+```json
+{
+  "transport": {
+    "target": "@kb-labs/adapters-pino-http",
+    "options": {
+      "url": "http://localhost:5050/api/v1/logs/ingest",
+      "debug": true
+    }
+  }
+}
+```
+
+Output:
+
+```
+[PinoHTTP] Flushing 50 logs to http://localhost:5050/api/v1/logs/ingest
+[PinoHTTP] Flush successful
+[PinoHTTP] Shutting down, flushing pending logs...
+[PinoHTTP] Shutdown complete
+```
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team