pi-shepherd 0.1.1 → 0.2.0

package/shepherd/rules-editor.ts

@@ -1,135 +1,250 @@
-/**
- * Shepherd 规则文件安全编辑器
- *
- * 提供 rules.json 的安全增删改查：
- * - 写入前校验（必填字段、正则合法性、枚举值）
- * - 自动备份（.bak）
- * - 写入后回读验证
- * - 失败自动回滚
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { validateRule } from "./rules-validate";
-export { validateRule } from "./rules-validate";
-export type { ValidationResult } from "./rules-validate";
-
-// ── 类型 ──────────────────────────────────────────────────
-
-export interface RuleSummary {
-	index: number;
-	comment: string;
-	action?: string;
-	tool?: string;
-	hook?: string;
-	enabled?: boolean;
-	pattern?: string;
-}
-
-export interface ListResult {
-	rules: RuleSummary[];
-	count: number;
-	error?: string;
-}
-
-export interface WriteResult {
-	success: boolean;
-	error?: string;
-	index?: number;
-	deleted?: { comment: string; [key: string]: unknown };
-}
-
-// ── 文件操作辅助 ──────────────────────────────────────────
-
-interface FileData {
-	rules: Record<string, unknown>[];
-	error?: string;
-}
-
-function readFile(filePath: string): FileData {
-	if (!fs.existsSync(filePath)) return { rules: [] };
-	try {
-		const raw = fs.readFileSync(filePath, "utf-8");
-		const parsed = JSON.parse(raw);
-		if (!Array.isArray(parsed)) {
-			return { rules: [], error: `顶层必须是 JSON 数组，当前是 ${typeof parsed}` };
-		}
-		return { rules: parsed };
-	} catch (e: unknown) {
-		return { rules: [], error: `JSON 解析失败: ${e.message}` };
-	}
-}
-
-function safeWrite(filePath: string, rules: Record<string, unknown>[]): WriteResult {
-	const backupPath = `${filePath}.bak`;
-	if (fs.existsSync(filePath)) fs.copyFileSync(filePath, backupPath);
-	const dir = path.dirname(filePath);
-	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-	fs.writeFileSync(filePath, JSON.stringify(rules, null, "\t"), "utf-8");
-	try {
-		const raw = fs.readFileSync(filePath, "utf-8");
-		const parsed = JSON.parse(raw);
-		if (!Array.isArray(parsed)) throw new Error("not array");
-		return { success: true };
-	} catch {
-		if (fs.existsSync(backupPath)) fs.copyFileSync(backupPath, filePath);
-		return { success: false, error: "写入后验证失败，已从备份恢复" };
-	}
-}
-
-// ── 公开 API ─────────────────────────────────────────────
-
-export function listRules(filePath: string): ListResult {
-	const { rules, error } = readFile(filePath);
-	if (error) return { rules: [], count: 0, error };
-	return {
-		rules: rules.map((r, i) => ({
-			index: i,
-			comment: (r.comment as string) || "",
-			action: r.action as string | undefined,
-			tool: r.tool as string | undefined,
-			hook: r.hook as string | undefined,
-			enabled: r.enabled as boolean | undefined,
-			pattern: r.pattern as string | undefined,
-		})),
-		count: rules.length,
-	};
-}
-
-export function addRule(filePath: string, rule: Record<string, unknown>): WriteResult {
-	const { rules, error } = readFile(filePath);
-	if (error) return { success: false, error };
-	const validation = validateRule(rule);
-	if (!validation.valid) return { success: false, error: validation.errors.join("; ") };
-	rules.push(rule);
-	const writeResult = safeWrite(filePath, rules);
-	return writeResult.success ? { success: true, index: rules.length - 1 } : writeResult;
-}
-
-export function updateRule(
-	filePath: string,
-	index: number,
-	changes: Record<string, unknown>,
-): WriteResult {
-	if (index < 0) return { success: false, error: `编号越界: ${index}` };
-	const { rules, error } = readFile(filePath);
-	if (error) return { success: false, error };
-	if (index >= rules.length) return { success: false, error: `编号越界: ${index}（共 ${rules.length} 条）` };
-	const merged = { ...rules[index], ...changes };
-	const validation = validateRule(merged);
-	if (!validation.valid) return { success: false, error: validation.errors.join("; ") };
-	rules[index] = merged;
-	return safeWrite(filePath, rules);
-}
-
-export function deleteRule(filePath: string, index: number): WriteResult {
-	if (index < 0) return { success: false, error: `编号越界: ${index}` };
-	const { rules, error } = readFile(filePath);
-	if (error) return { success: false, error };
-	if (index >= rules.length) return { success: false, error: `编号越界: ${index}（共 ${rules.length} 条）` };
-	const deleted = rules.splice(index, 1)[0];
-	const writeResult = safeWrite(filePath, rules);
-	return writeResult.success
-		? { success: true, deleted: { comment: (deleted.comment as string) || "", ...deleted } }
-		: writeResult;
-}
+/**
+ * Shepherd 规则文件安全编辑器
+ *
+ * 提供 rules.json 的安全增删改查：
+ * - 写入前校验（必填字段、正则合法性、枚举值）
+ * - 自动备份（.bak）
+ * - 写入后回读验证
+ * - 失败自动回滚
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { validateRule } from "./rules-validate";
+
+export type { ValidationResult } from "./rules-validate";
+export { validateRule } from "./rules-validate";
+
+// ── 类型 ──────────────────────────────────────────────────
+
+export interface RuleSummary {
+	index: number;
+	comment: string;
+	action?: string;
+	tool?: string;
+	hook?: string;
+	enabled?: boolean;
+	pattern?: string;
+}
+
+export interface ListResult {
+	rules: RuleSummary[];
+	count: number;
+	error?: string;
+}
+
+export interface RuleDetail {
+	index: number;
+	[key: string]: unknown;
+}
+
+export interface ListDetailResult {
+	rules: RuleDetail[];
+	count: number;
+	error?: string;
+}
+
+export interface WriteResult {
+	success: boolean;
+	error?: string;
+	index?: number;
+	deleted?: { comment: string; [key: string]: unknown };
+	overwritten?: boolean;
+	warning?: string;
+}
+
+// ── 文件操作辅助 ──────────────────────────────────────────
+
+interface FileData {
+	rules: Record<string, unknown>[];
+	error?: string;
+}
+
+function readFile(filePath: string): FileData {
+	if (!fs.existsSync(filePath)) return { rules: [] };
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) {
+			return {
+				rules: [],
+				error: `顶层必须是 JSON 数组，当前是 ${typeof parsed}`,
+			};
+		}
+		return { rules: parsed };
+	} catch (e: unknown) {
+		const msg = e instanceof Error ? e.message : String(e);
+		return { rules: [], error: `JSON 解析失败: ${msg}` };
+	}
+}
+
+function safeWrite(
+	filePath: string,
+	rules: Record<string, unknown>[],
+): WriteResult {
+	const backupPath = `${filePath}.bak`;
+	if (fs.existsSync(filePath)) fs.copyFileSync(filePath, backupPath);
+	const dir = path.dirname(filePath);
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(filePath, JSON.stringify(rules, null, "\t"), "utf-8");
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) throw new Error("not array");
+		return { success: true };
+	} catch {
+		if (fs.existsSync(backupPath)) fs.copyFileSync(backupPath, filePath);
+		return { success: false, error: "写入后验证失败，已从备份恢复" };
+	}
+}
+
+// ── 去重签名 ─────────────────────────────────────────────
+
+/** 规范化 conditions 数组：按 field+pattern 排序，取关键属性 */
+function normalizeConditions(
+	conditions: Array<Record<string, unknown>>,
+): string {
+	const normalized = conditions
+		.map((c) => ({
+			f: (c.field as string) || "",
+			p: (c.pattern as string) || "",
+		}))
+		.sort((a, b) => (a.f + a.p).localeCompare(b.f + b.p));
+	return JSON.stringify(normalized);
+}
+
+/** 生成规则去重签名 key */
+export function dedupKey(rule: Record<string, unknown>): string {
+	const tool = (rule.tool as string) || "";
+	const hook = (rule.hook as string) || "";
+	const action = (rule.action as string) || "";
+	let trigger: string;
+	if (Array.isArray(rule.conditions) && rule.conditions.length > 0) {
+		trigger = normalizeConditions(
+			rule.conditions as Array<Record<string, unknown>>,
+		);
+	} else if (rule.pattern) {
+		trigger = rule.pattern as string;
+	} else if (rule.check) {
+		trigger = rule.check as string;
+	} else {
+		trigger = "";
+	}
+	return `${tool}|${hook}|${trigger}|${action}`;
+}
+
+/** 在规则数组中查找签名相同的规则，返回 index 或 null */
+export function findDuplicateBySignature(
+	rules: Record<string, unknown>[],
+	newRule: Record<string, unknown>,
+): number | null {
+	const newKey = dedupKey(newRule);
+	for (let i = 0; i < rules.length; i++) {
+		if (dedupKey(rules[i]) === newKey) return i;
+	}
+	return null;
+}
+
+// ── 公开 API ─────────────────────────────────────────────
+
+export function listRules(filePath: string): ListResult {
+	const { rules, error } = readFile(filePath);
+	if (error) return { rules: [], count: 0, error };
+	return {
+		rules: rules.map((r, i) => ({
+			index: i,
+			comment: (r.comment as string) || "",
+			action: r.action as string | undefined,
+			tool: r.tool as string | undefined,
+			hook: r.hook as string | undefined,
+			enabled: r.enabled as boolean | undefined,
+			pattern: r.pattern as string | undefined,
+		})),
+		count: rules.length,
+	};
+}
+
+export function listRulesDetail(filePath: string): ListDetailResult {
+	const { rules, error } = readFile(filePath);
+	if (error) return { rules: [], count: 0, error };
+	return {
+		rules: rules.map((r, i) => ({ index: i, ...r })),
+		count: rules.length,
+	};
+}
+
+export function getRuleDetail(
+	filePath: string,
+	index: number,
+): RuleDetail | { error: string } {
+	const { rules, error } = readFile(filePath);
+	if (error) return { error };
+	if (index < 0 || index >= rules.length)
+		return { error: `编号越界: ${index}（共 ${rules.length} 条）` };
+	return { index, ...rules[index] };
+}
+
+export function addRule(
+	filePath: string,
+	rule: Record<string, unknown>,
+): WriteResult {
+	const { rules, error } = readFile(filePath);
+	if (error) return { success: false, error };
+	const validation = validateRule(rule);
+	if (!validation.valid)
+		return { success: false, error: validation.errors.join("; ") };
+	// 去重检测：签名相同则覆盖
+	const dupIdx = findDuplicateBySignature(rules, rule);
+	if (dupIdx !== null) {
+		rules[dupIdx] = rule;
+		const writeResult = safeWrite(filePath, rules);
+		return writeResult.success
+			? { success: true, index: dupIdx, overwritten: true }
+			: writeResult;
+	}
+	rules.push(rule);
+	const writeResult = safeWrite(filePath, rules);
+	return writeResult.success
+		? { success: true, index: rules.length - 1 }
+		: writeResult;
+}
+
+export function updateRule(
+	filePath: string,
+	index: number,
+	changes: Record<string, unknown>,
+): WriteResult {
+	if (index < 0) return { success: false, error: `编号越界: ${index}` };
+	const { rules, error } = readFile(filePath);
+	if (error) return { success: false, error };
+	if (index >= rules.length)
+		return {
+			success: false,
+			error: `编号越界: ${index}（共 ${rules.length} 条）`,
+		};
+	const merged = { ...rules[index], ...changes };
+	const validation = validateRule(merged);
+	if (!validation.valid)
+		return { success: false, error: validation.errors.join("; ") };
+	rules[index] = merged;
+	return safeWrite(filePath, rules);
+}
+
+export function deleteRule(filePath: string, index: number): WriteResult {
+	if (index < 0) return { success: false, error: `编号越界: ${index}` };
+	const { rules, error } = readFile(filePath);
+	if (error) return { success: false, error };
+	if (index >= rules.length)
+		return {
+			success: false,
+			error: `编号越界: ${index}（共 ${rules.length} 条）`,
+		};
+	const deleted = rules.splice(index, 1)[0];
+	const writeResult = safeWrite(filePath, rules);
+	return writeResult.success
+		? {
+				success: true,
+				deleted: { comment: (deleted.comment as string) || "", ...deleted },
+			}
+		: writeResult;
+}

