pi-shepherd 0.1.1 → 0.1.2

package/node_modules/@pi-atelier/shared-utils/src/settings-backup.ts

@@ -1,172 +0,0 @@
-/**
- * Settings 备份与安全修改
- *
- * 提供带备份的 settings.json 修改能力：
- *   - 修改前自动备份
- *   - 类型校验（validateConfigSchema）
- *   - 备份轮转（maxBackups）
- *   - 回滚（rollbackSettings）
- *
- * 用法：
- *   import { patchSettingsSectionWithBackup, rollbackSettings, listBackups } from "@pi-atelier/shared-utils/settings-backup";
- *
- *   const result = patchSettingsSectionWithBackup("context", { distillThreshold: 8000 }, defaults, { settingsPath, backupDir });
- *   rollbackSettings({ settingsPath, backupDir });
- */
-
-import { existsSync } from "node:fs";
-import { withFileLock } from "./file-lock";
-import { validateConfigSchema, type SchemaError } from "./project-config";
-import { isArrayPatch, applyArrayPatch } from "./settings-array";
-import { createBackup, getDefaultBackupDir, readFull, writeFull } from "./settings-backup-utils";
-import { rotateBackups } from "./settings-backup-rollback";
-export { rollbackSettings, listBackups } from "./settings-backup-rollback";
-export type { BackupEntry, RollbackOptions } from "./settings-backup-rollback";
-
-// ── 类型 ─────────────────────────────────────────────────
-
-export interface PatchBackupOptions {
-	/** 要修改的 settings.json 路径（默认全局） */
-	settingsPath?: string;
-	/** 备份目录路径 */
-	backupDir?: string;
-	/** 是否创建备份（默认 true） */
-	backup?: boolean;
-	/** 最大保留备份数（默认 10） */
-	maxBackups?: number;
-	/** 是否校验类型（默认 true） */
-	validate?: boolean;
-}
-
-export interface PatchBackupResult<T extends Record<string, any>> {
-	/** 合并后的配置 */
-	config: T;
-	/** 类型校验错误 */
-	errors: SchemaError[];
-	/** 备份文件路径（如果创建了备份） */
-	backupPath?: string;
-}
-
-// rotateBackups / rollbackSettings / listBackups 已拆分到 settings-backup-rollback.ts
-
-// ── API ─────────────────────────────────────────────────
-
-/**
- * 带备份的 settings.json 安全修改
- *
- * 执行流程：备份 → 校验 → 合并 → 写入
- *
- * @param section - settings.json 中的顶层 key
- * @param patch - 要修改的字段
- * @param defaults - 该段的默认值（用于校验）
- * @param options - 备份和校验选项
- * @returns 合并后的配置 + 校验错误
- */
-export function patchSettingsSectionWithBackup<T extends Record<string, any>>(
-	section: string,
-	patch: Partial<T>,
-	defaults: T,
-	options?: PatchBackupOptions,
-): PatchBackupResult<T> {
-	const settingsPath = options?.settingsPath ?? "";
-	const backupDir = options?.backupDir ?? getDefaultBackupDir(settingsPath);
-	const shouldBackup = options?.backup !== false;
-	const maxBackups = options?.maxBackups ?? 10;
-	const shouldValidate = options?.validate !== false;
-
-	// 1. 读取当前配置
-	const settings = readFull(settingsPath);
-
-	// ── 数组 patch 分支 ──
-	if (isArrayPatch(patch)) {
-		const currentArr: any[] = Array.isArray(settings[section]) ? settings[section] : (Array.isArray(defaults) ? defaults : []);
-		const mergedArr = applyArrayPatch(currentArr, patch);
-
-		// 备份
-		let backupPath: string | undefined;
-		if (shouldBackup && backupDir && existsSync(settingsPath)) {
-			backupPath = createBackup(settingsPath, backupDir);
-			rotateBackups(backupDir, maxBackups);
-		}
-
-		// 加锁写入
-		if (settingsPath) {
-			withFileLock(settingsPath, () => {
-				const latest = readFull(settingsPath);
-				latest[section] = mergedArr;
-				writeFull(settingsPath, latest);
-			});
-		} else {
-			settings[section] = mergedArr;
-			writeFull(settingsPath, settings);
-		}
-
-		return { config: mergedArr as any as T, errors: [], backupPath };
-	}
-
-	// ── 对象 merge 分支（原有逻辑） ──
-	const current = settings[section] ?? {};
-
-	// 2. 计算合并后的配置（用于校验）
-	const merged: Record<string, any> = { ...current };
-	for (const [key, value] of Object.entries(patch)) {
-		if (value !== undefined) merged[key] = value;
-	}
-
-	// 3. 类型校验（校验合并后的结果 vs defaults）
-	const errors: SchemaError[] = [];
-	if (shouldValidate) {
-		// 构造一个临时的"项目配置"用于校验
-		for (const key of Object.keys(merged)) {
-			if (key in defaults) {
-				const defaultVal = (defaults as Record<string, any>)[key];
-				const mergedVal = merged[key];
-				const expectedType = Array.isArray(defaultVal) ? "array" : defaultVal === null ? "null" : typeof defaultVal;
-				const actualType = Array.isArray(mergedVal) ? "array" : mergedVal === null ? "null" : typeof mergedVal;
-
-				if (expectedType === "object" && actualType === "object") {
-					// 嵌套对象暂不深度校验
-				} else if (expectedType !== actualType) {
-					errors.push({
-						section,
-						key,
-						expectedType,
-						actualType,
-						description: `配置 "${section}.${key}" 类型错误：期望 ${expectedType}，实际 ${actualType}`,
-					});
-				}
-			}
-		}
-
-		// 有类型错误 → 不写入
-		if (errors.length > 0) {
-			return { config: { ...defaults, ...current } as T, errors };
-		}
-	}
-
-	// 4. 备份
-	let backupPath: string | undefined;
-	if (shouldBackup && backupDir && existsSync(settingsPath)) {
-		backupPath = createBackup(settingsPath, backupDir);
-		rotateBackups(backupDir, maxBackups);
-	}
-
-	// 5. 加锁写入（与 pi SettingsManager 互斥）
-	if (settingsPath) {
-		withFileLock(settingsPath, () => {
-			// 重新读取（可能在等锁期间被其他进程修改）
-			const latest = readFull(settingsPath);
-			latest[section] = merged;
-			writeFull(settingsPath, latest);
-		});
-	} else {
-		settings[section] = merged;
-		writeFull(settingsPath, settings);
-	}
-
-	// 6. 返回合并后的配置
-	const finalConfig = { ...defaults, ...merged } as T;
-	return { config: finalConfig, errors, backupPath };
-}
-
-// rollbackSettings / listBackups 已拆分到 settings-backup-rollback.ts，通过 re-export 暴露

