@vibesdotdev/logging 0.0.2 → 1.0.0-rc.4

package/src/docs/transports.docs.descriptor.ts

@@ -1,428 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-	kind: 'docs/topic',
-	id: 'logging.transports',
-	title: 'Logging Transports',
-	summary: 'Transport layers including console, file, and remote outputs',
-	body: {
-		type: 'markdown',
-		sourceType: 'raw',
-		source: `---
-title: Logging Transports
-summary: Transport layers including console, file, and remote outputs
-tags: [logging, transports, console, file, remote, outputs]
-parent: logging
-order: 2
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-# Logging Transports
-
-Transports (called "sinks" and "outputs" in the logging system) determine where log entries are written. The \`logging/sink\` and \`logging/output\` runtime kinds provide multiple transport options.
-
-## Transport Types
-
-### Console Sink
-
-Writes to stdout/stderr:
-
-\`\`\`ts
-import { logger } from '@vibesdotdev/logging';
-
-logger.info('Console output');
-// [INFO] [app] Console output
-\`\`\`
-
-**Configuration:**
-- Default for CLI and browser
-- Uses pretty formatter by default
-- Color-coded output
-
-**Use cases:**
-- Development debugging
-- CLI applications
-- Browser console
-
-### File Output
-
-Writes to log files:
-
-\`\`\`ts
-import { getVibesRuntime } from '@vibesdotdev/runtime';
-
-const runtime = getVibesRuntime();
-
-await runtime.registerPlugin(loggingPlugin({
-  outputs: [{
-    type: 'file',
-    path: './logs/app.log',
-    format: 'jsonl',
-    maxSize: '10MB',
-    maxFiles: 5
-  }]
-}));
-\`\`\`
-
-**Features:**
-- Automatic rotation
-- Compression of old files
-- Timestamp-based naming
-
-**Use cases:**
-- Production logging
-- Audit trails
-- Long-term storage
-
-### Memory Sink
-
-Buffers logs in memory:
-
-\`\`\`ts
-import { memorySinkPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(memorySinkPlugin({
-  maxSize: 1000,  // Keep last 1000 entries
-  flushOn: 'error'  // Auto-flush on error level
-}));
-\`\`\`
-
-**Use cases:**
-- Testing
-- Debug sessions
-- Temporary buffering
-
-### Buffer Sink
-
-Circular buffer with flush capability:
-
-\`\`\`ts
-import { bufferSinkPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(bufferSinkPlugin({
-  capacity: 500,
-  flushInterval: 60_000  // Flush every minute
-}));
-\`\`\`
-
-**Use cases:**
-- Batch processing
-- Network optimization
-- Error context capture
-
-### Remote Output
-
-Sends logs to remote service:
-
-\`\`\`ts
-import { remoteOutputPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(remoteOutputPlugin({
-  endpoint: 'https://logs.vibes.dev/ingest',
-  apiKey: process.env.LOGS_API_KEY,
-  batchSize: 100,
-  flushInterval: 5_000
-}));
-\`\`\`
-
-**Features:**
-- Batched delivery
-- Retry on failure
-- Compression
-
-**Use cases:**
-- Centralized logging
-- Log aggregation services
-- Multi-app correlation
-
-## Configuring Transports
-
-### Multiple Transports
-
-\`\`\`ts
-import { loggingPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(loggingPlugin({
-  sinks: ['console', 'memory'],
-  outputs: [{
-    type: 'file',
-    path: './logs/app.log'
-  }, {
-    type: 'remote',
-    endpoint: 'https://logs.vibes.dev/ingest'
-  }]
-}));
-\`\`\`
-
-**Log flow:**
-\`\`\`
-Logger → Console (immediate)
-       → Memory (buffer)
-       → File (batched)
-       → Remote (batched, compressed)
-\`\`\`
-
-### Transport Selection by Environment
-
-\`\`\`ts
-const loggingConfig = {
-  development: {
-    sinks: ['console'],
-    level: 'debug'
-  },
-  production: {
-    sinks: ['console', 'memory'],
-    outputs: [
-      { type: 'file', path: '/var/log/app.log' },
-      { type: 'remote', endpoint: 'https://logs.vibes.dev' }
-    ],
-    level: 'info'
-  }
-};
-
-const env = process.env.NODE_ENV || 'development';
-await runtime.registerPlugin(loggingPlugin(loggingConfig[env]));
-\`\`\`
-
-### Transport Selection by Hardware
-
-\`\`\`ts
-const loggingConfig = {
-  consumer: {
-    sinks: ['console'],
-    outputs: [{ type: 'file', path: '~/.logs/app.log' }]
-  },
-  cloud: {
-    sinks: ['stdout'],
-    outputs: [{ type: 'remote', endpoint: 'https://logs.vibes.dev' }]
-  }
-};
-
-const hardware = runtime.scope.hardware;
-await runtime.registerPlugin(loggingPlugin(loggingConfig[hardware]));
-\`\`\`
-
-## Formatter Integration
-
-Transports use formatters to format log entries:
-
-### Pretty Formatter (Console)
-
-\`\`\`ts
-[INFO] [app:server] Server started on port 3000
-\`\`\`
-
-**Features:**
-- Color-coded levels
-- Human-readable timestamps
-- Indented context objects
-
-### JSON Formatter
-
-\`\`\`json
-{"level":"info","namespace":"app:server","message":"Server started","port":3000,"timestamp":"2024-01-01T00:00:00.000Z"}
-\`\`\`
-
-**Features:**
-- Machine-parseable
-- Structured data
-- Log aggregation friendly
-
-### JSONL Formatter
-
-\`\`\`
-{"level":"info",...}
-{"level":"error",...}
-{"level":"warn",...}
-\`\`\`
-
-**Features:**
-- One JSON per line
-- Easy streaming
-- Efficient storage
-
-## Transport Configuration
-
-### Console Sink
-
-\`\`\`ts
-import { consoleSinkPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(consoleSinkPlugin({
-  stderrThreshold: 'warn',  // warn/error to stderr
-  colors: true,              // ANSI colors
-  timestamp: true            // Include timestamps
-}));
-\`\`\`
-
-### File Output
-
-\`\`\`ts
-import { fileOutputPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(fileOutputPlugin({
-  path: './logs/app.log',
-  format: 'jsonl',
-  rotation: {
-    strategy: 'size',
-    maxSize: '10MB',
-    maxFiles: 5,
-    compress: true
-  },
-  schedule: {
-    type: 'daily',
-    time: '00:00'  // Rotate at midnight
-  }
-}));
-\`\`\`
-
-### Remote Output
-
-\`\`\`ts
-import { remoteOutputPlugin } from '@vibesdotdev/logging';
-
-await runtime.registerPlugin(remoteOutputPlugin({
-  endpoint: 'https://logs.vibes.dev/ingest',
-  method: 'POST',
-  headers: {
-    'Authorization': \`Bearer \${process.env.LOGS_API_KEY}\`,
-    'Content-Type': 'application/json'
-  },
-  batch: {
-    maxSize: 100,
-    maxWait: 5_000
-  },
-  retry: {
-    maxAttempts: 3,
-    backoff: 'exponential',
-    initialDelay: 1_000
-  },
-  compression: 'gzip'
-}));
-\`\`\`
-
-## Transport Lifecycle
-
-### Initialization
-
-\`\`\`ts
-const transport = await runtime.query('logging/sink')
-  .filter(d => d.id === 'console')
-  .resolve();
-
-await transport.ensureReady();
-\`\`\`
-
-### Flushing
-
-\`\`\`ts
-// Flush buffered logs
-await transport.flush();
-
-// Or auto-flush on interval
-await runtime.registerPlugin(bufferSinkPlugin({
-  flushInterval: 60_000  // 1 minute
-}));
-\`\`\`
-
-### Cleanup
-
-\`\`\`ts
-// Close transport and release resources
-await transport.close();
-\`\`\`
-
-## Transport Resolution
-
-### Query by ID
-
-\`\`\`ts
-const consoleSink = await runtime.query('logging/sink')
-  .filter(d => d.id === 'console')
-  .resolve();
-\`\`\`
-
-### Query by Hardware
-
-\`\`\`ts
-const sink = await runtime.query('logging/sink')
-  .forHardware('consumer')
-  .resolve();
-\`\`\`
-
-### List All Transports
-
-\`\`\`ts
-const sinks = runtime.query('logging/sink').descriptors();
-const outputs = runtime.query('logging/output').descriptors();
-
-console.log('Available sinks:', sinks.map(s => s.id));
-console.log('Available outputs:', outputs.map(o => o.id));
-\`\`\`
-
-## Custom Transport
-
-\`\`\`ts
-import { createRuntimePlugin } from '@vibesdotdev/runtime';
-import type { SinkImplementation } from '@vibesdotdev/logging';
-
-class CustomSink implements SinkImplementation {
-  constructor(private config: CustomConfig) {}
-  
-  emit(entry: LogEntry): void {
-    // Custom transport logic
-    console.log('Custom:', entry);
-  }
-  
-  async flush(): Promise<void> {
-    // Flush buffered entries
-  }
-  
-  async close(): Promise<void> {
-    // Cleanup resources
-  }
-}
-
-const descriptor: SinkDescriptor = {
-  kind: 'logging/sink',
-  id: 'logging.sink.custom',
-  title: 'Custom Sink'
-};
-
-export const customSinkPlugin = createRuntimePlugin({
-  id: 'custom-sink',
-  kinds: [{
-    id: 'logging/sink',
-    descriptorSchema: SinkDescriptorSchema,
-    defaultImplementation: CustomSink
-  }],
-  descriptors: [descriptor]
-});
-\`\`\`
-
-## Transport Best Practices
-
-1. **Use appropriate transports** — Console for dev, file/remote for prod
-2. **Configure rotation** — Prevent disk exhaustion
-3. **Batch remote sends** — Reduce network overhead
-4. **Handle failures gracefully** — Don't crash on log failures
-5. **Sanitize sensitive data** — Remove PII before sending
-6. **Monitor transport health** — Alert on delivery failures
-
-:::card{title="See also"}
-- [\`logging.levels\`](logging.levels) — Log levels
-- [\`logging.structured\`](logging.structured) — Structured logging
-- [\`config.environment\`](config.environment) — Environment configuration
-:::
-`
-	},
-	parent: 'logging',
-	order: 2,
-	tags: ['logging', 'transports', 'console', 'file', 'remote', 'outputs'],
-	surfaces: ['cli', 'web', 'in-app'],
-	hardware: ['consumer', 'cloud'],
-	enabled: true
-};
-
-export default descriptor;

