pi-shepherd 0.1.0

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

@@ -0,0 +1,520 @@
+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";
+
+// 测试前先 mock paths 模块的 SETTINGS_PATH
+const TEST_DIR = join(tmpdir(), `pi-settings-backup-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 });
+}
+
+function countBackups(): number {
+	if (!existsSync(TEST_BACKUP_DIR)) return 0;
+	return readdirSync(TEST_BACKUP_DIR).filter((f) => f.endsWith(".json")).length;
+}
+
+// ── 测试 ─────────────────────────────────────────────────
+
+describe("settings-backup", () => {
+	beforeEach(() => {
+		cleanupTestDir();
+		mkdirSync(TEST_DIR, { recursive: true });
+	});
+	afterEach(() => {
+		cleanupTestDir();
+	});
+
+	// ── patchSettingsSectionWithBackup ──────────────────
+
+	describe("patchSettingsSectionWithBackup", () => {
+		it("修改后自动创建备份", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000, agingThreshold: 20 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(result.config.distillThreshold).toBe(8000);
+			expect(result.config.agingThreshold).toBe(20); // defaults 填充
+			expect(existsSync(TEST_BACKUP_DIR)).toBe(true);
+			expect(countBackups()).toBe(1);
+
+			// 备份内容应该是修改前的值
+			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.context.distillThreshold).toBe(5000);
+		});
+
+		it("多次修改产生多个备份", async () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 6000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 7000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(countBackups()).toBe(2);
+		});
+
+		it("超过 maxBackups 时清理旧备份", async () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			for (let i = 0; i < 5; i++) {
+				patchSettingsSectionWithBackup(
+					"context",
+					{ distillThreshold: 5000 + i },
+					{ distillThreshold: 5000 },
+					{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, maxBackups: 3 },
+				);
+				await new Promise((r) => setTimeout(r, 10));
+			}
+
+			expect(countBackups()).toBe(3);
+		});
+
+		it("类型校验不通过时返回错误但不写入", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: "wrong-type" as any },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: true },
+			);
+
+			expect(result.errors.length).toBeGreaterThan(0);
+			expect(result.errors[0].key).toBe("distillThreshold");
+			// settings.json 不应该被修改
+			expect(readTestSettings().context.distillThreshold).toBe(5000);
+		});
+
+		it("validate: false 跳过类型校验", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: "skip-validation" as any },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+			);
+
+			expect(result.errors).toEqual([]);
+			expect(readTestSettings().context.distillThreshold).toBe("skip-validation");
+		});
+
+		it("备份目录不存在时自动创建", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+			expect(existsSync(TEST_BACKUP_DIR)).toBe(false);
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(existsSync(TEST_BACKUP_DIR)).toBe(true);
+		});
+
+		it("备份文件名包含时间戳", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			const files = readdirSync(TEST_BACKUP_DIR).filter((f) => f.endsWith(".json"));
+			expect(files.length).toBe(1);
+			expect(files[0]).toMatch(/^settings\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}/);
+		});
+
+		// ── 边缘情况 ─────────────────────────────
+
+		it("settings.json 不存在时创建新文件", () => {
+			// 不写 settings.json，让它不存在
+			expect(existsSync(TEST_SETTINGS)).toBe(false);
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(result.config.distillThreshold).toBe(8000);
+			expect(existsSync(TEST_SETTINGS)).toBe(true);
+			expect(readTestSettings().context.distillThreshold).toBe(8000);
+			// 不存在时不创建备份（没有东西可备份）
+			expect(countBackups()).toBe(0);
+		});
+
+		it("settings.json 内容是非法 JSON 时当作空对象处理", () => {
+			mkdirSync(TEST_DIR, { recursive: true });
+			writeFileSync(TEST_SETTINGS, "{ broken json !!!");
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			// 不崩溃，当作空对象处理
+			expect(result.config.distillThreshold).toBe(8000);
+		});
+
+		it("section 不存在时新增 section", () => {
+			writeTestSettings({ other: { foo: 1 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(result.config.distillThreshold).toBe(8000);
+			const settings = readTestSettings();
+			expect(settings.context.distillThreshold).toBe(8000);
+			expect(settings.other.foo).toBe(1); // 其他 section 不受影响
+		});
+
+		it("patch 值为 undefined 时跳过该 key", () => {
+			writeTestSettings({ context: { distillThreshold: 5000, agingThreshold: 20 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: undefined },
+				{ distillThreshold: 5000, agingThreshold: 20 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			// undefined 不应该覆盖现有值
+			const settings = readTestSettings();
+			expect(settings.context.distillThreshold).toBe(5000);
+			expect(settings.context.agingThreshold).toBe(20);
+		});
+
+		it("patch 值为 null 时被类型校验拦截（null !== number）", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: null as any },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			// null 被校验拦截 — 类型不匹配（null vs number）
+			expect(result.errors.length).toBeGreaterThan(0);
+			expect(readTestSettings().context.distillThreshold).toBe(5000);
+		});
+
+		it("patch 值为 null 且 validate:false 时正常写入 null", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: null as any },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, validate: false },
+			);
+
+			expect(readTestSettings().context.distillThreshold).toBeNull();
+		});
+
+		it("backup: false 跳过备份创建", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+			);
+
+			expect(countBackups()).toBe(0);
+			expect(readTestSettings().context.distillThreshold).toBe(8000);
+		});
+
+		it("空 patch 不修改配置值但正常写入", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{},
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(result.config.distillThreshold).toBe(5000);
+			expect(readTestSettings().context.distillThreshold).toBe(5000);
+			// 空修改也会备份（安全起见）
+			expect(countBackups()).toBe(1);
+		});
+
+		it("defaults 中有嵌套对象时不深度校验", () => {
+			writeTestSettings({});
+
+			const result = patchSettingsSectionWithBackup(
+				"mcp",
+				{ disabled: ["server-a"] },
+				{ disabled: [] },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(result.errors).toEqual([]);
+			expect(result.config.disabled).toEqual(["server-a"]);
+		});
+
+		it("保留其他 section 不受影响", () => {
+			writeTestSettings({
+				other: { foo: 1 },
+				context: { distillThreshold: 5000 },
+			});
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			expect(readTestSettings().other.foo).toBe(1);
+		});
+	});
+
+	// ── rollbackSettings ──────────────────────────────
+
+	describe("rollbackSettings", () => {
+		it("恢复到最近一次备份", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			expect(readTestSettings().context.distillThreshold).toBe(8000);
+
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+			expect(readTestSettings().context.distillThreshold).toBe(5000);
+		});
+
+		it("无备份时抛错", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+			expect(() => rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR })).toThrow(
+				/无可用备份/,
+			);
+		});
+
+		it("回滚后删除已恢复的备份", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			expect(countBackups()).toBe(1);
+
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+			expect(countBackups()).toBe(0);
+		});
+
+		it("连续两次回滚（第二次无备份应抛错）", async () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 6000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 7000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			// 第一次回滚：7000 → 6000
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+			expect(readTestSettings().context.distillThreshold).toBe(6000);
+			expect(countBackups()).toBe(1);
+
+			// 第二次回滚：6000 → 5000
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+			expect(readTestSettings().context.distillThreshold).toBe(5000);
+			expect(countBackups()).toBe(0);
+
+			// 第三次回滚：无备份，抛错
+			expect(() => rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR })).toThrow();
+		});
+
+		it("回滚不影响备份目录外的文件", () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+			// 在备份目录外创建一个文件
+			const extraFile = join(TEST_DIR, "other-file.json");
+			writeFileSync(extraFile, '{"test": true}');
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 8000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			rollbackSettings({ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR });
+
+			expect(existsSync(extraFile)).toBe(true);
+			expect(JSON.parse(readFileSync(extraFile, "utf-8")).test).toBe(true);
+		});
+	});
+
+	// ── listBackups ──────────────────────────────────
+
+	describe("listBackups", () => {
+		it("返回备份列表（按时间倒序）", async () => {
+			writeTestSettings({ context: { distillThreshold: 5000 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 6000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+			await new Promise((r) => setTimeout(r, 10));
+			patchSettingsSectionWithBackup(
+				"context",
+				{ distillThreshold: 7000 },
+				{ distillThreshold: 5000 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR },
+			);
+
+			const backups = listBackups({ backupDir: TEST_BACKUP_DIR });
+			expect(backups.length).toBe(2);
+			// 最新的在前
+			expect(backups[0].timestamp > backups[1].timestamp).toBe(true);
+		});
+
+		it("无备份时返回空数组", () => {
+			const backups = listBackups({ backupDir: TEST_BACKUP_DIR });
+			expect(backups).toEqual([]);
+		});
+
+		it("备份目录不存在时返回空数组", () => {
+			const backups = listBackups({ backupDir: "/nonexistent/path" });
+			expect(backups).toEqual([]);
+		});
+	});
+
+	describe("文件锁", () => {
+		it("加锁期间其他操作不会被覆盖", () => {
+			cleanupTestDir();
+			writeTestSettings({ context: { threshold: 100 }, otherSection: { keep: true } });
+
+			// 模拟：在 patch 加锁期间，另一个进程写入了新字段
+			// 这里通过 patch 两次验证加锁读-写是原子的
+			const result1 = patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+				);
+			const result2 = patchSettingsSectionWithBackup(
+				"shepherd",
+				{ maxWarnings: 3 },
+				{ maxWarnings: 5 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+				);
+
+			// 两次 patch 都成功
+			expect(result1.config.threshold).toBe(200);
+			expect(result2.config.maxWarnings).toBe(3);
+
+			// 文件中两个 section 都保留
+			const finalSettings = readTestSettings();
+			expect(finalSettings.context.threshold).toBe(200);
+			expect(finalSettings.shepherd.maxWarnings).toBe(3);
+			expect(finalSettings.otherSection.keep).toBe(true);
+		});
+
+		it("锁文件在操作后会被清理", () => {
+			cleanupTestDir();
+			writeTestSettings({ context: { threshold: 100 } });
+
+			patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 200 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+				);
+
+			// 锁目录不应残留
+			expect(existsSync(`${TEST_SETTINGS}.lock`)).toBe(false);
+		});
+
+		it("过时锁会被自动清理", () => {
+			cleanupTestDir();
+			writeTestSettings({ context: { threshold: 100 } });
+
+			// 创建一个过时锁（mtime 设为 20 秒前）
+			const lockDir = `${TEST_SETTINGS}.lock`;
+			mkdirSync(lockDir);
+			// 手动修改 mtime 为 20 秒前
+			const { utimesSync } = require("node:fs");
+			const oldTime = (Date.now() - 20_000) / 1000;
+			utimesSync(lockDir, oldTime, oldTime);
+
+			// patch 应该能清理过时锁并正常执行
+			const result = patchSettingsSectionWithBackup(
+				"context",
+				{ threshold: 300 },
+				{ threshold: 100 },
+				{ settingsPath: TEST_SETTINGS, backupDir: TEST_BACKUP_DIR, backup: false },
+				);
+
+			expect(result.config.threshold).toBe(300);
+			expect(existsSync(lockDir)).toBe(false);
+		});
+	});
+});

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

@@ -0,0 +1,116 @@
+/**
+ * settings.ts 读取操作测试（getSettingsSection, getSettingsValue）
+ *
+ * 使用有状态的 fs mock：writeFileSync 更新存储区，readFileSync 读取最新内容。
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const store = vi.hoisted(() => {
+	let content = "";
+	return { get: () => content, set: (v: string) => { content = v; } };
+});
+
+const mockOs = vi.hoisted(() => ({
+	homedir: vi.fn().mockReturnValue("/fake-home"),
+}));
+vi.mock("node:os", () => mockOs);
+
+const mockFs = vi.hoisted(() => ({
+	existsSync: vi.fn(),
+	readFileSync: vi.fn(() => store.get()),
+	writeFileSync: vi.fn((_path: string, data: string) => store.set(data)),
+}));
+vi.mock("node:fs", () => mockFs);
+
+import { getSettingsSection, getSettingsValue } from "../settings";
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	store.set("");
+});
+
+function mockSettings(content: Record<string, unknown>): void {
+	store.set(JSON.stringify(content));
+	mockFs.existsSync.mockReturnValue(true);
+}
+
+// ── getSettingsSection ──────────────────────────────────
+
+describe("getSettingsSection", () => {
+	it("returns defaults when settings.json does not exist", () => {
+		mockFs.existsSync.mockReturnValue(false);
+		const result = getSettingsSection("context", { threshold: 5000, active: true });
+		expect(result).toEqual({ threshold: 5000, active: true });
+	});
+
+	it("returns defaults when settings.json is empty object", () => {
+		mockSettings({});
+		const result = getSettingsSection("context", { threshold: 5000 });
+		expect(result).toEqual({ threshold: 5000 });
+	});
+
+	it("merges stored values over defaults", () => {
+		mockSettings({ context: { threshold: 8000 } });
+		const result = getSettingsSection("context", { threshold: 5000, active: true });
+		expect(result).toEqual({ threshold: 8000, active: true });
+	});
+
+	it("ignores stored keys not in defaults", () => {
+		mockSettings({ context: { threshold: 8000, junk: "ignore" } });
+		const result = getSettingsSection("context", { threshold: 5000 });
+		expect(result).toEqual({ threshold: 8000 });
+	});
+
+	it("returns defaults when section exists but is empty", () => {
+		mockSettings({ context: {} });
+		const result = getSettingsSection("context", { threshold: 5000, active: true });
+		expect(result).toEqual({ threshold: 5000, active: true });
+	});
+
+	it("returns defaults when settings.json is invalid JSON", () => {
+		mockFs.existsSync.mockReturnValue(true);
+		store.set("{ invalid json ");
+		const result = getSettingsSection("context", { threshold: 5000 });
+		expect(result).toEqual({ threshold: 5000 });
+	});
+
+	it("handles section not present in settings", () => {
+		mockSettings({ otherSection: { key: 1 } });
+		const result = getSettingsSection("context", { threshold: 5000 });
+		expect(result).toEqual({ threshold: 5000 });
+	});
+});
+
+// ── getSettingsValue ────────────────────────────────────
+
+describe("getSettingsValue", () => {
+	it("returns value at simple path", () => {
+		mockSettings({ recording: { enabled: true } });
+		expect(getSettingsValue("recording.enabled", false)).toBe(true);
+	});
+
+	it("returns fallback when path does not exist", () => {
+		mockSettings({});
+		expect(getSettingsValue("recording.enabled", false)).toBe(false);
+	});
+
+	it("returns fallback when settings.json does not exist", () => {
+		mockFs.existsSync.mockReturnValue(false);
+		expect(getSettingsValue("some.key", "default")).toBe("default");
+	});
+
+	it("returns nested fallback for deep path", () => {
+		mockSettings({ a: { b: {} } });
+		expect(getSettingsValue("a.b.c.d", "fallback")).toBe("fallback");
+	});
+
+	it("returns null when value is null", () => {
+		mockSettings({ key: null });
+		expect(getSettingsValue("key", "fallback")).toBeNull();
+	});
+
+	it("returns fallback when intermediate key is null", () => {
+		mockSettings({ a: null });
+		expect(getSettingsValue("a.b", "fallback")).toBe("fallback");
+	});
+});