@vibesdotdev/logging 0.0.1

package/src/schemas/entry.ts

@@ -0,0 +1,88 @@
+/**
+ * Logging Entry Schemas
+ *
+ * Core types for log entries, levels, and contexts.
+ */
+
+import * as z from 'zod/v4';
+
+/** Log severity levels */
+export const LogLevelSchema = z.enum(['debug', 'info', 'warn', 'error']);
+export type LogLevel = z.infer<typeof LogLevelSchema>;
+
+/** Log level priority ordering */
+export const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+
+/** Context attached to log entries */
+export const LogContextSchema = z.record(z.string(), z.unknown());
+export type LogContext = z.infer<typeof LogContextSchema>;
+
+/** Options for creating child loggers */
+export const LoggerChildOptionsSchema = z.union([
+	z.string(),
+	z
+		.object({
+			namespace: z.string().optional(),
+			context: z.string().optional()
+		})
+		.and(LogContextSchema)
+]);
+export type LoggerChildOptions = z.infer<typeof LoggerChildOptionsSchema>;
+
+/** A single log entry */
+export const RuntimeLogEntrySchema = z.object({
+	/** Timestamp of the entry (ISO 8601) */
+	timestamp: z.string(),
+	/** Log severity level */
+	level: LogLevelSchema,
+	/** Hierarchical namespace (e.g., 'vibes:pm:daemon') */
+	namespace: z.string(),
+	/** Log message */
+	message: z.string(),
+	/** Arbitrary context data */
+	context: LogContextSchema
+});
+export type RuntimeLogEntry = z.infer<typeof RuntimeLogEntrySchema>;
+
+/** Request-specific context fields */
+export const RequestLogContextSchema = z.object({
+	requestId: z.string().optional(),
+	correlationId: z.string().optional(),
+	sessionId: z.string().optional(),
+	userId: z.string().optional(),
+	userAgent: z.string().optional(),
+	ip: z.string().optional(),
+	route: z.string().optional(),
+	method: z.string().optional()
+});
+export type RequestLogContext = z.infer<typeof RequestLogContextSchema>;
+
+/** Job-specific context fields */
+export const JobLogContextSchema = z.object({
+	jobId: z.string().optional(),
+	queueId: z.string().optional(),
+	queueName: z.string().optional(),
+	toolId: z.string().optional(),
+	parentJobId: z.string().optional(),
+	attempt: z.number().optional(),
+	maxAttempts: z.number().optional()
+});
+export type JobLogContext = z.infer<typeof JobLogContextSchema>;
+
+/** Performance tracking parameters */
+export interface PerformanceTrackerParams {
+	operation: string;
+	metadata?: LogContext;
+}
+
+/** Performance tracker for timing operations */
+export interface PerformanceTracker {
+	start(): void;
+	end(successContext?: LogContext): void;
+	fail(error: unknown, errorContext?: LogContext): void;
+}

package/src/schemas/formatter.ts

@@ -0,0 +1,37 @@
+/**
+ * Logging Formatter Descriptor Schema
+ *
+ * Formatters serialize and deserialize log entries.
+ * Examples: JSONL, JSON, JSON5, pretty-printed text.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+import { SinkFormatSchema } from './sink.ts';
+
+/** Formatter-specific options */
+export const FormatterOptionsSchema = z.object({
+	/** Pretty-print with indentation */
+	indent: z.number().int().min(0).default(0),
+	/** Include timestamp in formatted output */
+	includeTimestamp: z.boolean().default(true),
+	/** Include namespace in formatted output */
+	includeNamespace: z.boolean().default(true),
+	/** Include level in formatted output */
+	includeLevel: z.boolean().default(true),
+	/** Use colors (for pretty formatter) */
+	colors: z.boolean().default(true)
+});
+export type FormatterOptions = z.infer<typeof FormatterOptionsSchema>;
+
+/** Formatter descriptor schema */
+export const FormatterDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('logging/formatter'),
+
+	/** Output format type */
+	format: SinkFormatSchema,
+
+	/** Formatter options */
+	options: FormatterOptionsSchema.optional()
+});
+export type FormatterDescriptor = z.infer<typeof FormatterDescriptorSchema>;