package/src/formatters/index.ts

@@ -1,6 +0,0 @@
-/**
- * Logging Formatters
- *
- * Descriptors and implementations are autoloaded by the runtime.
- * No public types to export — formatter interfaces live in kinds/formatter.
- */

package/src/formatters/json/json.formatters.descriptor.ts

@@ -1,25 +0,0 @@
-/**
- * JSON Formatter Descriptor
- *
- * Formats log entries as pretty-printed JSON.
- */
-
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-
-export const jsonFormatterDescriptor: FormatterDescriptor = {
-	kind: 'logging/formatter',
-	id: 'json',
-	name: 'JSON Formatter',
-	description: 'Formats log entries as indented JSON',
-	tags: ['readable', 'debug'],
-	format: 'json',
-	options: {
-		indent: 2,
-		includeTimestamp: true,
-		includeNamespace: true,
-		includeLevel: true,
-		colors: false
-	}
-};
-
-export default jsonFormatterDescriptor;

package/src/formatters/json/json.impl.ts

@@ -1,41 +0,0 @@
-/**
- * JSON Formatter Implementation
- *
- * Pretty-printed JSON with configurable indentation.
- */
-
-import type { FormatterImplementation, FormatterContext } from '../../kinds/formatter.ts';
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-import type { RuntimeLogEntry } from '../../schemas/entry.ts';
-
-/**
- * JSON formatter - indented JSON for readability.
- */
-export default class JsonFormatter implements FormatterImplementation {
-	readonly id: string;
-	readonly descriptor: FormatterDescriptor;
-	private readonly indent: number;
-
-	constructor(descriptor: FormatterDescriptor, _context: FormatterContext) {
-		this.id = descriptor.id;
-		this.descriptor = descriptor;
-		this.indent = descriptor.options?.indent ?? 2;
-	}
-
-	format(entry: RuntimeLogEntry): string {
-		return JSON.stringify(entry, null, this.indent);
-	}
-
-	parse(formatted: string): RuntimeLogEntry {
-		return JSON.parse(formatted) as RuntimeLogEntry;
-	}
-
-	formatBatch(entries: RuntimeLogEntry[]): string {
-		return JSON.stringify(entries, null, this.indent);
-	}
-
-	parseBatch(formatted: string): RuntimeLogEntry[] {
-		const parsed = JSON.parse(formatted);
-		return Array.isArray(parsed) ? parsed : [parsed];
-	}
-}

