@camstack/core 0.1.15 → 0.1.16

package/dist/formatter-C-5An4Bl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter-C-5An4Bl.mjs","names":[],"sources":["../src/logging/formatter.ts"],"sourcesContent":["/**\n * Canonical single-line formatter for every `LogEntry` that reaches a\n * console transport — hub-side `WinstonDestination` +\n * `ConsoleDestination`, agent-side `HubForwarderDestination`. One\n * definition so the three paths can't drift.\n *\n * Layout mirrors NestJS `ConsoleLogger` output:\n *\n *   [Nest] 54994  - 04/20/2026, 12:45:53 AM     LOG [InstanceLoader] TrpcModule dependencies initialized +0ms\n *\n * Mapping for camstack — cluster-aware:\n *   - `[Nest]` (brand bracket)   → `[<agent>/<addonId>]` so operators see\n *                                   at a glance which node emitted the line\n *                                   (matches the cluster topology)\n *   - `54994` (pid)              → `process.pid`\n *   - `<timestamp>`              → `M/D/YYYY, H:MM:SS AM`\n *   - `LOG` / `WARN` / `ERROR`   → `entry.level` upper-cased, colour per level\n *   - `[InstanceLoader]` (ctx)   → `[<device>]` — shown only when a device\n *                                   tag is present; omitted otherwise\n *   - `<message>`                → `entry.message`\n *   - trailing `+Nms`            → we don't compute timing yet; omitted\n *\n * Rendered examples:\n *   [hub/winston-logging]        71184  - 04/20/2026, 12:45:53 AM     INFO  Winston logging initialized\n *   [hub/provider-rtsp]          71184  - 04/20/2026, 12:46:01 AM     WARN  [salone] probe failed {err=\"timeout\"}\n *   [dev-agent-0/detection]      12345  - 04/20/2026, 12:47:15 AM     ERROR [cortile] no detector {codec=av1}\n */\nimport type { LogEntry, LogTags } from '@camstack/types'\n\n// Emit ANSI colour codes when the runtime supports them. Heuristic\n// follows npm ecosystem convention so log-consumers can override:\n//   - `NO_COLOR` env present → OFF (https://no-color.org/)\n//   - `FORCE_COLOR=0` → OFF\n//   - `FORCE_COLOR` truthy (1/2/3/true) → ON  (forces even when piped)\n//   - stdout.isTTY → ON\n//   - else → OFF\n// Rationale: running via `concurrently` / `npm run dev` often pipes\n// stdout and strips `isTTY`, making colours disappear. Dev sets\n// `FORCE_COLOR=1` in the shell to opt back in; CI / file-piping\n// pipelines set `NO_COLOR=1` to strip.\n//\n// Destinations that always render for console (ConsoleDestination,\n// HubForwarderDestination) pass `colorize: true` explicitly — still\n// gated by NO_COLOR. File sinks (Winston JSON) pass `colorize: false`\n// so log files stay plain text regardless of the shell environment.\nconst USE_COLOR = (() => {\n  try {\n    if (typeof process === 'undefined') return false\n    const env = process.env ?? {}\n    if (env['NO_COLOR']) return false\n    const force = env['FORCE_COLOR']\n    if (force !== undefined) return force !== '' && force !== '0' && force !== 'false'\n    return Boolean((process.stdout as { isTTY?: boolean })?.isTTY)\n  } catch { return false }\n})()\n\n/** True when `NO_COLOR` is set — destinations that force colour on still honour this. */\nconst NO_COLOR = (() => {\n  try { return Boolean(process?.env?.['NO_COLOR']) } catch { return false }\n})()\n\nconst RESET = '\\x1b[0m'\nconst ANSI = {\n  green:  '\\x1b[32m',\n  yellow: '\\x1b[33m',\n  red:    '\\x1b[31m',\n  cyan:   '\\x1b[36m',\n  gray:   '\\x1b[90m',\n} as const\n\nconst COLOR_BY_LEVEL: Readonly<Record<string, string>> = {\n  debug: ANSI.gray,\n  info:  ANSI.green,\n  warn:  ANSI.yellow,\n  error: ANSI.red,\n}\n\nfunction paint(color: string, text: string, enabled: boolean): string {\n  return enabled ? `${color}${text}${RESET}` : text\n}\n\nfunction colorizeLevel(level: string, text: string, enabled: boolean): string {\n  if (!enabled) return text\n  const code = COLOR_BY_LEVEL[level]\n  return code ? `${code}${text}${RESET}` : text\n}\n\n/** Right-pad `value` to exactly `width` characters. */\nfunction padRight(value: string, width: number): string {\n  if (value.length >= width) return value.slice(0, width)\n  return value + ' '.repeat(width - value.length)\n}\n\n/** Derive the agent — the top-level cluster node, never the forked-worker suffix. */\nfunction resolveAgent(tags: LogTags | undefined): string | null {\n  const agentId = tags?.agentId\n  if (typeof agentId === 'string' && agentId.length > 0) return agentId\n  const nodeId = tags?.nodeId\n  if (typeof nodeId === 'string' && nodeId.length > 0) {\n    return nodeId.includes('/') ? nodeId.split('/')[0]! : nodeId\n  }\n  return null\n}\n\n/** Derive the addon — `tags.addonId` first; `system` when the tag is missing\n *  (scope is no longer a fallback — it's a sub-component label, not identity). */\nfunction resolveAddon(entry: Pick<LogEntry, 'tags'>): string {\n  const addonId = entry.tags?.addonId\n  if (typeof addonId === 'string' && addonId.length > 0) return addonId\n  return 'system'\n}\n\n/** Device name (or `#id` fallback) — used inside the context bracket when present. */\nfunction resolveDevice(tags: LogTags | undefined): string | null {\n  const name = tags?.deviceName\n  if (typeof name === 'string' && name.length > 0) return name\n  const id = tags?.deviceId\n  if (typeof id === 'number' && Number.isFinite(id)) return `#${id}`\n  return null\n}\n\n/**\n * Build the brand bracket content — `<agent>/<addonId>`. Agent is\n * always shown (even `hub`) so operators never have to guess which\n * node emitted a line. Falls back to `?/<addon>` when tags don't\n * carry an agent id (pre-boot logs, test harnesses).\n */\nfunction buildBrand(entry: Pick<LogEntry, 'tags'>): string {\n  const agent = resolveAgent(entry.tags) ?? '?'\n  const addon = resolveAddon(entry)\n  return `${agent}/${addon}`\n}\n\n/**\n * Build the optional device-context bracket. Returns `null` when the\n * line doesn't carry a device tag — renders as just the brand + message\n * without the second bracket. With a device tag: `salone` / `#42`.\n */\nfunction buildDeviceContext(entry: Pick<LogEntry, 'tags'>): string | null {\n  return resolveDevice(entry.tags)\n}\n\n/**\n * NestJS-style locale timestamp: `M/D/YYYY, H:MM:SS AM`. Built with\n * `toLocaleString('en-US')` to match the default NestJS format that\n * operators are used to from Nest boot output.\n */\nfunction formatTimestamp(value: unknown): string {\n  const date = value instanceof Date ? value : new Date(typeof value === 'string' ? value : Date.now())\n  return date.toLocaleString('en-US', {\n    month: 'numeric',\n    day: 'numeric',\n    year: 'numeric',\n    hour: 'numeric',\n    minute: '2-digit',\n    second: '2-digit',\n    hour12: true,\n  })\n}\n\n/** Compact `{key=value key=\"with space\"}` rendering of an arbitrary object. Empty → ''. */\nfunction formatMeta(meta: Record<string, unknown> | undefined): string {\n  if (!meta) return ''\n  const keys = Object.keys(meta)\n  if (keys.length === 0) return ''\n  const parts: string[] = []\n  for (const key of keys) {\n    const value = meta[key]\n    parts.push(`${key}=${formatMetaValue(value)}`)\n  }\n  return `{${parts.join(' ')}}`\n}\n\nfunction formatMetaValue(value: unknown): string {\n  if (value === null) return 'null'\n  if (value === undefined) return 'undefined'\n  if (typeof value === 'string') {\n    return /\\s|\"/.test(value) ? JSON.stringify(value) : value\n  }\n  if (typeof value === 'number' || typeof value === 'boolean') return String(value)\n  if (value instanceof Error) return JSON.stringify(value.message)\n  try { return JSON.stringify(value) } catch { return String(value) }\n}\n\n/** Cached renderer PID — fallback when the entry doesn't carry its own `tags.pid`. */\nconst PID = typeof process !== 'undefined' && typeof process.pid === 'number' ? String(process.pid) : '?'\n\n/** Options for `formatLogLine`. */\nexport interface FormatLogLineOptions {\n  /**\n   * Emit ANSI colour codes. When omitted, falls back to the shell-env\n   * heuristic (`NO_COLOR`/`FORCE_COLOR`/`isTTY`). Destinations that\n   * always target a console (ConsoleDestination, HubForwarderDestination)\n   * pass `true`; file sinks (Winston JSON) pass `false` so logs on disk\n   * stay plain text regardless of the shell env.\n   *\n   * `NO_COLOR=1` in the environment still wins — consumer opt-in beats\n   * producer opt-in, matching the https://no-color.org/ convention.\n   */\n  readonly colorize?: boolean\n}\n\n/**\n * Render a `LogEntry` as one complete console line — no trailing newline.\n * Caller appends `\\n` (file sinks) or relies on `console.log` (stdout sink).\n *\n * PID column prefers `entry.tags.pid` when set (so forked-worker entries\n * carry the worker's OS pid even when the hub renders them), falling back\n * to the renderer's own `process.pid`.\n *\n * Colours (when enabled) follow the NestJS convention: the level token\n * AND the message body share the level colour (green/yellow/red/gray for\n * info/warn/error/debug). Brand, device context, scope and meta keep\n * their fixed hues so the structural fields stay visually distinct from\n * the message content.\n */\nexport function formatLogLine(entry: LogEntry, options?: FormatLogLineOptions): string {\n  const wantsColor = options?.colorize ?? USE_COLOR\n  const colorize = wantsColor && !NO_COLOR\n  const levelColor = COLOR_BY_LEVEL[entry.level]\n\n  const brand = paint(ANSI.green, `[${buildBrand(entry)}]`, colorize)\n  const entryPid = entry.tags?.pid\n  const pid = typeof entryPid === 'number' ? String(entryPid) : PID\n  const timestamp = formatTimestamp(entry.timestamp)\n  // Right-pad level to 5 chars (matches NestJS) so the context/message\n  // column aligns across different levels without fixed-width hacks\n  // on the surrounding fields.\n  const level = colorizeLevel(entry.level, padRight(entry.level.toUpperCase(), 5), colorize)\n  const device = buildDeviceContext(entry)\n  const ctxPart = device ? ' ' + paint(ANSI.yellow, `[${device}]`, colorize) : ''\n  const scope = typeof entry.scope === 'string' && entry.scope.length > 0 ? entry.scope : null\n  const scopePart = scope ? ' ' + paint(ANSI.cyan, `(${scope})`, colorize) : ''\n  const metaText = formatMeta(entry.meta)\n  const metaPart = metaText ? ' ' + paint(ANSI.gray, metaText, colorize) : ''\n  // NestJS layout: `[<agent>/<addon>] <pid>  - <timestamp>     <LEVEL> [<device>] (<scope>) <message>`\n  // Message body is tinted by level colour so `error`/`warn` stand out at a glance.\n  const message = colorize && levelColor\n    ? `${levelColor}${entry.message}${RESET}`\n    : entry.message\n  return `${brand} ${pid}  - ${timestamp}     ${level}${ctxPart}${scopePart} ${message}${metaPart}`\n}\n"],"mappings":"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"}

