@vibesdotdev/logging 0.0.1

package/src/formatters/pretty/pretty.impl.cli.ts

@@ -0,0 +1,101 @@
+/**
+ * Pretty Formatter Implementation (CLI)
+ *
+ * Colorized output using ansis for terminal display.
+ */
+
+import type { FormatterImplementation, FormatterContext } from '../../kinds/formatter.ts';
+import type { FormatterDescriptor } from '../../schemas/formatter.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)
+};
+
+/** Level symbols */
+const LEVEL_SYMBOLS: Record<LogLevel, string> = {
+	debug: '·',
+	info: '●',
+	warn: '▲',
+	error: '✖'
+};
+
+/**
+ * Pretty formatter - colorized CLI output.
+ */
+export default class PrettyFormatter implements FormatterImplementation {
+	readonly id: string;
+	readonly descriptor: FormatterDescriptor;
+	private readonly useColors: boolean;
+	private readonly includeTimestamp: boolean;
+
+	constructor(descriptor: FormatterDescriptor, _context: FormatterContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor;
+		this.useColors = descriptor.options?.colors ?? true;
+		this.includeTimestamp = descriptor.options?.includeTimestamp ?? true;
+	}
+
+	format(entry: RuntimeLogEntry): string {
+		const { level, namespace, message, timestamp, context } = entry;
+		const colorFn = this.useColors ? LEVEL_COLORS[level] : (t: string) => t;
+		const symbol = LEVEL_SYMBOLS[level];
+
+		const parts: string[] = [];
+
+		// Timestamp
+		if (this.includeTimestamp) {
+			const time = new Date(timestamp).toLocaleTimeString('en-US', { hour12: false });
+			parts.push(this.useColors ? ansis.dim(time) : time);
+		}
+
+		// Level symbol
+		parts.push(colorFn(symbol));
+
+		// Namespace
+		parts.push(this.useColors ? ansis.cyan(`[${namespace}]`) : `[${namespace}]`);
+
+		// Message
+		parts.push(message);
+
+		// Context (if any non-standard fields)
+		const contextKeys = Object.keys(context).filter(
+			(k) => !['timestamp', 'level', 'namespace', 'runtime'].includes(k)
+		);
+		if (contextKeys.length > 0) {
+			const contextObj: Record<string, unknown> = {};
+			for (const key of contextKeys) {
+				contextObj[key] = context[key];
+			}
+			const contextStr = JSON.stringify(contextObj);
+			parts.push(this.useColors ? ansis.dim(contextStr) : contextStr);
+		}
+
+		return parts.join(' ');
+	}
+
+	parse(formatted: string): RuntimeLogEntry {
+		// Pretty format is not designed for parsing back
+		// Return a minimal entry with the raw line as message
+		return {
+			timestamp: new Date().toISOString(),
+			level: 'info',
+			namespace: 'unknown',
+			message: formatted,
+			context: {}
+		};
+	}
+
+	formatBatch(entries: RuntimeLogEntry[]): string {
+		return entries.map((e) => this.format(e)).join('\n');
+	}
+
+	parseBatch(formatted: string): RuntimeLogEntry[] {
+		return formatted.split('\n').map((line) => this.parse(line));
+	}
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+/**
+ * Vibes Logging Module
+ *
+ * Runtime-aligned logging with sinks, formatters, outputs, and audit trails.
+ *
+ * ## Usage Pattern
+ *
+ * 1. Define a logger descriptor in your module:
+ * ```ts
+ * // myapp/logging/myapp.logger.descriptor.ts
+ * import type { LoggerDescriptor } from '@vibesdotdev/logging';
+ *
+ * const descriptor: LoggerDescriptor = {
+ *   kind: 'logging/logger',
+ *   id: 'myapp',
+ *   namespace: 'myapp',
+ *   runtime: 'server',
+ *   sinks: ['console'],
+ *   level: 'info'
+ * };
+ *
+ * export default descriptor;
+ * ```
+ *
+ * 2. Get the logger from runtime:
+ * ```ts
+ * import { getLogger } from '@vibesdotdev/logging';
+ *
+ * const logger = getLogger('myapp');
+ * logger.info('Application started', { version: '1.0.0' });
+ *
+ * // Child loggers
+ * const dbLogger = logger.child('database');
+ * dbLogger.debug('Connected to database');
+ * ```
+ *
+ * 3. Audit logging:
+ * ```ts
+ * import { auditLog } from '@vibesdotdev/logging';
+ *
+ * await auditLog({
+ *   category: 'authentication',
+ *   severity: 'medium',
+ *   action: 'login',
+ *   actor: { id: 'user-123', type: 'user' },
+ *   outcome: 'success'
+ * });
+ * ```
+ *
+ * @module
+ */
+
+// Plugin
+export { default as loggingPlugin } from './logging.plugin';
+
+// Core logger types
+export type { Logger, Runtime, RuntimeLoggerOptions, RuntimeLoggerConfig } from './core/types.ts';
+
+// Re-export LoggerChildOptions from schemas
+export type { LoggerChildOptions } from './schemas/index.ts';
+
+/**
+ * Default logger instance.
+ * For most server-side code, use this directly.
+ *
+ * @example
+ * ```ts
+ * import { logger } from '@vibesdotdev/logging';
+ * logger.info('Server started');
+ * ```
+ */
+import { getDefaultLogger } from './contexts/logger.ts';
+export const logger = getDefaultLogger();
+
+// Namespace utilities
+export {
+	parseNamespaceSettings,
+	parseNamespaceSettingsFromEnv,
+	shouldLog,
+	updateNamespaceSettings,
+	getNamespaceSettings,
+	defaultNamespaceSettings,
+	type NamespaceSettings,
+	type NamespaceSelector,
+	type NamespaceSelectors
+} from './core/namespace.ts';
+
+// Schemas
+export {
+	// Entry types
+	LogLevelSchema,
+	type LogLevel,
+	LOG_LEVEL_ORDER,
+	LogContextSchema,
+	type LogContext,
+	LoggerChildOptionsSchema,
+	RuntimeLogEntrySchema,
+	type RuntimeLogEntry,
+	type RequestLogContext,
+	type JobLogContext,
+	type PerformanceTracker,
+	type PerformanceTrackerParams,
+	// Sink schemas
+	SinkDescriptorSchema,
+	type SinkDescriptor,
+	type SinkFormat,
+	type SinkBatching,
+	// Formatter schemas
+	FormatterDescriptorSchema,
+	type FormatterDescriptor,
+	type FormatterOptions,
+	// Output schemas
+	OutputDescriptorSchema,
+	type OutputDescriptor,
+	type OutputRotation,
+	type OutputBuffering,
+	type OutputStorage,
+	// Audit schemas
+	AuditDescriptorSchema,
+	type AuditDescriptor,
+	AuditEntrySchema,
+	type AuditEntry,
+	type AuditCategory,
+	type AuditSeverity,
+	type AuditOutcome,
+	type AuditActor,
+	type AuditTarget,
+	// Logger schemas
+	LoggerDescriptorSchema,
+	type LoggerDescriptor,
+	type LoggerRuntime
+} from './schemas/index.ts';
+
+// Kinds
+export { sinkKind, type SinkImplementation, type SinkContext } from './kinds/sink.ts';
+export {
+	formatterKind,
+	type FormatterImplementation,
+	type FormatterContext
+} from './kinds/formatter.ts';
+export {
+	outputKind,
+	type OutputImplementation,
+	type OutputContext,
+	type OutputReadOptions,
+	type OutputTailOptions,
+	type TailHandle,
+	type OutputStats
+} from './kinds/output.ts';
+export {
+	auditKind,
+	type AuditImplementation,
+	type AuditContext,
+	type AuditLogInput,
+	type AuditQueryOptions
+} from './kinds/audit.ts';
+export { loggerKind } from './kinds/logger.ts';
+export { type LoggerImplementation, type LoggerContext } from './kinds/logger.impl';
+
+// Context providers
+export {
+	// Logger context
+	configureLoggerContext,
+	createLoggerContextProvider,
+	getLoggerContext,
+	setLoggerContext,
+	getLogger,
+	getDefaultLogger,
+	registerLogger,
+	initializeLoggers,
+	type LoggerContextConfig,
+	type LoggerContextProvider,
+	type RuntimeLogger,
+	// Audit context types only — use runtime to resolve audit implementations
+	type AuditContextConfig,
+	type AuditContextProvider
+} from './contexts/index.ts';
+
+// Sinks (types only — implementations autoloaded by runtime)
+export { type MemorySinkQueryOptions } from './sinks/index.ts';
+
+// Audit (storage schemas only — implementations autoloaded by runtime)
+export {
+	AuditEntryStorageSchema,
+	type AuditEntryStorage,
+	type AuditRetentionPolicy,
+	DEFAULT_RETENTION_POLICIES,
+	type AuditStorageConfig,
+	defaultAuditStorageConfig
+} from './audit/index.ts';

package/src/kinds/audit.ts

@@ -0,0 +1,169 @@
+/**
+ * Audit Logging Kind Definition
+ *
+ * Audit loggers capture compliance and security events.
+ */
+
+import type { RuntimeKindDescriptor, KindContext, RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import {
+	AuditDescriptorSchema,
+	type AuditDescriptor,
+	type AuditEntry,
+	type AuditCategory,
+	type AuditSeverity,
+	type AuditOutcome,
+	type AuditActor,
+	type AuditTarget
+} from '../schemas/audit.ts';
+
+/**
+ * Input for logging an audit event.
+ */
+export interface AuditLogInput {
+	/** Event category */
+	category: AuditCategory;
+	/** Severity level */
+	severity: AuditSeverity;
+	/** Action performed */
+	action: string;
+	/** Who triggered the event */
+	actor: AuditActor;
+	/** What was affected (optional) */
+	target?: AuditTarget;
+	/** Event outcome */
+	outcome: AuditOutcome;
+	/** Additional context */
+	context?: Record<string, unknown>;
+	/** Error details */
+	error?: string;
+}
+
+/**
+ * Query options for retrieving audit entries.
+ */
+export interface AuditQueryOptions {
+	/** Filter by category */
+	category?: AuditCategory;
+	/** Filter by severity (minimum) */
+	severity?: AuditSeverity;
+	/** Filter by actor ID */
+	actorId?: string;
+	/** Filter by target ID */
+	targetId?: string;
+	/** Filter by action */
+	action?: string;
+	/** Filter by outcome */
+	outcome?: AuditOutcome;
+	/** Start time (ISO 8601) */
+	after?: string;
+	/** End time (ISO 8601) */
+	before?: string;
+	/** Maximum entries to return */
+	limit?: number;
+	/** Offset for pagination */
+	offset?: number;
+}
+
+/**
+ * Audit implementation interface.
+ * Implementations persist audit entries with integrity guarantees.
+ */
+export interface AuditImplementation {
+	/** Log an audit event */
+	log(input: AuditLogInput): Promise<AuditEntry>;
+	/** Query audit entries (if supported) */
+	query?(options: AuditQueryOptions): Promise<AuditEntry[]>;
+}
+
+/**
+ * Context provided to audit implementations.
+ */
+export interface AuditContext extends KindContext {
+	/** Runtime reference */
+	readonly runtime: unknown;
+	/** Workspace path for storage */
+	readonly workspacePath?: string;
+}
+
+/**
+ * Default audit implementation - logs to stderr.
+ * Used when no specific implementation is registered.
+ */
+class DefaultAuditImplementation implements AuditImplementation {
+	readonly id: string;
+	readonly descriptor: AuditDescriptor;
+
+	constructor(descriptor: RuntimeDescriptor, _context: AuditContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor as AuditDescriptor;
+	}
+
+	async log(input: AuditLogInput): Promise<AuditEntry> {
+		const entry: AuditEntry = {
+			id: crypto.randomUUID(),
+			timestamp: new Date().toISOString(),
+			category: input.category,
+			severity: input.severity,
+			action: input.action,
+			actor: input.actor,
+			target: input.target,
+			outcome: input.outcome,
+			context: input.context,
+			error: input.error
+		};
+
+		// Default: log to stderr to avoid stdout pollution (critical for MCP stdio)
+		console.error(`[AUDIT] ${JSON.stringify(entry)}`);
+
+		return entry;
+	}
+}
+
+/**
+ * Audit kind resolution logic.
+ * Selects audit logger based on category and hardware.
+ */
+function resolveAudit(
+	candidates: RuntimeDescriptor[],
+	scope: RuntimeScope,
+	_context: KindContext
+): AuditDescriptor | undefined {
+	const typed = candidates as AuditDescriptor[];
+	if (typed.length === 0) return undefined;
+	if (typed.length === 1) return typed[0];
+
+	const hardware = scope.hardware;
+
+	// Filter by hardware compatibility
+	const matching = typed.filter((d) => {
+		if (!d.hardware || d.hardware.length === 0) return true;
+		return d.hardware.includes(hardware);
+	});
+
+	if (matching.length === 0) return undefined;
+
+	// Prefer audits with explicit hardware match
+	const explicit = matching.filter((d) => d.hardware && d.hardware.length > 0);
+	if (explicit.length > 0) return explicit[0];
+
+	return matching[0];
+}
+
+/**
+ * Audit kind definition for runtime registration.
+ */
+export const auditKind: RuntimeKindDescriptor<AuditDescriptor, AuditImplementation, AuditContext> =
+	{
+		id: 'logging/audit',
+		descriptorSchema: AuditDescriptorSchema,
+		defaultImplementation: DefaultAuditImplementation,
+		resolve: resolveAudit,
+		contexts: ['runtime/workspace-path']
+	};
+
+declare module '@vibesdotdev/runtime/schemas/kind-types' {
+	interface KindTypeMap {
+		'logging/audit': { descriptor: AuditDescriptor; impl: AuditImplementation };
+	}
+}

package/src/kinds/contexts.ts

@@ -0,0 +1,22 @@
+/**
+ * Logging Context Types
+ *
+ * Shared context interfaces to avoid circular dependencies.
+ * This file contains only type definitions - no implementations.
+ */
+
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type { SinkImplementation } from './sink.ts';
+import type { OutputImplementation } from './output.ts';
+
+/**
+ * Context provided to logger implementations.
+ */
+export interface LoggerContext extends KindContext {
+	/** Runtime reference */
+	readonly runtime: unknown;
+	/** Available sinks for this logger */
+	readonly sinks?: Map<string, SinkImplementation> | SinkImplementation[];
+	/** Available outputs for this logger */
+	readonly outputs?: Map<string, OutputImplementation> | OutputImplementation[];
+}

package/src/kinds/formatter.ts

@@ -0,0 +1,117 @@
+/**
+ * Logging Formatter Kind Definition
+ *
+ * Formatters serialize log entries to various output formats.
+ */
+
+import type { RuntimeKindDescriptor, KindContext, RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import { FormatterDescriptorSchema, type FormatterDescriptor } from '../schemas/formatter.ts';
+import type { RuntimeLogEntry } from '../schemas/entry.ts';
+
+/**
+ * Formatter implementation interface.
+ * Implementations convert log entries to/from string representation.
+ */
+export interface FormatterImplementation {
+	/** Format a single log entry */
+	format(entry: RuntimeLogEntry): string;
+	/** Parse a formatted string back to log entry */
+	parse(formatted: string): RuntimeLogEntry;
+	/** Format multiple entries (batch optimization) */
+	formatBatch?(entries: RuntimeLogEntry[]): string;
+	/** Parse multiple formatted strings */
+	parseBatch?(formatted: string): RuntimeLogEntry[];
+}
+
+/**
+ * Context provided to formatter implementations.
+ */
+export interface FormatterContext extends KindContext {
+	/** Runtime reference */
+	readonly runtime: unknown;
+}
+
+/**
+ * Default formatter implementation - JSON output.
+ * Used when no specific implementation is registered.
+ */
+class DefaultFormatterImplementation implements FormatterImplementation {
+	readonly id: string;
+	readonly descriptor: FormatterDescriptor;
+
+	constructor(descriptor: RuntimeDescriptor, _context: FormatterContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor as FormatterDescriptor;
+	}
+
+	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) => this.format(e)).join('\n');
+	}
+
+	parseBatch(formatted: string): RuntimeLogEntry[] {
+		return formatted
+			.split('\n')
+			.filter((line) => line.trim())
+			.map((line) => this.parse(line));
+	}
+}
+
+/**
+ * Formatter kind resolution logic.
+ * Selects formatter based on format and hardware.
+ */
+function resolveFormatter(
+	candidates: RuntimeDescriptor[],
+	scope: RuntimeScope,
+	_context: KindContext
+): FormatterDescriptor | undefined {
+	const typed = candidates as FormatterDescriptor[];
+	if (typed.length === 0) return undefined;
+	if (typed.length === 1) return typed[0];
+
+	const hardware = scope.hardware;
+
+	// Filter by hardware compatibility
+	const matching = typed.filter((d) => {
+		if (!d.hardware || d.hardware.length === 0) return true;
+		return d.hardware.includes(hardware);
+	});
+
+	if (matching.length === 0) return undefined;
+
+	// Prefer formatters with explicit hardware match
+	const explicit = matching.filter((d) => d.hardware && d.hardware.length > 0);
+	if (explicit.length > 0) return explicit[0];
+
+	return matching[0];
+}
+
+/**
+ * Formatter kind definition for runtime registration.
+ */
+export const formatterKind: RuntimeKindDescriptor<
+	FormatterDescriptor,
+	FormatterImplementation,
+	FormatterContext
+> = {
+	id: 'logging/formatter',
+	descriptorSchema: FormatterDescriptorSchema,
+	defaultImplementation: DefaultFormatterImplementation,
+	resolve: resolveFormatter,
+	contexts: []
+};
+
+declare module '@vibesdotdev/runtime/schemas/kind-types' {
+	interface KindTypeMap {
+		'logging/formatter': { descriptor: FormatterDescriptor; impl: FormatterImplementation };
+	}
+}

