@zhushanwen/pi-ext-guards 0.4.3 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-ext-guards",
-  "version": "0.4.3",
+  "version": "0.5.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

@@ -1,14 +1,28 @@
 // src/__tests__/predicates.test.ts
 //
-// isRecord / isEnoentError / isSubagentProcess 单测（ext-simplify-17 D3/D2/D4 新导出）：
+// isRecord / isEnoentError / isErrnoWithCode / isSubagentProcess / isTaijiHost /
+// isTaijiGuiHost 单测
+//（ext-simplify-17 D3/D2/D4 新导出 + isErrnoWithCode errno 守卫上收 +
+// dmg-r1-7 宿主谓词跨包收敛）：
 //   - isRecord 排数组严版：数组必须 false（钉值，防回退到允数组宽版）
 //   - isEnoentError scheduler 严版：仅 Error 子类 + code === "ENOENT" 才 true，
 //     非 Error 对象带 code 是宽版才接受的形态，严版必须 false
+//   - isErrnoWithCode：isEnoentError 的 code 参数化形态，收窄纪律同源
 //   - isSubagentProcess 三态 + env 注入隔离 + 旧键宁缺勿污钉值（D4 重锚定）
+//   - isTaijiHost / isTaijiGuiHost：env 严格等值 + mode 收紧 rpc 真值表
+//     （自 plan state.ts / canvas host.ts 双实现收敛，dmg-r1-7）
 
 import { describe, expect, it } from "vitest";
 
