@vibesdotdev/logging 0.0.1

package/src/kinds/sink.ts

@@ -0,0 +1,100 @@
+/**
+ * Logging Sink Kind Definition
+ *
+ * Sinks are output destinations for log entries.
+ */
+
+import type { RuntimeKindDescriptor, KindContext, RuntimeDescriptor } from '@vibesdotdev/runtime/schemas/kind';
+import type { RuntimeScope } from '@vibesdotdev/runtime/schemas/scope';
+import { SinkDescriptorSchema, type SinkDescriptor } from '../schemas/sink.ts';
+import type { RuntimeLogEntry } from '../schemas/entry.ts';
+
+/**
+ * Sink implementation interface.
+ * Implementations emit log entries to their destination.
+ */
+export interface SinkImplementation {
+	/** Emit a log entry to this sink */
+	emit(entry: RuntimeLogEntry): void | Promise<void>;
+	/** Flush any buffered entries */
+	flush?(): Promise<void>;
+	/** Close the sink and release resources */
+	close?(): Promise<void>;
+}
+
+/**
+ * Context provided to sink implementations.
+ */
+export interface SinkContext extends KindContext {
+	/** Runtime reference */
+	readonly runtime: unknown;
+}
+
+/**
+ * Default sink implementation - console output.
+ * Used when no specific implementation is registered.
+ */
+class DefaultSinkImplementation implements SinkImplementation {
+	readonly id: string;
+	readonly descriptor: SinkDescriptor;
+
+	constructor(descriptor: RuntimeDescriptor, _context: SinkContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor as SinkDescriptor;
+	}
+
+	emit(entry: RuntimeLogEntry): void {
+		const { level, namespace, message, context } = entry;
+		const prefix = `[${namespace}]`;
+		const payload = JSON.stringify(context);
+		const line = `[${level.toUpperCase()}] ${prefix} ${message} ${payload}`;
+		console.error(line);
+	}
+}
+
+/**
+ * Sink kind resolution logic.
+ * Selects sink based on hardware compatibility.
+ */
+function resolveSink(
+	candidates: RuntimeDescriptor[],
+	scope: RuntimeScope,
+	_context: KindContext
+): SinkDescriptor | undefined {
+	const typed = candidates as SinkDescriptor[];
+	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 sinks 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];
+}
+
+/**
+ * Sink kind definition for runtime registration.
+ */
+export const sinkKind: RuntimeKindDescriptor<SinkDescriptor, SinkImplementation, SinkContext> = {
+	id: 'logging/sink',
+	descriptorSchema: SinkDescriptorSchema,
+	defaultImplementation: DefaultSinkImplementation,
+	resolve: resolveSink,
+	contexts: []
+};
+
+declare module '@vibesdotdev/runtime/schemas/kind-types' {
+	interface KindTypeMap {
+		'logging/sink': { descriptor: SinkDescriptor; impl: SinkImplementation };
+	}
+}

package/src/logger.context.descriptor.ts

@@ -0,0 +1,13 @@
+/**
+ * CLI Logger Context Descriptor
+ *
+ * Provides logger instance for CLI surface.
+ */
+
+import { createContextDescriptor } from '@vibesdotdev/runtime/factory/context';
+
+export default createContextDescriptor({
+	id: 'cli/logger',
+	description: 'Logger instance for CLI and terminal output.',
+	hardware: ['consumer']
+});

package/src/logging.cli.plugin.ts

