@vibesdotdev/logging 0.0.1

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

@@ -0,0 +1,428 @@
+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

@@ -0,0 +1,6 @@
+/**
+ * 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

@@ -0,0 +1,25 @@
+/**
+ * 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

@@ -0,0 +1,41 @@
+/**
+ * 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

@@ -0,0 +1,25 @@
+/**
+ * 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

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,26 @@
+/**
+ * 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

@@ -0,0 +1,39 @@
+/**
+ * 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

@@ -0,0 +1,26 @@
+/**
+ * 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;