@vibesdotdev/logging 0.0.1

package/src/kinds/logger.impl.ts

@@ -0,0 +1,206 @@
+import type { LoggerDescriptor } from '../schemas/logger.ts';
+import type {
+	LogLevel,
+	LogContext,
+	RuntimeLogEntry,
+	LoggerChildOptions,
+	RequestLogContext,
+	JobLogContext,
+	PerformanceTrackerParams,
+	PerformanceTracker
+} from '../schemas/entry.ts';
+export type { PerformanceTracker } from '../schemas/entry.ts';
+import type { SinkImplementation } from './sink.ts';
+import type { OutputImplementation } from './output.ts';
+import type { LoggerContext } from './contexts.ts';
+import { shouldLog, getNamespaceSettings, type NamespaceSettings } from '../core/namespace.ts';
+import {
+	resolveSinkContext,
+	resolveOutputContext,
+	createDefaultConsoleSink,
+	deriveChildConfig,
+	resolveSinks,
+	resolveOutputs
+} from './logger.utils';
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+
+export type { LoggerContext } from './contexts.ts';
+
+const defaultSink = createDefaultConsoleSink();
+
+export interface LoggerImplementation {
+	readonly namespace: string;
+	readonly fullNamespace: string;
+	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): LoggerImplementation;
+	withContext(context: LogContext): LoggerImplementation;
+	withRequestContext(context: RequestLogContext): LoggerImplementation;
+	withJobContext(context: JobLogContext): LoggerImplementation;
+	performanceTracker(params: PerformanceTrackerParams): PerformanceTracker;
+}
+
+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 default class DefaultLoggerImplementation implements LoggerImplementation {
+	readonly namespace: string;
+	readonly fullNamespace: string;
+	private readonly descriptor: LoggerDescriptor;
+	private readonly sinks: SinkImplementation[];
+	private readonly outputs: OutputImplementation[];
+	private readonly staticMetadata: LogContext;
+
+	constructor(
+		descriptor: RuntimeDescriptor,
+		context: KindContext,
+		fullNamespace?: string,
+		additionalMetadata?: LogContext
+	) {
+		this.descriptor = descriptor as LoggerDescriptor;
+		this.namespace = (descriptor as LoggerDescriptor).namespace;
+		this.fullNamespace = fullNamespace ?? (descriptor as LoggerDescriptor).namespace;
+		const typedCtx = context as LoggerContext;
+		this.sinks = resolveSinks(descriptor as LoggerDescriptor, resolveSinkContext(typedCtx), defaultSink);
+		this.outputs = resolveOutputs(descriptor as LoggerDescriptor, resolveOutputContext(typedCtx));
+		this.staticMetadata = {
+			runtime: (descriptor as LoggerDescriptor).runtime,
+			...(descriptor as LoggerDescriptor).metadata,
+			...additionalMetadata
+		};
+	}
+
+	private getLevelSettings(): NamespaceSettings {
+		const base = getNamespaceSettings();
+		if (this.descriptor.level && base.defaultLevel !== this.descriptor.level) {
+			return { ...base, defaultLevel: this.descriptor.level };
+		}
+		return base;
+	}
+
+	private emit(level: LogLevel, message: string, context?: unknown): void {
+		const settings = this.getLevelSettings();
+		if (!shouldLog({ namespace: this.fullNamespace, level, settings })) return;
+
+		const entry: RuntimeLogEntry = {
+			timestamp: new Date().toISOString(),
+			level,
+			namespace: this.fullNamespace,
+			message,
+			context: { ...this.staticMetadata, ...normalizeLogContext(context) }
+		};
+
+		for (const sink of this.sinks) {
+			try {
+				sink.emit(entry);
+			} catch (e) {
+				defaultSink.emit(entry);
+			}
+		}
+
+		for (const output of this.outputs) {
+			try {
+				output.write(entry).catch(() => {});
+			} catch {
+				/* output sync error */
+			}
+		}
+	}
+
+	debug(message: string, context?: unknown): void { this.emit('debug', message, context); }
+	info(message: string, context?: unknown): void { this.emit('info', message, context); }
+	warn(message: string, context?: unknown): void { this.emit('warn', message, context); }
+	error(message: string, context?: unknown): void { this.emit('error', message, context); }
+
+	private createContextualLogger(merged: LogContext): LoggerImplementation {
+		return new DefaultLoggerImplementation(
+			this.descriptor,
+			{ runtime: undefined, sinks: this.sinks, outputs: this.outputs },
+			this.fullNamespace,
+			merged
+		);
+	}
+
+	child(options: LoggerChildOptions): LoggerImplementation {
+		const { nextNamespace, childMetadata } = deriveChildConfig(this.fullNamespace, options);
+		return new DefaultLoggerImplementation(
+			this.descriptor,
+			{ runtime: undefined, sinks: this.sinks, outputs: this.outputs },
+			nextNamespace,
+			{ ...this.staticMetadata, ...childMetadata }
+		);
+	}
+
+	withContext(context: LogContext): LoggerImplementation {
+		return this.createContextualLogger({ ...this.staticMetadata, ...context });
+	}
+
+	withRequestContext(context: RequestLogContext): LoggerImplementation {
+		const s = this.staticMetadata;
+		return this.createContextualLogger({
+			...s,
+			requestId: context.requestId ?? s.requestId,
+			correlationId: context.correlationId ?? s.correlationId,
+			sessionId: context.sessionId ?? s.sessionId,
+			userId: context.userId ?? s.userId,
+			userAgent: context.userAgent ?? s.userAgent,
+			ip: context.ip ?? s.ip,
+			route: context.route ?? s.route,
+			method: context.method ?? s.method
+		});
+	}
+
+	withJobContext(context: JobLogContext): LoggerImplementation {
+		const s = this.staticMetadata;
+		return this.createContextualLogger({
+			...s,
+			jobId: context.jobId ?? s.jobId,
+			queueId: context.queueId ?? s.queueId,
+			queueName: context.queueName ?? s.queueName,
+			toolId: context.toolId ?? s.toolId,
+			parentJobId: context.parentJobId ?? s.parentJobId,
+			attempt: context.attempt ?? s.attempt,
+			maxAttempts: context.maxAttempts ?? s.maxAttempts
+		});
+	}
+
+	performanceTracker(params: PerformanceTrackerParams): PerformanceTracker {
+		let startTime = 0;
+		const tracker = this.withContext({ 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
+				});
+			}
+		};
+	}
+}