@@ -0,0 +1,43 @@
+/**
+ * Logging CLI Slice Plugin
+ *
+ * Registers the `vibes logs *` CLI surface (group + commands) against the
+ * `cli/group` and `cli/command` kinds owned by `@vibesdotdev/cli`.
+ *
+ * Per docs/architecture/RUNTIME-FIRST-MODULES.md §What Surfaces Are Allowed To Do
+ * and §Plugin Composition Rules, CLI is a surface adapter. The core
+ * `@vibesdotdev/logging/plugin` registers logging kinds and sinks/formatters/
+ * outputs that every consumer needs; this slice plugin layers the CLI surface
+ * on top so SSR/web/worker apps can consume logging without dragging the CLI
+ * machinery into their plugin chain.
+ *
+ * Apps that ship a CLI surface (account, ai, tools, cli-bin, etc.) should
+ * include both `@vibesdotdev/cli/cli.plugin` and `@vibesdotdev/logging/cli.plugin`
+ * after the core logging plugin in their `vibes.config.ts`.
+ */
+
+import { createRuntimePlugin, loader } from '@vibesdotdev/runtime';
+
+import logsGroup from './cli/logs.descriptor';
+import logsList from './cli/logs.list.descriptor';
+import logsSearch from './cli/logs.search.descriptor';
+import logsTail from './cli/logs.tail.descriptor';
+import logsRotate from './cli/logs.rotate.descriptor';
+import logsView from './cli/logs.view.descriptor';
+
+export default createRuntimePlugin({
+	id: 'logging.cli',
+	name: 'Logging CLI Surface',
+	description: '`vibes logs *` CLI commands for viewing, searching, tailing, rotating logs',
+	dependencies: ['logging', 'cli'],
+
+	descriptors: [logsGroup, logsList, logsSearch, logsTail, logsRotate, logsView],
+
+	loaders: [
+		loader('logs.list', { kind: 'cli/command' }, () => import('./cli/logs.list.impl.ts')),
+		loader('logs.search', { kind: 'cli/command' }, () => import('./cli/logs.search.impl.ts')),
+		loader('logs.tail', { kind: 'cli/command' }, () => import('./cli/logs.tail.impl.ts')),
+		loader('logs.rotate', { kind: 'cli/command' }, () => import('./cli/logs.rotate.impl.ts')),
+		loader('logs.view', { kind: 'cli/command' }, () => import('./cli/logs.view.impl.ts'))
+	]
+});

package/src/logging.plugin.ts

