@zhushanwen/subagent-core 0.2.0

package/src/orchestration/__tests__/skill-discovery.test.ts

@@ -0,0 +1,210 @@
+/**
+ * skill-discovery — resolveSkillPath 结果缓存（IF8/#14）+ 搜索序测试。
+ *
+ * 现状该文件此前零测试，本文件为首个测试（design IF8 契约）：
+ * - hit 不再 existsSync（计数 wrapper 观察，spyOn ESM namespace 不可配置的既有教训）
+ * - 未命中 undefined 也缓存（不存在的名字二次调用零 stat）
+ * - clearSkillPathCache 后重扫
+ * - project 优先于 user/npm 的搜索序
+ *
+ * [merge 注] main 侧同名文件（mock-fs 版）的 5 用例语义均已覆盖：搜索序三用例
+ * 同名等价；「npm 候选路径构造含 agentDir」= 本文件各用例断言 join(homeRoot,
+ * ".pi/agent/npm/...") 完整路径 + npm 兜底用例的多包枚举；「全 miss undefined 含
+ * readdirSync ENOENT 兜底」= 「未命中 undefined 也缓存」用例（homeRoot 无 npm 目录，
+ * 真实 fs 下 ENOENT 由实现 catch）。mock 版被本集成版取代。
+ *
+ * 隔离：node:fs 的 existsSync 用 vi.mock 包一层计数（委托真实实现）；
+ * skills 发现根经 HostServices.discoveryRoots 端口注入（u0-data-discovery 注入化后
+ * 不再消费 pi SDK getAgentDir），每用例 resetCoreForTests + configureCore 假宿主，
+ * 假宿主根清单按 pi-host.ts skillRoots 契约形状推导自 hoisted 临时 home；
+ * process.cwd 用 spyOn。
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { configureCore, resetCoreForTests } from "../../core/host-services.ts";
+
+const { existsSyncCalls } = vi.hoisted(() => ({
+  existsSyncCalls: { count: 0 },
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  const realExistsSync = actual.existsSync;
+  // 计数 wrapper（委托真实实现）——vi.spyOn(fs, "existsSync") 在 ESM 模块
+  // 命名空间不可配置（record-store-index.test.ts:419 同款教训），改用 mock 工厂。
+  const countingExistsSync = ((p: string) => {
+    existsSyncCalls.count++;
+    return realExistsSync(p);
+  }) as typeof actual.existsSync;
+  return { ...actual, existsSync: countingExistsSync };
+});
+
+import { clearSkillPathCache, resolveSkillPath } from "../skill-discovery.ts";
+
+// ── 临时目录工具 ──────────────────────────────────────────────
+
+let projRoot: string;
+let homeRoot: string;
+
+beforeEach(() => {
+  clearSkillPathCache();
+  existsSyncCalls.count = 0;
+  projRoot = mkdtempSync(join(tmpdir(), "skill-proj-"));
+  homeRoot = mkdtempSync(join(tmpdir(), "skill-home-"));
+  // 假宿主根清单 = pi-host.ts skillRoots() 契约形状（user-pi + npm 两根，
+  // 每用例绑定当轮临时 home——discoveryRoots 每次调用现取，用例内改 homeRoot 即生效）
+  const agentDir = join(homeRoot, ".pi", "agent");
+  resetCoreForTests();
+  configureCore({
+    dataRoot: () => agentDir,
+    log: () => {},
+    discoveryRoots: () => ({
+      skills: [
+        { dir: join(agentDir, "skills"), source: "user-pi" },
+        { dir: join(agentDir, "npm", "node_modules"), source: "npm" },
+      ],
+    }),
+  });
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  resetCoreForTests();
+  rmSync(projRoot, { recursive: true, force: true });
+  rmSync(homeRoot, { recursive: true, force: true });
+});
+
+/** mkdir -p（目录存在即 resolveSkillPath 命中——检查的是目录而非 SKILL.md）。 */
+function mkdirp(dir: string): void {
+  mkdirSync(dir, { recursive: true });
+}
+
+describe("resolveSkillPath — 搜索序（project > user > npm）", () => {
+  it("project 优先：同名 skill 同时存在于 project/user/npm 时返回 project 路径", () => {
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "dup-skill";
+    mkdirp(join(projRoot, ".agents/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    const resolved = resolveSkillPath(name);
+
+    expect(resolved).toBe(join(projRoot, ".agents/skills", name));
+    expect(cwdSpy).toHaveBeenCalled();
+  });
+
+  it("user 次之：仅 user/npm 存在时返回 user 路径", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "user-skill";
+    mkdirp(join(homeRoot, ".pi/agent/skills", name));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    expect(resolveSkillPath(name)).toBe(join(homeRoot, ".pi/agent/skills", name));
+  });
+
+  it("npm 兜底：仅 npm 包内存在时返回包内 skills 路径（readdirSync 枚举多包候选）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "npm-skill";
+    // 两个包并存：断言实现枚举 npm/node_modules 下每个包（S-6 语义，防只查首个包的回退）
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/pkg-a/other", "x"));
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name));
+
+    expect(resolveSkillPath(name)).toBe(
+      join(homeRoot, ".pi/agent/npm/node_modules/some-pkg/skills", name),
+    );
+  });
+});
+
+describe("resolveSkillPath — 结果缓存（IF8/DM3）", () => {
+  it("hit 不再 existsSync：二次调用零 stat", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "cache-hit";
+    const expected = join(projRoot, ".agents/skills", name);
+    mkdirp(expected);
+
+    const first = resolveSkillPath(name);
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(first).toBe(expected);
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    const second = resolveSkillPath(name);
+    expect(second).toBe(expected);
+    expect(existsSyncCalls.count).toBe(callsAfterFirst); // 零增量
+  });
+
+  it("未命中 undefined 也缓存：不存在的名字二次调用零 stat", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "no-such-skill-xyz";
+
+    const first = resolveSkillPath(name);
+    expect(first).toBeUndefined();
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    const second = resolveSkillPath(name);
+    expect(second).toBeUndefined();
+    expect(existsSyncCalls.count).toBe(callsAfterFirst); // 零增量（未命中也缓存）
+  });
+
+  it("clearSkillPathCache 后重扫：计数恢复增长且结果一致", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const name = "cache-clear";
+    const expected = join(projRoot, ".agents/skills", name);
+    mkdirp(expected);
+
+    expect(resolveSkillPath(name)).toBe(expected);
+    const callsAfterFirst = existsSyncCalls.count;
+    expect(callsAfterFirst).toBeGreaterThan(0);
+
+    clearSkillPathCache();
+    expect(resolveSkillPath(name)).toBe(expected);
+    expect(existsSyncCalls.count).toBeGreaterThan(callsAfterFirst); // 重扫发生
+  });
+});
+
+describe("resolveSkillPath — `..` 穿越守卫（三通道对称修复：skill 名是名字不是路径）", () => {
+  it("project 源：含 .. 逃逸 skills 根的名字 → not found（即使逃逸目标真实存在）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // 逃逸目标真实存在：projRoot/.agents/skills/../../escape-target = projRoot/escape-target。
+    // 旧实现 path.resolve 吸收 .. 后 existsSync 命中 → 返回树外目录；守卫后必须 undefined。
+    mkdirp(join(projRoot, "escape-target"));
+
+    expect(resolveSkillPath("../../escape-target")).toBeUndefined();
+  });
+
+  it("user 源：含 .. 逃逸的名字 → not found（同样不受 existsSync 命中误导）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // user skills 根 = homeRoot/.pi/agent/skills；../../escape-target → homeRoot/escape-target。
+    mkdirp(join(homeRoot, "escape-target"));
+
+    expect(resolveSkillPath("../../escape-target")).toBeUndefined();
+  });
+
+  it("npm 源：含 .. 逃逸包内 skills 根的名字 → not found", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    // npm skills 根 = homeRoot/.pi/agent/npm/node_modules/pkg/skills；"../steal" 逃逸到 node_modules/<pkg>/steal。
+    mkdirp(join(homeRoot, ".pi/agent/npm/node_modules/pkg-a/steal"));
+
+    expect(resolveSkillPath("../steal")).toBeUndefined();
+  });
+
+  it("根内归一化不被误拒：sub/../real 解析后仍在 skills 根内，正常命中", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    const real = join(projRoot, ".agents/skills", "real");
+    mkdirp(real);
+
+    // 守卫只拒逃逸，不拒归一化：root/sub/../real = root/real（根内）→ 命中。
+    expect(resolveSkillPath("sub/../real")).toBe(real);
+  });
+
+  it("绝对路径形式的 skill 名 → not found（名字不具备绝对寻址能力）", () => {
+    vi.spyOn(process, "cwd").mockReturnValue(projRoot);
+    mkdirp(join(projRoot, "outside-abs"));
+
+    // resolve(root, "/outside-abs") = /outside-abs —— 树外，拒。
+    expect(resolveSkillPath(join(projRoot, "outside-abs"))).toBeUndefined();
+  });
+});

