pi-extension-utils 0.3.3 → 0.4.1

package/dist/src/index.d.ts

@@ -1,6 +1,6 @@
 export { connect, type FullscreenComponentFactory, type FullscreenLease, type RemindersClient, type UtilsClient, type UtilsClientOptions, type WidgetSetOptions } from "./client/index.ts";
 export { defineConfig, type DeepPartial, type DefinedConfig, type DefineConfigOptions } from "./config/index.ts";
-export { createLogger, LOG_LEVELS, loggerLevelSchema, loggingConfigSchema, type Logger, type LoggerLevel, type LoggerOptions, type LoggingConfig, type LogLevel } from "./logger/index.ts";
+export { createLogger, LOG_LEVELS, loggerLevelSchema, loggingConfigSchema, type Logger, type LoggerFields, type LoggerLevel, type LoggerOptions, type LoggerRecord, type LoggingConfig, type LogLevel } from "./logger/index.ts";
 export { utilsConfigSchema, type UtilsConfig } from "./utils-config.ts";
 export * from "./pane/key-dispatch.ts";
 export * from "./pane/state.ts";

package/dist/src/logger/index.d.ts

@@ -3,18 +3,25 @@ export { LOG_LEVELS, loggerLevelSchema, loggingConfigSchema, type LoggerLevel, t
 export interface LoggerOptions {
     dir?: string;
     maxBytes?: number;
-    /** Number of rotated files to retain: name.log.1, name.log.2, ... */
+    /** Number of rotated files to retain: name.jsonl.1, name.jsonl.2, ... */
     maxFiles?: number;
     /** Minimum level to write. Defaults to utilsConfig.logging.level. */
     level?: LoggerLevel;
 }
+export type LoggerFields = Record<string, unknown>;
 export interface Logger {
-    debug(message: string): void;
-    info(message: string): void;
-    warn(message: string): void;
-    error(message: string): void;
-    log(level: LogLevel, message: string): void;
+    debug(message: string, fields?: LoggerFields): void;
+    info(message: string, fields?: LoggerFields): void;
+    warn(message: string, fields?: LoggerFields): void;
+    error(message: string, fields?: LoggerFields): void;
+    log(level: LogLevel, message: string, fields?: LoggerFields): void;
     setLevel(level: LoggerLevel): void;
     isEnabled(level: LogLevel): boolean;
 }
+export interface LoggerRecord {
+    ts: string;
+    level: LogLevel;
+    message: string;
+    [field: string]: unknown;
+}
 export declare function createLogger(name: string, opts?: LoggerOptions): Logger;

package/dist/src/logger/index.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { readUtilsConfigOrDefaults } from "../utils-config.js";
 export { LOG_LEVELS, loggerLevelSchema, loggingConfigSchema } from "./config.js";
+const RESERVED_RECORD_FIELDS = new Set(["ts", "level", "message"]);
 const LEVEL_WEIGHT = {
     debug: 10,
     info: 20,
@@ -21,7 +22,7 @@ export function createLogger(name, opts = {}) {
     const maxBytes = Math.max(0, Math.floor(opts.maxBytes ?? configured?.maxBytes ?? 1024 * 1024));
     const maxFiles = Math.max(0, Math.floor(opts.maxFiles ?? configured?.maxFiles ?? 3));
     let level = opts.level ?? configured?.level ?? "info";
-    const file = join(dir, `${name}.log`);
+    const file = join(dir, `${name}.jsonl`);
     mkdirSync(dirname(file), { recursive: true });
     function rotateIfNeeded(nextBytes) {
         if (maxBytes <= 0 || !existsSync(file))
@@ -46,26 +47,31 @@ export function createLogger(name, opts = {}) {
     function isEnabled(candidate) {
         return LEVEL_WEIGHT[candidate] >= LEVEL_WEIGHT[level];
     }
-    function log(candidate, message) {
+    function log(candidate, message, fields = {}) {
         if (!isEnabled(candidate))
             return;
-        const line = `${new Date().toISOString()} ${candidate} ${message}\n`;
+        const record = { ts: new Date().toISOString(), level: candidate, message };
+        for (const [key, value] of Object.entries(fields)) {
+            if (!RESERVED_RECORD_FIELDS.has(key))
+                record[key] = value;
+        }
+        const line = `${JSON.stringify(record)}\n`;
         mkdirSync(dirname(file), { recursive: true });
         rotateIfNeeded(Buffer.byteLength(line));
         appendFileSync(file, line);
     }
     return {
-        debug(message) {
-            log("debug", message);
+        debug(message, fields) {
+            log("debug", message, fields);
         },
-        info(message) {
-            log("info", message);
+        info(message, fields) {
+            log("info", message, fields);
         },
-        warn(message) {
-            log("warn", message);
+        warn(message, fields) {
+            log("warn", message, fields);
         },
-        error(message) {
-            log("error", message);
+        error(message, fields) {
+            log("error", message, fields);
         },
         log,
         setLevel(nextLevel) {

package/docs/client.md

@@ -77,12 +77,12 @@ const log = createLogger("my-extension", {
 });
 
 log.debug("hidden at info level");
-log.info("started");
-log.warn("slow path");
+log.info("started", { command: "example" });
+log.warn("slow path", { durationMs: 1200 });
 log.error("failed");
 ```
 
-`createLogger(name)` writes to `getAgentDir()/log/<name>.log` by default. `level` is typed as `"debug" | "info" | "warn" | "error" | "silent"`; `maxFiles` controls retained rotations (`.1`, `.2`, ...). If `level`, `maxFiles`, or `maxBytes` are omitted, the value comes from `getAgentDir()/config/utils.jsonc` `logging` defaults. Explicit options always win.
+`createLogger(name)` writes JSONL to `getAgentDir()/log/<name>.jsonl` by default. Each line is a flat object like `{"ts":"...","level":"info","message":"started","command":"example"}`. `ts`, `level`, and `message` are logger-owned fields and caller fields with those names are ignored. `level` is typed as `"debug" | "info" | "warn" | "error" | "silent"`; `maxFiles` controls retained rotations (`.1`, `.2`, ...). If `level`, `maxFiles`, or `maxBytes` are omitted, the value comes from `getAgentDir()/config/utils.jsonc` `logging` defaults. Explicit options always win.
 
 Override when needed:
 

package/examples/logger.ts

@@ -8,7 +8,7 @@ const log = createLogger("example-extension", {
 
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
-    log.info(`session started cwd=${ctx.cwd}`);
+    log.info("session started", { cwd: ctx.cwd });
   });
 
   pi.registerCommand("example-log", {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-extension-utils",
-	"version": "0.3.3",
+	"version": "0.4.1",
 	"description": "Shared Pi extension utilities for coordinated widgets, fullscreen leases, and logging.",
 	"type": "module",
 	"main": "./dist/src/index.js",