@@ -0,0 +1,93 @@
+/**
+ * Logging Plugin
+ *
+ * Registers logging kinds (sink, formatter, output, audit, logger) with the
+ * runtime. Context providers for 'logging/sinks' and 'logging/outputs' are
+ * autoloaded.
+ *
+ * Surface-neutral: depends only on `context`. Apps that ship a CLI surface
+ * (cli-bin, account, ai, tools) layer `@vibesdotdev/logging/cli.plugin` on
+ * top to register the `vibes logs *` commands. SSR/web/worker apps where
+ * `@vibesdotdev/cli` is shimmed out by the cloud build must NOT pull in the
+ * CLI slice — see logging.cli.plugin.ts.
+ */
+
+import {
+	createRuntimePlugin,
+	type AnyRuntimeKindDescriptor
+} from '@vibesdotdev/runtime';
+import { loader } from '@vibesdotdev/runtime';
+import { sinkKind, formatterKind, outputKind, auditKind, loggerKind } from './kinds/index.ts';
+import sinksContextDescriptor from './sinks.context.descriptor';
+import outputsContextDescriptor from './outputs.context.descriptor';
+import cliLoggerContextDescriptor from './logger.context.descriptor';
+import consoleSinkDescriptor from './sinks/console/console.descriptor';
+import bufferSinkDescriptor from './sinks/buffer/buffer.descriptor';
+import stdoutSinkDescriptor from './sinks/stdout/stdout.descriptor';
+import memorySinkDescriptor from './sinks/memory/memory.descriptor';
+import prettyFormatterDescriptor from './formatters/pretty/pretty.descriptor';
+import json5FormatterDescriptor from './formatters/json5/json5.descriptor';
+import jsonlFormatterDescriptor from './formatters/jsonl/jsonl.descriptor';
+import jsonFormatterDescriptor from './formatters/json/json.formatters.descriptor';
+import remoteOutputDescriptor from './outputs/remote/remote.descriptor';
+import defaultAuditDescriptor, { authenticationAuditDescriptor, securityAuditDescriptor } from './audit/audit.descriptor';
+
+// Docs
+import levelsDescriptor from './docs/levels.docs.descriptor';
+import transportsDescriptor from './docs/transports.docs.descriptor';
+import structuredDescriptor from './docs/structured.docs.descriptor';
+
+export default createRuntimePlugin({
+	id: 'logging',
+	name: 'Logging Module',
+	description: 'Structured logging with sinks, formatters, outputs, and audit trails',
+	dependencies: ['context'],
+
+	// Cast required: kind descriptors use specific TDescriptor types which are
+	// contravariant in the defaultImplementation constructor parameter.
+	kinds: [
+		sinkKind,
+		formatterKind,
+		outputKind,
+		auditKind,
+		loggerKind
+	] as AnyRuntimeKindDescriptor[],
+
+	descriptors: [
+		sinksContextDescriptor,
+		outputsContextDescriptor,
+		cliLoggerContextDescriptor,
+		consoleSinkDescriptor,
+		bufferSinkDescriptor,
+		stdoutSinkDescriptor,
+		memorySinkDescriptor,
+		prettyFormatterDescriptor,
+		json5FormatterDescriptor,
+		jsonlFormatterDescriptor,
+		jsonFormatterDescriptor,
+		remoteOutputDescriptor,
+		defaultAuditDescriptor,
+		authenticationAuditDescriptor,
+		securityAuditDescriptor,
+		levelsDescriptor,
+		transportsDescriptor,
+		structuredDescriptor
+	],
+
+	loaders: [
+		loader(sinksContextDescriptor.id, { kind: 'context' }, () => import('./sinks.context.impl.ts')),
+		loader(outputsContextDescriptor.id, { kind: 'context' }, () =>
+			import('./outputs.context.impl.ts')
+		),
+		loader('console', { kind: 'logging/sink' }, () => import('./sinks/console/console.impl.cli.ts')),
+		loader('console', { kind: 'logging/sink', scope: 'browser' }, () => import('./sinks/console/console.impl.browser.ts')),
+		loader('buffer', { kind: 'logging/sink' }, () => import('./sinks/buffer/buffer.impl.cli.ts')),
+		loader('stdout', { kind: 'logging/sink' }, () => import('./sinks/stdout/stdout.impl.cli.ts')),
+		loader('memory', { kind: 'logging/sink' }, () => import('./sinks/memory/memory.impl.ts')),
+		loader('pretty', { kind: 'logging/formatter' }, () => import('./formatters/pretty/pretty.impl.cli.ts')),
+		loader('json5', { kind: 'logging/formatter' }, () => import('./formatters/json5/json5.impl.ts')),
+		loader('jsonl', { kind: 'logging/formatter' }, () => import('./formatters/jsonl/jsonl.impl.ts')),
+		loader('json', { kind: 'logging/formatter' }, () => import('./formatters/json/json.impl.ts')),
+		loader('remote', { kind: 'logging/output' }, () => import('./outputs/remote/remote.impl.ts'))
+	]
+});

package/src/outputs/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Logging Outputs
+ *
+ * Descriptors and implementations are autoloaded by the runtime.
+ * No public API — use the runtime to resolve output implementations.
+ */

package/src/outputs/remote/remote.descriptor.ts

@@ -0,0 +1,27 @@
+/**
+ * Remote Output Descriptor
+ *
+ * Sends logs to a remote HTTP endpoint.
+ * Cloud hardware target.
+ */
+
+import type { OutputDescriptor } from '../../schemas/output.ts';
+
+export const remoteOutputDescriptor: OutputDescriptor = {
+	kind: 'logging/output',
+	id: 'remote',
+	name: 'Remote Output',
+	description: 'Sends logs to a remote HTTP endpoint',
+	tags: ['cloud', 'centralized'],
+	hardware: ['cloud'],
+	storage: 'remote',
+	format: 'jsonl',
+	buffering: {
+		enabled: true,
+		size: 16384,
+		flushInterval: 5000,
+		maxBufferEntries: 5000
+	}
+};
+
+export default remoteOutputDescriptor;

package/src/outputs/remote/remote.impl.ts