package/dist/formatter-Dr_6NNZc.js

@@ -0,0 +1,169 @@
+//#region src/logging/formatter.ts
+var USE_COLOR = (() => {
+	try {
+		if (typeof process === "undefined") return false;
+		const env = process.env ?? {};
+		if (env["NO_COLOR"]) return false;
+		const force = env["FORCE_COLOR"];
+		if (force !== void 0) return force !== "" && force !== "0" && force !== "false";
+		return Boolean(process.stdout?.isTTY);
+	} catch {
+		return false;
+	}
+})();
+/** True when `NO_COLOR` is set — destinations that force colour on still honour this. */
+var NO_COLOR = (() => {
+	try {
+		return Boolean(process?.env?.["NO_COLOR"]);
+	} catch {
+		return false;
+	}
+})();
+var RESET = "\x1B[0m";
+var ANSI = {
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	red: "\x1B[31m",
+	cyan: "\x1B[36m",
+	gray: "\x1B[90m"
+};
+var COLOR_BY_LEVEL = {
+	debug: ANSI.gray,
+	info: ANSI.green,
+	warn: ANSI.yellow,
+	error: ANSI.red
+};
+function paint(color, text, enabled) {
+	return enabled ? `${color}${text}${RESET}` : text;
+}
+function colorizeLevel(level, text, enabled) {
+	if (!enabled) return text;
+	const code = COLOR_BY_LEVEL[level];
+	return code ? `${code}${text}${RESET}` : text;
+}
+/** Right-pad `value` to exactly `width` characters. */
+function padRight(value, width) {
+	if (value.length >= width) return value.slice(0, width);
+	return value + " ".repeat(width - value.length);
+}
+/** Derive the agent — the top-level cluster node, never the forked-worker suffix. */
+function resolveAgent(tags) {
+	const agentId = tags?.agentId;
+	if (typeof agentId === "string" && agentId.length > 0) return agentId;
+	const nodeId = tags?.nodeId;
+	if (typeof nodeId === "string" && nodeId.length > 0) return nodeId.includes("/") ? nodeId.split("/")[0] : nodeId;
+	return null;
+}
+/** Derive the addon — `tags.addonId` first; `system` when the tag is missing
+*  (scope is no longer a fallback — it's a sub-component label, not identity). */
+function resolveAddon(entry) {
+	const addonId = entry.tags?.addonId;
+	if (typeof addonId === "string" && addonId.length > 0) return addonId;
+	return "system";
+}
+/** Device name (or `#id` fallback) — used inside the context bracket when present. */
+function resolveDevice(tags) {
+	const name = tags?.deviceName;
+	if (typeof name === "string" && name.length > 0) return name;
+	const id = tags?.deviceId;
+	if (typeof id === "number" && Number.isFinite(id)) return `#${id}`;
+	return null;
+}
+/**
+* Build the brand bracket content — `<agent>/<addonId>`. Agent is
+* always shown (even `hub`) so operators never have to guess which
+* node emitted a line. Falls back to `?/<addon>` when tags don't
+* carry an agent id (pre-boot logs, test harnesses).
+*/
+function buildBrand(entry) {
+	return `${resolveAgent(entry.tags) ?? "?"}/${resolveAddon(entry)}`;
+}
+/**
+* Build the optional device-context bracket. Returns `null` when the
+* line doesn't carry a device tag — renders as just the brand + message
+* without the second bracket. With a device tag: `salone` / `#42`.
+*/
+function buildDeviceContext(entry) {
+	return resolveDevice(entry.tags);
+}
+/**
+* NestJS-style locale timestamp: `M/D/YYYY, H:MM:SS AM`. Built with
+* `toLocaleString('en-US')` to match the default NestJS format that
+* operators are used to from Nest boot output.
+*/
+function formatTimestamp(value) {
+	return (value instanceof Date ? value : new Date(typeof value === "string" ? value : Date.now())).toLocaleString("en-US", {
+		month: "numeric",
+		day: "numeric",
+		year: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+		second: "2-digit",
+		hour12: true
+	});
+}
+/** Compact `{key=value key="with space"}` rendering of an arbitrary object. Empty → ''. */
+function formatMeta(meta) {
+	if (!meta) return "";
+	const keys = Object.keys(meta);
+	if (keys.length === 0) return "";
+	const parts = [];
+	for (const key of keys) {
+		const value = meta[key];
+		parts.push(`${key}=${formatMetaValue(value)}`);
+	}
+	return `{${parts.join(" ")}}`;
+}
+function formatMetaValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return /\s|"/.test(value) ? JSON.stringify(value) : value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (value instanceof Error) return JSON.stringify(value.message);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+/** Cached renderer PID — fallback when the entry doesn't carry its own `tags.pid`. */
+var PID = typeof process !== "undefined" && typeof process.pid === "number" ? String(process.pid) : "?";
+/**
+* Render a `LogEntry` as one complete console line — no trailing newline.
+* Caller appends `\n` (file sinks) or relies on `console.log` (stdout sink).
+*
+* PID column prefers `entry.tags.pid` when set (so forked-worker entries
+* carry the worker's OS pid even when the hub renders them), falling back
+* to the renderer's own `process.pid`.
+*
+* Colours (when enabled) follow the NestJS convention: the level token
+* AND the message body share the level colour (green/yellow/red/gray for
+* info/warn/error/debug). Brand, device context, scope and meta keep
+* their fixed hues so the structural fields stay visually distinct from
+* the message content.
+*/
+function formatLogLine(entry, options) {
+	const colorize = (options?.colorize ?? USE_COLOR) && !NO_COLOR;
+	const levelColor = COLOR_BY_LEVEL[entry.level];
+	const brand = paint(ANSI.green, `[${buildBrand(entry)}]`, colorize);
+	const entryPid = entry.tags?.pid;
+	const pid = typeof entryPid === "number" ? String(entryPid) : PID;
+	const timestamp = formatTimestamp(entry.timestamp);
+	const level = colorizeLevel(entry.level, padRight(entry.level.toUpperCase(), 5), colorize);
+	const device = buildDeviceContext(entry);
+	const ctxPart = device ? " " + paint(ANSI.yellow, `[${device}]`, colorize) : "";
+	const scope = typeof entry.scope === "string" && entry.scope.length > 0 ? entry.scope : null;
+	const scopePart = scope ? " " + paint(ANSI.cyan, `(${scope})`, colorize) : "";
+	const metaText = formatMeta(entry.meta);
+	const metaPart = metaText ? " " + paint(ANSI.gray, metaText, colorize) : "";
+	return `${brand} ${pid}  - ${timestamp}     ${level}${ctxPart}${scopePart} ${colorize && levelColor ? `${levelColor}${entry.message}${RESET}` : entry.message}${metaPart}`;
+}
+//#endregion
+Object.defineProperty(exports, "formatLogLine", {
+	enumerable: true,
+	get: function() {
+		return formatLogLine;
+	}
+});
+
+//# sourceMappingURL=formatter-Dr_6NNZc.js.map