package/node_modules/@pi-atelier/shared-utils/src/settings.ts

@@ -1,104 +0,0 @@
-/**
- * 通用 settings.json 读写工具
- *
- * 所有扩展共享同一份 ~/.pi/agent/settings.json，通过 namespace 区分各扩展的配置段。
- * 用法：
- *   import { getSettingsSection, patchSettingsSection } from "@pi-atelier/shared-utils";
- *   const cfg = getSettingsSection("context", defaults);
- *   patchSettingsSection("context", { distillThreshold: 3000 });
- */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const SETTINGS_PATH = join(homedir(), ".pi/agent/settings.json");
-
-function readFull(): Record<string, any> {
-	try {
-		if (!existsSync(SETTINGS_PATH)) return {};
-		return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
-	} catch {
-		return {};
-	}
-}
-
-function writeFull(settings: Record<string, any>): void {
-	writeFileSync(SETTINGS_PATH, `${JSON.stringify(settings, null, "\t")}\n`);
-}
-
-/**
- * 读取 settings.json 中某个命名空间的配置，与默认值合并
- *
- * @param section - settings.json 中的顶层 key，如 "context"、"smartContext"
- * @param defaults - 该段的默认值（完整对象）
- * @returns 合并后的配置（defaults 中存在的字段用 settings 覆盖，缺失则用 defaults 填充）
- */
-export function getSettingsSection<T extends Record<string, any>>(section: string, defaults: T): T {
-	const settings = readFull();
-	const stored = settings?.[section] ?? {};
-	const result: Record<string, any> = {};
-	for (const key of Object.keys(defaults)) {
-		result[key] = key in stored ? stored[key] : (defaults as Record<string, any>)[key];
-	}
-	return result as T;
-}
-
-/**
- * 增量更新 settings.json 中某个命名空间的配置
- *
- * 只修改 patch 中指定的字段，其余字段保持不变。写入后返回合并后的完整配置。
- *
- * @param section - settings.json 中的顶层 key
- * @param patch - 要修改的字段（部分对象）
- * @returns 更新后的完整配置
- */
-export function patchSettingsSection<T extends Record<string, any>>(
-	section: string,
-	patch: Partial<T>,
-	defaults: T,
-): T {
-	const settings = readFull();
-	const current = settings[section] ?? {};
-	for (const [key, value] of Object.entries(patch)) {
-		if (value !== undefined) current[key] = value;
-	}
-	settings[section] = current;
-	writeFull(settings);
-	return getSettingsSection(section, defaults);
-}
-
-/**
- * 读取 settings.json 中某个叶子字段的值（如 recording.enabled）
- *
- * @param path - 点分隔的路径，如 "recording.enabled"
- * @param fallback - 字段不存在时的默认值
- */
-export function getSettingsValue<T>(path: string, fallback: T): T {
-	const settings = readFull();
-	const keys = path.split(".");
-	let current: unknown = settings;
-	for (const key of keys) {
-		if (current == null || typeof current !== "object") return fallback;
-		current = (current as Record<string, unknown>)[key];
-	}
-	return current !== undefined ? (current as T) : fallback;
-}
-
-/**
- * 设置 settings.json 中某个叶子字段的值
- *
- * @param path - 点分隔的路径，如 "recording.enabled"
- * @param value - 要写入的值
- */
-export function setSettingsValue<T>(path: string, value: T): void {
-	const settings = readFull();
-	const keys = path.split(".");
-	let current: Record<string, unknown> = settings;
-	for (let i = 0; i < keys.length - 1; i++) {
-		const key = keys[i];
-		if (current[key] == null || typeof current[key] !== "object") current[key] = {};
-		current = current[key] as Record<string, unknown>;
-	}
-	current[keys[keys.length - 1]] = value;
-	writeFull(settings);
-}