package/shepherd/rules-tool-helpers.ts

@@ -0,0 +1,119 @@
+/**
+ * Shepherd 规则工具辅助函数
+ *
+ * scope 路径推导、合并列表、跨 scope 去重检测。
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findDuplicateBySignature, listRules } from "./rules-editor";
+
+/** 项目级规则文件名 */
+const PROJECT_RULES_FILE = "shepherd-rules.json";
+
+export type Scope = "global" | "project";
+
+/** 根据 scope 推导规则文件路径 */
+export function getRulesFilePath(
+	scope: Scope | undefined,
+	globalDir: string,
+	cwd: string,
+): string {
+	if (scope === "project") {
+		return path.join(cwd, ".pi", "extensions", PROJECT_RULES_FILE);
+	}
+	// 默认 global
+	return path.join(globalDir, "rules.json");
+}
+
+export interface ListRuleItem {
+	index: number;
+	comment: string;
+	scope: Scope;
+	enabled?: boolean;
+	action?: string;
+	tool?: string;
+	hook?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * 按_scope 列出规则。scope 不传时返回全局+项目合并列表。
+ */
+export function listRulesByScope(
+	globalDir: string,
+	cwd: string,
+	scope?: Scope,
+): ListRuleItem[] {
+	const results: ListRuleItem[] = [];
+
+	if (!scope || scope === "global") {
+		const globalPath = path.join(globalDir, "rules.json");
+		if (fs.existsSync(globalPath)) {
+			const r = listRules(globalPath);
+			if (!r.error && r.rules) {
+				for (const rule of r.rules) {
+					results.push({ ...rule, scope: "global" });
+				}
+			}
+		}
+	}
+
+	if (!scope || scope === "project") {
+		const projectPath = path.join(cwd, ".pi", "extensions", PROJECT_RULES_FILE);
+		if (fs.existsSync(projectPath)) {
+			const r = listRules(projectPath);
+			if (!r.error && r.rules) {
+				for (const rule of r.rules) {
+					results.push({ ...rule, scope: "project" });
+				}
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * 跨 scope 去重检测：写入 A scope 时检查 B scope 是否有签名相同的规则。
+ * 返回 warning 字符串或 null。
+ */
+export function checkCrossScopeDuplicate(
+	targetScope: Scope,
+	globalDir: string,
+	cwd: string,
+	newRule: Record<string, unknown>,
+): string | null {
+	const otherScope: Scope = targetScope === "global" ? "project" : "global";
+	const otherPath = getRulesFilePath(otherScope, globalDir, cwd);
+
+	if (!fs.existsSync(otherPath)) return null;
+
+	const content = fs.readFileSync(otherPath, "utf-8");
+	let rules: Record<string, unknown>[];
+	try {
+		const parsed = JSON.parse(content);
+		if (!Array.isArray(parsed)) return null;
+		rules = parsed;
+	} catch {
+		return null;
+	}
+
+	const dupIdx = findDuplicateBySignature(rules, newRule);
+	if (dupIdx !== null) {
+		const scopeLabel = otherScope === "global" ? "全局" : "项目级";
+		return `⚠ ${scopeLabel}已有相似规则 [${otherScope}:${dupIdx}]`;
+	}
+
+	return null;
+}
+
+/**
+ * 确保项目级规则文件的目录存在
+ */
+export function ensureProjectDir(cwd: string): void {
+	const dir = path.join(cwd, ".pi", "extensions");
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+}

package/shepherd/rules-tool-list.ts

@@ -0,0 +1,124 @@
+/**
+ * Shepherd 规则工具 — list 输出格式化
+ *
+ * 处理 list 的两种输出模式：摘要模式和 verbose（完整 JSON）模式。
+ */
+
+import { getRuleDetail, listRules, listRulesDetail } from "./rules-editor";
+import {
+	getRulesFilePath,
+	listRulesByScope,
+	type Scope,
+} from "./rules-tool-helpers";
+
+/** 构造 pi 工具 execute 的标准返回格式 */
+export function textResult(text: string) {
+	return { content: [{ type: "text" as const, text }] };
+}
+
+export const scopeLabel = (s: Scope) => (s === "global" ? "全局" : "项目级");
+
+/** 按编号查看单条规则的完整 JSON */
+export function handleListByIndex(
+	scope: Scope | undefined,
+	index: number,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	const effectiveScope = scope || "global";
+	const filePath = getRulesFilePath(effectiveScope, rulesDir, effectiveCwd);
+	const detail = getRuleDetail(filePath, index);
+	if ("error" in detail) return textResult(`❌ ${detail.error}`);
+	const { index: _, ...ruleData } = detail;
+	return textResult(
+		`📋 规则 [${effectiveScope}:${index}] 完整内容:\n${JSON.stringify(ruleData, null, "\t")}`,
+	);
+}
+
+/** verbose 模式：显示每条规则的完整 JSON */
+export function handleListVerbose(
+	scope: Scope | undefined,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	if (!scope) {
+		// 全部 scope
+		const parts: string[] = [];
+		const globalPath = getRulesFilePath("global", rulesDir, effectiveCwd);
+		const projectPath = getRulesFilePath("project", rulesDir, effectiveCwd);
+
+		const gResult = listRulesDetail(globalPath);
+		if (gResult.rules.length > 0) {
+			parts.push("── 全局规则 ──");
+			for (const r of gResult.rules) {
+				const { index: _, ...data } = r;
+				parts.push(`[global:${r.index}] ${JSON.stringify(data, null, "\t")}`);
+			}
+		}
+		const pResult = listRulesDetail(projectPath);
+		if (pResult.rules.length > 0) {
+			parts.push("── 项目级规则 ──");
+			for (const r of pResult.rules) {
+				const { index: _, ...data } = r;
+				parts.push(`[project:${r.index}] ${JSON.stringify(data, null, "\t")}`);
+			}
+		}
+		if (parts.length === 0)
+			return textResult("暂无规则（全局和项目级均为空）。");
+		return textResult(parts.join("\n\n"));
+	}
+	// 指定 scope
+	const filePath = getRulesFilePath(scope, rulesDir, effectiveCwd);
+	const result = listRulesDetail(filePath);
+	if (result.error) return textResult(`❌ ${result.error}`);
+	if (result.count === 0) return textResult(`暂无${scopeLabel(scope)}规则。`);
+	return textResult(
+		result.rules
+			.map((r) => {
+				const { index: _, ...data } = r;
+				return `[${scope}:${r.index}] ${JSON.stringify(data, null, "\t")}`;
+			})
+			.join("\n\n"),
+	);
+}
+
+/** 摘要模式：一行一条，只显示 comment + action + tool + hook */
+export function handleListSummary(
+	scope: Scope | undefined,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	if (!scope) {
+		const items = listRulesByScope(rulesDir, effectiveCwd);
+		if (items.length === 0)
+			return textResult("暂无规则（全局和项目级均为空）。");
+		return textResult(
+			items
+				.map(
+					(r) =>
+						`[${r.scope}:${r.index}] ${r.comment}` +
+						(r.enabled === false ? " (disabled)" : "") +
+						(r.action ? ` — ${r.action}` : "") +
+						(r.tool ? ` on ${r.tool}` : "") +
+						(r.hook ? ` @ ${r.hook}` : ""),
+				)
+				.join("\n"),
+		);
+	}
+	const filePath = getRulesFilePath(scope, rulesDir, effectiveCwd);
+	const result = listRules(filePath);
+	if (result.error) return textResult(`❌ ${result.error}`);
+	if (result.count === 0) return textResult(`暂无${scopeLabel(scope)}规则。`);
+	return textResult(
+		result.rules
+			.map(
+				(r) =>
+					`[${scope}:${r.index}] ${r.comment}` +
+					(r.enabled === false ? " (disabled)" : "") +
+					(r.action ? ` — ${r.action}` : "") +
+					(r.tool ? ` on ${r.tool}` : "") +
+					(r.hook ? ` @ ${r.hook}` : ""),
+			)
+			.join("\n"),
+	);
+}