pi-shepherd 0.1.1 → 0.1.2

package/node_modules/@pi-atelier/shared-utils/README.md

@@ -1,182 +0,0 @@
-[English](README.en.md) | 程序中文文档
-
-# pi-shared-utils
-
-Shared utility library for the [pi](https://github.com/earendil-works/pi-coding-agent) extension ecosystem — memory file parsing, path constants, settings management, tool output truncation, and more. Used by 7+ pi extensions.
-
-## Why You Need It
-
-If you're building a pi extension, you'll inevitably need the same building blocks: reading settings, parsing memory files, truncating tool output, finding agent directories. pi-shared-utils provides these as a single dependency so every extension doesn't reinvent the wheel.
-
-**Used by**: pi-memory, pi-context, pi-shepherd, pi-roadmap, pi-session-analyzer, pi-workflow, and more.
-
-## How It Works
-
-```
-pi-shared-utils provides 6 independent modules:
-
-┌─────────────────────────────────────────────────┐
-│  memory-parser  ── 解析 topic--kw1,kw2.md 文件名  │
-│  paths         ── pi agent 标准路径常量            │
-│  settings      ── settings.json 读写扩展配置段    │
-│  tool-output   ── 工具输出截断（防上下文溢出）    │
-│  agents        ── 子代理定义文件发现              │
-│  ephemeral     ── 会话临时 hint/label 栈          │
-└─────────────────────────────────────────────────┘
-```
-
-Each module is independently importable — use only what you need.
-
-## Installation
-
-```bash
-pi install git:github.com/catlain/pi-atelier
-```
-
-> 这是 pi-atelier monorepo 内的 workspace 包，通常不需要单独安装。其他独立扩展通过 `bundledDependencies` 自动包含它。
-
-## 导出模块
-
-### 记忆文件解析 (`memory-parser`)
-
-解析 `topic--kw1,kw2,kw3.md` 格式的记忆文件名，扫描目录生成索引。
-
-```ts
-import { parseFileName, buildFileName, scanMemoryDir } from "@pi-atelier/shared-utils";
-
-// 解析文件名 → { topic, keywords }
-const { topic, keywords } = parseFileName("coding_standards--编码,git,lint.md");
-// topic = "coding_standards", keywords = ["编码", "git", "lint"]
-
-// 反向构建文件名
-const name = buildFileName("coding_standards", ["编码", "git", "lint"]);
-// "coding_standards--编码,git,lint.md"
-
-// 扫描目录，返回 MemoryEntry[]
-const entries = await scanMemoryDir("/path/to/memory");
-```
-
-### 路径常量 (`paths`)
-
-pi agent 标准路径，避免硬编码。
-
-| 常量 | 路径 | 说明 |
-|------|------|------|
-| `AGENT_DIR` | `~/.pi/agent/` | agent 根目录 |
-| `SETTINGS_PATH` | `~/.pi/agent/settings.json` | 全局设置 |
-| `MODELS_CONFIG_PATH` | `~/.pi/agent/models.json` | 模型配置 |
-| `MCP_CONFIG_PATH` | `~/.pi/agent/mcp.json` | MCP 服务器配置 |
-| `MCP_CACHE_PATH` | `~/.pi/agent/mcp-cache/` | MCP 工具缓存 |
-| `AGENTS_DIR` | `~/.pi/agent/agents/` | 子代理定义 |
-| `GLOBAL_RULES_PATH` | `~/.pi/agent/rules.md` | 全局规则 |
-| `MEMORY_DIR` | `~/.pi/agent/memory/` | 全局记忆 |
-| `MEMORY_MD_PATH` | `MEMORY.md` | 记忆索引文件名 |
-
-### 设置管理 (`settings`)
-
-读写 `settings.json` 中扩展的自定义配置段。
-
-```ts
-import { getSettingsSection, patchSettingsSection, getSettingsValue, setSettingsValue } from "@pi-atelier/shared-utils";
-
-// 读取扩展配置段
-const config = await getSettingsSection("my-extension");
-
-// 增量更新配置
-await patchSettingsSection("my-extension", { enabled: true });
-
-// 读取/写入单个值
-const val = await getSettingsValue("my-extension", "key", "default");
-await setSettingsValue("my-extension", "key", "new-value");
-```
-
-### 工具输出截断 (`tool-output`)
-
-防止工具返回超大结果撑爆 LLM 上下文。
-
-```ts
-import { truncateToolOutput, truncatedResult, TOOL_OUTPUT_MAX_LINES } from "@pi-atelier/shared-utils";
-
-// 截断过长的输出
-const result = truncateToolOutput(longText, { maxLines: 200 });
-// { text: "...", truncated: true, originalLines: 1500, keptLines: 200 }
-
-// 快捷方式：返回 pi tool result 格式
-return truncatedResult(text);  // 自动截断 + 返回 { content: [{ type: "text", text }] }
-```
-
-### 子代理发现 (`agents`)
-
-扫描 `~/.pi/agent/agents/` 目录下的子代理定义文件。
-
-```ts
-import { discoverAgents, getAgentDescription, formatAgentsList } from "@pi-atelier/shared-utils";
-
-// 发现所有可用子代理
-const agents = await discoverAgents();
-// [{ name: "pv-executor", description: "...", filePath: "..." }, ...]
-
-// 获取单个描述
-const desc = await getAgentDescription("pv-executor");
-
-// 格式化为可读列表
-const list = formatAgentsList(agents);
-```
-
-### 会话临时数据 (`ephemeral`)
-
-当前会话的临时 hint/label 栈，会话结束即消失。用于跨工具调用的轻量状态传递。
-
-```ts
-import { pushHint, hasHints, peekHints, drainHints, peekLabels } from "@pi-atelier/shared-utils";
-
-pushHint({ key: "recent-files", values: ["file1.ts", "file2.ts"] });
-const has = hasHints("recent-files");
-const hints = peekHints("recent-files");   // 查看不移除
-const all = drainHints();                   // 取出并清空
-```
-
-## Best Practices
-
-### ✅ Recommended
-- Import only the modules you need to keep bundle size small
-- Use `truncatedResult()` for all tool outputs — prevents context overflow
-- Use `paths` constants instead of hardcoding `~/.pi/agent/...`
-- Use `settings` module for any persistent configuration
-
-### ❌ Not Recommended
-- Don't hardcode pi paths — they may change between versions
-- Don't return raw tool output without truncation
-- Don't use `ephemeral` for persistent data — it's session-scoped only
-
-## Limitations
-
-| Limitation | Detail |
-|------------|--------|
-| Memory file format only | Only supports `topic--kw1,kw2.md` naming convention |
-| No validation | Settings reads don't validate schema — caller must handle |
-| Ephemeral is in-memory | Lost on process restart, not persisted to disk |
-| Token estimation | `tool-output` truncates by lines, not by token count |
-
-## Architecture
-
-```
-pi-shared-utils/
-├── src/
-│   ├── index.ts           # Re-exports all modules
-│   ├── memory-parser.ts   # Memory file name parsing + directory scanning
-│   ├── paths.ts           # Path constants (AGENT_DIR, SETTINGS_PATH, ...)
-│   ├── settings.ts        # settings.json section read/write
-│   ├── tool-output.ts     # Output truncation + truncatedResult helper
-│   ├── agents.ts          # Sub-agent discovery from ~/.pi/agent/agents/
-│   ├── ephemeral.ts       # Session-scoped hint/label stack
-│   └── __tests__/         # Unit tests
-├── package.json
-└── tsconfig.json
-```
-
-**Dependencies**: Zero runtime dependencies (pure Node.js).
-
-## License
-
-MIT

package/node_modules/@pi-atelier/shared-utils/package.json

@@ -1,51 +0,0 @@
-{
-  "name": "@pi-atelier/shared-utils",
-  "version": "1.0.0",
-  "description": "Shared utilities for pi-atelier extensions — settings, project config, memory parsing, tool output truncation, and more",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "exports": {
-    ".": "./src/index.ts",
-    "./*": "./src/*.ts"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "lint": "biome check lib src index.ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.6.0"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.15",
-    "@vitest/coverage-v8": "^3.2.4",
-    "tsup": "^8.0.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
-  },
-  "tsup": {
-    "entry": [
-      "src/index.ts"
-    ],
-    "format": [
-      "esm"
-    ],
-    "dts": true,
-    "clean": true
-  },
-  "files": [
-    "src/",
-    "README.md",
-    "README.en.md",
-    "tsconfig.json",
-    "vitest.config.ts",
-    "package.json"
-  ]
-}

package/node_modules/@pi-atelier/shared-utils/src/__tests__/agents.test.ts

@@ -1,120 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-// vi.mock factory is hoisted, use vi.hoisted to declare variables at the hoisted position
-const mockFs = vi.hoisted(() => ({
-	existsSync: vi.fn(),
-	readdirSync: vi.fn(),
-	readFileSync: vi.fn(),
-}));
-
-vi.mock("node:fs", () => mockFs);
-
-import { discoverAgents, getAgentDescription, formatAgentsList } from "../agents";
-
-beforeEach(() => {
-	vi.clearAllMocks();
-});
-
-describe("discoverAgents", () => {
-	it("returns empty array when AGENTS_DIR does not exist", () => {
-		mockFs.existsSync.mockReturnValue(false);
-		expect(discoverAgents()).toEqual([]);
-	});
-
-	it("filters .md files and strips leading underscore", () => {
-		mockFs.existsSync.mockReturnValue(true);
-		mockFs.readdirSync.mockReturnValue([
-			"coder.md",
-			"_private.md",
-			"reviewer.md",
-			"readme.txt",
-			"notes.md",
-		]);
-		const result = discoverAgents();
-		expect(result).toEqual(["coder", "reviewer", "notes"]);
-	});
-
-	it("returns empty when only non-md files exist", () => {
-		mockFs.existsSync.mockReturnValue(true);
-		mockFs.readdirSync.mockReturnValue(["file.txt", "file.json"]);
-		expect(discoverAgents()).toEqual([]);
-	});
-
-	it("returns empty when only underscored md files exist", () => {
-		mockFs.existsSync.mockReturnValue(true);
-		mockFs.readdirSync.mockReturnValue(["_private.md", "_template.md"]);
-		expect(discoverAgents()).toEqual([]);
-	});
-});
-
-describe("getAgentDescription", () => {
-	it("extracts description from frontmatter", () => {
-		const content = [
-			"---",
-			"description: 代码审查助手",
-			"version: 1.0",
-			"---",
-			"# Coder Agent",
-			"Some content",
-		].join("\n");
-		mockFs.readFileSync.mockReturnValue(content);
-		const result = getAgentDescription("coder");
-		expect(result).toBe("代码审查助手");
-	});
-
-	it("uses default description when no frontmatter", () => {
-		mockFs.readFileSync.mockReturnValue("plain content without frontmatter");
-		const result = getAgentDescription("coder");
-		expect(result).toBe("read, grep, find, ls");
-	});
-
-	it("uses default description when file read fails", () => {
-		mockFs.readFileSync.mockImplementation(() => {
-			throw new Error("ENOENT");
-		});
-		const result = getAgentDescription("nonexistent");
-		expect(result).toBe("read, grep, find, ls");
-	});
-
-	it("uses default description when frontmatter has no description field", () => {
-		const content = [
-			"---",
-			"title: Agent",
-			"---",
-			"# Content",
-		].join("\n");
-		mockFs.readFileSync.mockReturnValue(content);
-		const result = getAgentDescription("agent");
-		expect(result).toBe("read, grep, find, ls");
-	});
-
-	it("handles description with trailing whitespace", () => {
-		const content = [
-			"---",
-			"description:  帮我写代码  ",
-			"---",
-		].join("\n");
-		mockFs.readFileSync.mockReturnValue(content);
-		const result = getAgentDescription("agent");
-		expect(result).toBe("帮我写代码");
-	});
-});
-
-describe("formatAgentsList", () => {
-	it("returns placeholder when no agents", () => {
-		mockFs.existsSync.mockReturnValue(false);
-		expect(formatAgentsList()).toBe("(无可用子代理)");
-	});
-
-	it("formats agent list with descriptions", () => {
-		mockFs.existsSync.mockReturnValue(true);
-		mockFs.readdirSync.mockReturnValue(["coder.md", "reviewer.md"]);
-		mockFs.readFileSync.mockImplementation((filePath: string) => {
-			if (filePath.includes("coder")) return "---\ndescription: Coder助手\n---\n";
-			if (filePath.includes("reviewer")) return "---\ndescription: Reviewer助手\n---\n";
-			return "";
-		});
-		const result = formatAgentsList();
-		expect(result).toBe("- **coder**: Coder助手\n- **reviewer**: Reviewer助手");
-	});
-});

package/node_modules/@pi-atelier/shared-utils/src/__tests__/ephemeral.test.ts

@@ -1,100 +0,0 @@
-/**
- * ephemeral.ts 测试
- *
- * 模块内 _hints/_labels 是模块级变量，每次 import 可能返回缓存模块。
- * 使用 vi.resetModules() 确保每个测试得到干净的模块状态。
- */
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-function importEphemeral() {
-	return import("../ephemeral");
-}
-
-beforeEach(() => {
-	vi.resetModules();
-});
-
-describe("ephemeral hints lifecycle", () => {
-	it("starts empty: hasHints returns false", async () => {
-		const { hasHints } = await importEphemeral();
-		expect(hasHints()).toBe(false);
-	});
-
-	it("peekHints returns null when empty", async () => {
-		const { peekHints } = await importEphemeral();
-		expect(peekHints()).toBeNull();
-	});
-
-	it("drainHints returns null when empty", async () => {
-		const { drainHints } = await importEphemeral();
-		expect(drainHints()).toBeNull();
-	});
-
-	it("peekLabels returns empty array when empty", async () => {
-		const { peekLabels } = await importEphemeral();
-		expect(peekLabels()).toEqual([]);
-	});
-});
-
-describe("pushHint and peek", () => {
-	it("pushHint adds hint, peekHints returns it without consuming", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("提示A");
-		expect(mod.hasHints()).toBe(true);
-		expect(mod.peekHints()).toBe("提示A");
-		// peek does not consume
-		expect(mod.peekHints()).toBe("提示A");
-	});
-
-	it("pushHint with label adds label to peekLabels", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("提示B", "label-b");
-		expect(mod.peekLabels()).toEqual(["label-b"]);
-		expect(mod.peekHints()).toBe("提示B");
-	});
-
-	it("multiple hints joined by double newline", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("first");
-		mod.pushHint("second");
-		expect(mod.peekHints()).toBe("first\n\nsecond");
-	});
-});
-
-describe("drainHints", () => {
-	it("drainHints returns hints and clears state", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("hint1", "lbl1");
-		mod.pushHint("hint2", "lbl2");
-		const result = mod.drainHints();
-		expect(result).toBe("hint1\n\nhint2");
-		// after drain, state is cleared
-		expect(mod.hasHints()).toBe(false);
-		expect(mod.peekHints()).toBeNull();
-		expect(mod.peekLabels()).toEqual([]);
-	});
-
-	it("labels are cleared after drain", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("test", "mylabel");
-		mod.drainHints();
-		expect(mod.peekLabels()).toEqual([]);
-	});
-});
-
-describe("multiple push then drain", () => {
-	it("push 3 hints without labels", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("a");
-		mod.pushHint("b");
-		mod.pushHint("c");
-		expect(mod.drainHints()).toBe("a\n\nb\n\nc");
-	});
-
-	it("push with labels, peekLabels returns all labels", async () => {
-		const mod = await importEphemeral();
-		mod.pushHint("x", "l1");
-		mod.pushHint("y", "l2");
-		expect(mod.peekLabels()).toEqual(["l1", "l2"]);
-	});
-});

