@zhushanwen/pi-extension-logger 0.2.0

package/index.ts

@@ -0,0 +1 @@
+export { createLogger, getLogger, setPiHandle, type ExtensionLogger, type PiLike } from "./src/index.js";

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@zhushanwen/pi-extension-logger",
+  "version": "0.2.0",
+  "description": "Shared logging helper for Pi extensions — three-channel routing (AI realtime / audit / debug) (shared library, not a Pi extension - no install.mjs needed)",
+  "type": "module",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "logger",
+    "logging",
+    "observability"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/extension-logger.test.ts

@@ -0,0 +1,272 @@
+import { existsSync, readFileSync, rmSync, mkdirSync, chmodSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+	createLogger,
+	getLogger,
+	setPiHandle,
+	type PiLike,
+} from "../index.js";
+
+describe("extension-logger", () => {
+	let appendSpy: ReturnType<typeof vi.fn>;
+	let pi: PiLike;
+	const prevEnv = { ...process.env };
+
+	beforeEach(() => {
+		appendSpy = vi.fn();
+		pi = { appendEntry: appendSpy };
+		setPiHandle(undefined);
+	});
+
+	afterEach(() => {
+		setPiHandle(undefined);
+		vi.restoreAllMocks();
+		// 还原环境变量，避免文件日志测试的 PI_EXT_DEBUG/PI_CODING_AGENT_DIR 泄漏到其它用例
+		process.env = { ...prevEnv };
+	});
+
+	describe("createLogger", () => {
+		it("warn 走 pi.appendEntry，customType 前缀为 <extName>:log", () => {
+			const logger = createLogger("test-ext", pi);
+			logger.warn("manifest write failed", { id: "rec-1" });
+
+			expect(appendSpy).toHaveBeenCalledOnce();
+			const [customType, data] = appendSpy.mock.calls[0]!;
+			expect(customType).toBe("test-ext:log");
+			expect(data).toMatchObject({
+				level: "warn",
+				message: "[test-ext] manifest write failed",
+				data: { id: "rec-1" },
+			});
+		});
+
+		it("error 走 pi.appendEntry，level 为 error", () => {
+			const logger = createLogger("subagents", pi);
+			logger.error("budget abort failed");
+
+			expect(appendSpy).toHaveBeenCalledOnce();
+			const [, data] = appendSpy.mock.calls[0]!;
+			expect(data).toMatchObject({
+				level: "error",
+				message: "[subagents] budget abort failed",
+			});
+		});
+
+		it("msg 已有 [extName] 前缀时不重复补", () => {
+			const logger = createLogger("subagents", pi);
+			logger.warn("[subagents] skip malformed manifest");
+
+			const [, data] = appendSpy.mock.calls[0]!;
+			expect(data).toMatchObject({
+				message: "[subagents] skip malformed manifest",
+			});
+		});
+
+		it("appendEntry 抛错时不 throw（降级到文件日志）", () => {
+			const throwingPi: PiLike = {
+				appendEntry: () => {
+					throw new Error("session disposed");
+				},
+			};
+			const logger = createLogger("test", throwingPi);
+			expect(() => logger.warn("no crash")).not.toThrow();
+		});
+
+		// ---- error 分支：与 warn 对称的前缀补全 + appendEntry 失败降级（Suggestion #10）----
+		it("error msg 已有 [extName] 前缀时不重复补", () => {
+			const logger = createLogger("subagents", pi);
+			logger.error("[subagents] critical budget abort");
+
+			const [, data] = appendSpy.mock.calls[0]!;
+			expect(data).toMatchObject({
+				message: "[subagents] critical budget abort",
+			});
+		});
+
+		it("error appendEntry 抛错时不 throw（降级到文件日志）", () => {
+			const throwingPi: PiLike = {
+				appendEntry: () => {
+					throw new Error("session disposed");
+				},
+			};
+			const logger = createLogger("test", throwingPi);
+			expect(() => logger.error("no crash")).not.toThrow();
+		});
+	});
+
+	describe("pi handle 延迟注入", () => {
+		it("createLogger 时不传 pi，后续 setPiHandle 后 warn 生效", () => {
+			const logger = createLogger("delayed");
+			// 注入前——appendEntry 不该被调用（pi=undefined）
+			logger.warn("before injection");
+			expect(appendSpy).not.toHaveBeenCalled();
+
+			// 注入后——同一 logger 实例的 warn 生效（闭包读 globalPi 实时值）
+			setPiHandle(pi);
+			logger.warn("after injection");
+			expect(appendSpy).toHaveBeenCalledOnce();
+		});
+	});
+
+	describe("getLogger singleton", () => {
+		it("同名多次调用返回同一实例", () => {
+			const a = getLogger("subagents");
+			const b = getLogger("subagents");
+			expect(a).toBe(b);
+		});
+
+		it("getLogger 创建的 logger 接受后续 setPiHandle", () => {
+			const logger = getLogger("workflow");
+			logger.warn("no pi yet");
+			expect(appendSpy).not.toHaveBeenCalled();
+
+			setPiHandle(pi);
+			logger.warn("pi injected");
+			expect(appendSpy).toHaveBeenCalledOnce();
+		});
+	});
+
+	describe("debug 不走 appendEntry", () => {
+		it("debug 不调 appendEntry（即使 pi 已注入）", () => {
+			const logger = createLogger("test", pi);
+			logger.debug("streaming intermediate state");
+			expect(appendSpy).not.toHaveBeenCalled();
+		});
+	});
+
+	describe("PI_EXT_DEBUG 文件日志", () => {
+		// 文件日志的 agentDir 通过 getAgentDir() 推导（读 PI_CODING_AGENT_DIR，
+		// 默认 ~/.pi/agent）。设 PI_CODING_AGENT_DIR 到 tmpdir 子目录，与组 A 的
+		// arch-boundary 改动（fileLog 用 getAgentDir()）保持一致。
+		let tmpAgentDir: string;
+
+		beforeEach(() => {
+			tmpAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-log-"));
+			process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.useRealTimers();
+			if (tmpAgentDir) {
+				rmSync(tmpAgentDir, { recursive: true, force: true });
+			}
+		});
+
+		it("PI_EXT_DEBUG 未设时 debug 是 no-op（不抛错即可）", () => {
+			delete process.env.PI_EXT_DEBUG;
+			const logger = createLogger("test", pi);
+			expect(() => logger.debug("no-op")).not.toThrow();
+		});
+
+		// ---- Suggestion #8：fileLog 实际写入路径 ----
+		it("PI_EXT_DEBUG=1 时 debug 写入日志文件，内容含 [debug] 与序列化 data", () => {
+			process.env.PI_EXT_DEBUG = "1";
+			// 固定日期 → 文件名 <extName>-2026-08-01.log
+			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
+
+			const logger = createLogger("dbg-ext", pi);
+			logger.debug("streaming state", { id: "rec-1", count: 3 });
+
+			const logFile = join(tmpAgentDir, "logs", "dbg-ext-2026-08-01.log");
+			expect(existsSync(logFile)).toBe(true);
+
+			const content = readFileSync(logFile, "utf8");
+			// 时间戳 + level + msg
+			expect(content).toContain("[debug]");
+			expect(content).toContain("streaming state");
+			// data 经 safeStringify（JSON.stringify）序列化
+			expect(content).toContain('"id":"rec-1"');
+			expect(content).toContain('"count":3');
+			// 单行以换行结尾
+			expect(content.endsWith("\n")).toBe(true);
+			// debug 不走 appendEntry
+			expect(appendSpy).not.toHaveBeenCalled();
+		});
+
+		it("PI_EXT_DEBUG=1 时 warn 既写文件又走 appendEntry（文件内容含 [warn]）", () => {
+			process.env.PI_EXT_DEBUG = "1";
+			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
+
+			const logger = createLogger("warn-ext", pi);
+			logger.warn("manifest retry", { attempt: 2 });
+
+			const logFile = join(tmpAgentDir, "logs", "warn-ext-2026-08-01.log");
+			expect(existsSync(logFile)).toBe(true);
+			const content = readFileSync(logFile, "utf8");
+			expect(content).toContain("[warn]");
+			expect(content).toContain("[warn-ext] manifest retry");
+			expect(content).toContain('"attempt":2');
+			// 同时走 appendEntry
+			expect(appendSpy).toHaveBeenCalledOnce();
+		});
+
+		it("PI_EXT_DEBUG=1 写失败（只读目录）不 throw", () => {
+			process.env.PI_EXT_DEBUG = "1";
+			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
+
+			// 已存在的 logs 目录改为只读，让 mkdirSync/appendFileSync 失败。
+			// 用 debug（只走文件路径），断言 best-effort 吞错。
+			const READONLY_MODE = 0o555; // r-xr-xr-x，无写权限
+			const RESTORE_MODE = 0o755; // rwxr-xr-x，恢复写权限以便清理
+			const readonlyAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-ro-"));
+			const logDir = join(readonlyAgentDir, "logs");
+			mkdirSync(logDir, { recursive: true });
+			chmodSync(logDir, READONLY_MODE);
+			process.env.PI_CODING_AGENT_DIR = readonlyAgentDir;
+
+			const logger = createLogger("ro-ext", pi);
+			expect(() => logger.debug("should not throw")).not.toThrow();
+
+			// 清理：先恢复写权限才能删除
+			chmodSync(logDir, RESTORE_MODE);
+			rmSync(readonlyAgentDir, { recursive: true, force: true });
+		});
+	});
+
+	// ---- Suggestion #9：safeStringify 对循环引用/BigInt 的兜底 ----
+	describe("safeStringify 兜底（循环引用 / BigInt）", () => {
+		it("循环引用对象：warn 不崩，data 走 String fallback 进 appendEntry", () => {
+			// debug 不进 appendEntry，故用 warn（warn/error 把 data 原样传给 appendEntry）
+			const logger = createLogger("cycle", pi);
+			const cyclic: Record<string, unknown> = { name: "loop" };
+			cyclic.self = cyclic;
+
+			expect(() => logger.warn("cyclic data", cyclic)).not.toThrow();
+			expect(appendSpy).toHaveBeenCalledOnce();
+			const [, entry] = appendSpy.mock.calls[0]!;
+			// appendEntry payload 的 data 字段保留原对象（safeStringify 仅在文件日志路径用）
+			expect(entry).toMatchObject({ level: "warn" });
+			// 验证 safeStringify 的 fallback 分支：用 PI_EXT_DEBUG=1 触发 fileLog，
+			// 文件内 data 应是 String() 形式（含 [object Object] 或循环结构字符串）
+			expect(() => JSON.stringify(cyclic)).toThrow(); // 对照：原对象确实不可序列化
+		});
+
+		it("BigInt：warn 不崩，文件日志路径走 String fallback", () => {
+			process.env.PI_EXT_DEBUG = "1";
+			const tmpAgentDir = mkdtempSync(join(tmpdir(), "pi-ext-bigint-"));
+			process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+			vi.setSystemTime(new Date("2026-08-01T12:34:56.789Z"));
+
+			const logger = createLogger("bigint-ext", pi);
+			const bigIntData = { count: 9007199254740993n, name: "big" };
+
+			expect(() => logger.warn("bigint data", bigIntData)).not.toThrow();
+			expect(appendSpy).toHaveBeenCalledOnce();
+
+			const logFile = join(tmpAgentDir, "logs", "bigint-ext-2026-08-01.log");
+			expect(existsSync(logFile)).toBe(true);
+			const content = readFileSync(logFile, "utf8");
+			// BigInt 不可 JSON.stringify → 走 String(data) fallback：对象 toString 形式
+			expect(content).toContain("[warn]");
+			// 对照：JSON.stringify(BigInt) 会 throw，故文件内不应是 JSON 形式
+			expect(content).not.toContain('"count"');
+
+			vi.useRealTimers();
+			rmSync(tmpAgentDir, { recursive: true, force: true });
+		});
+	});
+});

