@zhushanwen/pi-ext-guards 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ext-guards",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared runtime-environment guards for Pi extensions — oncePerProcess(key, fn) dedupes cross-session side-effect operations against pi factory re-invocation and handler accumulation (shared library, not a Pi extension, zero dependencies).",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/predicates.test.ts

@@ -0,0 +1,109 @@
+// src/__tests__/predicates.test.ts
+//
+// isRecord / isEnoentError / isSubagentProcess 单测（ext-simplify-17 D3/D2/D4 新导出）：
+//   - isRecord 排数组严版：数组必须 false（钉值，防回退到允数组宽版）
+//   - isEnoentError scheduler 严版：仅 Error 子类 + code === "ENOENT" 才 true，
+//     非 Error 对象带 code 是宽版才接受的形态，严版必须 false
+//   - isSubagentProcess 三态 + env 注入隔离 + 旧键宁缺勿污钉值（D4 重锚定）
+
+import { describe, expect, it } from "vitest";
+
+import { isEnoentError, isRecord, isSubagentProcess } from "../index.ts";
+
+describe("isRecord", () => {
+	it("对象 true", () => {
+		expect(isRecord({})).toBe(true);
+		expect(isRecord({ key: "value" })).toBe(true);
+	});
+
+	it("null false", () => {
+		expect(isRecord(null)).toBe(false);
+	});
+
+	it("undefined false", () => {
+		expect(isRecord(undefined)).toBe(false);
+	});
+
+	it("数组 false（排数组钉值——Record 语义不含数组）", () => {
+		expect(isRecord([])).toBe(false);
+		expect(isRecord([{ a: 1 }])).toBe(false);
+	});
+
+	it("字符串 false", () => {
+		expect(isRecord("text")).toBe(false);
+	});
+});
+
+describe("isEnoentError", () => {
+	it("Error 带 code=ENOENT true（Node fs 错误的构造形态）", () => {
+		expect(isEnoentError(Object.assign(new Error("no such file"), { code: "ENOENT" }))).toBe(
+			true,
+		);
+	});
+
+	it("普通 Error false（无 code 属性）", () => {
+		expect(isEnoentError(new Error("x"))).toBe(false);
+	});
+
+	it("code 为其他值 false", () => {
+		expect(isEnoentError(Object.assign(new Error("denied"), { code: "EACCES" }))).toBe(false);
+	});
+
+	it("非 Error 对象带 code=ENOENT false（严版：宽版才接受的形态）", () => {
+		expect(isEnoentError({ code: "ENOENT" })).toBe(false);
+	});
+
+	it("undefined false", () => {
+		expect(isEnoentError(undefined)).toBe(false);
+	});
+});
+
+describe("isSubagentProcess", () => {
+	it("XYZ_AGENT_SUBAGENT=1 命中（引擎 spawn 链恒注入的现行标记）", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+	});
+
+	it("值非 \"1\" 不命中（标记必须是引擎注入的字面 \"1\"）", () => {
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "0" })).toBe(false);
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "" })).toBe(false);
+		expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "true" })).toBe(false);
+	});
+
+	it("缺失不命中（顶层会话 → 消费方不降级）", () => {
+		expect(isSubagentProcess({})).toBe(false);
+	});
+
+	it("env 参数注入隔离：传入的 env 与宿主 process.env 无关（宿主即使带标记，空 env 也不命中）", () => {
+		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		try {
+			process.env.XYZ_AGENT_SUBAGENT = "1";
+			// 显式传 env：宿主的标记不渗透，判据只看参数
+			expect(isSubagentProcess({})).toBe(false);
+			expect(isSubagentProcess({ XYZ_AGENT_SUBAGENT: "1" })).toBe(true);
+		} finally {
+			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
+			else process.env.XYZ_AGENT_SUBAGENT = saved;
+		}
+	});
+
+	it("缺省参数读 process.env（不传 env 时以宿主环境为判据）", () => {
+		const saved = process.env.XYZ_AGENT_SUBAGENT;
+		try {
+			process.env.XYZ_AGENT_SUBAGENT = "1";
+			expect(isSubagentProcess()).toBe(true);
+			delete process.env.XYZ_AGENT_SUBAGENT;
+			expect(isSubagentProcess()).toBe(false);
+		} finally {
+			if (saved === undefined) delete process.env.XYZ_AGENT_SUBAGENT;
+			else process.env.XYZ_AGENT_SUBAGENT = saved;
+		}
+	});
+
+	it("旧 PI_SUBAGENT_* 身份键不再命中（[HISTORICAL] D4 重锚前两键任一存在即命中；引擎协议化后无写入方，宁缺勿污）", () => {
+		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1" })).toBe(false);
+		expect(isSubagentProcess({ PI_SUBAGENT_SELF_RECORD_ID: "r1" })).toBe(false);
+		expect(isSubagentProcess({ PI_SUBAGENT_ROOT_SESSION_ID: "s1", PI_SUBAGENT_SELF_RECORD_ID: "r1" })).toBe(
+			false,
+		);
+	});
+});