package/src/schemas/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Logging Schemas
+ *
+ * Exports all logging-related schemas and types.
+ */
+
+// Core entry types
+export {
+	LogLevelSchema,
+	type LogLevel,
+	LOG_LEVEL_ORDER,
+	LogContextSchema,
+	type LogContext,
+	LoggerChildOptionsSchema,
+	type LoggerChildOptions,
+	RuntimeLogEntrySchema,
+	type RuntimeLogEntry,
+	RequestLogContextSchema,
+	type RequestLogContext,
+	JobLogContextSchema,
+	type JobLogContext,
+	type PerformanceTrackerParams,
+	type PerformanceTracker
+} from './entry.ts';
+
+// Sink schemas
+export {
+	SinkFormatSchema,
+	type SinkFormat,
+	SinkBatchingSchema,
+	type SinkBatching,
+	SinkDescriptorSchema,
+	type SinkDescriptor
+} from './sink.ts';
+
+// Formatter schemas
+export {
+	FormatterOptionsSchema,
+	type FormatterOptions,
+	FormatterDescriptorSchema,
+	type FormatterDescriptor
+} from './formatter.ts';
+
+// Output schemas
+export {
+	OutputRotationSchema,
+	type OutputRotation,
+	OutputBufferingSchema,
+	type OutputBuffering,
+	OutputStorageSchema,
+	type OutputStorage,
+	OutputDescriptorSchema,
+	type OutputDescriptor
+} from './output.ts';
+
+// Audit schemas
+export {
+	AuditCategorySchema,
+	type AuditCategory,
+	AuditSeveritySchema,
+	type AuditSeverity,
+	AuditOutcomeSchema,
+	type AuditOutcome,
+	AuditActorSchema,
+	type AuditActor,
+	AuditTargetSchema,
+	type AuditTarget,
+	AuditEntrySchema,
+	type AuditEntry,
+	AuditDescriptorSchema,
+	type AuditDescriptor
+} from './audit.ts';
+
+// Logger schemas
+export {
+	LoggerRuntimeSchema,
+	type LoggerRuntime,
+	LoggerDescriptorSchema,
+	type LoggerDescriptor
+} from './logger.ts';

package/src/schemas/logger.ts

@@ -0,0 +1,38 @@
+/**
+ * Logger Descriptor Schema
+ *
+ * Loggers are named log emitters with namespace filtering and sink routing.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+import { LogLevelSchema } from './entry.ts';
+
+/** Runtime environment for the logger */
+export const LoggerRuntimeSchema = z.enum(['server', 'cli', 'worker', 'browser', 'mcp']);
+export type LoggerRuntime = z.infer<typeof LoggerRuntimeSchema>;
+
+/** Logger descriptor schema */
+export const LoggerDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('logging/logger'),
+
+	/** Hierarchical namespace for filtering (e.g., 'vibes:pm:daemon') */
+	namespace: z.string(),
+
+	/** Runtime environment */
+	runtime: LoggerRuntimeSchema.default('server'),
+
+	/** Sink IDs to emit to (default: ['console']) */
+	sinks: z.array(z.string()).default(['console']),
+
+	/** Output IDs to write to (optional, for persistent logging) */
+	outputs: z.array(z.string()).optional(),
+
+	/** Minimum log level (default: 'info') */
+	level: LogLevelSchema.default('info'),
+
+	/** Static metadata to include in all entries */
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+
+export type LoggerDescriptor = z.infer<typeof LoggerDescriptorSchema>;

package/src/schemas/output.ts