package/src/kinds/index.ts

@@ -0,0 +1,25 @@
+import { sinkKind, type SinkImplementation, type SinkContext } from './sink.ts';
+import { formatterKind, type FormatterImplementation, type FormatterContext } from './formatter.ts';
+import { outputKind, type OutputImplementation, type OutputContext } from './output.ts';
+import {
+	auditKind,
+	type AuditImplementation,
+	type AuditContext,
+	type AuditLogInput,
+	type AuditQueryOptions
+} from './audit.ts';
+import { loggerKind } from './logger.ts';
+import DefaultLoggerImplementation, { type LoggerImplementation, type LoggerContext } from './logger.impl';
+
+export { sinkKind, type SinkImplementation, type SinkContext };
+export { formatterKind, type FormatterImplementation, type FormatterContext };
+export { outputKind, type OutputImplementation, type OutputContext };
+export {
+	auditKind,
+	type AuditImplementation,
+	type AuditContext,
+	type AuditLogInput,
+	type AuditQueryOptions
+};
+export { loggerKind };
+export { DefaultLoggerImplementation, type LoggerImplementation, type LoggerContext };

package/src/kinds/logger.contracts.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger kind context contract.
+ *
+ * Extracted from `./logger.impl.ts` so the helper module
+ * (`./logger.utils.ts`) can reference `LoggerContext` without forming a
+ * cycle (logger.impl imports value helpers from logger.utils).
+ */
+
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type { OutputImplementation } from './output.contracts';
+import type { SinkImplementation } from './sink.ts';
+
+export interface LoggerContext extends KindContext {
+	readonly runtime: unknown;
+	readonly sinks?: Map<string, SinkImplementation> | SinkImplementation[];
+	readonly outputs?: Map<string, OutputImplementation> | OutputImplementation[];
+}