@@ -0,0 +1,218 @@
+/**
+ * Remote Output Implementation
+ *
+ * Batched HTTP delivery to a logging endpoint.
+ */
+
+import type {
+	OutputImplementation,
+	OutputContext,
+	OutputReadOptions,
+	OutputTailOptions,
+	TailHandle,
+	OutputStats
+} from '../../kinds/output.ts';
+import type { OutputDescriptor, OutputBuffering } from '../../schemas/output.ts';
+import type { RuntimeLogEntry } from '../../schemas/entry.ts';
+import type { FormatterImplementation } from '../../kinds/formatter.ts';
+import { getDefaultLogger } from '../../contexts/logger.ts';
+const logger = getDefaultLogger();
+
+/** Default remote endpoint */
+const DEFAULT_ENDPOINT = 'http://localhost:3000/api/logs';
+
+/** Metrics for buffer operations */
+interface BufferMetrics {
+	/** Total entries added to buffer */
+	added: number;
+	/** Total entries sent successfully */
+	sent: number;
+	/** Total entries dropped due to buffer overflow */
+	dropped: number;
+	/** Total failed sends that were re-buffered for retry */
+	retried: number;
+}
+
+/**
+ * Remote output - sends logs via HTTP.
+ */
+export default class RemoteOutput implements OutputImplementation {
+	readonly id: string;
+	readonly descriptor: OutputDescriptor;
+	private readonly formatter: FormatterImplementation;
+	private readonly endpoint: string;
+	private readonly buffering: OutputBuffering;
+	private readonly maxBufferEntries: number;
+
+	private buffer: RuntimeLogEntry[] = [];
+	private flushTimer: ReturnType<typeof setInterval> | null = null;
+	private isFlushing = false;
+	private metrics: BufferMetrics = { added: 0, sent: 0, dropped: 0, retried: 0 };
+
+	constructor(descriptor: OutputDescriptor, context: OutputContext) {
+		this.id = descriptor.id;
+		this.descriptor = descriptor;
+
+		// Use formatter from context or create default
+		this.formatter = context.formatter ?? {
+			format: (e: RuntimeLogEntry) => JSON.stringify(e),
+			parse: (s: string) => JSON.parse(s) as RuntimeLogEntry,
+			formatBatch: (entries: RuntimeLogEntry[]) => entries.map((e) => JSON.stringify(e)).join('\n')
+		};
+
+		// Configuration
+		this.endpoint = descriptor.endpoint ?? DEFAULT_ENDPOINT;
+		this.buffering = descriptor.buffering ?? {
+			enabled: true,
+			size: 16384,
+			flushInterval: 5000,
+			maxBufferEntries: 10000
+		};
+		this.maxBufferEntries = this.buffering.maxBufferEntries ?? 10000;
+
+		// Start flush timer if buffering enabled
+		if (this.buffering.enabled && this.buffering.flushInterval) {
+			this.flushTimer = setInterval(() => {
+				this.flush().catch((err) => logger.error('Remote output flush error', { error: err }));
+			}, this.buffering.flushInterval);
+			this.flushTimer.unref?.();
+		}
+	}
+
+	/** Get current buffer metrics */
+	getMetrics(): BufferMetrics {
+		return { ...this.metrics };
+	}
+
+	/** Get current buffer size */
+	getBufferSize(): number {
+		return this.buffer.length;
+	}
+
+	private addToBuffer(entries: RuntimeLogEntry[]): void {
+		const spaceAvailable = this.maxBufferEntries - this.buffer.length;
+
+		if (entries.length <= spaceAvailable) {
+			// All entries fit
+			this.buffer.push(...entries);
+			this.metrics.added += entries.length;
+		} else if (spaceAvailable > 0) {
+			// Partial fit - add what we can, drop the oldest to make room for rest
+			const toAdd = entries.slice(-spaceAvailable); // Keep newest entries
+			const toDrop = entries.slice(0, entries.length - spaceAvailable);
+			this.buffer.push(...toAdd);
+			this.metrics.added += toAdd.length;
+			this.metrics.dropped += toDrop.length;
+		} else {
+			// No space - drop oldest entries to make room for newest
+			const dropCount = Math.min(entries.length, this.maxBufferEntries);
+			this.buffer.splice(0, dropCount); // Remove oldest
+			this.metrics.dropped += dropCount;
+			this.buffer.push(...entries);
+			this.metrics.added += entries.length;
+		}
+	}
+
+	async write(entry: RuntimeLogEntry): Promise<void> {
+		if (this.buffering.enabled) {
+			this.addToBuffer([entry]);
+
+			// Flush if buffer is large enough
+			const estimatedSize = JSON.stringify(this.buffer).length;
+			if (estimatedSize >= this.buffering.size) {
+				await this.flush();
+			}
+		} else {
+			await this.send([entry]);
+		}
+	}
+
+	async writeBatch(entries: RuntimeLogEntry[]): Promise<void> {
+		if (this.buffering.enabled) {
+			this.addToBuffer(entries);
+
+			const estimatedSize = JSON.stringify(this.buffer).length;
+			if (estimatedSize >= this.buffering.size) {
+				await this.flush();
+			}
+		} else {
+			await this.send(entries);
+		}
+	}
+
+	async flush(): Promise<void> {
+		if (this.buffer.length === 0 || this.isFlushing) return;
+
+		this.isFlushing = true;
+		try {
+			const entries = this.buffer.splice(0);
+			await this.send(entries);
+		} finally {
+			this.isFlushing = false;
+		}
+	}
+
+	async read(_options?: OutputReadOptions): Promise<string[]> {
+		// Remote outputs do not support reading
+		return [];
+	}
+
+	tail(_callback: (line: string) => void, _options?: OutputTailOptions): TailHandle {
+		// Remote outputs do not support tailing
+		return { close: () => {} };
+	}
+
+	async stats(): Promise<OutputStats> {
+		return { size: 0, exists: true };
+	}
+
+	async close(): Promise<void> {
+		// Clear flush timer
+		if (this.flushTimer) {
+			clearInterval(this.flushTimer);
+			this.flushTimer = null;
+		}
+
+		// Flush remaining buffer
+		await this.flush();
+	}
+
+	private async send(entries: RuntimeLogEntry[]): Promise<void> {
+		if (entries.length === 0) return;
+
+		const body = this.formatter.formatBatch
+			? this.formatter.formatBatch(entries)
+			: entries.map((e) => this.formatter.format(e)).join('\n');
+
+		try {
+			const response = await fetch(this.endpoint, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/x-ndjson'
+				},
+				body
+			});
+
+			if (!response.ok) {
+				logger.error('Failed to send logs to remote endpoint', {
+					status: response.status,
+					statusText: response.statusText,
+					endpoint: this.endpoint
+				});
+				// Re-add failed entries to buffer for retry
+				this.addToBuffer(entries);
+				this.metrics.retried += entries.length;
+			} else {
+				this.metrics.sent += entries.length;
+			}
+		} catch (error) {
+			logger.error('Network error sending logs to remote endpoint', {
+				error: error instanceof Error ? error.message : String(error),
+				endpoint: this.endpoint
+			});
+			// Re-add failed entries to buffer for retry
+			this.addToBuffer(entries);
+			this.metrics.retried += entries.length;
+		}
+	}
+}