-import { isEnoentError, isRecord, isSubagentProcess } from "../index.ts";
+import {
+	isEnoentError,
+	isErrnoWithCode,
+	isRecord,
+	isSubagentProcess,
+	isTaijiGuiHost,
+	isTaijiHost,
+	TAIJI_GUI_HOST_ENV,
+} from "../index.ts";
 
 describe("isRecord", () => {
 	it("对象 true", () => {
@@ -58,6 +72,32 @@ describe("isEnoentError", () => {
 	});
 });
 
+describe("isErrnoWithCode", () => {
+	it("Error 带 code=期望值 true（Node fs 错误的构造形态）", () => {
+		expect(isErrnoWithCode(Object.assign(new Error("exists"), { code: "EEXIST" }), "EEXIST")).toBe(
+			true,
+		);
+	});
+
+	it("code 为其他值 false", () => {
+		expect(isErrnoWithCode(Object.assign(new Error("exists"), { code: "EEXIST" }), "EACCES")).toBe(
+			false,
+		);
+	});
+
+	it("普通 Error false（无 code 属性）", () => {
+		expect(isErrnoWithCode(new Error("x"), "EEXIST")).toBe(false);
+	});
+
+	it("非 Error 对象带同名 code false（与 isEnoentError 同一严版口径）", () => {
+		expect(isErrnoWithCode({ code: "EEXIST" }, "EEXIST")).toBe(false);
+	});
+
+	it("undefined false", () => {
+		expect(isErrnoWithCode(undefined, "EEXIST")).toBe(false);
+	});
+});
+
 describe("isSubagentProcess", () => {
 	it("TAIJI_AGENT_SUBAGENT=1 命中（引擎 spawn 链恒注入的现行标记）", () => {
 		expect(isSubagentProcess({ TAIJI_AGENT_SUBAGENT: "1" })).toBe(true);
@@ -107,3 +147,48 @@ describe("isSubagentProcess", () => {
 		);
 	});
 });
+
+describe("isTaijiHost / isTaijiGuiHost", () => {
+	// 谓词读活 env（每次调用时取 process.env，不缓存），用 saved/finally 操纵恢复；
+	// 键经 TAIJI_GUI_HOST_ENV 常量取值（常量改值时测试自动跟随，防键名漂移）
+	function withEnv(value: string | undefined, fn: () => void): void {
+		const key = TAIJI_GUI_HOST_ENV;
+		const saved = process.env[key];
+		try {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+			fn();
+		} finally {
+			if (saved === undefined) delete process.env[key];
+			else process.env[key] = saved;
+		}
+	}
+
+	it("env 信号缺失 = 非宿主（mode 无关）", () => {
+		withEnv(undefined, () => {
+			expect(isTaijiHost()).toBe(false);
+			expect(isTaijiGuiHost({ mode: "rpc" })).toBe(false);
+		});
+	});
+
+	it("env=1 但 mode 非 rpc（TUI / json / print）= 非 GUI 宿主（env 泄漏形态，禁入 select）", () => {
+		withEnv("1", () => {
+			expect(isTaijiHost()).toBe(true);
+			expect(isTaijiGuiHost({ mode: "tui" })).toBe(false);
+			expect(isTaijiGuiHost({ mode: "json" })).toBe(false);
+			expect(isTaijiGuiHost({ mode: "print" })).toBe(false);
+		});
+	});
+
+	it("env=1 + rpc = taiji GUI 宿主", () => {
+		withEnv("1", () => {
+			expect(isTaijiGuiHost({ mode: "rpc" })).toBe(true);
+		});
+	});
+
+	it("env 非 \"1\" 值 = 非宿主（严格等值判定）", () => {
+		withEnv("0", () => {
+			expect(isTaijiHost()).toBe(false);
+		});
+	});
+});

package/src/index.ts

@@ -116,6 +116,18 @@ export function isEnoentError(err: unknown): boolean {
 	return err instanceof Error && "code" in err && err.code === "ENOENT";
 }
 
+/**
+ * 判断 error 是否为带指定 errno code 的 Node 系统调用错误（`Error` 实例且
+ * `code === 期望值`）。
+ *
+ * 与 isEnoentError 同一收窄纪律（`"code" in err` 零断言——taste/no-unsafe-cast），
+ * code 参数化：isEnoentError = code 钉死 "ENOENT" 的特化形态。非 Error 对象即使带
+ * 同名 code 也 false（与 isEnoentError 的严版口径一致——Node fs 抛错恒为 Error 实例）。
+ */
+export function isErrnoWithCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+
 // ── subagent 进程判据（isSubagentProcess，ext-simplify-17 D4）────────────
 //
 // 背景：extension 需要知道「当前 pi 进程是否引擎链上的 subagent 子进程」来决定降级
@@ -148,6 +160,52 @@ export function isSubagentProcess(
 	return env[SUBAGENT_MARKER_ENV] === "1";
 }
 
+// ── taiji GUI 宿主判据（isTaijiGuiHost，dmg-r1-7 跨包收敛）──────────────
+//
+// 背景：taiji runtime 对托管 pi 恒注入 TAIJI_AGENT_EXT_LOG=1（恒注入点
+// packages/pi-rpc/src/env.ts 的 outboundExtras；名义语义是扩展日志开关，
+// extension-logger 见之落盘 INFO），独立 pi 无此信号。env 只证明 taiji runtime
+// 在上游，宿主没有 marker 路由的形态（TUI / json / print）select 会落终端 UI——
+// 完整谓词必须再收紧 ctx.mode === "rpc"；单查 env 会在 env 泄漏到独立 pi 时误入
+// select 挂起（禁超时探测，对齐时间平抑红线：不做「挂起后超时回退」类时间窗兜底）。
+//
+// [双语义耦合登记，SSOT 随谓词收敛单点化于此] 本 env 名义语义是扩展日志开关，
+// 本谓词是第二消费方（宿主分流）——若日志开关走向可配置（值不再是恒 '1'），全部
+// 宿主分流同帧静默失效，届时必须拆专用宿主信号 env 并纳入恒注入，不得沿用本名；
+// 拆分时消费方（plan state.ts / canvas host.ts 的 re-export 调用点）一并随迁移。
+//
+// 收敛历史：plan 包内三处 `isTaijiHost() && ctx.mode === "rpc"` 复写先收敛为
+// plan state.ts 单点（D-B1-7），canvas host.ts 此前持独立实现、一致性靠两侧注释
+// 互指维持（dmg-r1-7 判其为无机器检查的双实现）——现整体收敛于本包，两包改
+// re-export，一致性由构造保证。
+
+/** taiji GUI 宿主判定 env 键（taiji runtime 恒注入 "1"；名义语义 = 扩展日志开关，见分节双语义耦合登记）。 */
+export const TAIJI_GUI_HOST_ENV = "TAIJI_AGENT_EXT_LOG";
+
+/**
+ * taiji runtime 宿主 env 信号（isTaijiGuiHost 的 env 腿）：`TAIJI_GUI_HOST_ENV`
+ * 严格等值 "1" 判定。每次调用时读（不可模块加载时缓存——测试与运行中 env 都可能
+ * 变化）。
+ */
+export function isTaijiHost(): boolean {
+	return process.env[TAIJI_GUI_HOST_ENV] === "1";
+}
+
+/** 宿主形态判别的最小结构面（pi ExtensionContext 的 mode 字段结构化投影——零 pi SDK 依赖）。 */
+// oe-exempt:20261016:framework:宿主形态判别的数据形状契约（pi ctx 的结构化投影，非抽象接口单实现）
+export interface GuiHostContextLike {
+	mode: string;
+}
+
+/**
+ * taiji GUI 宿主完整谓词：env 信号 + rpc 模式（marker select 只在 rpc 宿主有路由）。
+ * 消费方 = plan 的 submit-review marker select / complete 执行方式 form / E3 恢复
+ * 分流（state.ts re-export）与 canvas 六工具的 select 前置门（host.ts re-export）。
+ */
+export function isTaijiGuiHost(ctx: GuiHostContextLike): boolean {
+	return isTaijiHost() && ctx.mode === "rpc";
+}
+
 // ── stale ctx 守卫（guardStaleCtx，崩溃韧性 D1）────────────────────────
 //
 // 背景：pi 的 extension API