package/src/kinds/logger.ts

@@ -0,0 +1,46 @@
+import type { RuntimeKindDescriptor, KindContext, RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import { LoggerDescriptorSchema, type LoggerDescriptor } from '../schemas/logger.ts';
+import DefaultLoggerImplementation, { type LoggerImplementation } from './logger.impl';
+import type { LoggerContext } from './contexts.ts';
+
+export type { LoggerImplementation, LoggerContext };
+
+function resolveLogger(
+	candidates: RuntimeDescriptor[],
+	scope: RuntimeScope,
+	_context: KindContext
+): LoggerDescriptor | undefined {
+	const typed = candidates as LoggerDescriptor[];
+	if (typed.length === 0) return undefined;
+	if (typed.length === 1) return typed[0];
+
+	const purposeToRuntime: Record<string, string> = {
+		cli: 'cli',
+		worker: 'worker',
+		mcp: 'mcp',
+		agent: 'server'
+	};
+	const runtime = purposeToRuntime[scope.purpose ?? ''] ?? 'server';
+	const matching = typed.filter((d) => d.runtime === runtime);
+	if (matching.length > 0) return matching[0];
+	return typed[0];
+}
+
+export const loggerKind: RuntimeKindDescriptor<
+	LoggerDescriptor,
+	LoggerImplementation,
+	LoggerContext
+> = {
+	id: 'logging/logger',
+	descriptorSchema: LoggerDescriptorSchema,
+	defaultImplementation: DefaultLoggerImplementation,
+	resolve: resolveLogger,
+	contexts: ['logging/sinks', 'logging/outputs']
+};
+
+declare module '@vibesdotdev/runtime/schemas/kind-types' {
+	interface KindTypeMap {
+		'logging/logger': { descriptor: LoggerDescriptor; impl: LoggerImplementation };
+	}
+}

package/src/kinds/logger.utils.ts

@@ -0,0 +1,91 @@
+import type { LoggerDescriptor } from '../schemas/logger.ts';
+import type { LogContext, LoggerChildOptions } from '../schemas/entry.ts';
+import type { SinkImplementation } from './sink.ts';
+import type { OutputImplementation } from './output.ts';
+import type { LoggerContext } from './contexts.ts';
+
+export function resolveSinkContext(
+	context: LoggerContext
+): Map<string, SinkImplementation> | SinkImplementation[] | undefined {
+	const runtimeKeyed = (
+		context as LoggerContext & {
+			'logging/sinks'?: Map<string, SinkImplementation> | SinkImplementation[];
+		}
+	)['logging/sinks'];
+	return context.sinks ?? runtimeKeyed;
+}
+
+export function resolveOutputContext(
+	context: LoggerContext
+): Map<string, OutputImplementation> | OutputImplementation[] | undefined {
+	const runtimeKeyed = (
+		context as LoggerContext & {
+			'logging/outputs'?: Map<string, OutputImplementation> | OutputImplementation[];
+		}
+	)['logging/outputs'];
+	return context.outputs ?? runtimeKeyed;
+}
+
+export function createDefaultConsoleSink(): SinkImplementation {
+	return {
+		emit(entry: { level: string; namespace: string; message: string; context: LogContext }): void {
+			const payload = JSON.stringify(entry.context);
+			const line = `[${entry.level.toUpperCase()}] [${entry.namespace}] ${entry.message} ${payload}`;
+			console.error(line);
+		}
+	};
+}
+
+export function deriveChildConfig(
+	parentNamespace: string,
+	options: LoggerChildOptions
+): { nextNamespace: string; childMetadata: LogContext } {
+	if (typeof options === 'string') {
+		return { nextNamespace: `${parentNamespace}:${options}`, childMetadata: {} };
+	}
+	const namespaceSuffix =
+		typeof options.namespace === 'string'
+			? options.namespace
+			: typeof options.context === 'string'
+				? options.context
+				: undefined;
+	return {
+		nextNamespace: namespaceSuffix ? `${parentNamespace}:${namespaceSuffix}` : parentNamespace,
+		childMetadata: { ...options }
+	};
+}
+
+export function resolveSinks(
+	descriptor: LoggerDescriptor,
+	resolvedSinkContext: Map<string, SinkImplementation> | SinkImplementation[] | undefined,
+	fallback: SinkImplementation
+): SinkImplementation[] {
+	if (resolvedSinkContext instanceof Map) {
+		const resolved =
+			descriptor.sinks
+				?.map((id) => resolvedSinkContext.get(id))
+				.filter((s): s is SinkImplementation => s !== undefined) ?? [];
+		return resolved.length > 0 ? resolved : [fallback];
+	}
+	if (Array.isArray(resolvedSinkContext) && resolvedSinkContext.length > 0) {
+		return resolvedSinkContext;
+	}
+	return [fallback];
+}
+
+export function resolveOutputs(
+	descriptor: LoggerDescriptor,
+	resolvedOutputContext: Map<string, OutputImplementation> | OutputImplementation[] | undefined
+): OutputImplementation[] {
+	if (resolvedOutputContext instanceof Map) {
+		return (
+			descriptor.outputs
+				?.map((id) => resolvedOutputContext.get(id))
+				.filter((o): o is OutputImplementation => o !== undefined) ?? []
+		);
+	}
+	if (Array.isArray(resolvedOutputContext) && resolvedOutputContext.length > 0) {
+		return resolvedOutputContext;
+	}
+	return [];
+}

package/src/kinds/output.contracts.ts

@@ -0,0 +1,54 @@
+/**
+ * Output kind contract types.
+ *
+ * Extracted from `./output.ts` so the default implementation
+ * (`./output.impl.ts`) can implement these contracts without forming a
+ * cycle (output.ts itself imports the default implementation to wire it
+ * into the kind descriptor).
+ */
+
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeLogEntry } from '../schemas/entry.ts';
+import type { FormatterImplementation } from './formatter.ts';
+
+export interface OutputReadOptions {
+	lines?: number;
+	offset?: number;
+	filter?: string | RegExp;
+	ignoreCase?: boolean;
+}
+
+export interface OutputTailOptions {
+	lines?: number;
+	filter?: string | RegExp;
+	ignoreCase?: boolean;
+}
+
+export interface TailHandle {
+	close(): void;
+}
+
+export interface OutputStats {
+	size: number;
+	lines?: number;
+	modifiedAt?: Date;
+	exists: boolean;
+}
+
+export interface OutputImplementation {
+	write(entry: RuntimeLogEntry): Promise<void>;
+	writeBatch?(entries: RuntimeLogEntry[]): Promise<void>;
+	writeLine?(line: string): Promise<void>;
+	flush(): Promise<void>;
+	close(): Promise<void>;
+	rotate?(): Promise<{ archived: string }>;
+	read(options?: OutputReadOptions): Promise<string[]>;
+	tail(callback: (line: string) => void, options?: OutputTailOptions): TailHandle;
+	stats(): Promise<OutputStats>;
+}
+
+export interface OutputContext extends KindContext {
+	readonly runtime: unknown;
+	readonly formatter?: FormatterImplementation;
+	readonly workspacePath?: string;
+}