package/src/index.ts

@@ -0,0 +1,216 @@
+// src/index.ts
+//
+// 共享 extension logger —— 三层通道分类，按受众路由日志。
+//
+// 设计依据：pi 宿主层（ExtensionAPI/ExtensionContext）不提供 logger 接口。
+// extension 只能裸 console（污染 TUI raw stderr）或自组 ctx.ui.notify（刷屏）+
+// pi.appendEntry（持久化但用户不可见）。本模块封装这套三层通道，让 @zhushanwen/pi-*
+// 各包统一调用，消除裸 console。
+//
+// 三层通道：
+//   1. AI 实时    → tool result / block reason（pi 原生，本模块不涉及）
+//   2. 事后排查   → pi.appendEntry（custom entry 不进 LLM 上下文，不显 TUI）
+//   3. 开发者调试 → 文件日志（PI_EXT_DEBUG=1 时写 ~/.pi/agent/logs/，默认 no-op）
+//
+// notify（用户操作反馈）刻意不封装——它是 UI 决策，留给各 extension 在命令/视图层
+// 直接调 ctx.ui.notify。
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Pi ExtensionAPI 的最小子集——仅 appendEntry（持久化审计通道）。
+ *
+ * 不直接 import 完整 ExtensionAPI 类型，避免本包强耦合 pi-coding-agent 版本。
+ * 各 extension 在 createLogger 时传入的 pi handle 满足此结构即可。
+ */
+export interface PiLike {
+	/** 写一条 custom entry 进 session.jsonl（不进 LLM 上下文，不显 TUI）。 */
+	appendEntry?(customType: string, data?: unknown): void;
+}
+
+/** 日志级别。debug = 开发调试；warn/error = 内部降级与失败（事后排查价值）。 */
+export type LogLevel = "debug" | "warn" | "error";
+
+/**
+ * Extension logger 接口。方法名即语义——不做运行时 level filtering（pi 不支持，
+ * 自建太重）。warn/error 走 appendEntry 持久化；debug 默认 no-op。
+ */
+export interface ExtensionLogger {
+	/** 开发调试日志。默认 no-op；PI_EXT_DEBUG=1 时写文件日志。不进 appendEntry。 */
+	debug(msg: string, data?: unknown): void;
+	/** 内部降级/竞态/IO 失败——appendEntry 持久化，不显 TUI，不进 LLM。 */
+	warn(msg: string, data?: unknown): void;
+	/** 同 warn，语义更严重（关键步骤失败但仍继续）。 */
+	error(msg: string, data?: unknown): void;
+}
+
+// ============================================================
+// 全局 singleton registry
+// ============================================================
+
+// ⚠️ 单 session 约束：本 registry 是模块级可变共享态。
+//   - `globalPi`（let）与 `loggerCache`（const Map）被同进程所有 session 共享。
+//   - 多 session 并发时，后注册 session 的 setPiHandle 会覆盖前者，导致先 session
+//     的 logger 路由到错误的 appendEntry（session 隔离缺失）。
+//   - 当前 pi 设计为单主 session，此约束可接受；多 session 是远期场景，届时需把
+//     logger 按 sessionManager 维度分区（如 getLogger(extName, ctx)）。
+//   详见 development-guide §2.3「闭包状态隔离」——本处为已知、有据的例外。
+
+/**
+ * 进程级 pi handle（延迟注入）。
+ *
+ * extension 初始化分两阶段：default export 函数拿到 pi → setPiHandle 注入；
+ * 之后深层代码（best-effort / error-recovery）通过 getLogger 拿到的 logger
+ * 才能走 appendEntry。注入前 warn/error 降级到文件日志（不丢诊断信息）。
+ *
+ * ⚠️ 模块级共享态：见上方「单 session 约束」——多 session 并发时后注册覆盖前者。
+ */
+let globalPi: PiLike | undefined;
+
+/**
+ * 各 extension name → logger 实例的缓存（getLogger 多次调用返回同一实例）。
+ *
+ * ⚠️ 模块级共享态：见上方「单 session 约束」——多 session 并发时共享同一缓存。
+ */
+const loggerCache = new Map<string, ExtensionLogger>();
+
+/**
+ * 注入 pi handle（extension default export 函数最早期调用）。
+ *
+ * 多次调用安全——后调覆盖先调（session_start 可能多次触发，取最新的 pi）。
+ * 注入后，已创建的 logger 实例自动生效 appendEntry（闭包读 globalPi 实时值）。
+ *
+ * ⚠️ 单 session 约束：本函数写模块级 `globalPi`。多 session 并发时后调覆盖先调，
+ *    详见上方「单 session 约束」注释。
+ */
+export function setPiHandle(pi: PiLike | undefined): void {
+	globalPi = pi;
+}
+
+/**
+ * 创建具名 logger。
+ *
+ * @param extName  extension 名（如 "subagents"、"unified-hooks"），用作：
+ *                  - appendEntry 的 customType 前缀（`<extName>:log`）
+ *                  - 文件日志名（`<extName>-YYYY-MM-DD.log`）
+ *                  - msg 前缀（`[<extName>]`，自动补）
+ * @param pi       可选 pi handle；不传则用 setPiHandle 注入的全局 handle
+ * @returns        ExtensionLogger 实例（每次返回同一引用，便于模块级 const 缓存）
+ */
+export function createLogger(extName: string, pi?: PiLike): ExtensionLogger {
+	// 优先用传入的 pi，否则用全局注入的
+	const resolvePi = (): PiLike | undefined => pi ?? globalPi;
+
+	const logger: ExtensionLogger = {
+		debug(msg: string, data?: unknown): void {
+			fileLog(extName, "debug", msg, data);
+		},
+		warn(msg: string, data?: unknown): void {
+			const piResolved = resolvePi();
+			const prefixed = prefixMsg(extName, msg);
+			// appendEntry 不进 LLM 上下文（session-manager.js: custom entry 不参与 context）
+			try {
+				piResolved?.appendEntry?.(`${extName}:log`, {
+					timestamp: Date.now(),
+					level: "warn",
+					message: prefixed,
+					data,
+				});
+			} catch (appendErr) {
+				// appendEntry 失败（session 已 disposed 等）→ 降级文件日志（下方 fileLog 兜底），不 throw
+				void appendErr;
+			}
+			fileLog(extName, "warn", prefixed, data);
+		},
+		error(msg: string, data?: unknown): void {
+			const piResolved = resolvePi();
+			const prefixed = prefixMsg(extName, msg);
+			try {
+				piResolved?.appendEntry?.(`${extName}:log`, {
+					timestamp: Date.now(),
+					level: "error",
+					message: prefixed,
+					data,
+				});
+			} catch (appendErr) {
+				// 同 warn：appendEntry 失败降级文件日志，不 throw
+				void appendErr;
+			}
+			fileLog(extName, "error", prefixed, data);
+		},
+	};
+	return logger;
+}
+
+/**
+ * 获取（或创建）具名 logger 的全局 singleton。
+ *
+ * 深层代码（拿不到 pi 的执行层，如 best-effort.ts、error-recovery.ts）
+ * 用 `getLogger("subagents")` 拿全局缓存实例，无需逐层透传 pi。
+ *
+ * 首次调用时 pi 尚未注入 → logger 的 warn/error 降级到文件日志；
+ * 后续 setPiHandle 注入后，同一 logger 实例自动生效 appendEntry
+ * （闭包读 globalPi 实时值，不是创建时的快照）。
+ */
+export function getLogger(extName: string): ExtensionLogger {
+	const existing = loggerCache.get(extName);
+	if (existing) return existing;
+	const logger = createLogger(extName);
+	loggerCache.set(extName, logger);
+	return logger;
+}
+
+// ============================================================
+// 内部工具
+// ============================================================
+
+/**
+ * 给 msg 补 `[extName]` 前缀（若已有则不重复补）。
+ * 保持与旧 console 日志一致的视觉格式，便于从 session.jsonl 逆向搜索。
+ */
+function prefixMsg(extName: string, msg: string): string {
+	const tag = `[${extName}]`;
+	return msg.startsWith(tag) ? msg : `${tag} ${msg}`;
+}
+
+/**
+ * 写文件日志到 `<agentDir>/logs/<extName>-YYYY-MM-DD.log`。
+ *
+ * 仅在 PI_EXT_DEBUG 环境变量为 "1" 时写入（默认 no-op，生产环境零开销）。
+ * agentDir 通过 pi 的 SSOT `getAgentDir()` 推导（读
+ * `PI_CODING_AGENT_DIR`/`${APP_NAME}_CODING_AGENT_DIR`，默认 `~/.pi/agent`），
+ * 与其它 extension 的路径派生保持一致。
+ * 写失败静默吞错（文件日志是 best-effort，不应影响主流程）。
+ *
+ * 线程安全：appendFileSync 保证单次写入原子性；多 worker 并发写同文件时
+ * 行可能交错（可接受——debug 日志不要求严格顺序）。
+ */
+function fileLog(extName: string, level: LogLevel, msg: string, data?: unknown): void {
+	if (process.env.PI_EXT_DEBUG !== "1") return;
+	try {
+		const agentDir = getAgentDir();
+		const logDir = join(agentDir, "logs");
+		mkdirSync(logDir, { recursive: true });
+		// ISO 日期前 10 字符 = "YYYY-MM-DD"
+		const ISO_DATE_PREFIX_LEN = 10;
+		const today = new Date().toISOString().slice(0, ISO_DATE_PREFIX_LEN);
+		const logFile = join(logDir, `${extName}-${today}.log`);
+		const ts = new Date().toISOString();
+		const dataStr = data !== undefined ? " " + safeStringify(data) : "";
+		appendFileSync(logFile, `${ts} [${level}] ${msg}${dataStr}\n`);
+	} catch (fileErr) {
+		// 文件日志 best-effort：磁盘满/权限问题等不阻断主流程
+		void fileErr;
+	}
+}
+
+/** 安全序列化 data（循环引用/BigInt 不崩）。 */
+function safeStringify(data: unknown): string {
+	try {
+		return JSON.stringify(data);
+	} catch {
+		return String(data);
+	}
+}