package/src/orchestration/__tests__/test-mocks.ts

@@ -0,0 +1,197 @@
+// src/orchestration/__tests__/test-mocks.ts
+//
+// Pi ExtensionAPI / ExtensionContext 测试 mock 工厂（PR #173 review S8）。
+//
+// 为什么需要工厂：此前测试用 `as never` 注入残缺 mock（如 `{ appendEntry: vi.fn() }`
+// 直接塞进 `JsonlRunStoreOptions.pi`）。`as never` 是 bottom type 断言，mock 缺字段时
+// 编译期零报错，比 `as unknown as T` 更危险。工厂返回**类型完整**的对象——被 mock
+// 接口（真实 SDK 类型，tsc 按根 tsconfig 排除规则不检查 __tests__，但编辑器 LSP 与
+// 显式 tsc 文件级检查会检查）新增成员时，这里补默认值即暴露，用例侧不再有断言后门。
+//
+// 语义约定：
+// - 默认值贴近真实行为：sessionManager.getEntries 返回浅拷贝（真实 SessionManager
+//   契约）；appendEntry 捕获变体追加完整 CustomEntry（真实 pi.appendEntry 即向 session
+//   追加 CustomEntry）；isIdle → true、hasPendingMessages → false 等按真实语义取值。
+// - 测试真正消费的成员（jsonl-run-store 只读 ctx.sessionManager.getEntries 与
+//   pi.appendEntry）行为真实；其余成员为 no-op spy（vi.fn()），调用不炸但返回
+//   undefined——本包测试不消费它们。
+// - modelRegistry / ui.theme 是含 private 字段的 nominal class：真实构造需
+//   ModelRuntime.create()（async + 读用户级 models.json）/ loadTheme 读包文件。
+//   pi-coding-agent 在本包测试中仅剩 import type（转译擦除，无运行时导出可用），
+//   结构构造又被 private 字段阻断。二者经 fail-loud Proxy 提供：误用时立即抛错（而非
+//   静默 undefined），把「缺 mock」变成显式失败。这是本文件仅有的两处断言收敛点。
+
+import { vi } from "vitest";
+
+import type {
+  CustomEntry,
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionUIContext,
+  ModelRegistry,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+
+/**
+ * 误用即抛错的占位成员：比静默返回 undefined 的 no-op 更早暴露「缺 mock」。
+ *
+ * T 收窄为 object：调用点（ModelRegistry/Theme）均为对象类型；Proxy 静态类型是 `{}`，
+ * 目标是 nominal class（private 字段阻断结构构造），单重 `as T` 断言已足够表达
+ * 「结构上无法构造，运行时 fail-loud 兜底」的意图，无需 `as unknown as T` 双重断言。
+ */
+function failLoud<T extends object>(memberPath: string): T {
+  return new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        throw new Error(
+          `[test-mocks] ${memberPath}.${String(prop)} 未提供 mock 实现——` +
+            `本测试不应消费该成员；确需消费时经 overrides 显式提供`,
+        );
+      },
+    },
+  ) as T;
+}
+
+/**
+ * 构造类型完整的 ExtensionContext。
+ *
+ * @param entries sessionManager.getEntries 的返回源（浅拷贝返回）。与 mkPi(entries)
+ *   共享同一数组时可复现真实 pi 行为：appendEntry 写入 ↔ getEntries 读出。
+ * @param overrides 覆写任意 ctx 字段（浅合并，整体替换成员，最后应用）。
+ */
+export function mkCtx(
+  entries: CustomEntry[] = [],
+  overrides: Partial<ExtensionContext> = {},
+): ExtensionContext {
+  const ctx: ExtensionContext = {
+    ui: mkUi(),
+    // pi 在 xyz-agent 下以 rpc 子进程模式运行；rpc 模式 hasUI 为 true（SDK 契约注释）
+    mode: "rpc",
+    hasUI: true,
+    cwd: "/tmp",
+    sessionManager: {
+      getCwd: () => "/tmp",
+      getSessionDir: () => "/tmp/sessions-test",
+      getSessionId: () => "session-test",
+      // 真实语义：首条 assistant 消息前 session 文件未落盘，返回 undefined
+      getSessionFile: () => undefined,
+      getLeafId: () => null,
+      getLeafEntry: () => undefined,
+      getEntry: () => undefined,
+      getLabel: () => undefined,
+      getBranch: () => [],
+      buildContextEntries: () => [],
+      getHeader: () => null,
+      // 真实 SessionManager.getEntries 返回浅拷贝
+      getEntries: () => [...entries],
+      getTree: () => [],
+      getSessionName: () => undefined,
+    },
+    modelRegistry: failLoud<ModelRegistry>("ctx.modelRegistry"),
+    // SDK 契约：model / signal 在 agent 未流式输出时合法为 undefined
+    model: undefined,
+    isIdle: vi.fn(() => true),
+    isProjectTrusted: vi.fn(() => true),
+    signal: undefined,
+    abort: vi.fn(),
+    hasPendingMessages: vi.fn(() => false),
+    shutdown: vi.fn(),
+    getContextUsage: vi.fn(() => undefined),
+    compact: vi.fn(),
+    getSystemPrompt: vi.fn(() => ""),
+  };
+  return Object.assign(ctx, overrides);
+}
+
+/** ExtensionUIContext 完整 no-op mock（theme 为 fail-loud 占位，见文件头说明）。 */
+function mkUi(): ExtensionUIContext {
+  return {
+    select: vi.fn(async () => undefined),
+    confirm: vi.fn(async () => false),
+    input: vi.fn(async () => undefined),
+    notify: vi.fn(),
+    onTerminalInput: vi.fn(() => () => {}),
+    setStatus: vi.fn(),
+    setWorkingMessage: vi.fn(),
+    setWorkingVisible: vi.fn(),
+    setWorkingIndicator: vi.fn(),
+    setHiddenThinkingLabel: vi.fn(),
+    setWidget: vi.fn(),
+    setFooter: vi.fn(),
+    setHeader: vi.fn(),
+    setTitle: vi.fn(),
+    custom: vi.fn(),
+    pasteToEditor: vi.fn(),
+    setEditorText: vi.fn(),
+    getEditorText: vi.fn(() => ""),
+    editor: vi.fn(async () => undefined),
+    addAutocompleteProvider: vi.fn(),
+    setEditorComponent: vi.fn(),
+    getEditorComponent: vi.fn(() => undefined),
+    theme: failLoud<Theme>("ctx.ui.theme"),
+    getAllThemes: vi.fn(() => []),
+    getTheme: vi.fn(() => undefined),
+    setTheme: vi.fn(() => ({ success: true })),
+    getToolsExpanded: vi.fn(() => false),
+    setToolsExpanded: vi.fn(),
+  };
+}
+
+/**
+ * 构造类型完整的 ExtensionAPI。
+ *
+ * @param entries 给定时，appendEntry 追加完整 CustomEntry 到该数组（真实
+ *   pi.appendEntry 语义：向 session 追加 custom entry）；缺省为纯 spy（可断言
+ *   调用次数、无副作用）。
+ * @param overrides 覆写任意 pi 字段（浅合并，最后应用）。
+ */
+export function mkPi(
+  entries?: CustomEntry[],
+  overrides: Partial<ExtensionAPI> = {},
+): ExtensionAPI {
+  const appendEntry =
+    entries === undefined
+      ? vi.fn()
+      : vi.fn((customType: string, data?: unknown) => {
+          entries.push({
+            type: "custom",
+            customType,
+            data,
+            id: `entry-${entries.length}`,
+            parentId: null,
+            timestamp: new Date().toISOString(),
+          });
+        });
+  const pi: ExtensionAPI = {
+    on: vi.fn(),
+    registerTool: vi.fn(),
+    registerCommand: vi.fn(),
+    registerShortcut: vi.fn(),
+    registerFlag: vi.fn(),
+    getFlag: vi.fn(() => undefined),
+    registerMessageRenderer: vi.fn(),
+    registerEntryRenderer: vi.fn(),
+    sendMessage: vi.fn(),
+    sendUserMessage: vi.fn(),
+    appendEntry,
+    setSessionName: vi.fn(),
+    getSessionName: vi.fn(() => undefined),
+    setLabel: vi.fn(),
+    exec: vi.fn(),
+    getActiveTools: vi.fn(() => []),
+    getAllTools: vi.fn(() => []),
+    setActiveTools: vi.fn(),
+    getCommands: vi.fn(() => []),
+    setModel: vi.fn(async () => true),
+    getThinkingLevel: vi.fn(),
+    setThinkingLevel: vi.fn(),
+    registerProvider: vi.fn(),
+    unregisterProvider: vi.fn(),
+    events: {
+      emit: vi.fn(),
+      on: vi.fn(() => () => {}),
+    },
+  };
+  return Object.assign(pi, overrides);
+}