@db3.ai/app 0.1.0-beta.1

package/src/logging/README.md

@@ -0,0 +1,139 @@
+# Logging
+
+`@db3.ai/app/logging` provides the application logger exposed through
+`app().log`. Pino is the default driver, while the framework owns service discovery,
+configuration, redaction, transport selection, and shutdown.
+
+## Run a structured logging lab
+
+From your independent app after [Installation](https://db3.ai/docs/installation):
+
+```sh
+mkdir -p examples
+cp -R node_modules/@db3.ai/app/src/logging/examples/. examples/
+npx tsx examples/runNoteLogs.ts
+```
+
+This captures the real Pino driver's output in a writable stream, with devtools HTTP delivery disabled. Expect three records: `Note saved`, `Summary failed`, and `Diagnostics enabled`. The first debug message is filtered, then changing `log.level` enables debug output. Changing it to silent suppresses later errors. The output omits unstable metadata and stack text only for readability.
+
+The [Logging guide](https://db3.ai/docs/logging#testing) contains the exact consumer test. Save it as `tests/logging/runNoteLogs.test.ts` and run:
+
+```sh
+npx vitest run tests/logging/runNoteLogs.test.ts
+npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts
+```
+
+The test asserts structured context, error serialization, level changes and the absence of synthetic password/token/provider-key values. It uses the real logger, not a framework mock. This does not prove remote log ingestion or retention.
+
+## Writing Logs
+
+Prefer a short message plus structured fields:
+
+```ts
+app().log.info({
+	websiteId,
+	pageCount,
+}, 'Website crawl completed');
+```
+
+Pass errors under `err` so Pino retains their name, message, stack, and cause:
+
+```ts
+app().log.error({
+	err: error,
+	websiteId,
+}, 'Website crawl failed');
+```
+
+Use child loggers for context shared by several records:
+
+```ts
+const log = app().log.child({
+	component: 'crawler',
+	websiteId,
+});
+
+log.info('Crawl started');
+log.debug({ url }, 'Page discovered');
+```
+
+The standard levels are `trace`, `debug`, `info`, `warn`, `error`, `fatal`,
+and `silent`. The default level is `info`; tests default to `silent`.
+
+## Application Configuration
+
+Configure logging through `AppOptions.log`:
+
+```ts
+const app = new App({
+	log: {
+		level: 'debug',
+		source: 'example-api',
+		bindings: {
+			release: process.env.RELEASE_SHA,
+		},
+		devtools: true,
+	},
+});
+```
+
+Supported environment values:
+
+- `PLATFORM_LOG_LEVEL`: minimum standard log level.
+- `PLATFORM_LOG_SOURCE`: source name copied to every record.
+- `PLATFORM_LOG_DEVTOOLS`: explicitly enables or disables devtools delivery.
+- `PLATFORM_DEVTOOLS_EVENTS_URL`: complete development ingestion endpoint.
+- `PLATFORM_DEVTOOLS_HOST`: development service host when no URL is supplied.
+- `PLATFORM_DEVTOOLS_API_PORT`: development service port, defaulting to `9998`.
+
+Newline-delimited JSON is written to standard output by default. Interactive
+development also enables the framework devtools transport automatically. Tests
+do not enable network delivery unless explicitly configured.
+
+## Development Log Stream
+
+The Pino transport runs in a worker thread and sends bounded, best-effort HTTP
+batches to the same generic event endpoint used by database and queue
+instrumentation:
+
+```text
+app().log
+	-> Pino worker transport
+	-> POST /api/events
+	-> development event store
+	-> WebSocket
+	-> Logs panel
+```
+
+The default batch contains at most 25 records and a partial batch waits at most
+100 milliseconds. At most 1,000 unsent events are retained; the oldest event is
+discarded when that bound is exceeded. A failed batch is discarded and later
+delivery pauses for one second. Logging therefore remains observability rather
+than an application dependency.
+
+`App.close()` flushes the logger and closes its worker transport. Application
+entrypoints should always use the framework shutdown lifecycle rather than
+calling `process.exit()` directly after writing a log.
+
+## Security
+
+The default Pino driver removes common password, secret, token, authorization,
+and cookie paths before records reach stdout or devtools. Applications can add
+more redaction paths through `AppOptions.log.redact`.
+
+Redaction is a safeguard, not permission to log request bodies, credentials,
+payment details, or personal data. Prefer explicit safe fields over logging
+large application objects.
+
+Redaction removes configured paths, not arbitrary secret substrings. Error messages, URL query strings and unfamiliar nested properties may still contain sensitive data. Test your application paths and never embed a credential in the log message itself. `redact: false` disables the protection.
+
+`Log.level` changes take effect on subsequent method lookups; avoid capturing a log function and then expecting it to be replaced when the level changes. `App.close()` owns its logger; a manually supplied output stream remains the creator's resource to end. The [full API](https://db3.ai/docs/logging-api) includes all current logger, driver, options and HTTP exchange contracts.
+
+## Framework Boundaries
+
+Logs describe operations for people and observability tools. They are not a
+framework event bus and must not trigger application behavior.
+
+Database query events, queue lifecycle events, and durable flow events retain
+their own typed contracts. They can be correlated with logs through fields such
+as `requestId`, `jobId`, `websiteId`, `flowId`, and `component`.

package/src/logging/contracts/HttpExchange.ts

@@ -0,0 +1,53 @@
+/**
+ * Body representation retained by development HTTP exchange logging.
+ */
+export interface HttpBodyLog {
+	/** How the original payload was represented or why it was omitted. */
+	kind: 'empty' | 'json' | 'text' | 'binary' | 'stream';
+	/** Media type reported by the request or response. */
+	contentType?: string;
+	/** Redacted serialized payload size before the development capture limit. */
+	sizeBytes?: number;
+	/** Whether the displayed value was shortened to the configured byte limit. */
+	truncated?: boolean;
+	/** Redacted JSON value or captured text when the body is inspectable. */
+	value?: unknown;
+	/** Human-readable explanation for an omitted payload. */
+	note?: string;
+}
+
+/**
+ * Request fields retained by a development HTTP exchange record.
+ */
+export interface HttpRequestLog {
+	/** HTTP method used by the client. */
+	method: string;
+	/** Path and query string requested by the client. */
+	url: string;
+	/** Redacted request headers. */
+	headers: Record<string, unknown>;
+	/** Bounded and redacted request payload. */
+	body: HttpBodyLog;
+}
+
+/**
+ * Response fields retained by a development HTTP exchange record.
+ */
+export interface HttpResponseLog {
+	/** HTTP status selected before the response is sent. */
+	statusCode: number;
+	/** Redacted response headers. */
+	headers: Record<string, unknown>;
+	/** Bounded and redacted response payload. */
+	body: HttpBodyLog;
+}
+
+/**
+ * Development-only request and response data attached to a Pino log record.
+ */
+export interface HttpExchangeLog {
+	/** Incoming request details visible to the Fastify handler. */
+	request: HttpRequestLog;
+	/** Outgoing response details visible to Fastify's send lifecycle. */
+	response: HttpResponseLog;
+}

package/src/logging/contracts/Logger.ts

@@ -0,0 +1,45 @@
+import type { ChildLoggerOptions, LogFn } from 'pino';
+
+/**
+ * Standard severity levels supported by the framework logger.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+
+/**
+ * Structured fields attached to one log record or child logger.
+ */
+export type LogBindings = Record<string, unknown>;
+
+/**
+ * Application logger contract shared by framework services and app code.
+ *
+ * The call signatures intentionally match Pino so structured records can be
+ * passed directly to Fastify and Pino-compatible transports.
+ */
+export interface Logger {
+	/** Minimum severity currently emitted by the logger. */
+	level: string;
+	/** Writes a highly detailed diagnostic record. */
+	trace: LogFn;
+	/** Writes a development diagnostic record. */
+	debug: LogFn;
+	/** Writes a normal operational record. */
+	info: LogFn;
+	/** Writes a recoverable problem record. */
+	warn: LogFn;
+	/** Writes a failed operation record. */
+	error: LogFn;
+	/** Writes a process-ending failure record. */
+	fatal: LogFn;
+	/** Accepts a record without emitting output. */
+	silent: LogFn;
+
+	/**
+	 * Creates a logger that includes stable fields on every record.
+	 *
+	 * @param bindings - Structured context inherited by child records.
+	 * @param options - Optional Pino child logger behavior.
+	 * @returns Child logger sharing the same destinations.
+	 */
+	child(bindings: LogBindings, options?: ChildLoggerOptions): Logger;
+}

package/src/logging/contracts/LoggerDriver.ts

@@ -0,0 +1,19 @@
+import type { Logger } from './Logger';
+
+/**
+ * Driver boundary used by the framework logging service.
+ */
+export interface LoggerDriver {
+	/** Logger implementation used for record creation. */
+	readonly logger: Logger;
+
+	/**
+	 * Waits until records already accepted by the driver reach its destination.
+	 */
+	flush(): Promise<void>;
+
+	/**
+	 * Flushes records and releases transport resources.
+	 */
+	close(): Promise<void>;
+}

package/src/logging/contracts/LoggingOptions.ts

@@ -0,0 +1,51 @@
+import type { LoggerDriver } from './LoggerDriver';
+import type { LogBindings, LogLevel } from './Logger';
+
+/**
+ * HTTP delivery settings for the Platform development log transport.
+ */
+export interface DevtoolsLogOptions {
+	/** Explicit event ingestion endpoint, overriding devtools environment values. */
+	url?: string;
+	/** Maximum log records sent in one HTTP request. */
+	batchSize?: number;
+	/** Maximum delay before a partial log batch is sent. */
+	flushIntervalMs?: number;
+	/** Pause before later records are attempted after a failed request. */
+	retryAfterMs?: number;
+	/** Maximum duration allowed for one ingestion request. */
+	requestTimeoutMs?: number;
+	/** Maximum unsent records retained before the oldest record is discarded. */
+	maxPendingEvents?: number;
+	/** Additional ingestion headers, such as a future service token. */
+	headers?: Record<string, string>;
+}
+
+/**
+ * Application logging configuration.
+ */
+export interface LoggingOptions {
+	/** Injectable logging driver used by tests or alternate implementations. */
+	driver?: LoggerDriver;
+	/** Minimum emitted severity. Defaults to info, or silent in tests. */
+	level?: LogLevel;
+	/** Human-readable application or process name attached to every record. */
+	source?: string;
+	/** Runtime environment copied onto every record. */
+	environment?: string;
+	/** Disables all logging when false. */
+	enabled?: boolean;
+	/** Stable fields attached to every root logger record. */
+	bindings?: LogBindings;
+	/** Sensitive field paths removed before records reach any destination. */
+	redact?: false | string[];
+	/** Writes newline-delimited JSON to standard output. Defaults to true. */
+	console?: boolean;
+	/**
+	 * Streams logs to Platform devtools.
+	 *
+	 * Interactive development enables this automatically. Pass false to opt out
+	 * or an options object to configure delivery explicitly.
+	 */
+	devtools?: boolean | DevtoolsLogOptions;
+}

package/src/logging/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from './HttpExchange';
+export * from './Logger';
+export * from './LoggerDriver';
+export * from './LoggingOptions';

package/src/logging/drivers/PinoLoggerDriver.ts

@@ -0,0 +1,376 @@
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { hostname } from 'node:os';
+import pino, {
+	type DestinationStream,
+	type Logger as PinoLogger,
+	type TransportTargetOptions,
+} from 'pino';
+import type ThreadStream from 'thread-stream';
+
+import { isInteractiveDevelopmentEnvironment } from '../../devtools';
+import type * as logging from '../contracts';
+
+/**
+ * Pino worker transport lifecycle members present at runtime but omitted from
+ * the published ThreadStream type.
+ */
+interface ManagedPinoTransport extends ThreadStream {
+	/** Whether the worker has loaded every configured destination. */
+	readonly ready: boolean;
+	/** Keeps the worker referenced while an explicit lifecycle action runs. */
+	ref(): void;
+	/** Allows an idle logging worker to stop keeping the process alive. */
+	unref(): void;
+}
+
+/**
+ * Process values used to derive default logging configuration.
+ */
+interface LoggingEnvironment {
+	NODE_ENV?: string;
+	PLATFORM_LOG_DEVTOOLS?: string;
+	PLATFORM_LOG_LEVEL?: string;
+	PLATFORM_LOG_SOURCE?: string;
+	npm_package_name?: string;
+}
+
+const defaultRedactions = [
+	'password',
+	'*.password',
+	'secret',
+	'*.secret',
+	'token',
+	'*.token',
+	'authorization',
+	'headers.authorization',
+	'headers.cookie',
+	'req.headers.authorization',
+	'req.headers.cookie',
+	'request.headers.authorization',
+	'request.headers.cookie',
+];
+
+/**
+ * Pino-backed logger driver with optional worker-thread devtools delivery.
+ */
+export class PinoLoggerDriver implements logging.LoggerDriver {
+	readonly logger: PinoLogger;
+	readonly #transport: ManagedPinoTransport | null;
+	#closed = false;
+	#closing = false;
+	#closePromise: Promise<void> | null = null;
+
+	/**
+	 * Creates a Pino logger and its configured destinations.
+	 *
+	 * @param options - Framework logging configuration.
+	 * @param destination - Optional direct destination used by focused tests.
+	 */
+	constructor(
+		options: logging.LoggingOptions = {},
+		destination?: DestinationStream,
+	) {
+		const environment = options.environment ?? process.env.NODE_ENV ?? 'development';
+		const level = resolveLogLevel(options, process.env);
+		const source = options.source
+			?? process.env.PLATFORM_LOG_SOURCE
+			?? process.env.npm_package_name
+			?? 'app';
+		const pinoOptions = {
+			level,
+			base: {
+				pid: process.pid,
+				hostname: hostname(),
+				source,
+				environment,
+				...options.bindings,
+			},
+			redact: options.redact === false
+				? undefined
+				: {
+					paths: [...defaultRedactions, ...(options.redact ?? [])],
+					remove: true,
+				},
+		};
+
+		if (destination) {
+			this.#transport = null;
+			this.logger = pino(pinoOptions, destination);
+			return;
+		}
+
+		const targets = transportTargets(options, level, environment, process.env);
+
+		if (targets.length === 0) {
+			this.#transport = null;
+			this.logger = pino({
+				...pinoOptions,
+				level: 'silent',
+			});
+			return;
+		}
+
+		if (targets.length === 1 && targets[0]?.target === 'pino/file') {
+			this.#transport = null;
+			this.logger = pino(pinoOptions);
+			return;
+		}
+
+		this.#transport = pino.transport({
+			targets,
+		}) as ManagedPinoTransport;
+		this.#transport.on('error', reportTransportError);
+		this.logger = pino(pinoOptions, this.#transport);
+	}
+
+	/**
+	 * Waits until Pino has handed accepted records to its destination.
+	 */
+	async flush(): Promise<void> {
+		if (this.#closed) return;
+
+		this.#transport?.ref();
+
+		try {
+			if (this.#transport) {
+				await waitForTransportReady(this.#transport);
+				this.#transport.ref();
+			}
+
+			await new Promise<void>((resolve, reject) => {
+				this.logger.flush((error?: Error) => {
+					if (error) {
+						reject(error);
+						return;
+					}
+
+					resolve();
+				});
+			});
+		} finally {
+			if (!this.#closing) {
+				this.#transport?.unref();
+			}
+		}
+	}
+
+	/**
+	 * Flushes records and closes the worker transport when one is active.
+	 */
+	async close(): Promise<void> {
+		this.#closePromise ??= this.#close();
+		await this.#closePromise;
+	}
+
+	/**
+	 * Performs the one-time driver shutdown.
+	 */
+	async #close(): Promise<void> {
+		if (this.#closed) return;
+
+		this.#closing = true;
+		await this.flush();
+		this.#closed = true;
+
+		if (!this.#transport) return;
+
+		const closed = once(this.#transport, 'close');
+
+		this.#transport.end();
+		await closed;
+	}
+}
+
+/**
+ * Resolves the configured standard Pino level.
+ *
+ * @param options - Explicit application logging options.
+ * @param env - Process environment values.
+ * @returns Valid standard logging level.
+ */
+function resolveLogLevel(
+	options: logging.LoggingOptions,
+	env: LoggingEnvironment,
+): logging.LogLevel {
+	if (options.enabled === false) return 'silent';
+
+	const candidate = options.level
+		?? env.PLATFORM_LOG_LEVEL
+		?? ((options.environment ?? env.NODE_ENV) === 'test' ? 'silent' : 'info');
+
+	if (isLogLevel(candidate)) return candidate;
+
+	throw new Error(
+		`Invalid PLATFORM_LOG_LEVEL value "${candidate}". Use trace, debug, info, warn, error, fatal, or silent.`,
+	);
+}
+
+/**
+ * Builds Pino transport targets for stdout and Platform devtools.
+ *
+ * @param options - Framework logging destination options.
+ * @param level - Minimum severity routed to each destination.
+ * @param environment - Current runtime environment.
+ * @param env - Process environment values.
+ * @returns Pino worker transport targets.
+ */
+function transportTargets(
+	options: logging.LoggingOptions,
+	level: logging.LogLevel,
+	environment: string,
+	env: LoggingEnvironment,
+): TransportTargetOptions[] {
+	if (level === 'silent') return [];
+
+	const targets: TransportTargetOptions[] = [];
+
+	if (options.console !== false) {
+		targets.push({
+			target: 'pino/file',
+			level,
+			options: {
+				destination: 1,
+			},
+		});
+	}
+
+	if (devtoolsEnabled(options.devtools, environment, env)) {
+		targets.push({
+			target: devtoolsTransportTarget(),
+			level,
+			options: typeof options.devtools === 'object'
+				? options.devtools
+				: {},
+		});
+	}
+
+	return targets;
+}
+
+/**
+ * Resolves whether the devtools transport is enabled.
+ *
+ * @param configured - Explicit transport setting.
+ * @param environment - Current runtime environment.
+ * @param env - Process environment values.
+ * @returns True when logs should stream to the development service.
+ */
+function devtoolsEnabled(
+	configured: logging.LoggingOptions['devtools'],
+	environment: string,
+	env: LoggingEnvironment,
+): boolean {
+	if (configured === false) return false;
+	if (configured === true || typeof configured === 'object') return true;
+
+	const envValue = env.PLATFORM_LOG_DEVTOOLS?.toLowerCase().trim();
+
+	if (envValue) {
+		return envValue === '1'
+			|| envValue === 'true'
+			|| envValue === 'yes'
+			|| envValue === 'on';
+	}
+
+	return isInteractiveDevelopmentEnvironment(environment);
+}
+
+/**
+ * Resolves the source or compiled transport module beside this driver.
+ *
+ * @returns Absolute module path suitable for Pino's worker loader.
+ */
+function devtoolsTransportTarget(): string {
+	const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+
+	return fileURLToPath(
+		new URL(`../transports/DevtoolsLogTransport.${extension}`, import.meta.url),
+	);
+}
+
+/**
+ * Narrows a value into one of the supported framework levels.
+ *
+ * @param input - Candidate log level.
+ * @returns True when the value is a standard level.
+ */
+function isLogLevel(input: unknown): input is logging.LogLevel {
+	return input === 'trace'
+		|| input === 'debug'
+		|| input === 'info'
+		|| input === 'warn'
+		|| input === 'error'
+		|| input === 'fatal'
+		|| input === 'silent';
+}
+
+/**
+ * Surfaces transport boot failures without recursively invoking the logger.
+ *
+ * @param error - Worker transport error.
+ */
+function reportTransportError(error: Error): void {
+	process.stderr.write(`[logging] Transport failed: ${error.message}\n`);
+}
+
+/**
+ * Waits for an asynchronous Pino worker to accept flush requests.
+ *
+ * The timeout also keeps short-lived command processes alive while the worker
+ * loads its transport module.
+ *
+ * @param transport - Pino worker transport.
+ */
+async function waitForTransportReady(
+	transport: ManagedPinoTransport,
+): Promise<void> {
+	if (transport.ready) return;
+
+	await new Promise<void>((resolve, reject) => {
+		const timeout = setTimeout(() => {
+			cleanup();
+			reject(new Error('Logging transport did not become ready within 5 seconds.'));
+		}, 5000);
+
+		/**
+		 * Resolves after the worker has loaded its destination.
+		 */
+		const onReady = (): void => {
+			cleanup();
+			resolve();
+		};
+
+		/**
+		 * Rejects when the worker closes before initialization.
+		 */
+		const onClose = (): void => {
+			cleanup();
+			reject(new Error('Logging transport closed before becoming ready.'));
+		};
+
+		/**
+		 * Rejects when the worker cannot load its destination.
+		 *
+		 * @param error - Worker initialization error.
+		 */
+		const onError = (error: Error): void => {
+			cleanup();
+			reject(error);
+		};
+
+		/**
+		 * Removes readiness listeners after one terminal outcome.
+		 */
+		const cleanup = (): void => {
+			clearTimeout(timeout);
+			transport.off('ready', onReady);
+			transport.off('close', onClose);
+			transport.off('error', onError);
+		};
+
+		transport.once('ready', onReady);
+		transport.once('close', onClose);
+		transport.once('error', onError);
+	});
+}

package/src/logging/drivers/index.ts

@@ -0,0 +1 @@
+export * from './PinoLoggerDriver';