feat: improve logs output and docs

src/logging/parse-log-line.ts

@@ -0,0 +1,63 @@
+export type ParsedLogLine = {
+  time?: string;
+  level?: string;
+  subsystem?: string;
+  module?: string;
+  message: string;
+  raw: string;
+};
+
+function extractMessage(value: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const key of Object.keys(value)) {
+    if (!/^\d+$/.test(key)) continue;
+    const item = value[key];
+    if (typeof item === "string") {
+      parts.push(item);
+    } else if (item != null) {
+      parts.push(JSON.stringify(item));
+    }
+  }
+  return parts.join(" ");
+}
+
+function parseMetaName(
+  raw?: unknown,
+): { subsystem?: string; module?: string } {
+  if (typeof raw !== "string") return {};
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return {
+      subsystem:
+        typeof parsed.subsystem === "string" ? parsed.subsystem : undefined,
+      module: typeof parsed.module === "string" ? parsed.module : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function parseLogLine(raw: string): ParsedLogLine | null {
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const meta = parsed._meta as Record<string, unknown> | undefined;
+    const nameMeta = parseMetaName(meta?.name);
+    const levelRaw =
+      typeof meta?.logLevelName === "string" ? meta.logLevelName : undefined;
+    return {
+      time:
+        typeof parsed.time === "string"
+          ? parsed.time
+          : typeof meta?.date === "string"
+            ? meta.date
+            : undefined,
+      level: levelRaw ? levelRaw.toLowerCase() : undefined,
+      subsystem: nameMeta.subsystem,
+      module: nameMeta.module,
+      message: extractMessage(parsed),
+      raw,
+    };
+  } catch {
+    return null;
+  }
+}