package/node_modules/@pi-atelier/shared-utils/src/tool-output.ts

@@ -1,149 +0,0 @@
-/**
- * Tool Output Protection — 共享的工具输出截断模块
- *
- * 为所有自注册工具提供统一的输出保护：
- * - 超限时截断输出，保留头部内容
- * - 完整内容写入临时文件，供 AI 按需读取
- * - 附加截断提示，告诉 AI 如何获取完整内容
- *
- * 使用方式：
- *   import { truncatedResult } from "../_shared/tool-output";
- *   return truncatedResult(text, { toolName: "session_search" });
- */
-
-import { createHash } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead } from "@earendil-works/pi-coding-agent";
-
-// ── 配置 ─────────────────────────────────────────────────
-
-export const TOOL_OUTPUT_MAX_LINES = DEFAULT_MAX_LINES; // 2000
-export const TOOL_OUTPUT_MAX_BYTES = DEFAULT_MAX_BYTES; // 50KB
-
-// ── 类型 ─────────────────────────────────────────────────
-
-export interface TruncationOptions {
-	maxLines?: number;
-	maxBytes?: number;
-	toolName?: string;
-	label?: string;
-}
-
-export interface ToolOutputResult {
-	content: string;
-	truncated: boolean;
-	totalLines: number;
-	totalBytes: number;
-	outputLines: number;
-	outputBytes: number;
-	savedPath?: string;
-}
-
-// ── 核心函数 ─────────────────────────────────────────────
-
-/**
- * 截断工具输出，超限时写入临时文件并返回截断内容 + 位置提示。
- *
- * 对 SDK truncateHead() 的包装，追加：
- * - 自动写临时文件
- * - 附加截断提示文本
- * - 错误 fallback
- */
-export function truncateToolOutput(text: string, options: TruncationOptions = {}): ToolOutputResult {
-	const maxLines = options.maxLines ?? TOOL_OUTPUT_MAX_LINES;
-	const maxBytes = options.maxBytes ?? TOOL_OUTPUT_MAX_BYTES;
-
-	// SDK truncateHead 处理截断逻辑
-	const result = truncateHead(text, { maxLines, maxBytes });
-
-	if (!result.truncated) {
-		return {
-			content: text,
-			truncated: false,
-			totalLines: result.totalLines,
-			totalBytes: result.totalBytes,
-			outputLines: result.outputLines,
-			outputBytes: result.outputBytes,
-		};
-	}
-
-	// 超限 — 写完整内容到临时文件
-	const toolName = options.toolName || "tool";
-	const hash = createHash("sha256").update(text).digest("hex").slice(0, 12);
-	const fileName = `${toolName}-${hash}.txt`;
-	const toolDir = join(tmpdir(), "pi-tool-output");
-	let savedPath: string | undefined;
-
-	try {
-		mkdirSync(toolDir, { recursive: true });
-		savedPath = join(toolDir, fileName);
-		writeFileSync(savedPath, text, "utf-8");
-	} catch {
-		// 写入失败时 fallback — 只截断不保存，不抛异常
-		savedPath = undefined;
-	}
-
-	// 附加截断提示
-	const label = options.label || toolName;
-	let notice = `\n\n[输出已截断: ${label}] 显示 ${result.outputLines}/${result.totalLines} 行`;
-	notice += ` (${formatSize(result.outputBytes)}/${formatSize(result.totalBytes)})`;
-	if (savedPath) {
-		notice += `。完整内容: ${savedPath}]`;
-		notice += `\n提示: 用 read 工具的 offset/limit 参数精确读取需要的行范围。`;
-	} else {
-		notice += `。完整内容未能保存到临时文件。]`;
-	}
-
-	return {
-		content: result.content + notice,
-		truncated: true,
-		totalLines: result.totalLines,
-		totalBytes: result.totalBytes,
-		outputLines: result.outputLines,
-		outputBytes: result.outputBytes,
-		savedPath,
-	};
-}
-
-// ── 便捷封装 ─────────────────────────────────────────────
-
-/**
- * 便捷封装：截断 + 包装成 pi 工具需要的返回格式。
- *
- * 返回 { content: [{ type, text }], details: { truncation } }
- * 支持传入 existingDetails，截断信息会合并进去。
- */
-export function truncatedResult(
-	text: string,
-	options: TruncationOptions = {},
-	existingDetails?: Record<string, unknown>,
-): {
-	content: Array<{ type: "text"; text: string }>;
-	details: Record<string, unknown>;
-} {
-	const result = truncateToolOutput(text, options);
-
-	const details: Record<string, unknown> = {
-		...existingDetails,
-	};
-
-	if (result.truncated) {
-		details.truncation = {
-			truncated: true,
-			totalLines: result.totalLines,
-			totalBytes: result.totalBytes,
-			outputLines: result.outputLines,
-			outputBytes: result.outputBytes,
-			savedPath: result.savedPath,
-		};
-	} else {
-		details.truncation = null;
-	}
-
-	return {
-		content: [{ type: "text", text: result.content }],
-		details,
-	};
-}

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

@@ -1,9 +0,0 @@
-{
-  "extends": "../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": ["node"]
-  },
-  "include": ["src/**/*.ts"]
-}

package/node_modules/@pi-atelier/shared-utils/vitest.config.ts

@@ -1,24 +0,0 @@
-import { defineConfig } from "vitest/config";
-import path from "node:path";
-
-const ROOT = path.resolve(__dirname, "../..");
-
-export default defineConfig({
-  resolve: {
-    alias: {
-      "pi-shared-utils": path.resolve(ROOT, "packages/pi-shared-utils/src/index"),
-      "@pi-atelier/shared-utils": path.resolve(ROOT, "packages/pi-shared-utils/src/index"),
-    },
-  },
-  test: {
-    include: ["src/__tests__/**/*.test.ts"],
-    environment: "node",
-    testTimeout: 10000,
-    fileParallelism: false,
-    coverage: {
-      provider: "v8",
-      reporter: ["text", "html"],
-      exclude: ["src/index.ts", "vitest.config.ts", "src/__tests__/**"],
-    },
-  },
-});