pi-shepherd 0.1.0

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

@@ -0,0 +1,269 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const TEST_DIR = join(tmpdir(), `pi-settings-adv-test-${process.pid}`);
+const TEST_SETTINGS = join(TEST_DIR, "settings.json");
+const TEST_BACKUP_DIR = join(TEST_DIR, "settings-backup");
+
+const { patchSettingsSectionWithBackup, rollbackSettings, listBackups } = await import(
+	"../settings-backup"
+);
+
+function writeTestSettings(content: Record<string, any>) {
+	mkdirSync(TEST_DIR, { recursive: true });
+	writeFileSync(TEST_SETTINGS, JSON.stringify(content, null, 2));
+}
+
+function readTestSettings(): Record<string, any> {
+	if (!existsSync(TEST_SETTINGS)) return {};
+	return JSON.parse(readFileSync(TEST_SETTINGS, "utf-8"));
+}
+
+function cleanupTestDir() {
+	if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+}
+
+describe("settings-backup 高级测试", () => {
+	beforeEach(() => {
+		cleanupTestDir();
+		mkdirSync(TEST_DIR, { recursive: true });
+	});
+	afterEach(() => {
+		cleanupTestDir();
+	});
+
+	// ── 并发写入与竞态保护 ────────────────────────
+
+	describe("并发写入与竞态保护", () => {
+		it("快速连续 patch 不同 section 不丢数据", () => {
+			writeTestSettings({ context: { threshold: 100 }, shepherd: { maxWarnings: 5 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+			patchSettingsSectionWithBackup(
+				"shepherd",
+				{ maxWarnings: 10 },
+				{ maxWarnings: 5 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			const settings = readTestSettings();
+			expect(settings.context.threshold).toBe(200);
+			expect(settings.shepherd.maxWarnings).toBe(10);
+		});
+
+		it("加锁后重读最新数据 — 保留等锁期间外部修改", () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			// 第一次 patch
+			patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			// 模拟外部进程修改：直接写文件加一个新 section
+			const externalData = { ...readTestSettings(), externalSection: { addedByOther: true } };
+			writeFileSync(TEST_SETTINGS, JSON.stringify(externalData, null, 2));
+
+			// 第二次 patch 应该保留外部添加的 section
+			patchSettingsSectionWithBackup(
+				"shepherd",
+				{ maxWarnings: 3 },
+				{ maxWarnings: 5 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			const settings = readTestSettings();
+			expect(settings.context.threshold).toBe(200);
+			expect(settings.shepherd.maxWarnings).toBe(3);
+			expect(settings.externalSection.addedByOther).toBe(true);
+		});
+
+		it("3 个 section 快速连续 patch 全部保留", () => {
+			writeTestSettings({
+				context: { threshold: 100 },
+				shepherd: { maxWarnings: 5 },
+				mcp: { disabled: [] },
+			});
+
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 200 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+			patchSettingsSectionWithBackup(
+				"shepherd", { maxWarnings: 10 }, { maxWarnings: 5 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+			patchSettingsSectionWithBackup(
+				"mcp", { disabled: ["server-a"] }, { disabled: [] },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			const settings = readTestSettings();
+			expect(settings.context.threshold).toBe(200);
+			expect(settings.shepherd.maxWarnings).toBe(10);
+			expect(settings.mcp.disabled).toEqual(["server-a"]);
+		});
+	});
+
+	// ── 备份内容完整性 ──────────────────────────
+
+	describe("备份内容完整性", () => {
+		it("备份的 JSON 与修改前深度一致", () => {
+			const original = {
+				context: { threshold: 100, name: "test" },
+				deep: { nested: { value: [1, 2, 3] } },
+			};
+			writeTestSettings(original);
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			const backupFiles = readdirSync(TEST_BACKUP_DIR).filter((f) => f.endsWith(".json"));
+			const backupContent = JSON.parse(readFileSync(join(TEST_BACKUP_DIR, backupFiles[0]), "utf-8"));
+
+			expect(backupContent).toEqual(original);
+		});
+
+		it("两次备份内容分别对应各自修改前的状态", async () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 200 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 300 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			const backups = listBackups({ backupDir: TEST_BACKUP_DIR });
+			expect(backups.length).toBe(2);
+
+			// 最新备份（index 0）应该是第二次修改前的状态
+			const backup0 = JSON.parse(readFileSync(backups[0].path, "utf-8"));
+			expect(backup0.context.threshold).toBe(200);
+
+			// 旧备份（index 1）应该是第一次修改前的状态
+			const backup1 = JSON.parse(readFileSync(backups[1].path, "utf-8"));
+			expect(backup1.context.threshold).toBe(100);
+		});
+	});
+
+	// ── 写入格式验证 ──────────────────────────────
+
+	describe("写入格式验证", () => {
+		it("写入的 JSON 格式合法且包含所有字段", () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200, name: "测试" },
+				{ threshold: 100, name: "" },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			const raw = readFileSync(TEST_SETTINGS, "utf-8");
+			const parsed = JSON.parse(raw);
+			expect(parsed.context.threshold).toBe(200);
+			expect(parsed.context.name).toBe("测试");
+		});
+
+		it("写入后 settings.json 以换行结尾", () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 200 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			const raw = readFileSync(TEST_SETTINGS, "utf-8");
+			expect(raw.endsWith("\n")).toBe(true);
+		});
+	});
+
+	// ── detectConflicts 集成 ──────────────────────
+
+	describe("detectConflicts 集成", () => {
+		it("返回全局与项目级冲突列表", async () => {
+			const { detectConfigConflicts } = await import("../project-config");
+
+			// 创建一个临时项目级配置
+			const projectDir = join(TEST_DIR, "project");
+			const projectSettingsDir = join(projectDir, ".pi");
+			mkdirSync(projectSettingsDir, { recursive: true });
+
+			// 项目级覆盖全局配置（同 key 不同值）
+			writeFileSync(
+				join(projectSettingsDir, "settings.json"),
+				JSON.stringify({ context: { threshold: 999 } }),
+			);
+
+			// detectConfigConflicts 读全局 SETTINGS_PATH，项目级 threshold=999 和全局不同
+			const conflicts = detectConfigConflicts(projectDir);
+
+			// 可能检测到项目级的 context.threshold (999) 和全局不同
+			// 注意：这个测试依赖真实全局配置内容，所以只验证 API 不崩溃
+			expect(Array.isArray(conflicts)).toBe(true);
+		});
+	});
+
+	// ── rollback 到指定备份 ────────────────────────
+
+	describe("rollback 到指定备份", () => {
+		it("默认恢复最近一份备份", async () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 200 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 300 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			// 当前是 300，回滚应该恢复到 200（最近一份备份）
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+			expect(readTestSettings().context.threshold).toBe(200);
+		});
+
+		it("手动指定备份文件恢复到更早的状态", async () => {
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 200 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context", { threshold: 300 }, { threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			const backups = listBackups({ backupDir: TEST_BACKUP_DIR });
+			expect(backups.length).toBe(2);
+
+			// 手动恢复到最早那份（threshold = 100）
+			const oldestBackup = backups[backups.length - 1];
+			const content = readFileSync(oldestBackup.path, "utf-8");
+			writeFileSync(TEST_SETTINGS, content);
+
+			expect(readTestSettings().context.threshold).toBe(100);
+		});
+	});
+});

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

@@ -0,0 +1,267 @@
+/**
+ * patchSettingsSectionWithBackup 数组操作测试
+ *
+ * 测试 packages/extensions/skills 等数组类型 section 的增删改操作。
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const TEST_DIR = join(tmpdir(), `pi-settings-array-test-${process.pid}`);
+const TEST_SETTINGS = join(TEST_DIR, "settings.json");
+const TEST_BACKUP_DIR = join(TEST_DIR, "settings-backup");
+
+const { patchSettingsSectionWithBackup } = await import("../settings-backup");
+
+function writeTestSettings(content: Record<string, any>) {
+	mkdirSync(TEST_DIR, { recursive: true });
+	writeFileSync(TEST_SETTINGS, JSON.stringify(content, null, "\t"));
+}
+
+function readTestSettings(): Record<string, any> {
+	return JSON.parse(readFileSync(TEST_SETTINGS, "utf-8"));
+}
+
+beforeEach(() => {
+	mkdirSync(TEST_DIR, { recursive: true });
+	mkdirSync(TEST_BACKUP_DIR, { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+// ── addItem：向数组添加元素 ─────────────────────────────
+
+describe("patchSettingsSectionWithBackup — 数组 addItem", () => {
+	it("应向空数组添加元素", () => {
+		writeTestSettings({ packages: [] });
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ addItem: { source: "git:github.com/catlain/pi-foo" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual([{ source: "git:github.com/catlain/pi-foo" }]);
+		const written = readTestSettings();
+		expect(written.packages).toEqual([{ source: "git:github.com/catlain/pi-foo" }]);
+	});
+
+	it("应向已有数组追加元素", () => {
+		writeTestSettings({
+			packages: [{ source: "git:github.com/catlain/pi-shepherd" }],
+		});
+
+		patchSettingsSectionWithBackup(
+			"packages",
+			{ addItem: { source: "git:github.com/catlain/pi-foo" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		const written = readTestSettings();
+		expect(written.packages).toHaveLength(2);
+		expect(written.packages[1]).toEqual({ source: "git:github.com/catlain/pi-foo" });
+	});
+
+	it("addItem 为对象时用 source 字段去重，已存在则不重复添加", () => {
+		writeTestSettings({
+			packages: [{ source: "git:github.com/catlain/pi-shepherd" }],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ addItem: { source: "git:github.com/catlain/pi-shepherd" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toHaveLength(1);
+	});
+
+	it("addItem 为字符串时精确去重", () => {
+		writeTestSettings({
+			packages: ["npm:pi-tool-display"],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ addItem: "npm:pi-tool-display" },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toHaveLength(1);
+	});
+});
+
+// ── removeItem：从数组删除元素 ─────────────────────────────
+
+describe("patchSettingsSectionWithBackup — 数组 removeItem", () => {
+	it("应按 source 字段匹配删除对象元素", () => {
+		writeTestSettings({
+			packages: [
+				{ source: "git:github.com/catlain/pi-shepherd" },
+				{ source: "git:github.com/catlain/pi-foo" },
+			],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ removeItem: { source: "git:github.com/catlain/pi-foo" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual([{ source: "git:github.com/catlain/pi-shepherd" }]);
+	});
+
+	it("应按字符串精确匹配删除", () => {
+		writeTestSettings({
+			packages: ["npm:pi-tool-display", "npm:pi-foo"],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ removeItem: "npm:pi-foo" },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual(["npm:pi-tool-display"]);
+	});
+
+	it("removeItem 匹配不到时不应修改数组", () => {
+		writeTestSettings({
+			packages: [{ source: "git:github.com/catlain/pi-shepherd" }],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ removeItem: { source: "git:github.com/catlain/nonexistent" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toHaveLength(1);
+	});
+});
+
+// ── replaceItem：替换数组中匹配的元素 ─────────────────────────
+
+describe("patchSettingsSectionWithBackup — 数组 replaceItem", () => {
+	it("应按 source 匹配并替换整个对象元素", () => {
+		writeTestSettings({
+			packages: [
+				{ source: "git:github.com/catlain/pi-usage-stats" }, // 旧格式（字符串被修前）
+			],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{
+				replaceItem: {
+					match: { source: "git:github.com/catlain/pi-usage-stats" },
+					replacement: { source: "git:github.com/catlain/pi-usage-stats", extensions: ["+index.ts"] },
+				},
+			},
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual([
+			{ source: "git:github.com/catlain/pi-usage-stats", extensions: ["+index.ts"] },
+		]);
+	});
+
+	it("应按字符串精确匹配并替换", () => {
+		writeTestSettings({
+			packages: ["npm:old-package"],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{
+				replaceItem: {
+					match: "npm:old-package",
+					replacement: { source: "npm:new-package" },
+				},
+			},
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual([{ source: "npm:new-package" }]);
+	});
+
+	it("replaceItem 匹配不到时不应修改数组", () => {
+		writeTestSettings({
+			packages: [{ source: "git:github.com/catlain/pi-shepherd" }],
+		});
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{
+				replaceItem: {
+					match: { source: "git:github.com/catlain/nonexistent" },
+					replacement: { source: "git:github.com/catlain/something" },
+				},
+			},
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual([{ source: "git:github.com/catlain/pi-shepherd" }]);
+	});
+});
+
+// ── 创建备份 ─────────────────────────────────────────
+
+describe("patchSettingsSectionWithBackup — 数组操作应创建备份", () => {
+	it("addItem 应创建备份", () => {
+		writeTestSettings({ packages: [] });
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ addItem: { source: "git:github.com/catlain/pi-foo" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+		);
+
+		expect(result.backupPath).toBeDefined();
+		expect(existsSync(result.backupPath!)).toBe(true);
+	});
+
+	it("removeItem 应创建备份", () => {
+		writeTestSettings({ packages: [{ source: "git:github.com/catlain/pi-foo" }] });
+
+		const result = patchSettingsSectionWithBackup(
+			"packages",
+			{ removeItem: { source: "git:github.com/catlain/pi-foo" } },
+			[],
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+		);
+
+		expect(result.backupPath).toBeDefined();
+	});
+});
+
+// ── 对象 section 保持不变 ─────────────────────────────────
+
+describe("patchSettingsSectionWithBackup — 对象操作不受影响", () => {
+	it("对象 merge 仍然正常工作", () => {
+		writeTestSettings({ context: { distillThreshold: 5000 } });
+
+		const result = patchSettingsSectionWithBackup(
+			"context",
+			{ processorThreshold: 3000 },
+			{ distillThreshold: 8000, processorThreshold: 5000 },
+			{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+		);
+
+		expect(result.config).toEqual({ distillThreshold: 5000, processorThreshold: 3000 });
+	});
+});