@e9n/pi-logger 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-02-17
+
+### Added
+
+- Initial release.

package/README.md

@@ -0,0 +1,105 @@
+# @e9n/pi-logger
+
+Event bus logger for [pi](https://github.com/mariozechner/pi-mono). Subscribes to events on the shared event bus and writes structured JSONL log files, one per day.
+
+## Features
+
+- Captures any event on the pi event bus as a structured log entry
+- Writes JSONL files named `YYYY-MM-DD.jsonl`, one per day
+- **Global scope** — all sessions write to `~/.pi/agent/logs/`
+- **Project scope** — logs write to `.pi/logs/` next to project code
+- Configurable minimum level, event whitelist/ignore, and channel whitelist/ignore
+- Level inferred from event name when not explicitly set
+- Timestamps use the configured IANA timezone (defaults to system timezone)
+- Runtime control via `/logger` command — change level, scope, or reload settings without restarting
+
+## Setup / Settings
+
+Add to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project):
+
+```json
+{
+  "pi-logger": {
+    "level": "INFO",
+    "scope": "global",
+    "timezone": "Europe/Oslo",
+    "events_whitelist": ["log"],
+    "events_ignore": [],
+    "channels_whitelist": [],
+    "channels_ignore": []
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `level` | `"INFO"` | Minimum log level: `DEBUG`, `INFO`, `WARN`, `ERROR`. |
+| `scope` | `"global"` | `"global"` → `~/.pi/agent/logs/`, `"project"` → `.pi/logs/`. |
+| `timezone` | System tz | IANA timezone for timestamps (e.g. `"Europe/Oslo"`). |
+| `events_whitelist` | `["log"]` | Bus event prefixes to subscribe to. `[]` = capture all known events. |
+| `events_ignore` | `[]` | Bus event prefixes to skip (applied after whitelist). |
+| `channels_whitelist` | `[]` | Channels to accept in the `log` handler. `[]` = all. |
+| `channels_ignore` | `[]` | Channels to drop in the `log` handler. |
+
+### Logging from extensions
+
+Emit structured log entries via the `"log"` bus event:
+
+```typescript
+// Channel + level
+pi.events.emit("log", { channel: "myext", level: "WARN", data: { msg: "something odd" } });
+
+// Channel + sub-event
+pi.events.emit("log", { channel: "myext", event: "request", data: { path: "/api" } });
+
+// Shorthand by level (level inferred from event name)
+pi.events.emit("log:error", { event: "myext:crash", data: { message: "oops" } });
+pi.events.emit("log:warn",  { event: "myext:slow",  data: { ms: 2000 } });
+```
+
+### Level inference
+
+Events are assigned a level from their name when no explicit level is given:
+
+| Pattern in event name | Level |
+|-----------------------|-------|
+| `error` or `fail` | `ERROR` |
+| `warn` or `alert` | `WARN` |
+| `debug` | `DEBUG` |
+| Anything else | `INFO` |
+
+### Log format
+
+Each line is a JSON object:
+
+```json
+{"ts":"2026-02-12T11:24:17.123+01:00","level":"INFO","channel":"heartbeat","event":"result","data":{"ok":true,"durationMs":3200}}
+```
+
+The bus event name is split on the first `:` into `channel` and `event`:  
+`heartbeat:result` → `channel: "heartbeat"`, `event: "result"`
+
+### Known bus events captured
+
+`channel:send/receive/register` · `cron:job_start/job_complete/add/remove/enable/disable/run/status/reload` · `heartbeat:check/result` · `jobs:recorded` · `web:mount/unmount/mount-api/unmount-api/ready` · `kysely:ready/ack`
+
+For events not in this list, use the `log` / `log:*` protocol above.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/logger` or `/logger status` | Show current settings and active subscription count |
+| `/logger level <DEBUG\|INFO\|WARN\|ERROR>` | Change minimum log level for the current session |
+| `/logger scope <global\|project>` | Change log scope for the current session |
+| `/logger reload` | Reload settings from disk and resubscribe to events |
+
+## Install
+
+```bash
+pi install npm:@e9n/pi-logger
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@e9n/pi-logger",
+  "version": "0.1.0",
+  "description": "Event bus logger for pi — writes structured JSONL logs from bus events",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Espen Nilsen <hi@e9n.dev>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "README.md",
+    "package.json",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/espennilsen/pi.git",
+    "directory": "extensions/pi-logger"
+  }
+}

package/src/index.ts

@@ -0,0 +1,245 @@
+/**
+ * pi-logger — Event bus logger for pi.
+ *
+ * Listens for events on `pi.events` and writes structured JSONL log files.
+ * All configuration lives under "pi-logger" in settings.json.
+ *
+ * Settings:
+ *   level              — Minimum log level: DEBUG | INFO | WARN | ERROR (default: INFO)
+ *   scope              — Where to write: "global" (~/.pi/agent/logs/) or "project" (.pi/logs/) (default: global)
+ *   timezone           — IANA timezone for timestamps (default: system timezone, e.g. "Europe/Oslo")
+ *   events_whitelist   — Bus event prefixes to subscribe to (default: ["log"] — captures log and log:*)
+ *   events_ignore      — Bus event prefixes to skip (default: [])
+ *   channels_whitelist — Channels to accept in the "log" handler (default: [] = all)
+ *   channels_ignore    — Channels to drop in the "log" handler (default: [])
+ *
+ * Log entries split the bus event name into channel and event:
+ *   "log:webserver"     → channel: "log",       event: "webserver"
+ *   "heartbeat:result"  → channel: "heartbeat",  event: "result"
+ *
+ * Log events carry a level derived from the event name:
+ *   ERROR-level events — names containing "error" or "fail"
+ *   WARN-level events  — names containing "warn" or "alert"
+ *   DEBUG-level events — names containing "debug"
+ *   INFO-level events  — everything else
+ *
+ * Extensions emit structured logs via the "log" bus event:
+ *   pi.events.emit("log", { channel: "webserver", level: "WARN", data: { ... } })
+ *   pi.events.emit("log", { channel: "db", event: "slow-query", data: { ms: 500 } })
+ *
+ * Shorthand by level (level can still be overridden in payload):
+ *   pi.events.emit("log:error", { event: "my-ext:crash", data: { ... } })
+ *   pi.events.emit("log:warn", { event: "cache-miss", level: "ERROR", data: { ... } })
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { resolveSettings, type LogLevel, type LoggerSettings } from "./settings.ts";
+import { writeLogEntry } from "./writer.ts";
+
+// ── Level helpers ───────────────────────────────────────────────
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+	DEBUG: 0,
+	INFO: 1,
+	WARN: 2,
+	ERROR: 3,
+};
+
+function shouldLog(minLevel: LogLevel, eventLevel: LogLevel): boolean {
+	return LEVEL_ORDER[eventLevel] >= LEVEL_ORDER[minLevel];
+}
+
+/** Infer a log level from an event name. */
+function inferLevel(eventName: string): LogLevel {
+	const lower = eventName.toLowerCase();
+	if (lower.includes("error") || lower.includes("fail")) return "ERROR";
+	if (lower.includes("warn") || lower.includes("alert")) return "WARN";
+	if (lower.includes("debug")) return "DEBUG";
+	return "INFO";
+}
+
+// ── Filter helpers ──────────────────────────────────────────────
+
+function matchesPrefix(name: string, prefixes: string[]): boolean {
+	if (prefixes.length === 0) return true;
+	return prefixes.some((p) => name === p || name.startsWith(p + ":") || name.startsWith(p + "."));
+}
+
+/** Check if a bus event should be subscribed to. */
+function shouldCapture(name: string, settings: LoggerSettings): boolean {
+	if (settings.events_ignore.length > 0 && matchesPrefix(name, settings.events_ignore)) return false;
+	if (settings.events_whitelist.length > 0) return matchesPrefix(name, settings.events_whitelist);
+	return true;
+}
+
+/** Check if a channel from the "log" handler should be written. */
+function shouldCaptureChannel(channel: string, settings: LoggerSettings): boolean {
+	if (settings.channels_ignore.length > 0 && settings.channels_ignore.includes(channel)) return false;
+	if (settings.channels_whitelist.length > 0) return settings.channels_whitelist.includes(channel);
+	return true;
+}
+
+// ── Extension entry point ───────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	let settings: LoggerSettings;
+	let cwd = process.cwd();
+	const subscriptions: Array<() => void> = [];
+
+	// ── Setup / teardown ────────────────────────────────────────
+
+	function setup(): void {
+		settings = resolveSettings(cwd);
+		teardown();
+
+		// Main log handler: pi.events.emit("log", { level?, channel?, event?, data })
+		//
+		// All custom logging goes through "log". Extensions set their own level
+		// and channel in the payload. If level is omitted it defaults to INFO.
+		// The channel field controls the channel/event split in the log file:
+		//   emit("log", { channel: "webserver", level: "WARN", data: { ... } })
+		//   → { channel: "webserver", event: "", level: "WARN", ... }
+		//   emit("log", { channel: "webserver", event: "request", data: { ... } })
+		//   → { channel: "webserver", event: "request", level: "INFO", ... }
+		//
+		// channels_whitelist / channels_ignore filter which channels are written.
+		subscriptions.push(pi.events.on("log", (payload: unknown) => {
+			const p = payload as Record<string, any> | undefined;
+			if (!p || typeof p !== "object") return;
+			const channel = typeof p.channel === "string" ? p.channel : "log";
+			if (!shouldCaptureChannel(channel, settings)) return;
+			const level = (typeof p.level === "string" && LEVEL_ORDER[p.level.toUpperCase() as LogLevel] !== undefined
+				? p.level.toUpperCase()
+				: "INFO") as LogLevel;
+			if (!shouldLog(settings.level, level)) return;
+			const event = typeof p.event === "string" ? p.event : "";
+			const busEvent = event ? `${channel}:${event}` : channel;
+			writeLogEntry(busEvent, level, p.data ?? null, settings.scope, cwd, settings.timezone);
+		}));
+
+		// Shorthand: log:debug, log:info, log:warn, log:error
+		// Level is inferred from the event name but can be overridden in payload.
+		for (const lvl of ["debug", "info", "warn", "error"] as const) {
+			const defaultLevel = lvl.toUpperCase() as LogLevel;
+			subscriptions.push(pi.events.on(`log:${lvl}`, (payload: unknown) => {
+				const p = payload as Record<string, any> | undefined;
+				const level = (typeof p?.level === "string" && LEVEL_ORDER[p.level.toUpperCase() as LogLevel] !== undefined
+					? p.level.toUpperCase()
+					: defaultLevel) as LogLevel;
+				if (!shouldLog(settings.level, level)) return;
+				const event = typeof p?.event === "string" ? p.event : `log:${lvl}`;
+				writeLogEntry(event, level, p?.data ?? p ?? null, settings.scope, cwd, settings.timezone);
+			}));
+		}
+
+		// Subscribe to well-known bus events.
+		// For events not in this list, extensions should use the log/log:* protocol.
+		const knownEvents = [
+			"channel:send", "channel:receive", "channel:register",
+			"cron:job_start", "cron:job_complete", "cron:add", "cron:remove",
+			"cron:enable", "cron:disable", "cron:run", "cron:status", "cron:reload",
+			"heartbeat:check", "heartbeat:result",
+			"jobs:recorded",
+			"web:mount", "web:unmount", "web:mount-api", "web:unmount-api", "web:ready",
+			"kysely:ready", "kysely:ack",
+		];
+
+		for (const eventName of knownEvents) {
+			if (!shouldCapture(eventName, settings)) continue;
+			subscriptions.push(pi.events.on(eventName, (data: unknown) => {
+				const level = inferLevel(eventName);
+				if (!shouldLog(settings.level, level)) return;
+				writeLogEntry(eventName, level, data ?? null, settings.scope, cwd, settings.timezone);
+			}));
+		}
+	}
+
+	function teardown(): void {
+		for (const unsub of subscriptions) unsub();
+		subscriptions.length = 0;
+	}
+
+	// ── Lifecycle ───────────────────────────────────────────────
+
+	pi.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+		setup();
+		writeLogEntry("logger:start", "INFO", {
+			scope: settings.scope,
+			level: settings.level,
+			timezone: settings.timezone,
+			events_whitelist: settings.events_whitelist,
+			events_ignore: settings.events_ignore,
+			channels_whitelist: settings.channels_whitelist,
+			channels_ignore: settings.channels_ignore,
+		}, settings.scope, cwd, settings.timezone);
+	});
+
+	pi.on("session_shutdown", async () => {
+		writeLogEntry("logger:stop", "INFO", null, settings.scope, cwd, settings.timezone);
+		teardown();
+	});
+
+	// ── Command: /logger ────────────────────────────────────────
+
+	pi.registerCommand("logger", {
+		description: "Show logger status or change settings: /logger [status|level <LVL>|scope <global|project>|reload]",
+		getArgumentCompletions: (prefix: string) => {
+			const items = [
+				{ value: "status", label: "status — Show current logger settings" },
+				{ value: "level", label: "level <DEBUG|INFO|WARN|ERROR> — Change log level" },
+				{ value: "scope", label: "scope <global|project> — Change log scope" },
+				{ value: "reload", label: "reload — Reload settings from disk" },
+			];
+			return items.filter((i) => i.value.startsWith(prefix));
+		},
+		handler: async (args, ctx) => {
+			const parts = (args ?? "").trim().split(/\s+/);
+			const cmd = parts[0]?.toLowerCase();
+
+			if (cmd === "level" && parts[1]) {
+				const lvl = parts[1].toUpperCase() as LogLevel;
+				if (LEVEL_ORDER[lvl] === undefined) {
+					ctx.ui.notify("Invalid level. Use: DEBUG, INFO, WARN, ERROR", "error");
+					return;
+				}
+				settings.level = lvl;
+				ctx.ui.notify(`Log level set to ${lvl}`, "info");
+				writeLogEntry("logger:level_change", "INFO", { level: lvl }, settings.scope, cwd, settings.timezone);
+				return;
+			}
+
+			if (cmd === "scope" && parts[1]) {
+				const s = parts[1].toLowerCase();
+				if (s !== "global" && s !== "project") {
+					ctx.ui.notify("Invalid scope. Use: global, project", "error");
+					return;
+				}
+				settings.scope = s;
+				ctx.ui.notify(`Log scope set to ${s}`, "info");
+				writeLogEntry("logger:scope_change", "INFO", { scope: s }, settings.scope, cwd, settings.timezone);
+				return;
+			}
+
+			if (cmd === "reload") {
+				setup();
+				ctx.ui.notify(`Logger reloaded: level=${settings.level}, scope=${settings.scope}, tz=${settings.timezone}`, "info");
+				return;
+			}
+
+			// Default: status
+			const fmt = (arr: string[], label: string) =>
+				arr.length > 0 ? `${label}: ${arr.join(", ")}` : `${label}: all`;
+			const lines = [
+				`Logger: level=${settings.level}, scope=${settings.scope}`,
+				`Timezone: ${settings.timezone}`,
+				fmt(settings.events_whitelist, "Events whitelist"),
+				settings.events_ignore.length > 0 ? `Events ignore: ${settings.events_ignore.join(", ")}` : "Events ignore: none",
+				fmt(settings.channels_whitelist, "Channels whitelist"),
+				settings.channels_ignore.length > 0 ? `Channels ignore: ${settings.channels_ignore.join(", ")}` : "Channels ignore: none",
+				`Subscriptions: ${subscriptions.length}`,
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/src/settings.ts

@@ -0,0 +1,74 @@
+/**
+ * pi-logger — Settings loader.
+ *
+ * Reads "pi-logger" from global and project settings.json, merges them
+ * (project overrides global).
+ */
+
+import { getAgentDir, SettingsManager } from "@mariozechner/pi-coding-agent";
+
+export type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+
+export type LogScope = "global" | "project";
+
+export interface LoggerSettings {
+	/** Minimum level to write. Events below this are discarded. */
+	level: LogLevel;
+	/** Where to store logs: "global" → ~/.pi/agent/logs/, "project" → .pi/logs/ */
+	scope: LogScope;
+	/** IANA timezone for timestamps. Defaults to system tz. Example: "Europe/Oslo" */
+	timezone: string;
+	/** Bus event prefixes to subscribe to. Default: ["log"] (captures log, log:*). */
+	events_whitelist: string[];
+	/** Bus event prefixes to ignore (applied after whitelist). */
+	events_ignore: string[];
+	/** Channel whitelist for the "log" handler. Empty = accept all channels. */
+	channels_whitelist: string[];
+	/** Channels to ignore (applied after whitelist). */
+	channels_ignore: string[];
+}
+
+/** Detect the system timezone via Intl. Falls back to UTC. */
+function systemTimezone(): string {
+	try {
+		return Intl.DateTimeFormat().resolvedOptions().timeZone;
+	} catch {
+		return "UTC";
+	}
+}
+
+const DEFAULTS: LoggerSettings = {
+	level: "INFO",
+	scope: "global",
+	timezone: systemTimezone(),
+	events_whitelist: ["log"],
+	events_ignore: [],
+	channels_whitelist: [],
+	channels_ignore: [],
+};
+
+const VALID_LEVELS: LogLevel[] = ["DEBUG", "INFO", "WARN", "ERROR"];
+
+export function resolveSettings(cwd: string): LoggerSettings {
+	try {
+		const agentDir = getAgentDir();
+		const sm = SettingsManager.create(cwd, agentDir);
+		const global = sm.getGlobalSettings() as Record<string, any>;
+		const project = sm.getProjectSettings() as Record<string, any>;
+		const cfg = { ...(global?.["pi-logger"] ?? {}), ...(project?.["pi-logger"] ?? {}) };
+
+		const rawLevel = (cfg.level ?? "").toUpperCase();
+
+		return {
+			level: VALID_LEVELS.includes(rawLevel as LogLevel) ? (rawLevel as LogLevel) : DEFAULTS.level,
+			scope: cfg.scope === "project" ? "project" : DEFAULTS.scope,
+			timezone: typeof cfg.timezone === "string" && cfg.timezone ? cfg.timezone : DEFAULTS.timezone,
+			events_whitelist: Array.isArray(cfg.events_whitelist) ? cfg.events_whitelist : DEFAULTS.events_whitelist,
+			events_ignore: Array.isArray(cfg.events_ignore) ? cfg.events_ignore : DEFAULTS.events_ignore,
+			channels_whitelist: Array.isArray(cfg.channels_whitelist) ? cfg.channels_whitelist : DEFAULTS.channels_whitelist,
+			channels_ignore: Array.isArray(cfg.channels_ignore) ? cfg.channels_ignore : DEFAULTS.channels_ignore,
+		};
+	} catch {
+		return { ...DEFAULTS };
+	}
+}

package/src/writer.ts

@@ -0,0 +1,126 @@
+/**
+ * pi-logger — JSONL file writer.
+ *
+ * Writes one JSON line per log entry to per-day files.
+ * Directory depends on scope setting:
+ *   global:  ~/.pi/agent/logs/YYYY-MM-DD.jsonl
+ *   project: .pi/logs/YYYY-MM-DD.jsonl
+ *
+ * Timestamps are formatted in the configured timezone.
+ * Errors are silently swallowed — logging must never break the agent.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import type { LogScope } from "./settings.ts";
+
+export interface LogEntry {
+	ts: string;
+	level: string;
+	channel: string;
+	event: string;
+	data: unknown;
+}
+
+/** Resolve the logs directory based on scope. */
+function getLogsDir(scope: LogScope, cwd: string): string {
+	if (scope === "project") {
+		return path.join(cwd, ".pi", "logs");
+	}
+	return path.join(getAgentDir(), "logs");
+}
+
+/** Format a Date in the given IANA timezone as YYYY-MM-DD. */
+function dateTag(timezone: string): string {
+	try {
+		// Use sv-SE locale for ISO-ish date part (YYYY-MM-DD)
+		const parts = new Intl.DateTimeFormat("sv-SE", {
+			timeZone: timezone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+		}).formatToParts(new Date());
+
+		const y = parts.find((p) => p.type === "year")!.value;
+		const m = parts.find((p) => p.type === "month")!.value;
+		const d = parts.find((p) => p.type === "day")!.value;
+		return `${y}-${m}-${d}`;
+	} catch {
+		return new Date().toISOString().slice(0, 10);
+	}
+}
+
+/** Format a Date as an ISO-ish timestamp in the given timezone. */
+function formatTimestamp(timezone: string): string {
+	try {
+		const now = new Date();
+		const fmt = new Intl.DateTimeFormat("en-GB", {
+			timeZone: timezone,
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			fractionalSecondDigits: 3,
+			hour12: false,
+		});
+		const parts = fmt.formatToParts(now);
+		const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "00";
+		return `${get("year")}-${get("month")}-${get("day")}T${get("hour")}:${get("minute")}:${get("second")}.${get("fractionalSecond")}`;
+	} catch {
+		return new Date().toISOString();
+	}
+}
+
+/** Singleton-ish state to avoid re-creating dirs on every write. */
+let ensuredDir: string | null = null;
+
+/**
+ * Split a bus event name into channel and event.
+ * "log:webserver" → { channel: "log", event: "webserver" }
+ * "heartbeat:result" → { channel: "heartbeat", event: "result" }
+ * "log" → { channel: "log", event: "" }
+ */
+function splitEvent(busEvent: string): { channel: string; event: string } {
+	const idx = busEvent.indexOf(":");
+	if (idx === -1) return { channel: busEvent, event: "" };
+	return { channel: busEvent.slice(0, idx), event: busEvent.slice(idx + 1) };
+}
+
+/**
+ * Append a log entry to the daily JSONL file.
+ * Safe to call at any frequency — writes are synchronous appends.
+ */
+export function writeLogEntry(
+	busEvent: string,
+	level: string,
+	data: unknown,
+	scope: LogScope,
+	cwd: string,
+	timezone: string,
+): void {
+	try {
+		const dir = getLogsDir(scope, cwd);
+		if (ensuredDir !== dir) {
+			fs.mkdirSync(dir, { recursive: true });
+			ensuredDir = dir;
+		}
+
+		const { channel, event } = splitEvent(busEvent);
+
+		const entry: LogEntry = {
+			ts: formatTimestamp(timezone),
+			level,
+			channel,
+			event,
+			data,
+		};
+
+		const file = path.join(dir, `${dateTag(timezone)}.jsonl`);
+		fs.appendFileSync(file, JSON.stringify(entry) + "\n", "utf-8");
+	} catch {
+		// Swallow — logging must never disrupt the agent.
+	}
+}