package/src/formatters/json5/json5.descriptor.ts

@@ -1,25 +0,0 @@
-/**
- * JSON5 Formatter Descriptor
- *
- * Formats log entries as JSON5 (human-readable JSON with comments).
- */
-
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-
-export const json5FormatterDescriptor: FormatterDescriptor = {
-	kind: 'logging/formatter',
-	id: 'json5',
-	name: 'JSON5 Formatter',
-	description: 'Formats log entries as JSON5 for human readability',
-	tags: ['readable', 'config'],
-	format: 'json5',
-	options: {
-		indent: 2,
-		includeTimestamp: true,
-		includeNamespace: true,
-		includeLevel: true,
-		colors: false
-	}
-};
-
-export default json5FormatterDescriptor;

package/src/formatters/json5/json5.impl.ts

@@ -1,43 +0,0 @@
-/**
- * JSON5 Formatter Implementation
- *
- * Uses JSON5 for human-readable output with comments support.
- * Note: For serialization, we use standard JSON since JSON5 is a superset.
- */
-
-import type { FormatterImplementation, FormatterContext } from '../../kinds/formatter.ts';
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-import type { RuntimeLogEntry } from '../../schemas/entry.ts';
-import JSON5 from 'json5';
-
-/**
- * JSON5 formatter - human-readable JSON.
- */
-export default class Json5Formatter implements FormatterImplementation {
-	readonly id: string;
-	readonly descriptor: FormatterDescriptor;
-	private readonly indent: number;
-
-	constructor(descriptor: FormatterDescriptor, _context: FormatterContext) {
-		this.id = descriptor.id;
-		this.descriptor = descriptor;
-		this.indent = descriptor.options?.indent ?? 2;
-	}
-
-	format(entry: RuntimeLogEntry): string {
-		return JSON5.stringify(entry, null, this.indent);
-	}
-
-	parse(formatted: string): RuntimeLogEntry {
-		return JSON5.parse(formatted) as RuntimeLogEntry;
-	}
-
-	formatBatch(entries: RuntimeLogEntry[]): string {
-		return JSON5.stringify(entries, null, this.indent);
-	}
-
-	parseBatch(formatted: string): RuntimeLogEntry[] {
-		const parsed = JSON5.parse(formatted);
-		return Array.isArray(parsed) ? parsed : [parsed];
-	}
-}