package/src/kinds/output.impl.ts

@@ -0,0 +1,118 @@
+import type {
+	OutputReadOptions,
+	OutputTailOptions,
+	TailHandle,
+	OutputStats,
+	OutputImplementation,
+	OutputContext
+} from './output.types';
+import type { OutputDescriptor } from '../schemas/output.ts';
+import type { RuntimeLogEntry } from '../schemas/entry.ts';
+import type { RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+
+export class DefaultOutputImplementation implements OutputImplementation {
+	readonly id: string;
+	private readonly descriptor: OutputDescriptor;
+	private readonly context: OutputContext;
+	private delegate: OutputImplementation | null = null;
+	private delegatePromise: Promise<OutputImplementation> | null = null;
+	private pendingTailCloses: Array<() => void> = [];
+
+	constructor(
+		descriptor: RuntimeDescriptor,
+		context: KindContext
+	) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor as OutputDescriptor;
+		this.context = context as OutputContext;
+	}
+
+	private async resolveDelegate(): Promise<OutputImplementation> {
+		if (this.delegate) return this.delegate;
+
+		const storage = this.descriptor.storage ?? 'file';
+		const runtime = this.context.runtime as {
+			query(kind: string): {
+				withId(id: string): { resolve<T>(): Promise<T> };
+			};
+			hasKind(kind: string): boolean;
+		} | null;
+
+		if (runtime && runtime.hasKind('logging/output')) {
+			try {
+				const storageImpl = await runtime
+					.query('logging/output')
+					.withId(storage)
+					.resolve<OutputImplementation>();
+
+				const ImplClass = storageImpl.constructor as new (
+					descriptor: OutputDescriptor,
+					context: OutputContext
+				) => OutputImplementation;
+				this.delegate = new ImplClass(this.descriptor, this.context);
+				return this.delegate;
+			} catch {
+				// Fall through to error
+			}
+		}
+
+		throw new Error(
+			`No output implementation available for '${this.id}' (storage: ${storage}). ` +
+				`Ensure a '${storage}' output descriptor and implementation are registered.`
+		);
+	}
+
+	private getDelegatePromise(): Promise<OutputImplementation> {
+		if (this.delegate) return Promise.resolve(this.delegate);
+		if (!this.delegatePromise) {
+			this.delegatePromise = this.resolveDelegate().finally(() => {
+				this.delegatePromise = null;
+			});
+		}
+		return this.delegatePromise;
+	}
+
+	async write(entry: RuntimeLogEntry): Promise<void> {
+		return (await this.getDelegatePromise()).write(entry);
+	}
+
+	async flush(): Promise<void> {
+		return (await this.getDelegatePromise()).flush();
+	}
+
+	async close(): Promise<void> {
+		return (await this.getDelegatePromise()).close();
+	}
+
+	async read(options?: OutputReadOptions): Promise<string[]> {
+		return (await this.getDelegatePromise()).read(options);
+	}
+
+	tail(callback: (line: string) => void, options?: OutputTailOptions): TailHandle {
+		let handle: TailHandle | null = null;
+		let closed = false;
+
+		this.getDelegatePromise().then((delegate) => {
+			if (closed) return;
+			handle = delegate.tail(callback, options);
+			for (const closeOp of this.pendingTailCloses) closeOp();
+			this.pendingTailCloses = [];
+		});
+
+		return {
+			close: () => {
+				closed = true;
+				if (handle) {
+					handle.close();
+				} else {
+					this.pendingTailCloses.push(() => handle?.close());
+				}
+			}
+		};
+	}
+
+	async stats(): Promise<OutputStats> {
+		return (await this.getDelegatePromise()).stats();
+	}
+}