@@ -0,0 +1,62 @@
+/**
+ * Logging Output Descriptor Schema
+ *
+ * Outputs are named log streams with rotation and buffering.
+ * Examples: file output, remote HTTP endpoint.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+import { SinkFormatSchema } from './sink.ts';
+
+/** File rotation configuration */
+export const OutputRotationSchema = z.object({
+	/** Maximum file size before rotation (e.g., '10MB', '1GB') */
+	maxSize: z.string().optional(),
+	/** Maximum age before rotation (e.g., '7d', '24h') */
+	maxAge: z.string().optional(),
+	/** Maximum number of rotated files to keep */
+	maxFiles: z.number().int().positive().default(5)
+});
+export type OutputRotation = z.infer<typeof OutputRotationSchema>;
+
+/** Buffering configuration */
+export const OutputBufferingSchema = z.object({
+	/** Enable buffered writes */
+	enabled: z.boolean().default(true),
+	/** Buffer size in bytes */
+	size: z.number().int().positive().default(8192),
+	/** Flush interval in milliseconds */
+	flushInterval: z.number().int().positive().default(1000),
+	/** Maximum number of entries to buffer (for memory safety under failure conditions) */
+	maxBufferEntries: z.number().int().positive().default(10000)
+});
+export type OutputBuffering = z.infer<typeof OutputBufferingSchema>;
+
+/** Storage backend type */
+export const OutputStorageSchema = z.enum(['file', 'remote']);
+export type OutputStorage = z.infer<typeof OutputStorageSchema>;
+
+/** Output descriptor schema */
+export const OutputDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('logging/output'),
+
+	/** Storage backend (file or remote) */
+	storage: OutputStorageSchema,
+
+	/** Output format */
+	format: SinkFormatSchema.default('jsonl'),
+
+	/** File path (relative to workspace or absolute) */
+	path: z.string().optional(),
+
+	/** Remote endpoint URL */
+	endpoint: z.string().url().optional(),
+
+	/** Rotation configuration (file outputs only) */
+	rotation: OutputRotationSchema.optional(),
+
+	/** Buffering configuration */
+	buffering: OutputBufferingSchema.optional()
+});
+export type OutputDescriptor = z.infer<typeof OutputDescriptorSchema>;

package/src/schemas/sink.ts

@@ -0,0 +1,39 @@
+/**
+ * Logging Sink Descriptor Schema
+ *
+ * Sinks are output destinations for log entries.
+ * Examples: console, OpenTelemetry, memory buffer.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+
+/** Supported output formats for sinks */
+export const SinkFormatSchema = z.enum(['jsonl', 'json', 'json5', 'pretty', 'raw']);
+export type SinkFormat = z.infer<typeof SinkFormatSchema>;
+
+/** Batching configuration for async sinks */
+export const SinkBatchingSchema = z.object({
+	/** Enable batched writes */
+	enabled: z.boolean().default(false),
+	/** Maximum entries before flush */
+	maxSize: z.number().int().positive().default(100),
+	/** Maximum wait time (ms) before flush */
+	maxWait: z.number().int().positive().default(1000)
+});
+export type SinkBatching = z.infer<typeof SinkBatchingSchema>;
+
+/** Sink descriptor schema */
+export const SinkDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('logging/sink'),
+
+	/** Whether sink supports async writes */
+	async: z.boolean().default(false),
+
+	/** Batching configuration */
+	batching: SinkBatchingSchema.optional(),
+
+	/** Supported output formats */
+	formats: z.array(SinkFormatSchema).default(['raw'])
+});
+export type SinkDescriptor = z.infer<typeof SinkDescriptorSchema>;

package/src/sinks/buffer/buffer.descriptor.ts

@@ -0,0 +1,13 @@
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+
+const descriptor: SinkDescriptor = {
+	kind: 'logging/sink',
+	id: 'buffer',
+	name: 'Buffer Sink',
+	description: 'Temporary in-memory sink for startup buffering and deferred flush',
+	tags: ['cli', 'buffer'],
+	async: false,
+	formats: ['raw']
+};
+
+export default descriptor;