package/node_modules/@pi-atelier/shared-utils/src/__tests__/file-lock.test.ts

@@ -1,152 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-
-// ── Mock fs ─────────────────────────────────────────────
-// vi.hoisted ensures variables are available before vi.mock factory runs
-
-const { mockMkdirSync, mockRmSync, mockStatSync } = vi.hoisted(() => ({
-	mockMkdirSync: vi.fn(),
-	mockRmSync: vi.fn(),
-	mockStatSync: vi.fn(),
-}));
-
-vi.mock("node:fs", () => ({
-	mkdirSync: mockMkdirSync,
-	rmSync: mockRmSync,
-	statSync: mockStatSync,
-}));
-
-import { acquireLock, releaseLock, withFileLock } from "../file-lock";
-
-const EEXIST_ERROR = Object.assign(new Error("EEXIST"), { code: "EEXIST" });
-const UNKNOWN_ERROR = new Error("unknown");
-
-function makeRecentStat(): { mtimeMs: number } {
-	return { mtimeMs: Date.now() };
-}
-
-function makeStaleStat(): { mtimeMs: number } {
-	return { mtimeMs: 0 };
-}
-
-// ── Tests ───────────────────────────────────────────────
-
-beforeEach(() => {
-	vi.clearAllMocks();
-});
-
-describe("acquireLock", () => {
-	it("succeeds on first attempt", () => {
-		mockMkdirSync.mockReturnValue(undefined);
-		acquireLock("/tmp/test.lock");
-		expect(mockMkdirSync).toHaveBeenCalledTimes(1);
-		expect(mockMkdirSync).toHaveBeenCalledWith("/tmp/test.lock.lock");
-	});
-
-	it("rethrows non-EEXIST error", () => {
-		mockMkdirSync.mockImplementation(() => {
-			throw UNKNOWN_ERROR;
-		});
-		expect(() => acquireLock("/tmp/test.lock")).toThrow(UNKNOWN_ERROR);
-	});
-
-	it("handles EEXIST with stale lock, removes and retries success", () => {
-		mockMkdirSync
-			.mockImplementationOnce(() => {
-				throw EEXIST_ERROR;
-			})
-			.mockReturnValue(undefined);
-		mockStatSync.mockReturnValue(makeStaleStat());
-
-		acquireLock("/tmp/test.lock");
-
-		expect(mockMkdirSync).toHaveBeenCalledTimes(2);
-		expect(mockStatSync).toHaveBeenCalledTimes(1);
-		expect(mockStatSync).toHaveBeenCalledWith("/tmp/test.lock.lock");
-		expect(mockRmSync).toHaveBeenCalledWith("/tmp/test.lock.lock", { recursive: true });
-	});
-
-	it("handles EEXIST with statSync throw, retries and succeeds", () => {
-		mockMkdirSync
-			.mockImplementationOnce(() => {
-				throw EEXIST_ERROR;
-			})
-			.mockReturnValue(undefined);
-		mockStatSync.mockImplementation(() => {
-			throw new Error("ENOENT");
-		});
-
-		acquireLock("/tmp/test.lock");
-
-		expect(mockMkdirSync).toHaveBeenCalledTimes(2);
-		expect(mockStatSync).toHaveBeenCalledTimes(1);
-	});
-
-	it("handles EEXIST with non-stale lock, retries and succeeds after busy-wait", () => {
-		mockMkdirSync
-			.mockImplementationOnce(() => {
-				throw EEXIST_ERROR;
-			})
-			.mockReturnValue(undefined);
-		mockStatSync.mockReturnValue(makeRecentStat());
-
-		acquireLock("/tmp/test.lock");
-
-		expect(mockMkdirSync).toHaveBeenCalledTimes(2);
-		expect(mockStatSync).toHaveBeenCalledTimes(1);
-	});
-
-	it("times out after MAX_ATTEMPTS with EEXIST each time", () => {
-		mockMkdirSync.mockImplementation(() => {
-			throw EEXIST_ERROR;
-		});
-		mockStatSync.mockReturnValue(makeRecentStat());
-
-		expect(() => acquireLock("/tmp/test.lock")).toThrow(
-			"无法获取文件锁: /tmp/test.lock.lock（尝试 50 次后超时）",
-		);
-
-		expect(mockMkdirSync).toHaveBeenCalledTimes(50);
-		expect(mockStatSync).toHaveBeenCalledTimes(50);
-		expect(mockRmSync).not.toHaveBeenCalled();
-	});
-});
-
-describe("releaseLock", () => {
-	it("removes lock directory", () => {
-		mockRmSync.mockReturnValue(undefined);
-		releaseLock("/tmp/test.lock");
-		expect(mockRmSync).toHaveBeenCalledWith("/tmp/test.lock.lock", { recursive: true });
-	});
-
-	it("silently ignores rmSync errors", () => {
-		mockRmSync.mockImplementation(() => {
-			throw new Error("ENOENT");
-		});
-		expect(() => releaseLock("/tmp/test.lock")).not.toThrow();
-	});
-});
-
-describe("withFileLock", () => {
-	it("acquires lock, executes fn, releases lock", () => {
-		mockMkdirSync.mockReturnValue(undefined);
-		mockRmSync.mockReturnValue(undefined);
-
-		const result = withFileLock("/tmp/test.lock", () => "done");
-
-		expect(result).toBe("done");
-		expect(mockMkdirSync).toHaveBeenCalledWith("/tmp/test.lock.lock");
-		expect(mockRmSync).toHaveBeenCalledWith("/tmp/test.lock.lock", { recursive: true });
-	});
-
-	it("releases lock even when fn throws", () => {
-		mockMkdirSync.mockReturnValue(undefined);
-
-		expect(() =>
-			withFileLock("/tmp/test.lock", () => {
-				throw new Error("fn failed");
-			}),
-		).toThrow("fn failed");
-
-		expect(mockRmSync).toHaveBeenCalledWith("/tmp/test.lock.lock", { recursive: true });
-	});
-});