package/src/kinds/output.ts

@@ -0,0 +1,59 @@
+import type { RuntimeKindDescriptor, KindContext, RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import { OutputDescriptorSchema, type OutputDescriptor } from '../schemas/output.ts';
+import type { FormatterImplementation } from './formatter.ts';
+import { DefaultOutputImplementation } from './output.impl';
+import type { OutputImplementation } from './output.types';
+
+export type {
+	OutputReadOptions,
+	OutputTailOptions,
+	TailHandle,
+	OutputStats,
+	OutputImplementation
+} from './output.types';
+
+export interface OutputContext extends KindContext {
+	readonly runtime: unknown;
+	readonly formatter?: FormatterImplementation;
+	readonly workspacePath?: string;
+}
+
+function resolveOutput(
+	candidates: RuntimeDescriptor[],
+	scope: RuntimeScope,
+	_context: KindContext
+): OutputDescriptor | undefined {
+	const typed = candidates as OutputDescriptor[];
+	if (typed.length === 0) return undefined;
+	if (typed.length === 1) return typed[0];
+
+	const hardware = scope.hardware;
+	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;
+	const explicit = matching.filter((d) => d.hardware && d.hardware.length > 0);
+	if (explicit.length > 0) return explicit[0];
+	return matching[0];
+}
+
+export const outputKind: RuntimeKindDescriptor<
+	OutputDescriptor,
+	OutputImplementation,
+	OutputContext
+> = {
+	id: 'logging/output',
+	descriptorSchema: OutputDescriptorSchema,
+	defaultImplementation: DefaultOutputImplementation,
+	resolve: resolveOutput,
+	contexts: ['runtime/workspace-path']
+};
+
+declare module '@vibesdotdev/runtime/schemas/kind-types' {
+	interface KindTypeMap {
+		'logging/output': { descriptor: OutputDescriptor; impl: OutputImplementation };
+	}
+}

package/src/kinds/output.types.ts

@@ -0,0 +1,105 @@
+/**
+ * Output Type Definitions
+ *
+ * Type-only definitions to avoid circular dependencies.
+ */
+
+import type { RuntimeLogEntry } from '../schemas/entry.ts';
+import type { KindContext } from '@vibesdotdev/runtime/schemas/kind';
+import type { FormatterImplementation } from './formatter.ts';
+
+/**
+ * Options for reading from an output
+ */
+export interface OutputReadOptions {
+	/** Number of lines to read */
+	lines?: number;
+	/** Offset to start reading from */
+	offset?: number;
+	/** Filter pattern */
+	filter?: string | RegExp;
+	/** Whether to ignore case when filtering */
+	ignoreCase?: boolean;
+}
+
+/**
+ * Options for tailing an output
+ */
+export interface OutputTailOptions {
+	/** Number of lines to tail */
+	lines?: number;
+	/** Filter pattern */
+	filter?: string | RegExp;
+	/** Whether to ignore case when filtering */
+	ignoreCase?: boolean;
+}
+
+/**
+ * Handle for controlling a tail operation
+ */
+export interface TailHandle {
+	/** Close the tail operation */
+	close(): void;
+}
+
+/**
+ * Statistics about an output
+ */
+export interface OutputStats {
+	/** Size in bytes */
+	size: number;
+	/** Number of lines (if applicable) */
+	lines?: number;
+	/** Last modification time */
+	modifiedAt?: Date;
+	/** Whether the output exists */
+	exists: boolean;
+}
+
+/**
+ * Context provided to output implementations.
+ */
+export interface OutputContext extends KindContext {
+	/** Runtime reference */
+	readonly runtime: unknown;
+	/** Formatter to use for this output */
+	readonly formatter?: FormatterImplementation;
+	/** Workspace path for file outputs */
+	readonly workspacePath?: string;
+}
+
+/**
+ * Output implementation interface.
+ * Implementations write log entries to their destination.
+ */
+export interface OutputImplementation {
+	/** Unique identifier for this output */
+	readonly id: string;
+
+	/** Write a single log entry */
+	write(entry: RuntimeLogEntry): Promise<void>;
+
+	/** Write multiple entries in batch (optional optimization) */
+	writeBatch?(entries: RuntimeLogEntry[]): Promise<void>;
+
+	/** Write a raw line (optional) */
+	writeLine?(line: string): Promise<void>;
+
+	/** Flush any buffered entries */
+	flush(): Promise<void>;
+
+	/** Close the output and release resources */
+	close(): Promise<void>;
+
+	/** Rotate the output file (optional) */
+	rotate?(): Promise<{ archived: string }>;
+
+	/** Read entries from the output */
+	read(options?: OutputReadOptions): Promise<string[]>;
+
+	/** Tail the output for new entries */
+	tail(callback: (line: string) => void, options?: OutputTailOptions): TailHandle;
+
+	/** Get statistics about the output */
+	stats(): Promise<OutputStats>;
+}