package/src/sinks/buffer/buffer.impl.cli.ts

@@ -0,0 +1,49 @@
+import type { SinkImplementation, SinkContext } from '../../kinds/sink.ts';
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+import type { RuntimeLogEntry } from '../../schemas/entry.ts';
+
+export interface DrainableSink extends SinkImplementation {
+	drain(): RuntimeLogEntry[];
+	clear(): void;
+}
+
+export function drainable(sink: SinkImplementation): sink is DrainableSink {
+	return typeof (sink as Partial<DrainableSink>).drain === 'function';
+}
+
+export default class BufferSink implements DrainableSink {
+	readonly id: string;
+	readonly descriptor: SinkDescriptor;
+	private entries: RuntimeLogEntry[] = [];
+	private maxEntries = 50000;
+
+	constructor(descriptor: SinkDescriptor, _context: SinkContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor;
+	}
+
+	emit(entry: RuntimeLogEntry): void {
+		this.entries.push(entry);
+		if (this.entries.length > this.maxEntries) {
+			this.entries = this.entries.slice(-this.maxEntries);
+		}
+	}
+
+	drain(): RuntimeLogEntry[] {
+		const drained = this.entries;
+		this.entries = [];
+		return drained;
+	}
+
+	clear(): void {
+		this.entries = [];
+	}
+
+	async flush(): Promise<void> {
+		// Buffered in-memory only.
+	}
+
+	async close(): Promise<void> {
+		this.clear();
+	}
+}

package/src/sinks/console/console.descriptor.ts

@@ -0,0 +1,20 @@
+/**
+ * Console Sink Descriptor
+ *
+ * Default sink that writes colorized log output to stderr.
+ * Universal - works on all hardware.
+ */
+
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+
+export const consoleSinkDescriptor: SinkDescriptor = {
+	kind: 'logging/sink',
+	id: 'console',
+	name: 'Console Sink',
+	description: 'Writes colorized log entries to stderr',
+	tags: ['default', 'development'],
+	async: false,
+	formats: ['pretty', 'jsonl', 'raw']
+};
+
+export default consoleSinkDescriptor;

package/src/sinks/console/console.impl.browser.ts

@@ -0,0 +1,69 @@
+/**
+ * Console Sink Implementation (Browser)
+ *
+ * Uses native console methods for browser environments.
+ * Minimal bundle impact - no color library dependencies.
+ */
+
+import type { SinkImplementation, SinkContext } from '../../kinds/sink.ts';
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+import type { RuntimeLogEntry, LogLevel } from '../../schemas/entry.ts';
+
+/** Console methods by level */
+const CONSOLE_METHODS: Record<LogLevel, typeof console.log> = {
+	debug: console.debug,
+	info: console.info,
+	warn: console.warn,
+	error: console.error
+};
+
+/** CSS styles for levels (browser devtools) */
+const LEVEL_STYLES: Record<LogLevel, string> = {
+	debug: 'color: gray',
+	info: 'color: blue',
+	warn: 'color: orange',
+	error: 'color: red; font-weight: bold'
+};
+
+/**
+ * Console sink - writes to browser console.
+ */
+export default class BrowserConsoleSink implements SinkImplementation {
+	readonly id: string;
+	readonly descriptor: SinkDescriptor;
+
+	constructor(descriptor: SinkDescriptor, _context: SinkContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor;
+	}
+
+	emit(entry: RuntimeLogEntry): void {
+		const { level, namespace, message, context } = entry;
+		const consoleFn = CONSOLE_METHODS[level];
+		const style = LEVEL_STYLES[level];
+
+		// Extract non-standard context
+		const payload = { ...context };
+		delete payload.timestamp;
+		delete payload.level;
+		delete payload.namespace;
+		delete payload.runtime;
+
+		const prefix = `[${namespace}]`;
+
+		if (Object.keys(payload).length > 0) {
+			// Use styled console output
+			consoleFn(`%c${level.toUpperCase()} ${prefix}`, style, message, payload);
+		} else {
+			consoleFn(`%c${level.toUpperCase()} ${prefix}`, style, message);
+		}
+	}
+
+	async flush(): Promise<void> {
+		// Console is synchronous
+	}
+
+	async close(): Promise<void> {
+		// Nothing to close
+	}
+}