package/src/formatters/jsonl/jsonl.descriptor.ts

@@ -1,26 +0,0 @@
-/**
- * JSONL Formatter Descriptor
- *
- * Formats log entries as newline-delimited JSON.
- * Default formatter for file outputs.
- */
-
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-
-export const jsonlFormatterDescriptor: FormatterDescriptor = {
-	kind: 'logging/formatter',
-	id: 'jsonl',
-	name: 'JSONL Formatter',
-	description: 'Formats log entries as newline-delimited JSON',
-	tags: ['default', 'file', 'streaming'],
-	format: 'jsonl',
-	options: {
-		indent: 0,
-		includeTimestamp: true,
-		includeNamespace: true,
-		includeLevel: true,
-		colors: false
-	}
-};
-
-export default jsonlFormatterDescriptor;

package/src/formatters/jsonl/jsonl.impl.ts

@@ -1,39 +0,0 @@
-/**
- * JSONL Formatter Implementation
- *
- * Uses Bun's native JSON serialization for performance.
- */
-
-import type { FormatterImplementation, FormatterContext } from '../../kinds/formatter.ts';
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-import type { RuntimeLogEntry } from '../../schemas/entry.ts';
-
-/**
- * JSONL formatter - one JSON object per line.
- */
-export default class JsonlFormatter implements FormatterImplementation {
-	readonly id: string;
-	readonly descriptor: FormatterDescriptor;
-
-	constructor(descriptor: FormatterDescriptor, _context: FormatterContext) {
-		this.id = descriptor.id;
-		this.descriptor = descriptor;
-	}
-
-	format(entry: RuntimeLogEntry): string {
-		return JSON.stringify(entry);
-	}
-
-	parse(formatted: string): RuntimeLogEntry {
-		return JSON.parse(formatted) as RuntimeLogEntry;
-	}
-
-	formatBatch(entries: RuntimeLogEntry[]): string {
-		return entries.map((e) => JSON.stringify(e)).join('\n');
-	}
-
-	parseBatch(formatted: string): RuntimeLogEntry[] {
-		const lines = formatted.split('\n').filter((line) => line.trim());
-		return lines.map((line) => JSON.parse(line) as RuntimeLogEntry);
-	}
-}

package/src/formatters/pretty/pretty.descriptor.ts

@@ -1,26 +0,0 @@
-/**
- * Pretty Formatter Descriptor
- *
- * Colorized, human-readable output for CLI/TUI.
- */
-
-import type { FormatterDescriptor } from '../../schemas/formatter.ts';
-
-export const prettyFormatterDescriptor: FormatterDescriptor = {
-	kind: 'logging/formatter',
-	id: 'pretty',
-	name: 'Pretty Formatter',
-	description: 'Colorized, human-readable output for CLI/TUI',
-	tags: ['cli', 'tui', 'readable'],
-	hardware: ['consumer'],
-	format: 'pretty',
-	options: {
-		indent: 0,
-		includeTimestamp: true,
-		includeNamespace: true,
-		includeLevel: true,
-		colors: true
-	}
-};
-
-export default prettyFormatterDescriptor;