package/src/index.ts

@@ -3,7 +3,7 @@
 // @zhushanwen/pi-ext-guards —— pi 运行环境守卫共享库（不是 Pi extension，零依赖纯函数，
 // 无 pi SDK peerDep——供任意 @zhushanwen/pi-* 包与子代理核心消费）。
 //
-// 背景与设计依据：docs/design/file-lock-unification-and-reaper-sink.md §2.2 P3 / §3.2 D3。
+// 背景与设计依据：docs/architecture/file-lock-unification-and-reaper-sink.md §2.2 P3 / §3.2 D3。
 // pi 的 extension 缓存按 cwd 失效：switch_session 时 cwd 不变则 factory 被二次调用且
 // handler 累积注册——session_start handler 的真实派发语义是「每 session × factory
 // 调用次数」，不是「每 session 一次」。handler 体内的跨 session 副作用操作（写非本
@@ -83,6 +83,58 @@ export function toErrorMessage(e: unknown): string {
 	return e instanceof Error ? e.message : String(e);
 }
 
+/**
+ * 判断 value 是否为非 null、非数组的 object（`Record` 语义本义：可按字符串键安全取值）。
+ *
+ * canonical 来自 ext-simplify-17 D3（排数组严版，设计文档
+ * docs/architecture/ext-simplify-17-shared-extraction.md §3.1）。
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 判断 err 是否为 Node fs 的 ENOENT 错误（`Error` 实例且 `code === "ENOENT"`）。
+ *
+ * canonical 来自 ext-simplify-17 D2（scheduler 严版，`"code" in err` 收窄避免
+ * `as Record` 强转——taste/no-unsafe-cast）。
+ */
+export function isEnoentError(err: unknown): boolean {
+	return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+// ── subagent 进程判据（isSubagentProcess，ext-simplify-17 D4）────────────
+//
+// 背景：extension 需要知道「当前 pi 进程是否引擎链上的 subagent 子进程」来决定降级
+// （base-tool-enhance background 降级——bte background 生命周期设计的 D14 项，
+// commit 8599abd0c，该设计未在现行 docs 留档 / smart-context R6 不注册工具，
+// 规则定义见 smart-context src/index.ts R 规则族注释）。判据锚
+// XYZ_AGENT_SUBAGENT=1——subagent-engine-sdk env.ts 的 buildEngineChildEnv 对每个引擎
+// 子进程恒注入（L0 层最后写入），再经引擎内二次 spawn（buildOutboundChildEnv 全量
+// 继承）传到 subagent 内的 bash。旧判据（PI_SUBAGENT_ROOT_SESSION_ID /
+// PI_SUBAGENT_SELF_RECORD_ID 两键）在引擎协议化后已无写入方（20260914 探针证实，
+// 报告 .tmp/dev-flow/ext-simplify-17-d4-probe.md），判据失效态由 D4 重锚收敛于此。
+
+/** subagent 进程标记 env 键（引擎 spawn 链恒注入 "1"，subagent-engine-sdk env.ts L0）。 */
+export const SUBAGENT_MARKER_ENV = "XYZ_AGENT_SUBAGENT";
+
+/**
+ * 判断当前进程是否引擎链上的 subagent 子进程。
+ *
+ * 判据 = `env[SUBAGENT_MARKER_ENV] === "1"`（canonical 来自 ext-simplify-17 D4，
+ * 设计文档 docs/architecture/ext-simplify-17-shared-extraction.md §3.1）。口径
+ * 「宁缺勿污」：只有引擎 spawn 链上的真 subagent 才命中——人工 export 旧
+ * PI_SUBAGENT_ROOT_SESSION_ID / PI_SUBAGENT_SELF_RECORD_ID 身份键不再算（两键现
+ * 无写入方，见分节注释）。
+ *
+ * @param env env 快照；缺省读 process.env，显式传入即与宿主进程环境完全隔离（测试注入用）
+ */
+export function isSubagentProcess(
+	env: Record<string, string | undefined> = process.env,
+): boolean {
+	return env[SUBAGENT_MARKER_ENV] === "1";
+}
+
 // ── stale ctx 守卫（guardStaleCtx，崩溃韧性 D1）────────────────────────
 //
 // 背景（docs/design/crash-resilience.md §3.3 D1 / §2.2 事件 E1）：pi 的 extension API