package/src/outputs.context.descriptor.ts

@@ -0,0 +1,10 @@
+/**
+ * Logging Outputs Context Descriptor
+ */
+
+import { createContextDescriptor } from '@vibesdotdev/runtime/factory/context';
+
+export default createContextDescriptor({
+	id: 'logging/outputs',
+	description: 'Map of resolved logging output implementations by ID.'
+});

package/src/outputs.context.impl.ts

@@ -0,0 +1,30 @@
+/**
+ * Logging Outputs Context Implementation
+ */
+import type { OutputImplementation } from './kinds/output.ts';
+
+export default {
+	provide: async (runtime: unknown) => {
+		const rt = runtime as {
+			hasKind(k: string): boolean;
+			query(k: string): {
+				descriptors(): { id: string }[];
+				withId(id: string): { resolve(): Promise<unknown> };
+			};
+		};
+		const map = new Map<string, OutputImplementation>();
+		if (rt.hasKind('logging/output')) {
+			for (const desc of rt.query('logging/output').descriptors()) {
+				try {
+					map.set(
+						desc.id,
+						(await rt.query('logging/output').withId(desc.id).resolve()) as OutputImplementation
+					);
+				} catch {
+					// Skip outputs that fail to resolve
+				}
+			}
+		}
+		return map;
+	}
+};

