@vibesdotdev/logging 0.0.1

package/src/contexts/fallback-logger.ts

@@ -0,0 +1,80 @@
+import type { LoggerImplementation } from '../kinds/logger.impl';
+import type { LogLevel, LogContext, LoggerChildOptions, PerformanceTrackerParams } from '../schemas/entry.ts';
+import type { PerformanceTracker } from '../schemas/entry.ts';
+
+function createFallbackLoggerInternal(
+	namespace: string,
+	baseContext: LogContext
+): LoggerImplementation {
+	const normalizeLogContext = (context: unknown): LogContext => {
+		if (context === undefined || context === null) {
+			return {};
+		}
+		if (context instanceof Error) {
+			return {
+				errorName: context.name,
+				errorMessage: context.message,
+				stack: context.stack
+			};
+		}
+		if (typeof context === 'object' && !Array.isArray(context)) {
+			return context as LogContext;
+		}
+		return { value: context };
+	};
+
+	const emit = (level: LogLevel, message: string, context?: unknown) => {
+		if (level === 'debug') return;
+		const prefix = `[${namespace}]`;
+		const merged = { ...baseContext, ...normalizeLogContext(context) };
+		const payloadStr =
+			Object.keys(merged).length > 0 ? ` ${JSON.stringify(merged)}` : '';
+		const line = `${prefix} ${message}${payloadStr}`;
+		console.error(line);
+	};
+
+	return {
+		namespace,
+		fullNamespace: namespace,
+		debug: (msg, ctx) => emit('debug', msg, ctx),
+		info: (msg, ctx) => emit('info', msg, ctx),
+		warn: (msg, ctx) => emit('warn', msg, ctx),
+		error: (msg, ctx) => emit('error', msg, ctx),
+		child: (options: LoggerChildOptions) => {
+			const childNs =
+				typeof options === 'string'
+					? `${namespace}:${options}`
+					: `${namespace}:${options.namespace ?? options.context ?? ''}`;
+			return createFallbackLoggerInternal(childNs, baseContext);
+		},
+		withContext: (ctx: LogContext) =>
+			createFallbackLoggerInternal(namespace, { ...baseContext, ...ctx }),
+		withRequestContext: (ctx) =>
+			createFallbackLoggerInternal(namespace, { ...baseContext, ...ctx }),
+		withJobContext: (ctx) =>
+			createFallbackLoggerInternal(namespace, { ...baseContext, ...ctx }),
+		performanceTracker: (params: PerformanceTrackerParams): PerformanceTracker => {
+			let startTime = 0;
+			const tracker = createFallbackLoggerInternal(namespace, {
+				...baseContext,
+				operation: params.operation,
+				...params.metadata
+			});
+			return {
+				start() { startTime = Date.now(); tracker.debug(`operation.${params.operation}.start`); },
+				end(successContext?: LogContext) {
+					const duration = Date.now() - startTime;
+					tracker.info(`operation.${params.operation}.success`, { duration, ...successContext });
+				},
+				fail(error: unknown, errorContext?: LogContext) {
+					const duration = Date.now() - startTime;
+					tracker.error(`operation.${params.operation}.failure`, { duration, error, ...errorContext });
+				}
+			};
+		}
+	};
+}
+
+export function createFallbackLogger(namespace: string): LoggerImplementation {
+	return createFallbackLoggerInternal(namespace, {});
+}

package/src/contexts/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Logging Contexts
+ *
+ * Context providers for dependency injection.
+ */
+
+export {
+	configureLoggerContext,
+	getLoggerContextConfig,
+	createLoggerContextProvider,
+	getLoggerContext,
+	setLoggerContext,
+	getLogger,
+	getDefaultLogger,
+	registerLogger,
+	initializeLoggers,
+	type LoggerContextConfig,
+	type LoggerContextProvider,
+	type RuntimeLogger
+} from './logger.ts';
+
+// Audit context types only — use runtime to resolve audit implementations
+export { type AuditContextConfig, type AuditContextProvider } from './audit.ts';