package/dist/formatter-Dr_6NNZc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter-Dr_6NNZc.js","names":[],"sources":["../src/logging/formatter.ts"],"sourcesContent":["/**\n * Canonical single-line formatter for every `LogEntry` that reaches a\n * console transport — hub-side `WinstonDestination` +\n * `ConsoleDestination`, agent-side `HubForwarderDestination`. One\n * definition so the three paths can't drift.\n *\n * Layout mirrors NestJS `ConsoleLogger` output:\n *\n *   [Nest] 54994  - 04/20/2026, 12:45:53 AM     LOG [InstanceLoader] TrpcModule dependencies initialized +0ms\n *\n * Mapping for camstack — cluster-aware:\n *   - `[Nest]` (brand bracket)   → `[<agent>/<addonId>]` so operators see\n *                                   at a glance which node emitted the line\n *                                   (matches the cluster topology)\n *   - `54994` (pid)              → `process.pid`\n *   - `<timestamp>`              → `M/D/YYYY, H:MM:SS AM`\n *   - `LOG` / `WARN` / `ERROR`   → `entry.level` upper-cased, colour per level\n *   - `[InstanceLoader]` (ctx)   → `[<device>]` — shown only when a device\n *                                   tag is present; omitted otherwise\n *   - `<message>`                → `entry.message`\n *   - trailing `+Nms`            → we don't compute timing yet; omitted\n *\n * Rendered examples:\n *   [hub/winston-logging]        71184  - 04/20/2026, 12:45:53 AM     INFO  Winston logging initialized\n *   [hub/provider-rtsp]          71184  - 04/20/2026, 12:46:01 AM     WARN  [salone] probe failed {err=\"timeout\"}\n *   [dev-agent-0/detection]      12345  - 04/20/2026, 12:47:15 AM     ERROR [cortile] no detector {codec=av1}\n */\nimport type { LogEntry, LogTags } from '@camstack/types'\n\n// Emit ANSI colour codes when the runtime supports them. Heuristic\n// follows npm ecosystem convention so log-consumers can override:\n//   - `NO_COLOR` env present → OFF (https://no-color.org/)\n//   - `FORCE_COLOR=0` → OFF\n//   - `FORCE_COLOR` truthy (1/2/3/true) → ON  (forces even when piped)\n//   - stdout.isTTY → ON\n//   - else → OFF\n// Rationale: running via `concurrently` / `npm run dev` often pipes\n// stdout and strips `isTTY`, making colours disappear. Dev sets\n// `FORCE_COLOR=1` in the shell to opt back in; CI / file-piping\n// pipelines set `NO_COLOR=1` to strip.\n//\n// Destinations that always render for console (ConsoleDestination,\n// HubForwarderDestination) pass `colorize: true` explicitly — still\n// gated by NO_COLOR. File sinks (Winston JSON) pass `colorize: false`\n// so log files stay plain text regardless of the shell environment.\nconst USE_COLOR = (() => {\n  try {\n    if (typeof process === 'undefined') return false\n    const env = process.env ?? {}\n    if (env['NO_COLOR']) return false\n    const force = env['FORCE_COLOR']\n    if (force !== undefined) return force !== '' && force !== '0' && force !== 'false'\n    return Boolean((process.stdout as { isTTY?: boolean })?.isTTY)\n  } catch { return false }\n})()\n\n/** True when `NO_COLOR` is set — destinations that force colour on still honour this. */\nconst NO_COLOR = (() => {\n  try { return Boolean(process?.env?.['NO_COLOR']) } catch { return false }\n})()\n\nconst RESET = '\\x1b[0m'\nconst ANSI = {\n  green:  '\\x1b[32m',\n  yellow: '\\x1b[33m',\n  red:    '\\x1b[31m',\n  cyan:   '\\x1b[36m',\n  gray:   '\\x1b[90m',\n} as const\n\nconst COLOR_BY_LEVEL: Readonly<Record<string, string>> = {\n  debug: ANSI.gray,\n  info:  ANSI.green,\n  warn:  ANSI.yellow,\n  error: ANSI.red,\n}\n\nfunction paint(color: string, text: string, enabled: boolean): string {\n  return enabled ? `${color}${text}${RESET}` : text\n}\n\nfunction colorizeLevel(level: string, text: string, enabled: boolean): string {\n  if (!enabled) return text\n  const code = COLOR_BY_LEVEL[level]\n  return code ? `${code}${text}${RESET}` : text\n}\n\n/** Right-pad `value` to exactly `width` characters. */\nfunction padRight(value: string, width: number): string {\n  if (value.length >= width) return value.slice(0, width)\n  return value + ' '.repeat(width - value.length)\n}\n\n/** Derive the agent — the top-level cluster node, never the forked-worker suffix. */\nfunction resolveAgent(tags: LogTags | undefined): string | null {\n  const agentId = tags?.agentId\n  if (typeof agentId === 'string' && agentId.length > 0) return agentId\n  const nodeId = tags?.nodeId\n  if (typeof nodeId === 'string' && nodeId.length > 0) {\n    return nodeId.includes('/') ? nodeId.split('/')[0]! : nodeId\n  }\n  return null\n}\n\n/** Derive the addon — `tags.addonId` first; `system` when the tag is missing\n *  (scope is no longer a fallback — it's a sub-component label, not identity). */\nfunction resolveAddon(entry: Pick<LogEntry, 'tags'>): string {\n  const addonId = entry.tags?.addonId\n  if (typeof addonId === 'string' && addonId.length > 0) return addonId\n  return 'system'\n}\n\n/** Device name (or `#id` fallback) — used inside the context bracket when present. */\nfunction resolveDevice(tags: LogTags | undefined): string | null {\n  const name = tags?.deviceName\n  if (typeof name === 'string' && name.length > 0) return name\n  const id = tags?.deviceId\n  if (typeof id === 'number' && Number.isFinite(id)) return `#${id}`\n  return null\n}\n\n/**\n * Build the brand bracket content — `<agent>/<addonId>`. Agent is\n * always shown (even `hub`) so operators never have to guess which\n * node emitted a line. Falls back to `?/<addon>` when tags don't\n * carry an agent id (pre-boot logs, test harnesses).\n */\nfunction buildBrand(entry: Pick<LogEntry, 'tags'>): string {\n  const agent = resolveAgent(entry.tags) ?? '?'\n  const addon = resolveAddon(entry)\n  return `${agent}/${addon}`\n}\n\n/**\n * Build the optional device-context bracket. Returns `null` when the\n * line doesn't carry a device tag — renders as just the brand + message\n * without the second bracket. With a device tag: `salone` / `#42`.\n */\nfunction buildDeviceContext(entry: Pick<LogEntry, 'tags'>): string | null {\n  return resolveDevice(entry.tags)\n}\n\n/**\n * NestJS-style locale timestamp: `M/D/YYYY, H:MM:SS AM`. Built with\n * `toLocaleString('en-US')` to match the default NestJS format that\n * operators are used to from Nest boot output.\n */\nfunction formatTimestamp(value: unknown): string {\n  const date = value instanceof Date ? value : new Date(typeof value === 'string' ? value : Date.now())\n  return date.toLocaleString('en-US', {\n    month: 'numeric',\n    day: 'numeric',\n    year: 'numeric',\n    hour: 'numeric',\n    minute: '2-digit',\n    second: '2-digit',\n    hour12: true,\n  })\n}\n\n/** Compact `{key=value key=\"with space\"}` rendering of an arbitrary object. Empty → ''. */\nfunction formatMeta(meta: Record<string, unknown> | undefined): string {\n  if (!meta) return ''\n  const keys = Object.keys(meta)\n  if (keys.length === 0) return ''\n  const parts: string[] = []\n  for (const key of keys) {\n    const value = meta[key]\n    parts.push(`${key}=${formatMetaValue(value)}`)\n  }\n  return `{${parts.join(' ')}}`\n}\n\nfunction formatMetaValue(value: unknown): string {\n  if (value === null) return 'null'\n  if (value === undefined) return 'undefined'\n  if (typeof value === 'string') {\n    return /\\s|\"/.test(value) ? JSON.stringify(value) : value\n  }\n  if (typeof value === 'number' || typeof value === 'boolean') return String(value)\n  if (value instanceof Error) return JSON.stringify(value.message)\n  try { return JSON.stringify(value) } catch { return String(value) }\n}\n\n/** Cached renderer PID — fallback when the entry doesn't carry its own `tags.pid`. */\nconst PID = typeof process !== 'undefined' && typeof process.pid === 'number' ? String(process.pid) : '?'\n\n/** Options for `formatLogLine`. */\nexport interface FormatLogLineOptions {\n  /**\n   * Emit ANSI colour codes. When omitted, falls back to the shell-env\n   * heuristic (`NO_COLOR`/`FORCE_COLOR`/`isTTY`). Destinations that\n   * always target a console (ConsoleDestination, HubForwarderDestination)\n   * pass `true`; file sinks (Winston JSON) pass `false` so logs on disk\n   * stay plain text regardless of the shell env.\n   *\n   * `NO_COLOR=1` in the environment still wins — consumer opt-in beats\n   * producer opt-in, matching the https://no-color.org/ convention.\n   */\n  readonly colorize?: boolean\n}\n\n/**\n * Render a `LogEntry` as one complete console line — no trailing newline.\n * Caller appends `\\n` (file sinks) or relies on `console.log` (stdout sink).\n *\n * PID column prefers `entry.tags.pid` when set (so forked-worker entries\n * carry the worker's OS pid even when the hub renders them), falling back\n * to the renderer's own `process.pid`.\n *\n * Colours (when enabled) follow the NestJS convention: the level token\n * AND the message body share the level colour (green/yellow/red/gray for\n * info/warn/error/debug). Brand, device context, scope and meta keep\n * their fixed hues so the structural fields stay visually distinct from\n * the message content.\n */\nexport function formatLogLine(entry: LogEntry, options?: FormatLogLineOptions): string {\n  const wantsColor = options?.colorize ?? USE_COLOR\n  const colorize = wantsColor && !NO_COLOR\n  const levelColor = COLOR_BY_LEVEL[entry.level]\n\n  const brand = paint(ANSI.green, `[${buildBrand(entry)}]`, colorize)\n  const entryPid = entry.tags?.pid\n  const pid = typeof entryPid === 'number' ? String(entryPid) : PID\n  const timestamp = formatTimestamp(entry.timestamp)\n  // Right-pad level to 5 chars (matches NestJS) so the context/message\n  // column aligns across different levels without fixed-width hacks\n  // on the surrounding fields.\n  const level = colorizeLevel(entry.level, padRight(entry.level.toUpperCase(), 5), colorize)\n  const device = buildDeviceContext(entry)\n  const ctxPart = device ? ' ' + paint(ANSI.yellow, `[${device}]`, colorize) : ''\n  const scope = typeof entry.scope === 'string' && entry.scope.length > 0 ? entry.scope : null\n  const scopePart = scope ? ' ' + paint(ANSI.cyan, `(${scope})`, colorize) : ''\n  const metaText = formatMeta(entry.meta)\n  const metaPart = metaText ? ' ' + paint(ANSI.gray, metaText, colorize) : ''\n  // NestJS layout: `[<agent>/<addon>] <pid>  - <timestamp>     <LEVEL> [<device>] (<scope>) <message>`\n  // Message body is tinted by level colour so `error`/`warn` stand out at a glance.\n  const message = colorize && levelColor\n    ? `${levelColor}${entry.message}${RESET}`\n    : entry.message\n  return `${brand} ${pid}  - ${timestamp}     ${level}${ctxPart}${scopePart} ${message}${metaPart}`\n}\n"],"mappings":"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"}