package/src/paths.ts

@@ -0,0 +1,10 @@
+/**
+ * Log path utilities (string-only, universal-isomorphic).
+ *
+ * FS-backed path resolution (getVibesGlobalLogDir, resolveLogPathFromDescriptorPath)
+ * lives in @vibesdotdev/logging-fs.
+ */
+
+export function uniqueLogPaths(paths: Array<string | null | undefined>): string[] {
+	return Array.from(new Set(paths.filter((path): path is string => Boolean(path))));
+}

package/src/schemas/audit.ts

@@ -0,0 +1,98 @@
+/**
+ * Audit Logging Descriptor Schema
+ *
+ * Audit logging for compliance and security events.
+ * Entries are immutable and stored with integrity guarantees.
+ */
+
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/runtime/schemas/descriptor';
+
+/** Audit event categories */
+export const AuditCategorySchema = z.enum([
+	'authentication',
+	'authorization',
+	'data_access',
+	'data_modification',
+	'configuration',
+	'system',
+	'security'
+]);
+export type AuditCategory = z.infer<typeof AuditCategorySchema>;
+
+/** Audit event severity levels */
+export const AuditSeveritySchema = z.enum(['low', 'medium', 'high', 'critical']);
+export type AuditSeverity = z.infer<typeof AuditSeveritySchema>;
+
+/** Audit event outcome */
+export const AuditOutcomeSchema = z.enum(['success', 'failure', 'error', 'unknown']);
+export type AuditOutcome = z.infer<typeof AuditOutcomeSchema>;
+
+/** Actor who triggered the audit event */
+export const AuditActorSchema = z.object({
+	/** Actor identifier */
+	id: z.string(),
+	/** Actor type (user, service, system) */
+	type: z.enum(['user', 'service', 'system']),
+	/** Human-readable name */
+	name: z.string().optional(),
+	/** IP address */
+	ip: z.string().optional(),
+	/** User agent */
+	userAgent: z.string().optional()
+});
+export type AuditActor = z.infer<typeof AuditActorSchema>;
+
+/** Target of the audit event */
+export const AuditTargetSchema = z.object({
+	/** Target identifier */
+	id: z.string(),
+	/** Target type (e.g., 'user', 'document', 'api') */
+	type: z.string(),
+	/** Human-readable name */
+	name: z.string().optional()
+});
+export type AuditTarget = z.infer<typeof AuditTargetSchema>;
+
+/** Single audit log entry */
+export const AuditEntrySchema = z.object({
+	/** Unique entry ID */
+	id: z.string(),
+	/** Timestamp (ISO 8601) */
+	timestamp: z.string(),
+	/** Event category */
+	category: AuditCategorySchema,
+	/** Severity level */
+	severity: AuditSeveritySchema,
+	/** Action performed */
+	action: z.string(),
+	/** Who triggered the event */
+	actor: AuditActorSchema,
+	/** What was affected */
+	target: AuditTargetSchema.optional(),
+	/** Event outcome */
+	outcome: AuditOutcomeSchema,
+	/** Additional context */
+	context: z.record(z.string(), z.unknown()).optional(),
+	/** Error details (for failure/error outcomes) */
+	error: z.string().optional()
+});
+export type AuditEntry = z.infer<typeof AuditEntrySchema>;
+
+/** Audit descriptor schema */
+export const AuditDescriptorSchema = RuntimeDescriptorSchema.extend({
+	kind: z.literal('logging/audit'),
+
+	/** Event category this audit config handles */
+	category: AuditCategorySchema,
+
+	/** Minimum severity to log */
+	severity: AuditSeveritySchema.default('low'),
+
+	/** Retention period (e.g., '90d', '1y') */
+	retention: z.string().default('90d'),
+
+	/** Whether entries are immutable (append-only) */
+	immutable: z.boolean().default(true)
+});
+export type AuditDescriptor = z.infer<typeof AuditDescriptorSchema>;