package/src/contexts/logger.ts

@@ -0,0 +1,119 @@
+/**
+ * Logger Context Provider
+ *
+ * Provides logger instances to runtime assets via context injection.
+ * Loggers are resolved from the runtime and cached for sync access.
+ */
+
+import type { LoggerImplementation } from '../kinds/logger.impl';
+import { createFallbackLogger } from './fallback-logger.ts';
+
+export type RuntimeLogger = LoggerImplementation;
+
+export interface LoggerContextConfig {
+	defaultNamespace: string;
+	defaultRuntime: 'server' | 'cli' | 'worker' | 'browser' | 'mcp';
+}
+
+const defaultConfig: LoggerContextConfig = {
+	defaultNamespace: 'vibes',
+	defaultRuntime: 'server'
+};
+
+let activeConfig = { ...defaultConfig };
+
+export function configureLoggerContext(config: Partial<LoggerContextConfig>): void {
+	activeConfig = { ...activeConfig, ...config };
+}
+
+export function getLoggerContextConfig(): LoggerContextConfig {
+	return { ...activeConfig };
+}
+
+const loggerCache = new Map<string, LoggerImplementation>();
+
+export function registerLogger(id: string, logger: LoggerImplementation): void {
+	loggerCache.set(id, logger);
+}
+
+export async function initializeLoggers(): Promise<void> {
+	try {
+		const { getVibesRuntime } = await import('@vibesdotdev/runtime');
+		const runtime = getVibesRuntime();
+		const loggerIds = runtime.query('logging/logger').ids();
+		const errors: Array<{ id: string; error: unknown }> = [];
+
+		for (const id of loggerIds) {
+			try {
+				const logger = (await runtime.query('logging/logger').withId(id).resolve()) as LoggerImplementation;
+				loggerCache.set(id, logger);
+			} catch (error) {
+				// Collect errors for reporting but continue initializing other loggers
+				errors.push({ id, error });
+			}
+		}
+
+		// Log summary of initialization results
+		if (errors.length > 0) {
+			const fallbackLogger = createFallbackLogger('logging');
+			fallbackLogger.warn(`Failed to initialize ${errors.length} logger(s):`, {
+				loggerIds: errors.map((e) => e.id),
+				errors: errors.map((e) =>
+					e.error instanceof Error ? e.error.message : String(e.error)
+				)
+			});
+		}
+	} catch (error) {
+		// Runtime not available - this is expected in some contexts, use fallback
+		const fallbackLogger = createFallbackLogger('logging');
+		fallbackLogger.debug('Runtime not available for logger initialization, using fallback loggers', {
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+
+export interface LoggerContextProvider {
+	getLogger(id: string): LoggerImplementation;
+	getDefaultLogger(): LoggerImplementation;
+}
+
+export function createLoggerContextProvider(
+	config?: Partial<LoggerContextConfig>
+): LoggerContextProvider {
+	const mergedConfig = { ...activeConfig, ...config };
+
+	return {
+		getLogger(id: string): LoggerImplementation {
+			let logger = loggerCache.get(id);
+			if (logger) return logger;
+			logger = createFallbackLogger(id);
+			loggerCache.set(id, logger);
+			return logger;
+		},
+
+		getDefaultLogger(): LoggerImplementation {
+			return this.getLogger(mergedConfig.defaultNamespace);
+		}
+	};
+}
+
+let globalLoggerContext: LoggerContextProvider | null = null;
+
+export function getLoggerContext(): LoggerContextProvider {
+	if (!globalLoggerContext) {
+		globalLoggerContext = createLoggerContextProvider();
+	}
+	return globalLoggerContext;
+}
+
+export function setLoggerContext(provider: LoggerContextProvider): void {
+	globalLoggerContext = provider;
+}
+
+export function getLogger(id: string): LoggerImplementation {
+	return getLoggerContext().getLogger(id);
+}
+
+export function getDefaultLogger(): LoggerImplementation {
+	return getLoggerContext().getDefaultLogger();
+}

package/src/core/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Core Logging
+ *
+ * Exports logger factory and types.
+ */
+
+// Logger factory
+export { createRuntimeLogger } from './logger.ts';
+
+// Types
+export type {
+	Logger,
+	RuntimeLogger,
+	Runtime,
+	RuntimeLoggerOptions,
+	RuntimeLoggerConfig
+} from './types.ts';
+
+// Namespace utilities
+export {
+	parseNamespaceSettings,
+	parseNamespaceSettingsFromEnv,
+	matchesSelector,
+	isNamespaceIncluded,
+	shouldLog,
+	updateNamespaceSettings,
+	getNamespaceSettings,
+	defaultNamespaceSettings,
+	type NamespaceSelector,
+	type NamespaceSelectors,
+	type NamespaceSettings
+} from './namespace.ts';

package/src/core/logger.ts

@@ -0,0 +1,150 @@
+import type { SinkImplementation } from '../kinds/sink.ts';
+import type { RuntimeLogger, RuntimeLoggerOptions, RuntimeLoggerConfig } from './types.ts';
+import type {
+	LogLevel,
+	LogContext,
+	RuntimeLogEntry,
+	LoggerChildOptions,
+	RequestLogContext,
+	JobLogContext,
+	PerformanceTracker,
+	PerformanceTrackerParams
+} from '../schemas/entry.ts';
+import { shouldLog, getNamespaceSettings, type NamespaceSettings } from './namespace.ts';
+import {
+	createDefaultConsoleSink,
+	deriveChildConfig
+} from '../kinds/logger.utils';
+
+const defaultSink = createDefaultConsoleSink();
+
+function normalizeLogContext(context: unknown): LogContext {
+	if (context === undefined || context === null) {
+		return {};
+	}
+	if (context instanceof Error) {
+		return {
+			errorName: context.name,
+			errorMessage: context.message,
+			stack: context.stack
+		};
+	}
+	if (typeof context === 'object' && !Array.isArray(context)) {
+		return context as LogContext;
+	}
+	return { value: context };
+}
+
+export function createRuntimeLogger(options: RuntimeLoggerOptions): RuntimeLogger {
+	const sinks: SinkImplementation[] = options.sinkImpls ?? [defaultSink];
+
+	const config: RuntimeLoggerConfig = {
+		namespace: options.namespace,
+		fullNamespace: options.namespace,
+		runtime: options.runtime ?? 'server',
+		staticMetadata: { runtime: options.runtime ?? 'server', ...options.staticMetadata },
+		sinkIds: options.sinks ?? ['console']
+	};
+
+	const getLevelSettings = (): NamespaceSettings => {
+		const base = getNamespaceSettings();
+		if (options.level && base.defaultLevel !== options.level) {
+			return { ...base, defaultLevel: options.level };
+		}
+		return base;
+	};
+
+	const emitEntry = (level: LogLevel, message: string, ctx?: unknown, fullNs?: string): void => {
+		const ns = fullNs ?? config.namespace;
+		if (!shouldLog({ namespace: ns, level, settings: getLevelSettings() })) return;
+		const entry: RuntimeLogEntry = {
+			timestamp: new Date().toISOString(),
+			level,
+			namespace: ns,
+			message,
+			context: { ...config.staticMetadata, ...normalizeLogContext(ctx) }
+		};
+		for (const sink of sinks) {
+			try { sink.emit(entry); } catch { defaultSink.emit(entry); }
+		}
+	};
+
+	const buildLogger = (metadata: LogContext, fullNamespace: string): RuntimeLogger => {
+		const log = (level: LogLevel, message: string, ctx?: unknown) =>
+			emitEntry(
+				level,
+				message,
+				{ ...metadata, ...normalizeLogContext(ctx) },
+				fullNamespace
+			);
+
+		return {
+			namespace: config.namespace,
+			fullNamespace,
+
+			debug(message, ctx) { log('debug', message, ctx); },
+			info(message, ctx) { log('info', message, ctx); },
+			warn(message, ctx) { log('warn', message, ctx); },
+			error(message, ctx) { log('error', message, ctx); },
+
+			child(childOptions: LoggerChildOptions): RuntimeLogger {
+				const { nextNamespace, childMetadata } = deriveChildConfig(fullNamespace, childOptions);
+				return buildLogger({ ...metadata, ...childMetadata }, nextNamespace);
+			},
+
+			withContext(context: LogContext): RuntimeLogger {
+				return buildLogger({ ...metadata, ...context }, fullNamespace);
+			},
+
+			withRequestContext(context: RequestLogContext): RuntimeLogger {
+				const m = metadata;
+				return buildLogger({
+					...m,
+					requestId: context.requestId ?? m.requestId,
+					correlationId: context.correlationId ?? m.correlationId,
+					sessionId: context.sessionId ?? m.sessionId,
+					userId: context.userId ?? m.userId,
+					userAgent: context.userAgent ?? m.userAgent,
+					ip: context.ip ?? m.ip,
+					route: context.route ?? m.route,
+					method: context.method ?? m.method
+				}, fullNamespace);
+			},
+
+			withJobContext(context: JobLogContext): RuntimeLogger {
+				const m = metadata;
+				return buildLogger({
+					...m,
+					jobId: context.jobId ?? m.jobId,
+					queueId: context.queueId ?? m.queueId,
+					queueName: context.queueName ?? m.queueName,
+					toolId: context.toolId ?? m.toolId,
+					parentJobId: context.parentJobId ?? m.parentJobId,
+					attempt: context.attempt ?? m.attempt,
+					maxAttempts: context.maxAttempts ?? m.maxAttempts
+				}, fullNamespace);
+			},
+
+			performanceTracker(params: PerformanceTrackerParams): PerformanceTracker {
+				let startTime = 0;
+				const tracker = buildLogger(
+					{ ...metadata, operation: params.operation, ...params.metadata },
+					fullNamespace
+				);
+				return {
+					start() { startTime = Date.now(); tracker.debug(`operation.${params.operation}.start`); },
+					end(successContext?: LogContext) {
+						const duration = Date.now() - startTime;
+						tracker.info(`operation.${params.operation}.success`, { duration, ...successContext });
+					},
+					fail(error: unknown, errorContext?: LogContext) {
+						const duration = Date.now() - startTime;
+						tracker.error(`operation.${params.operation}.failure`, { duration, error, ...errorContext });
+					}
+				};
+			}
+		};
+	};
+
+	return buildLogger(options.staticMetadata ?? {}, config.namespace);
+}

package/src/core/namespace.ts

@@ -0,0 +1,195 @@
+/**
+ * Namespace Filtering
+ *
+ * Controls which log entries are emitted based on namespace patterns.
+ */
+
+import { type LogLevel, LOG_LEVEL_ORDER } from '../schemas/entry.ts';
+
+const DEFAULT_LEVEL: LogLevel = 'info';
+const REGEX_SPECIAL_CHARS = /[\\^$+?.()|[\]{}]/g;
+
+/**
+ * A compiled namespace selector.
+ */
+export interface NamespaceSelector {
+	raw: string;
+	regex: RegExp;
+	isExclusion: boolean;
+}
+
+/**
+ * Namespace selectors (includes and excludes).
+ */
+export interface NamespaceSelectors {
+	includes: NamespaceSelector[];
+	excludes: NamespaceSelector[];
+}
+
+/**
+ * Full namespace settings with level.
+ */
+export interface NamespaceSettings extends NamespaceSelectors {
+	defaultLevel: LogLevel;
+}
+
+type EnvRecord = Record<string, string | undefined>;
+
+/**
+ * Compile a glob pattern to regex.
+ */
+function compilePattern(pattern: string): RegExp {
+	const escaped = pattern.replace(REGEX_SPECIAL_CHARS, '\\$&').replace(/\*/g, '.*');
+	return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Parse a selector string into includes/excludes.
+ * Format: "namespace1,namespace2,-excluded1,-excluded2"
+ */
+function parseSelectors(raw: string): NamespaceSelectors {
+	const selectors: NamespaceSelectors = { includes: [], excludes: [] };
+
+	for (const token of raw.split(',').map((value) => value.trim())) {
+		if (!token) continue;
+
+		const isExclusion = token.startsWith('-');
+		const normalized = isExclusion ? token.slice(1) : token;
+		if (!normalized) continue;
+
+		const selector: NamespaceSelector = {
+			raw: normalized,
+			regex: compilePattern(normalized),
+			isExclusion
+		};
+
+		if (isExclusion) {
+			selectors.excludes.push(selector);
+		} else {
+			selectors.includes.push(selector);
+		}
+	}
+
+	return selectors;
+}
+
+/**
+ * Normalize a level string to LogLevel.
+ */
+function normalizeLevel(level?: string | null): LogLevel {
+	switch ((level || '').toLowerCase()) {
+		case 'debug':
+			return 'debug';
+		case 'warn':
+			return 'warn';
+		case 'error':
+			return 'error';
+		default:
+			return 'info';
+	}
+}
+
+/**
+ * Parse namespace settings from input string.
+ */
+export function parseNamespaceSettings({
+	input,
+	defaultLevel
+}: {
+	input?: string | null;
+	defaultLevel?: string | null;
+}): NamespaceSettings {
+	const selectors = input ? parseSelectors(input) : { includes: [], excludes: [] };
+	return {
+		...selectors,
+		defaultLevel: normalizeLevel(defaultLevel)
+	};
+}
+
+/**
+ * Parse namespace settings from environment variables.
+ */
+export function parseNamespaceSettingsFromEnv(env: EnvRecord): NamespaceSettings {
+	const logSelectors = env.VIBES_LOG ?? env.vibes_log ?? undefined;
+	const level =
+		env.VIBES_LOG_LEVEL ?? env.vibes_log_level ?? env.LOG_LEVEL ?? env.log_level ?? undefined;
+
+	return parseNamespaceSettings({
+		input: logSelectors,
+		defaultLevel: level
+	});
+}
+
+/**
+ * Check if a namespace matches a selector.
+ */
+export function matchesSelector(namespace: string, selector: NamespaceSelector): boolean {
+	return selector.regex.test(namespace);
+}
+
+/**
+ * Check if a namespace is included by settings.
+ */
+export function isNamespaceIncluded(namespace: string, settings: NamespaceSelectors): boolean {
+	const included =
+		settings.includes.length === 0 ||
+		settings.includes.some((selector) => matchesSelector(namespace, selector));
+	if (!included) return false;
+	return !settings.excludes.some((selector) => matchesSelector(namespace, selector));
+}
+
+/**
+ * Determine if a log entry should be emitted.
+ */
+export function shouldLog({
+	namespace,
+	level,
+	settings
+}: {
+	namespace: string;
+	level: LogLevel;
+	settings: NamespaceSettings;
+}): boolean {
+	const defaultLevel = settings.defaultLevel ?? DEFAULT_LEVEL;
+	const levelIndex = LOG_LEVEL_ORDER[level];
+	const baselineIndex = LOG_LEVEL_ORDER[defaultLevel] ?? LOG_LEVEL_ORDER[DEFAULT_LEVEL];
+
+	if (levelIndex >= baselineIndex) {
+		return !settings.excludes.some((selector) => matchesSelector(namespace, selector));
+	}
+
+	return settings.includes.some((selector) => matchesSelector(namespace, selector));
+}
+
+/**
+ * Default namespace settings.
+ */
+export const defaultNamespaceSettings: NamespaceSettings = {
+	includes: [],
+	excludes: [],
+	defaultLevel: DEFAULT_LEVEL
+};
+
+/**
+ * Global active namespace settings.
+ * Updated from environment or explicit configuration.
+ *
+ * Initialization is lazy: defaults are used until explicitly configured
+ * via updateNamespaceSettings(). The logging-fs plugin initializes
+ * settings from the host environment at startup automatically.
+ */
+let activeNamespaceSettings: NamespaceSettings = defaultNamespaceSettings;
+
+/**
+ * Update the active namespace settings.
+ */
+export function updateNamespaceSettings(settings: NamespaceSettings): void {
+	activeNamespaceSettings = settings;
+}
+
+/**
+ * Get the current active namespace settings.
+ */
+export function getNamespaceSettings(): NamespaceSettings {
+	return activeNamespaceSettings;
+}

package/src/core/parsing.ts

@@ -0,0 +1,21 @@
+export function parseSize(size: string | undefined): number {
+	if (!size) return 10 * 1024 * 1024;
+	const units: Record<string, number> = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+	const match = size.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/i);
+	if (!match) return 10 * 1024 * 1024;
+	return Math.floor(parseFloat(match[1]) * (units[match[2].toUpperCase()] ?? 1));
+}
+
+export function parseDuration(duration: string | undefined): number {
+	if (!duration) return 7 * 24 * 60 * 60 * 1000;
+	const units: Record<string, number> = {
+		s: 1000,
+		m: 60 * 1000,
+		h: 60 * 60 * 1000,
+		d: 24 * 60 * 60 * 1000,
+		w: 7 * 24 * 60 * 60 * 1000
+	};
+	const match = duration.match(/^(\d+)\s*(s|m|h|d|w)$/i);
+	if (!match) return 7 * 24 * 60 * 60 * 1000;
+	return parseInt(match[1], 10) * (units[match[2].toLowerCase()] ?? 1);
+}

package/src/core/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Core Logger Types
+ *
+ * Interfaces for logger instances and factories.
+ */
+
+import type {
+	LogLevel,
+	LogContext,
+	LoggerChildOptions,
+	RequestLogContext,
+	JobLogContext,
+	PerformanceTracker,
+	PerformanceTrackerParams
+} from '../schemas/entry.ts';
+import type { SinkImplementation } from '../kinds/sink.ts';
+
+/**
+ * Base logger interface.
+ */
+export interface Logger {
+	debug(message: string, context?: unknown): void;
+	info(message: string, context?: unknown): void;
+	warn(message: string, context?: unknown): void;
+	error(message: string, context?: unknown): void;
+	child?(options: LoggerChildOptions): Logger;
+	namespace?: string;
+}
+
+/**
+ * Extended runtime logger with context helpers.
+ */
+export interface RuntimeLogger extends Logger {
+	/** Create a child logger with additional context */
+	child(options: LoggerChildOptions): RuntimeLogger;
+	/** Add arbitrary context to this logger */
+	withContext(context: LogContext): RuntimeLogger;
+	/** Add request-specific context */
+	withRequestContext(context: RequestLogContext): RuntimeLogger;
+	/** Add job-specific context */
+	withJobContext(context: JobLogContext): RuntimeLogger;
+	/** Create a performance tracker for timing operations */
+	performanceTracker(params: PerformanceTrackerParams): PerformanceTracker;
+	/** Logger namespace */
+	namespace: string;
+	/** Full namespace path (including parent namespaces) */
+	fullNamespace: string;
+}
+
+/**
+ * Runtime type identifier.
+ */
+export type Runtime = 'server' | 'cli' | 'worker' | 'browser' | 'mcp';
+
+/**
+ * Options for creating a runtime logger.
+ */
+export interface RuntimeLoggerOptions {
+	/** Base namespace (e.g., 'vibes', 'pm') */
+	namespace: string;
+	/** Runtime environment */
+	runtime?: Runtime;
+	/** Override default log level */
+	level?: LogLevel;
+	/** Static metadata added to all entries */
+	staticMetadata?: LogContext;
+	/** Custom sink IDs for runtime resolution */
+	sinks?: string[];
+	/** Direct sink implementations (bypasses runtime resolution) */
+	sinkImpls?: SinkImplementation[];
+}
+
+/**
+ * Internal logger configuration.
+ */
+export interface RuntimeLoggerConfig {
+	namespace: string;
+	fullNamespace: string;
+	runtime: Runtime;
+	staticMetadata: LogContext;
+	sinkIds: string[];
+}