agent-purge 0.2.10 → 0.2.12

package/lib/persona-import.mjs

@@ -0,0 +1,351 @@
+// 从外部来源（GitHub 仓库或本地目录）拉取/导入人设并存入本地人设库
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { createStore, isReservedId } from "./personas.mjs";
+
+const IGNORED_NAMES = new Set([
+	"readme.md",
+	"readme_zh.md",
+	"readme.zh.md",
+	"readme.zh-cn.md",
+	"license.md",
+	"licence.md",
+	"changelog.md",
+	"contributing.md",
+	"security.md",
+	"active.md",
+]);
+
+/** 解析源字符串：判断是本地目录还是 GitHub 仓库 */
+export function parseSource(source) {
+	const raw = String(source ?? "").trim();
+	if (!raw) throw new Error("导入源不能为空");
+
+	// 1. 本地目录判断：绝对路径、相对路径前缀、或本地已存在该目录
+	if (
+		raw.startsWith("file://") ||
+		raw.startsWith(".") ||
+		raw.startsWith("/") ||
+		/^[A-Za-z]:[\\/]/.test(raw) ||
+		existsSync(raw)
+	) {
+		let cleanPath = raw;
+		if (raw.startsWith("file://")) {
+			try {
+				cleanPath = new URL(raw).pathname;
+			} catch {
+				cleanPath = raw.slice(7);
+			}
+		}
+		const localDir = resolve(process.cwd(), cleanPath);
+		if (!existsSync(localDir) || !statSync(localDir).isDirectory()) {
+			throw new Error(`本地目录不存在: ${localDir}`);
+		}
+		return { kind: "local", path: localDir };
+	}
+
+	// 2. GitHub URL 或 owner/repo 格式
+	let owner = "";
+	let repo = "";
+	let ref = "main";
+	let subpath = "";
+
+	if (raw.startsWith("http://") || raw.startsWith("https://")) {
+		try {
+			const u = new URL(raw);
+			if (!u.hostname.includes("github.com")) {
+				throw new Error("目前外部拉取仅支持 GitHub 仓库或本地目录");
+			}
+			const parts = u.pathname.replace(/^\/+|\/+$/g, "").split("/");
+			if (parts.length < 2) throw new Error("无效的 GitHub 仓库 URL");
+			owner = parts[0];
+			repo = parts[1].replace(/\.git$/i, "");
+			if (parts[2] === "tree" && parts[3]) {
+				ref = parts[3];
+				subpath = parts.slice(4).join("/");
+			}
+		} catch (e) {
+			throw new Error(`无法解析 GitHub URL: ${e.message}`);
+		}
+	} else {
+		// 可能是 "owner/repo" 或 "owner/repo@ref" 或 "owner/repo/subpath"
+		const clean = raw.replace(/\.git$/i, "");
+		const [repoPart, refPart] = clean.split("@");
+		if (refPart) ref = refPart;
+
+		const parts = repoPart.split("/");
+		if (parts.length >= 2) {
+			owner = parts[0];
+			repo = parts[1];
+			if (parts.length > 2) subpath = parts.slice(2).join("/");
+		} else {
+			throw new Error(`无法识别导入源: ${raw}（请指定 owner/repo 或本地目录路径）`);
+		}
+	}
+
+	return { kind: "github", owner, repo, ref, subpath };
+}
+
+/** 规范化从文件名或 frontmatter 得出的 persona id */
+export function sanitizeId(rawId, fallbackName = "persona") {
+	let s = String(rawId || "").trim().toLowerCase();
+	// 移除非法字符，替换为空格或连字符
+	s = s.replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!s || isReservedId(s)) {
+		let fb = String(fallbackName || "persona").trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+		s = fb && !isReservedId(fb) ? fb : `p-${Date.now().toString(36)}`;
+	}
+	return s.slice(0, 64);
+}
+
+/** 解析 markdown 中的 frontmatter 与提示词正文 */
+export function parsePersonaDoc(raw, fallbackId = "") {
+	let meta = {};
+	let body = raw;
+
+	if (raw.startsWith("---")) {
+		const end = raw.indexOf("\n---", 3);
+		if (end !== -1) {
+			const head = raw.slice(3, end).trim();
+			body = raw.slice(end + 4).replace(/^\r?\n/, "");
+			meta = parseFrontmatter(head);
+		}
+	}
+
+	const id = sanitizeId(meta.id || fallbackId, fallbackId);
+	const name = meta.name || meta.title || fallbackId || id;
+	const description = meta.description || meta.desc || "";
+	const harness = Array.isArray(meta.harness) ? meta.harness : ["*"];
+	const model = Array.isArray(meta.model) ? meta.model : ["*"];
+	const order = typeof meta.order === "number" ? meta.order : 50;
+
+	return {
+		id,
+		meta: {
+			...meta,
+			id,
+			name,
+			description,
+			harness,
+			model,
+			order,
+		},
+		body: body.trim(),
+	};
+}
+
+function parseFrontmatter(head) {
+	const meta = {};
+	let key = null;
+	for (const line of head.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		const arr = line.match(/^\s*-\s+(.*)$/);
+		if (arr && key) {
+			if (!Array.isArray(meta[key])) meta[key] = [];
+			meta[key].push(unquote(arr[1]));
+			continue;
+		}
+		const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+		if (!kv) continue;
+		key = kv[1];
+		const v = kv[2].trim();
+		if (!v) {
+			meta[key] = [];
+			continue;
+		}
+		if (v.startsWith("[")) {
+			meta[key] = v
+				.replace(/^\[|\]$/g, "")
+				.split(",")
+				.map((s) => unquote(s.trim()))
+				.filter(Boolean);
+		} else {
+			meta[key] = coerce(v);
+		}
+	}
+	return meta;
+}
+
+const unquote = (s) => s.replace(/^["']|["']$/g, "");
+const coerce = (v) => {
+	if (v === "true") return true;
+	if (v === "false") return false;
+	const n = Number(v);
+	return Number.isFinite(n) && !Number.isNaN(n) && String(n) === v ? n : unquote(v);
+};
+
+/** 从本地目录导入人设 */
+export function importFromDirectory(dirPath, root, { overwrite = true } = {}) {
+	const resolvedDir = resolve(dirPath);
+	if (!existsSync(resolvedDir)) throw new Error(`目录不存在: ${resolvedDir}`);
+
+	const entries = readdirSync(resolvedDir, { withFileTypes: true });
+	const store = createStore(root);
+	const imported = [];
+	const skipped = [];
+	const errors = [];
+
+	for (const entry of entries) {
+		if (entry.isDirectory()) continue;
+		const name = entry.name;
+		const lower = name.toLowerCase();
+		if (!lower.endsWith(".md") && !lower.endsWith(".markdown")) continue;
+		if (IGNORED_NAMES.has(lower) || lower.startsWith(".")) {
+			skipped.push({ file: name, reason: "忽略的文件名（文档或隐藏文件）" });
+			continue;
+		}
+
+		try {
+			const filePath = join(resolvedDir, name);
+			const raw = readFileSync(filePath, "utf8");
+			const fallbackId = basename(name, extname(name));
+			const parsed = parsePersonaDoc(raw, fallbackId);
+
+			if (!parsed.body) {
+				skipped.push({ file: name, reason: "提示词正文为空" });
+				continue;
+			}
+
+			const existing = store.read(parsed.id);
+			if (existing && !overwrite) {
+				skipped.push({ id: parsed.id, name: parsed.meta.name, file: name, reason: "已存在且未开启覆盖" });
+				continue;
+			}
+
+			const saved = store.save(parsed.id, { meta: parsed.meta, body: parsed.body });
+			imported.push({
+				id: saved.id,
+				name: saved.meta.name,
+				chars: saved.body.length,
+				action: existing ? "updated" : "created",
+			});
+		} catch (e) {
+			errors.push({ file: name, error: e.message });
+		}
+	}
+
+	return {
+		success: errors.length === 0,
+		source: { kind: "local", path: resolvedDir },
+		imported,
+		skipped,
+		errors,
+		total: imported.length,
+	};
+}
+
+/** 从 GitHub 仓库拉取人设 */
+export async function pullFromGitHub(
+	{ owner, repo, ref = "main", subpath = "" },
+	root,
+	{ overwrite = true, token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN } = {}
+) {
+	const store = createStore(root);
+	const headers = {
+		"User-Agent": "agent-purge-client",
+		Accept: "application/vnd.github.v3+json",
+	};
+	if (token) headers.Authorization = `Bearer ${token}`;
+
+	const apiPath = subpath ? `contents/${encodeURIComponent(subpath).replace(/%2F/g, "/")}` : "contents";
+	const url = `https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${apiPath}?ref=${encodeURIComponent(ref)}`;
+
+	let res;
+	try {
+		res = await fetch(url, { headers });
+	} catch (e) {
+		throw new Error(`连接 GitHub 失败: ${e.message}`);
+	}
+
+	if (!res.ok) {
+		const text = await res.text();
+		throw new Error(`GitHub API 响应 ${res.status}: ${text.slice(0, 200)}`);
+	}
+
+	const list = await res.json();
+	if (!Array.isArray(list)) {
+		throw new Error("GitHub 仓库指定路径不是文件列表");
+	}
+
+	const imported = [];
+	const skipped = [];
+	const errors = [];
+
+	for (const item of list) {
+		if (item.type !== "file") continue;
+		const name = item.name;
+		const lower = name.toLowerCase();
+		if (!lower.endsWith(".md") && !lower.endsWith(".markdown")) continue;
+		if (IGNORED_NAMES.has(lower) || lower.startsWith(".")) {
+			skipped.push({ file: name, reason: "忽略的文件名（文档或隐藏文件）" });
+			continue;
+		}
+
+		try {
+			let content = "";
+			// 优先使用 download_url（raw），失败时回退到 git_url 获取 base64 blob
+			if (item.download_url) {
+				try {
+					const r = await fetch(item.download_url, { headers: { "User-Agent": "agent-purge-client" } });
+					if (r.ok) content = await r.text();
+				} catch {
+					// 忽略 raw 失败，走 blob 降级
+				}
+			}
+
+			if (!content && item.git_url) {
+				const blobRes = await fetch(item.git_url, { headers });
+				if (blobRes.ok) {
+					const blobData = await blobRes.json();
+					if (blobData.content && blobData.encoding === "base64") {
+						content = Buffer.from(blobData.content, "base64").toString("utf8");
+					}
+				}
+			}
+
+			if (!content) throw new Error("无法读取文件内容");
+
+			const fallbackId = basename(name, extname(name));
+			const parsed = parsePersonaDoc(content, fallbackId);
+
+			if (!parsed.body) {
+				skipped.push({ file: name, reason: "提示词正文为空" });
+				continue;
+			}
+
+			const existing = store.read(parsed.id);
+			if (existing && !overwrite) {
+				skipped.push({ id: parsed.id, name: parsed.meta.name, file: name, reason: "已存在且未开启覆盖" });
+				continue;
+			}
+
+			const saved = store.save(parsed.id, { meta: parsed.meta, body: parsed.body });
+			imported.push({
+				id: saved.id,
+				name: saved.meta.name,
+				chars: saved.body.length,
+				action: existing ? "updated" : "created",
+			});
+		} catch (e) {
+			errors.push({ file: name, error: e.message });
+		}
+	}
+
+	return {
+		success: errors.length === 0,
+		source: { kind: "github", owner, repo, ref, subpath },
+		imported,
+		skipped,
+		errors,
+		total: imported.length,
+	};
+}
+
+/** 统一入口：根据来源自动分流导入 */
+export async function importPersonas(sourceStr, root, options = {}) {
+	const parsed = parseSource(sourceStr);
+	if (parsed.kind === "local") {
+		return importFromDirectory(parsed.path, root, options);
+	}
+	return pullFromGitHub(parsed, root, options);
+}

package/lib/personas.mjs

@@ -1,9 +1,11 @@
 // persona 管理：一个 markdown 文件 = 元数据(frontmatter) + 系统提示词正文。
 // 正文是唯一喂给 harness 的东西；元数据只用来做选择。
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join } from "node:path";
 import { loadState, saveState } from "./state.mjs";
+import { listResources, readResource } from "./root.mjs";
+
+const TEMPLATES = "lib/templates/personas/";
 
 const WILD = "*";
 // active.md 是派生物，不是状态：install 指向它、opencode 插件运行时读它 → 真热切。
@@ -19,9 +21,12 @@ export function createStore(root) {
 	// 首次运行（或 npm 安装后的空目录）：从 lib/templates/personas 拷一份中性的起步 persona。
 	{
 		const has = existsSync(dir) && readdirSync(dir).some((f) => f.endsWith(".md") && f !== "active.md");
-		const tpl = join(dirname(fileURLToPath(import.meta.url)), "templates", "personas");
-		if (!has && existsSync(tpl)) {
-			for (const f of readdirSync(tpl)) writeFileSync(join(dir, f), readFileSync(join(tpl, f), "utf8"));
+		if (!has) {
+			try {
+				for (const f of listResources(TEMPLATES)) writeFileSync(join(dir, f), readResource(TEMPLATES + f));
+			} catch {
+				// 模板目录不在（裁剪过/自定义安装）就跳过，不挡人用
+			}
 		}
 	}
 
@@ -54,15 +59,20 @@ export function createStore(root) {
 
 	function remove(id) {
 		if (!isValidId(id)) return false;
+		const wasActive = activeId() === id;
 		rmSync(join(dir, `${id}.md`), { force: true });
 		rmSync(join(build, `${id}.md`), { force: true });
 		// 删的就是 active 时必须改道：否则下次无参启动直接 “没有 persona”。
 		// 落点不抓 list()[0]（那是顺序序，等于静默换人），优先落到 neutral。
-		if (activeId() === id) {
+		if (wasActive) {
 			const all = list();
 			const next = all.find((p) => p.id === "neutral") ?? all[0] ?? null;
 			if (next) setActive(next.id);
-			else writeFileSync(join(dir, ACTIVE_BODY), "You are a helpful coding assistant.\n");
+			else {
+				const { state } = loadState(root);
+				saveState(root, { ...state, persona: null });
+				writeFileSync(join(dir, ACTIVE_BODY), "");
+			}
 		}
 		return true;
 	}

package/lib/private-server.mjs

@@ -0,0 +1,54 @@
+// OpenCode v2 的 prompt 在独立 server 进程执行：父进程直接持有该 PID，不把许可交给 CLI/后代。
+import { randomBytes } from "node:crypto";
+import { prepareCommand, spawnPrepared } from "./spawn.mjs";
+
+export function privateClientArgs(args, url) {
+	if (args.some(value => value === "--server" || value.startsWith("--server="))) throw new Error("本次启动使用独立服务，请移除 --server");
+	return ["--server", url, ...args.filter(value => value !== "--standalone")];
+}
+export async function startPrivateServer(command, { env, cwd, lease, timeout = 20000 }) {
+	const password = randomBytes(32).toString("base64url");
+	// 客户端和服务端使用同一次随机认证；不读取用户已有的服务器密码。
+	env.OPENCODE_PASSWORD = password;
+	delete env.OPENCODE_SERVER_PASSWORD;
+	const descriptor = prepareCommand(command, ["serve", "--stdio", "--hostname", "127.0.0.1", "--port", "0"], { env, cwd, stdio: ["pipe", "pipe", "pipe"] });
+	if (!descriptor.hostDirect) throw new Error("独立服务需要可核验的原生入口");
+	const startedAt = Date.now(), child = spawnPrepared(descriptor);
+	child.on("error", () => {});
+	child.stdin.on("error", () => {});
+	let closed = false, errors = "";
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		child.stdin.end();
+		if (child.exitCode === null) child.kill();
+	};
+	const exited = new Promise(resolve => child.once("close", code => resolve(code)));
+	child.stderr.on("data", chunk => { errors = (errors + chunk.toString()).slice(-2000); });
+	try {
+		if (child.pid) lease?.publish(child.pid, startedAt);
+		const url = await new Promise((resolve, reject) => {
+			let pending = "", settled = false;
+			const finish = (error, value) => { if (settled) return; settled = true; clearTimeout(timer); if (error) reject(error); else resolve(value); };
+			const timer = setTimeout(() => finish(new Error("独立服务启动超时")), timeout);
+			child.once("error", error => finish(error));
+			child.once("exit", code => finish(new Error(`独立服务提前退出 (${code})${errors ? ": " + errors.replaceAll(password, "[redacted]") : ""}`)));
+			child.stdout.on("data", chunk => {
+				if (settled) return;
+				pending += chunk.toString();
+				if (pending.length > 32768) { finish(new Error("独立服务 readiness 超出限制")); return; }
+				let end;
+				while ((end = pending.indexOf("\n")) !== -1) {
+					const line = pending.slice(0, end).trim(); pending = pending.slice(end + 1);
+					if (!line) continue;
+					try {
+						const data = JSON.parse(line), ready = new URL(data.url);
+						if (ready.protocol !== "http:" || !["127.0.0.1", "localhost", "[::1]"].includes(ready.hostname) || !ready.port || ready.username || ready.password || ready.pathname !== "/" || ready.search || ready.hash) throw new Error("readiness URL 不是本机独立服务");
+						finish(null, ready.origin); return;
+					} catch (error) { finish(new Error(`独立服务 readiness 无效：${error.message}`)); return; }
+				}
+			});
+		});
+		return { pid: child.pid, url, exited, close, clientArgs: args => privateClientArgs(args, url) };
+	} catch (error) { lease?.close(); close(); await exited; throw error; }
+}

package/lib/project.mjs

@@ -0,0 +1,134 @@
+// 项目级人设：写进当前项目根的 AGENTS.md / CLAUDE.md 托管块。
+//
+// 为什么要有这条通道：全局配置一改就是全机器生效，改坏了也只能回滚配置；项目块只影响
+// 当前目录，删块即还原，比全局配置更局部也更好解释。撤销走 persist.revertFile（stash 字节还原）。
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { cancel, listLedger, record } from "./footprints.mjs";
+import { readStash, revertFile, stripBlock, upsertBlock, writeStash } from "./persist.mjs";
+import { loadState, patchState } from "./state.mjs";
+import { dataHome } from "./home.mjs";
+
+/** 各家的项目规则文件。没列的家（codebuddy/dsh/antigravity）没有这个落点，不摆开关。 */
+const PROJECT_FILES = {
+	pi: "AGENTS.md",
+	omp: "AGENTS.md",
+	grok: "AGENTS.md",
+	zcode: "AGENTS.md",
+	codex: "AGENTS.md",
+	opencode: "AGENTS.md",
+	opencode2: "AGENTS.md",
+	claude: "CLAUDE.md",
+};
+
+export const projectTargets = PROJECT_FILES;
+export const projectFilePath = (id, dir = process.cwd()) => (PROJECT_FILES[id] ? resolve(dir, PROJECT_FILES[id]) : null);
+const pathKey = path => process.platform === "win32" ? path.toLowerCase() : path;
+
+/** 暂停会撤销磁盘块，因此目录选择单独保存在 state；旧安装只从账本恢复，不猜 cwd。 */
+export function projectDirectories(root, id) {
+	const { state } = loadState(root);
+	const saved = Array.isArray(state.projectDirs?.[id]) ? state.projectDirs[id] : [];
+	const recorded = listLedger(root)
+		.filter(e => e.harness === id && e.channel === "project" && typeof e.path === "string" && isAbsolute(e.path))
+		.map(e => dirname(e.path));
+	const dirs = new Map();
+	for (const path of [...saved, ...recorded]) {
+		if (typeof path !== "string" || !isAbsolute(path)) continue;
+		const dir = resolve(path);
+		dirs.set(pathKey(dir), dir);
+	}
+	return [...dirs.values()];
+}
+
+function saveDirectories(root, id, dirs) {
+	const { state } = loadState(root);
+	const projectDirs = { ...state.projectDirs };
+	if (dirs.length) projectDirs[id] = dirs;
+	else delete projectDirs[id];
+	patchState(root, { projectDirs });
+}
+
+function rememberDirectory(root, id, dir) {
+	const dirs = projectDirectories(root, id);
+	if (!dirs.some(path => pathKey(path) === pathKey(dir))) dirs.push(dir);
+	saveDirectories(root, id, dirs);
+}
+
+/** 项目块优先于全局块（harness 把项目规则放前面），所以两块同时开会两份都进。 */
+export const PROJECT_NOTE = "原生 harness 会共同读取同名规则文件；单文件只登记一个管理归属，同时开全局会有两份";
+
+function ownersOf(root, file) {
+	return Object.keys(PROJECT_FILES).filter(id => projectDirectories(root, id).some(dir => pathKey(projectFilePath(id, dir)) === pathKey(file)));
+}
+
+export function projectInstall(id, { root, active, dir = process.cwd(), paused = false }) {
+	const file = projectFilePath(id, dir);
+	if (!file) return { error: `${id} 没有项目级规则文件（可用: ${Object.keys(PROJECT_FILES).join(", ")}）` };
+	const owners = ownersOf(root, file).filter(owner => owner !== id);
+	if (owners.length) return { error: `项目文件归属冲突：${file} 已登记给 ${owners.join(", ")}，请先撤销原选择`, file, owners };
+	if (paused) {
+		rememberDirectory(root, id, dirname(file));
+		return { file, action: "selected-while-paused" };
+	}
+	const body = String(active ?? "").trim();
+	if (!body) return { error: "没有可用人设" };
+	mkdirSync(dirname(file), { recursive: true });
+	const old = existsSync(file) ? readFileSync(file, "utf8") : null;
+	if (/^(?:\s*)# (?:>>>|<<<) agent-purge/m.test(body)) return { error: `${id}: persona 正文包含 agent-purge 托管标记，拒绝写入` };
+	const next = upsertBlock(old ?? "", body);
+	// 多次同步沿用最初的还原基线；块外被用户编辑时，只移除旧托管块再保存。
+	const previous = readStash(file, root);
+	let before = previous && previous.after === old ? previous.before : old;
+	if (before !== null) before = stripBlock(before);
+	writeStash(file, { file, before, after: next }, root);
+	writeFileSync(file, next);
+	record(root, { kind: "block", harness: id, channel: "project", path: file, undo: { type: "block-revert" } });
+	rememberDirectory(root, id, dirname(file));
+	return { file, action: old === null ? "created" : stripBlock(old) !== old ? "replaced-block" : "appended-block", note: PROJECT_NOTE };
+}
+
+export function projectUninstall(id, { dir = process.cwd(), root = dataHome(), keepSelection = false } = {}) {
+	const file = projectFilePath(id, dir);
+	if (!file) return { error: `${id} 没有项目级规则文件` };
+	const owners = ownersOf(root, file);
+	if (owners.length && !owners.includes(id)) return { file, action: "not-owner", owners };
+	if (owners.length > 1) return { error: `旧项目归属冲突：${file} (${owners.join(", ")})，请先核对账本`, file };
+	// 在撤销账本前保存旧安装的目录，暂停后仍可恢复到同一位置。
+	if (root && keepSelection) rememberDirectory(root, id, dirname(file));
+	const r = revertFile(file, { root });
+	if (root && !r.error) {
+		cancel(root, { kind: "block", path: file });
+		if (!keepSelection) saveDirectories(root, id, projectDirectories(root, id).filter(path => pathKey(path) !== pathKey(dirname(file))));
+	}
+	return r;
+}
+
+/**
+ * 现场状态。同一个 AGENTS.md 可能被好几家共用，所以「开着」必须靠账本归属到具体 harness：
+ * 块在文件里、账本又有这条记录才算开着（账本丢了就说不知道，不自作主张）。
+ */
+export function projectStatus(dir = process.cwd(), root) {
+	const entries = root ? listLedger(root).filter((e) => e.channel === "project") : null;
+	return Object.entries(PROJECT_FILES).map(([id, name]) => {
+		const file = resolve(dir, name);
+		const text = existsSync(file) ? readFileSync(file, "utf8") : null;
+		const hasBlock = text !== null && stripBlock(text) !== text;
+		const mine = entries ? entries.some((e) => e.harness === id && typeof e.path === "string" && pathKey(e.path) === pathKey(file)) : hasBlock;
+		const selected = root ? projectDirectories(root, id).some(path => pathKey(path) === pathKey(dirname(file))) : hasBlock;
+		return { id, file, hasBlock, on: hasBlock && mine, selected };
+	});
+}
+
+/**
+ * git 仓库里没被跟踪的规则文件，改完容易意外进提交。只提示，不替用户改 .gitignore。
+ * 返回 null = 不需要提示（不是 git 仓库 / 文件已被跟踪 / 没有 git）。
+ */
+export function gitHint(id, dir = process.cwd()) {
+	const name = PROJECT_FILES[id];
+	if (!name || !existsSync(join(dir, ".git"))) return null;
+	const run = spawnSync("git", ["-C", dir, "ls-files", "--error-unmatch", "--", name], { encoding: "utf8" });
+	if (run.error || run.status === 0) return null;
+	return `${name} 还没被 git 跟踪：不想提交这份人设就 git update-index --skip-worktree ${name} 或写进 .gitignore（不自动改）`;
+}