package/src/sinks/console/console.impl.cli.ts

@@ -0,0 +1,71 @@
+/**
+ * Console Sink Implementation (CLI)
+ *
+ * Uses ansis for colorized output written to stderr.
+ * Stdout is never used - it may be reserved for protocols (MCP stdio).
+ */
+
+import type { SinkImplementation, SinkContext } from '../../kinds/sink.ts';
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+import type { RuntimeLogEntry, LogLevel } from '../../schemas/entry.ts';
+import ansis from 'ansis';
+
+/** Level colors */
+const LEVEL_COLORS: Record<LogLevel, (text: string) => string> = {
+	debug: (t) => ansis.gray(t),
+	info: (t) => ansis.blue(t),
+	warn: (t) => ansis.yellow(t),
+	error: (t) => ansis.red(t)
+};
+
+/**
+ * Console sink - writes to stderr with colors.
+ */
+export default class ConsoleSink implements SinkImplementation {
+	readonly id: string;
+	readonly descriptor: SinkDescriptor;
+
+	constructor(descriptor: SinkDescriptor, _context: SinkContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor;
+	}
+
+	emit(entry: RuntimeLogEntry): void {
+		const { level, namespace, message, context } = entry;
+		const rawLine = context.rawLine;
+		if (typeof rawLine === 'string') {
+			process.stderr.write(rawLine);
+			return;
+		}
+		const colorFn = LEVEL_COLORS[level];
+
+		const prefix = ansis.cyan(`[${namespace}]`);
+		const levelStr = colorFn(level.toUpperCase().padEnd(5));
+
+		// Extract non-standard context
+		const contextKeys = Object.keys(context).filter(
+			(k) => !['timestamp', 'level', 'namespace', 'runtime'].includes(k)
+		);
+
+		let line: string;
+		if (contextKeys.length > 0) {
+			const contextObj: Record<string, unknown> = {};
+			for (const key of contextKeys) {
+				contextObj[key] = context[key];
+			}
+			line = `${levelStr} ${prefix} ${message} ${ansis.dim(JSON.stringify(contextObj))}\n`;
+		} else {
+			line = `${levelStr} ${prefix} ${message}\n`;
+		}
+
+		process.stderr.write(line);
+	}
+
+	async flush(): Promise<void> {
+		// Console is synchronous, nothing to flush
+	}
+
+	async close(): Promise<void> {
+		// Nothing to close
+	}
+}

package/src/sinks/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Logging Sinks
+ *
+ * Descriptors and implementations are autoloaded by the runtime.
+ * This barrel exports only types needed by consumers.
+ */
+
+export type { MemorySinkQueryOptions } from './memory/memory.impl';

package/src/sinks/memory/memory.descriptor.ts

@@ -0,0 +1,20 @@
+/**
+ * Memory Sink Descriptor
+ *
+ * In-memory buffer for testing and debugging.
+ * Entries are queryable and clearable.
+ */
+
+import type { SinkDescriptor } from '../../schemas/sink.ts';
+
+export const memorySinkDescriptor: SinkDescriptor = {
+	kind: 'logging/sink',
+	id: 'memory',
+	name: 'Memory Sink',
+	description: 'In-memory buffer for testing and debugging',
+	tags: ['testing', 'debug'],
+	async: false,
+	formats: ['raw']
+};
+
+export default memorySinkDescriptor;