agents-gitflow-guard 0.0.1

package/lib/src-DWE1n9Zh.mjs

@@ -0,0 +1,813 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+//#region src/classify.ts
+/** 拆分命令为多段(&& / 分号 / 换行), 每段独立分类; 引号内的分隔符不算 */
+function classify(command, ctx = {}) {
+	return splitSegments(command).flatMap((seg) => classifySegment(seg, ctx));
+}
+/** 引号感知拆分: 保护 "..." 与 '...' 内的 && / ; / 换行 */
+function splitSegments(command) {
+	const segments = [];
+	let current = "";
+	let quote = null;
+	const push = () => {
+		if (current.trim()) segments.push(current.trim());
+		current = "";
+	};
+	for (let i = 0; i < command.length; i++) {
+		const ch = command[i];
+		if (quote != null) {
+			current += ch;
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'") {
+			quote = ch;
+			current += ch;
+			continue;
+		}
+		if (ch === "&" && command[i + 1] === "&") {
+			push();
+			i++;
+			continue;
+		}
+		if (ch === ";" || ch === "\n") {
+			push();
+			continue;
+		}
+		current += ch;
+	}
+	push();
+	return segments;
+}
+function classifySegment(segment, ctx) {
+	const tokens = tokenize(segment);
+	if (tokens.length === 0) return [{ kind: "other" }];
+	const [cmd, ...rest] = tokens;
+	if (cmd === "git") return classifyGit(rest, ctx);
+	if (cmd === "gh") return classifyGh(rest);
+	if (cmd === "gitflow-guard") return [{
+		kind: "guard-cli",
+		sub: guardSub(rest)
+	}];
+	return [{ kind: "other" }];
+}
+/** 分词: 引号内的空格不拆分 */
+function tokenize(segment) {
+	return segment.match(/"[^"]*"|'[^']*'|\S+/g)?.map((t) => t.replace(/^['"]|['"]$/g, "")) ?? [];
+}
+function classifyGit(args, ctx) {
+	const [sub, ...rest] = args;
+	if (sub === "push") return parsePush(rest, ctx);
+	if (sub === "merge") return parseMerge(rest);
+	if (sub === "branch") return parseBranch(rest);
+	if (sub === "checkout" || sub === "switch") return parseCheckout(rest);
+	return [{ kind: "other" }];
+}
+/** 分支切换: 门禁放行, 分支状态由 evaluateCommand 按段模拟 */
+function parseCheckout(args) {
+	const first = args[0];
+	if (first === "--") return [{
+		kind: "checkout",
+		branch: null
+	}];
+	if (first === "-b" || first === "-B" || first === "-c" || first === "-C") {
+		const name = args[1];
+		return [{
+			kind: "checkout",
+			branch: name && !name.startsWith("-") ? name : null
+		}];
+	}
+	if (first && !first.startsWith("-")) return [{
+		kind: "checkout",
+		branch: first
+	}];
+	return [{
+		kind: "checkout",
+		branch: null
+	}];
+}
+function parsePush(args, ctx) {
+	let force = false;
+	let isDelete = false;
+	let all = false;
+	const nonFlag = [];
+	for (const a of args) if (a === "-f" || a === "--force" || a === "--force-with-lease" || a.startsWith("--force-with-lease=")) force = true;
+	else if (a === "--delete" || a === "-d") isDelete = true;
+	else if (a === "--all" || a === "--mirror") all = true;
+	else if (a.startsWith("-")) {} else nonFlag.push(a);
+	if (all) return [{
+		kind: "push",
+		dst: null,
+		force,
+		delete: false,
+		all: true
+	}];
+	const refspecs = nonFlag.slice(1);
+	if (refspecs.length === 0) return [{
+		kind: "push",
+		dst: ctx.currentBranch ?? null,
+		force,
+		delete: false
+	}];
+	return refspecs.map((ref) => {
+		if (ref.startsWith(":")) return {
+			kind: "push",
+			dst: stripRefPrefix(ref.slice(1)) || null,
+			force,
+			delete: true
+		};
+		const colon = ref.indexOf(":");
+		if (colon >= 0) {
+			const deleteTarget = ref.endsWith(":");
+			const dst = deleteTarget ? ref.slice(colon + 1, ref.length - 1) || ref.slice(0, colon) : ref.slice(colon + 1);
+			return {
+				kind: "push",
+				dst: dst ? stripRefPrefix(dst) : null,
+				force,
+				delete: deleteTarget || isDelete
+			};
+		}
+		if (ref === "HEAD") return {
+			kind: "push",
+			dst: ctx.currentBranch ?? null,
+			force,
+			delete: isDelete
+		};
+		return {
+			kind: "push",
+			dst: stripRefPrefix(ref),
+			force,
+			delete: isDelete
+		};
+	});
+}
+/** 全限定 refspec(refs/heads/x)剥离前缀, 与角色分支名比对 */
+function stripRefPrefix(branch) {
+	return branch.startsWith("refs/heads/") ? branch.slice(11) : branch;
+}
+function parseMerge(args) {
+	if (args.some((a) => a === "--abort")) return [{ kind: "other" }];
+	return [{
+		kind: "local-merge",
+		source: args.find((a, i) => !a.startsWith("-") && args[i - 1] !== "-m" && args[i - 1] !== "--message") ?? null
+	}];
+}
+function parseBranch(args) {
+	const [flag, name] = args;
+	if ((flag === "-d" || flag === "-D" || flag === "--delete") && name && !name.startsWith("-")) return [{
+		kind: "branch-delete",
+		branch: name,
+		force: flag === "-D"
+	}];
+	return [{ kind: "other" }];
+}
+function classifyGh(args) {
+	const [sub, action, ...rest] = args;
+	if (sub !== "pr") return [{ kind: "other" }];
+	if (action === "create") return parsePrCreate(rest);
+	if (action === "merge") return parsePrMerge(rest);
+	return [{ kind: "other" }];
+}
+function parsePrCreate(args) {
+	if (hasHelpFlag(args)) return [{ kind: "other" }];
+	const out = {
+		kind: "pr-create",
+		target: null
+	};
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === "--base" || a === "-B") {
+			const value = args[i + 1];
+			if (value && !value.startsWith("-")) out.target = value;
+		} else if (a.startsWith("--base=")) out.target = a.slice(7) || null;
+	}
+	return [out];
+}
+function parsePrMerge(args) {
+	if (hasHelpFlag(args)) return [{ kind: "other" }];
+	return [{
+		kind: "pr-merge",
+		pr: args.find((a) => !a.startsWith("-") && /^\d+$/.test(a)) ?? null
+	}];
+}
+function hasHelpFlag(args) {
+	return args.some((a) => a === "-h" || a === "--help" || a === "--version");
+}
+function guardSub(args) {
+	const sub = args[0];
+	if (sub === "permit" || sub === "confirm" || sub === "status") return sub;
+	return "other";
+}
+//#endregion
+//#region src/config.ts
+const CONFIG_FILE = "gitflow-guard.config.json";
+/** 默认配置(分支角色必须由项目显式配置, 无默认) */
+const DEFAULT_CONFIG = {
+	enabled: false,
+	mode: "pr",
+	confirm: {
+		keywords: [
+			"确认",
+			"OK",
+			"可以",
+			"特许"
+		],
+		featurePattern: "feature/[\\w-]+"
+	},
+	ci: { enabled: true }
+};
+/** 合并默认值并校验; 任何校验错误都会导致未启用 */
+function mergeConfig(raw) {
+	const errors = [];
+	if (typeof raw !== "object" || raw === null) return {
+		config: null,
+		errors: ["配置文件必须是 JSON 对象"]
+	};
+	const r = raw;
+	const config = {
+		...DEFAULT_CONFIG,
+		confirm: { ...DEFAULT_CONFIG.confirm },
+		ci: { ...DEFAULT_CONFIG.ci },
+		branches: {
+			base: "",
+			preview: ""
+		}
+	};
+	if (typeof r.enabled === "boolean") config.enabled = r.enabled;
+	if (r.mode === void 0) {} else if (r.mode === "pr" || r.mode === "flexible") config.mode = r.mode;
+	else errors.push("mode 必须是 \"pr\" 或 \"flexible\"");
+	const b = r.branches ?? {};
+	if (typeof b.base === "string" && b.base !== "") config.branches.base = b.base;
+	if (typeof b.preview === "string" && b.preview !== "") config.branches.preview = b.preview;
+	if (typeof b.trunk === "string" && b.trunk !== "") config.branches.trunk = b.trunk;
+	const c = r.confirm ?? {};
+	if (c.keywords !== void 0) {
+		if (!Array.isArray(c.keywords) || c.keywords.length === 0 || !c.keywords.every((k) => typeof k === "string")) errors.push("confirm.keywords 必须是非空字符串数组");
+		else config.confirm.keywords = c.keywords;
+	}
+	if (typeof c.featurePattern === "string" && c.featurePattern !== "") config.confirm.featurePattern = c.featurePattern;
+	const ci = r.ci ?? {};
+	if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
+	errors.push(...validateConfig(config));
+	return {
+		config: errors.length > 0 ? null : config,
+		errors
+	};
+}
+/** 配置校验: 角色分支冲突等(风险清单第 5 条兜底) */
+function validateConfig(config) {
+	const errors = [];
+	if (!config.branches.base) errors.push("branches.base 必填");
+	if (!config.branches.preview) errors.push("branches.preview 必填");
+	if (config.branches.base && config.branches.preview && config.branches.base === config.branches.preview) errors.push("branches.base 与 branches.preview 不能是同一分支");
+	if (config.branches.trunk) {
+		if (config.branches.trunk === config.branches.base) errors.push("branches.trunk 与 branches.base 不能是同一分支");
+		if (config.branches.trunk === config.branches.preview) errors.push("branches.trunk 与 branches.preview 不能是同一分支");
+	}
+	if (config.confirm.keywords.length === 0) errors.push("confirm.keywords 不能为空");
+	try {
+		new RegExp(config.confirm.featurePattern);
+	} catch {
+		errors.push(`confirm.featurePattern 不是合法正则: ${config.confirm.featurePattern}`);
+	}
+	return errors;
+}
+/** 从项目根加载配置; 无文件 = 未启用(opt-in) */
+async function loadConfig(repoRoot) {
+	try {
+		const text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+		return mergeConfig(JSON.parse(text));
+	} catch (e) {
+		if (e.code === "ENOENT") return {
+			config: null,
+			errors: []
+		};
+		return {
+			config: null,
+			errors: [`读取配置文件失败: ${e.message}`]
+		};
+	}
+}
+//#endregion
+//#region src/gate.ts
+const FEATURE_UNKNOWN = "当前分支";
+/** 受保护分支集合: 基线/主干始终受保护; 预览仅在 pr 模式受保护 */
+function protectedBranches(config) {
+	const set = /* @__PURE__ */ new Set([config.branches.base]);
+	if (config.branches.trunk) set.add(config.branches.trunk);
+	if (config.mode === "pr") set.add(config.branches.preview);
+	return set;
+}
+function isProtected(branch, config) {
+	return branch != null && protectedBranches(config).has(branch);
+}
+function decide(classified, facts, config) {
+	switch (classified.kind) {
+		case "push": return decidePush(classified, facts, config);
+		case "local-merge": return decideMerge(classified, facts, config);
+		case "pr-create": return decidePrCreate(classified, facts, config);
+		case "pr-merge": return decidePrMerge(classified, facts, config);
+		case "branch-delete": return isProtected(classified.branch, config) ? deny(`受保护分支「${classified.branch}」禁止删除或强推`, "删除分支请到受保护分支外操作; 受保护分支由用户亲手管理") : { kind: "allow" };
+		case "guard-cli": return classified.sub === "permit" || classified.sub === "confirm" ? deny("特许/确认是用户专属操作, agent 不能自我授权", "请让用户在终端执行 gitflow-guard permit/confirm, 或在聊天中给出确认") : { kind: "allow" };
+		case "checkout": return { kind: "allow" };
+		default: return { kind: "allow" };
+	}
+}
+function decidePush(c, facts, config) {
+	if (c.all) return deny("--all/--mirror 推送会包含受保护分支", "请逐分支推送并显式指定 refspec");
+	const dst = c.dst ?? facts.currentBranch;
+	if (dst == null) return deny("无法确定推送目标分支(可能处于 detached HEAD)", "请显式指定 refspec, 如 git push origin <分支名>");
+	if (isProtected(dst, config)) return deny(c.delete ? `受保护分支「${dst}」禁止删除` : `受保护分支「${dst}」禁止直推${c.force ? "(含强推)" : ""}`, branchNext(dst, config));
+	return { kind: "allow" };
+}
+function decideMerge(c, facts, config) {
+	const { base, preview, trunk } = config.branches;
+	const current = facts.currentBranch;
+	const source = c.source;
+	if (current === trunk) return deny("合入主干(trunk)仅允许用户亲手执行", "如需发布, 请让用户在自己终端完成; 创建指向 trunk 的 PR 需用户特许(P3)");
+	if (current === base) {
+		if (source == null) return { kind: "allow" };
+		if (source === preview) return deny("将预览分支整体合入基线会绕过逐 feature 验证", "请按 feature 逐个合入: 每个 feature 需已合入预览且用户确认(P2)");
+		if (source === trunk) return { kind: "allow" };
+		if (source === base) return { kind: "allow" };
+		return mergeIntoBase(source, facts, config);
+	}
+	if (current === preview) {
+		if (config.mode === "pr" && source != null && source !== base && source !== trunk) return deny(`pr 模式禁止本地合入预览分支(当前在 ${preview})`, "请创建 PR(feature → preview)合入, 或改用 flexible 模式");
+		return { kind: "allow" };
+	}
+	return { kind: "allow" };
+}
+function mergeIntoBase(feature, facts, config) {
+	if (!facts.featureInPreview(feature)) return deny(`流程违规: feature「${feature}」尚未合入预览分支(${config.branches.preview}), 不能合入基线(${config.branches.base})`, "请先合入预览(PR①)并测试确认, 再合入基线; 或请用户特许提前操作(聊天「确认」/ 终端 gitflow-guard permit)");
+	if (!facts.hasPermit("confirm", feature)) return deny(`缺少用户确认: feature「${feature}」已在预览分支, 但用户尚未确认测试通过`, "请让用户确认测试结果(聊天输入「feature xxx 测试 OK」/ 终端 gitflow-guard confirm feature-xxx)");
+	return { kind: "allow" };
+}
+function decidePrCreate(c, facts, config) {
+	const { base, preview, trunk } = config.branches;
+	const head = facts.currentBranch;
+	if (c.target == null) return deny("无法确定 PR 目标分支", `请显式指定 --base <分支名>(如 gh pr create --base ${config.branches.preview})`);
+	if (c.target === preview) return { kind: "allow" };
+	if (c.target === base) {
+		if (head == null || head === base || head === preview || head === trunk) return deny(`当前分支(${head ?? FEATURE_UNKNOWN})是角色分支, 不能作为指向基线的 PR 源`, "请在 feature 分支上创建指向基线的 PR");
+		if (facts.featureInPreview(head)) return { kind: "allow" };
+		if (facts.hasPermit("early-pr", head)) return { kind: "allow" };
+		return deny(`流程违规: feature「${head}」尚未合入预览分支(${preview}), 提前创建指向基线(${base})的 PR 需要用户特许(P1)`, "请先合入预览; 或请用户特许(聊天确认「提前建 PR」/ 终端 gitflow-guard permit)");
+	}
+	if (c.target === trunk) {
+		const head = facts.currentBranch;
+		if (head != null && facts.hasPermit("trunk-pr", head)) return { kind: "allow" };
+		return deny("创建指向主干(trunk)的 PR 需要用户特许(P3)", "请让用户特许(聊天确认「上主干」/ 终端 gitflow-guard permit --kind trunk-pr)");
+	}
+	return { kind: "allow" };
+}
+function decidePrMerge(c, facts, config) {
+	const resolved = facts.resolvePrTarget?.(c.pr) ?? null;
+	const target = resolved?.target ?? null;
+	const head = resolved?.head ?? facts.currentBranch;
+	if (target === "preview") return { kind: "allow" };
+	if (target === "trunk") return deny("合入主干(trunk)仅允许用户亲手执行", "如需发布, 请让用户在自己终端合并");
+	if (target === "other") return { kind: "allow" };
+	if (head == null) return deny("无法确认 PR 的 feature 分支", "请先 checkout 到 feature 分支再合并, 或确认 gh 查询可用");
+	if (target === null) {
+		const reason = facts.featureInPreview(head) ? `缺少用户确认: feature「${head}」已在预览分支, 但无法确认 PR 目标(gh 查询失败), 仍须用户确认(P2)` : `流程违规: feature「${head}」尚未合入预览分支, 且无法确认 PR 目标(gh 查询失败)`;
+		if (!facts.featureInPreview(head) || !facts.hasPermit("confirm", head)) return deny(reason, "请确认 gh 可用后重试, 或改用本地合入(git merge)路径; 确认测试通过需用户特许(P2)");
+		return { kind: "allow" };
+	}
+	return mergeIntoBase(head, facts, config);
+}
+function deny(reason, next) {
+	return {
+		kind: "deny",
+		reason,
+		next
+	};
+}
+/** 受保护分支被拦后的下一步引导 */
+function branchNext(branch, config) {
+	if (branch == null) return "请明确目标分支后重试";
+	if (branch === config.branches.preview) return config.mode === "pr" ? `预览分支须走 PR: 先推 feature 分支, 再 gh pr create --base ${config.branches.preview}` : "预览分支可直推(当前 flexible 模式)";
+	if (branch === config.branches.base) return `基线分支(${branch})由 PR 合入: 先合入预览并确认(P2), 再创建指向基线的 PR`;
+	return `主干分支(${branch})仅用户亲手操作`;
+}
+//#endregion
+//#region src/permits.ts
+async function openPermitStore(stateFile, now = Date.now) {
+	let permits = [];
+	try {
+		const text = await readFile(stateFile, "utf8");
+		const parsed = JSON.parse(text);
+		if (!parsed || !Array.isArray(parsed.permits)) throw new Error("state.json 结构非法");
+		permits = parsed.permits;
+	} catch (e) {
+		if (e.code !== "ENOENT") throw new Error(`读取 ${stateFile} 失败: ${e.message}`);
+	}
+	async function save() {
+		await mkdir(dirname(stateFile), { recursive: true });
+		await writeFile(stateFile, JSON.stringify({
+			version: 1,
+			permits
+		}, null, 2), "utf8");
+	}
+	function findValid(kind, feature, at) {
+		return permits.find((p) => p.kind === kind && p.feature === feature && !p.used && (p.expiresAt == null || p.expiresAt > at));
+	}
+	return {
+		async grant(kind, feature, opts) {
+			permits = permits.filter((p) => !(p.kind === kind && p.feature === feature && !p.used));
+			const at = now();
+			const permit = {
+				id: randomUUID(),
+				kind,
+				feature,
+				grantedAt: at,
+				...opts?.ttlMs != null ? { expiresAt: at + opts.ttlMs } : {},
+				used: false
+			};
+			permits.push(permit);
+			await save();
+			return permit;
+		},
+		async consume(kind, feature) {
+			const at = now();
+			const idx = permits.findIndex((p) => p.kind === kind && p.feature === feature && !p.used && (p.expiresAt == null || p.expiresAt > at));
+			if (idx < 0) return null;
+			permits[idx] = {
+				...permits[idx],
+				used: true
+			};
+			await save();
+			return permits[idx];
+		},
+		hasValid(kind, feature, at = now()) {
+			return findValid(kind, feature, at) != null;
+		},
+		list() {
+			return [...permits];
+		}
+	};
+}
+//#endregion
+//#region src/repo.ts
+function makeRunner(bin) {
+	return { async run(args, cwd) {
+		return await new Promise((resolve) => {
+			execFile(bin, args, {
+				cwd,
+				maxBuffer: 16777216
+			}, (err, stdout, stderr) => {
+				resolve({
+					code: err ? typeof err.code === "number" ? err.code : 1 : 0,
+					stdout: stdout ?? "",
+					stderr: stderr ?? ""
+				});
+			});
+		});
+	} };
+}
+const gitRunner = makeRunner("git");
+/** gh 适配器: 解析 PR 目标分支(可选增强, 失败返回 null 由门禁保守处理) */
+const ghRunner = makeRunner("gh");
+async function findRepoRoot(runner, cwd) {
+	const r = await runner.run(["rev-parse", "--show-toplevel"], cwd);
+	return r.code === 0 ? r.stdout.trim() || null : null;
+}
+async function currentBranch(runner, cwd) {
+	const r = await runner.run(["branch", "--show-current"], cwd);
+	return r.code === 0 ? r.stdout.trim() || null : null;
+}
+/** feature 是否已合入 descendant(merge-base --is-ancestor, 退出码 0 = 是) */
+async function isAncestor(runner, cwd, ancestor, descendant) {
+	return (await runner.run([
+		"merge-base",
+		"--is-ancestor",
+		ancestor,
+		descendant
+	], cwd)).code === 0;
+}
+/** gh pr view: 返回 base/head 分支名; PR 不存在或 gh 不可用 → null */
+async function ghPrInfo(runner, cwd, pr) {
+	const args = pr ? [
+		"pr",
+		"view",
+		pr,
+		"--json",
+		"baseRefName,headRefName"
+	] : [
+		"pr",
+		"view",
+		"--json",
+		"baseRefName,headRefName"
+	];
+	const r = await runner.run(args, cwd);
+	if (r.code !== 0) return null;
+	try {
+		const j = JSON.parse(r.stdout);
+		if (typeof j.baseRefName === "string" && typeof j.headRefName === "string") return {
+			base: j.baseRefName,
+			head: j.headRefName
+		};
+		return null;
+	} catch {
+		return null;
+	}
+}
+/** gh pr checks: 返回 PR 检查状态(SUCCESS/FAILURE/PENDING/...); 查不到返回 null(自动跳过) */
+async function ghPrChecks(runner, cwd, pr) {
+	if (pr == null) return null;
+	const r = await runner.run([
+		"pr",
+		"checks",
+		pr,
+		"--json",
+		"state"
+	], cwd);
+	if (r.code !== 0) return null;
+	try {
+		const states = JSON.parse(r.stdout);
+		if (!Array.isArray(states) || states.length === 0) return null;
+		const distinct = new Set(states.map((s) => String(s.state ?? "")));
+		if (distinct.has("FAILURE")) return "FAILURE";
+		if (distinct.has("PENDING") || distinct.has("IN_PROGRESS") || distinct.has("QUEUED")) return "PENDING";
+		return "SUCCESS";
+	} catch {
+		return null;
+	}
+}
+/** 把 PR 的 base 分支映射为角色; 无法解析返回 null */
+function resolvePrTarget(info, config) {
+	if (!info) return null;
+	const { base, preview, trunk } = config.branches;
+	return {
+		target: info.base === base ? "base" : info.base === preview ? "preview" : info.base === trunk ? "trunk" : "other",
+		head: info.head
+	};
+}
+//#endregion
+//#region src/session.ts
+const EARLY_MARKERS = [
+	/提前\s*(?:建|开|创建)?\s*(?:pr|pull\s*request)/i,
+	/提前\s*建/i,
+	/early[- ]?pr/i
+];
+const TRUNK_MARKERS = [
+	/主干/,
+	/trunk/i,
+	/上线/,
+	/上\s*main/i
+];
+const CONFIRM_MARKERS = [
+	/测试\s*通过/,
+	/通过/,
+	/验证/,
+	/合入/,
+	/ok\b/i
+];
+function extractFeature(text, pattern) {
+	try {
+		return text.match(new RegExp(pattern))?.[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+/** 解析确认消息; 无法识别返回 null */
+function parseConfirmation(text, config) {
+	const feature = extractFeature(text, config.confirm.featurePattern);
+	if (!feature) return null;
+	const matchAny = (markers) => markers.some((m) => m.test(text));
+	if (matchAny(EARLY_MARKERS)) return {
+		kind: "early-pr",
+		feature
+	};
+	if (matchAny(TRUNK_MARKERS) || config.branches.trunk != null && text.includes(config.branches.trunk)) return {
+		kind: "trunk-pr",
+		feature
+	};
+	if (matchAny(CONFIRM_MARKERS) || config.confirm.keywords.some((k) => text.toLowerCase().includes(k.toLowerCase()))) return {
+		kind: "confirm",
+		feature
+	};
+	return null;
+}
+//#endregion
+//#region src/index.ts
+const name = "gitflow-guard";
+function stateDir(repoRoot) {
+	return join(repoRoot, ".git", "gitflow-guard");
+}
+function stateFile(repoRoot) {
+	return join(stateDir(repoRoot), "state.json");
+}
+/** 审计留痕; 失败不阻断门禁 */
+async function appendAudit(repoRoot, entry) {
+	try {
+		await mkdir(stateDir(repoRoot), { recursive: true });
+		await appendFile(join(stateDir(repoRoot), "audit.jsonl"), `${JSON.stringify(entry)}\n`, "utf8");
+	} catch {}
+}
+/** 解析一条命令: 分类 → git 事实 → 门禁 → allow/deny */
+async function evaluateCommand(command, opts) {
+	const runner = opts.runner ?? gitRunner;
+	const gh = opts.ghRunner ?? ghRunner;
+	const { config } = await loadConfig(opts.repoRoot);
+	if (!config?.enabled) return {
+		outcome: "skipped",
+		segmentCount: 0,
+		pendingConsume: []
+	};
+	const branch = opts.currentBranch ?? await currentBranch(runner, opts.repoRoot);
+	const store = await openPermitStore(stateFile(opts.repoRoot), opts.now);
+	const env = {
+		repoRoot: opts.repoRoot,
+		config,
+		branch,
+		runner,
+		gh,
+		store
+	};
+	const segments = classify(command, { currentBranch: branch });
+	const pendingConsume = [];
+	let simulatedBranch = branch;
+	for (const seg of segments) {
+		const { facts, head, inPreview } = await factsFor(seg, {
+			...env,
+			branch: simulatedBranch
+		});
+		const decision = decide(seg, facts, config);
+		if (decision.kind === "deny") {
+			await appendAudit(env.repoRoot, {
+				time: Date.now(),
+				event: "deny",
+				command,
+				reason: decision.reason
+			});
+			return {
+				outcome: "deny",
+				reason: {
+					why: decision.reason,
+					next: decision.next
+				},
+				segmentCount: segments.length,
+				pendingConsume
+			};
+		}
+		pendingConsume.push(...permitsUsedBy(seg, env, head, inPreview));
+		await logCiReference(seg, env);
+		if (seg.kind === "checkout" && seg.branch != null) simulatedBranch = seg.branch;
+	}
+	return {
+		outcome: "allow",
+		segmentCount: segments.length,
+		pendingConsume
+	};
+}
+/** CI 参考(可选适配器): gh pr checks 状态记入审计日志, 查不到自动跳过 */
+async function logCiReference(seg, env) {
+	if (!env.config.ci.enabled) return;
+	if (seg.kind !== "pr-merge") return;
+	const state = await ghPrChecks(env.gh, env.repoRoot, seg.pr);
+	if (state == null) return;
+	await appendAudit(env.repoRoot, {
+		time: Date.now(),
+		event: "ci",
+		kind: state,
+		feature: seg.pr ?? void 0
+	});
+}
+/** 按段预取 git 事实(异步 I/O 全部前置, 门禁保持纯函数) */
+async function factsFor(seg, env) {
+	const { config, repoRoot, branch, runner } = env;
+	const preview = config.branches.preview;
+	let head = null;
+	let prRes = null;
+	if (seg.kind === "pr-merge") {
+		prRes = resolvePrTarget(await ghPrInfo(env.gh, repoRoot, seg.pr), config);
+		head = prRes?.head ?? branch;
+	} else if (seg.kind === "local-merge") head = seg.source;
+	else if (seg.kind === "pr-create") head = branch;
+	const inPreview = head ? await isAncestor(runner, repoRoot, head, preview) : false;
+	return {
+		head,
+		inPreview,
+		facts: {
+			currentBranch: branch,
+			featureInPreview: (f) => f === head && inPreview,
+			hasPermit: (kind, f) => env.store.hasValid(kind, f),
+			...prRes ? { resolvePrTarget: () => prRes } : {}
+		}
+	};
+}
+/** 本次放行动作实际依赖了哪些特许(动作成功后消费; 未用到的特许不消耗) */
+function permitsUsedBy(seg, env, head, inPreview) {
+	const out = [];
+	const has = (kind, feature) => feature != null && env.store.hasValid(kind, feature);
+	if (seg.kind === "local-merge" || seg.kind === "pr-merge") {
+		if (head != null && inPreview && has("confirm", head)) out.push({
+			kind: "confirm",
+			feature: head
+		});
+	}
+	if (seg.kind === "pr-create") {
+		if (seg.target === env.config.branches.base && head != null && !inPreview && has("early-pr", head)) out.push({
+			kind: "early-pr",
+			feature: head
+		});
+		if (seg.target === env.config.branches.trunk && head != null && has("trunk-pr", head)) out.push({
+			kind: "trunk-pr",
+			feature: head
+		});
+	}
+	return out;
+}
+function commandText(exec) {
+	const args = exec.arguments;
+	return typeof args?.command === "string" ? args.command : "";
+}
+function messageText(msg) {
+	return (msg.content ?? []).map((b) => b?.type === "text" ? b.text : "").join(" ");
+}
+function formatDeny(why, next) {
+	return `[gitflow-guard] 已拦截: ${why}\n下一步: ${next}`;
+}
+function apply(ctx, pluginConfig = {}) {
+	const toolNames = new Set(pluginConfig.toolNames ?? ["pwsh", "bash"]);
+	const pending = /* @__PURE__ */ new WeakMap();
+	ctx.on("tools/pre-execute", async (exec, next) => {
+		try {
+			const command = commandText(exec);
+			if (!command || !toolNames.has(exec.name)) return next();
+			const cwd = exec.agent?.session.header.cwd ?? process.cwd();
+			const repoRoot = await findRepoRoot(gitRunner, cwd);
+			if (!repoRoot) return next();
+			const result = await evaluateCommand(command, {
+				repoRoot,
+				runner: gitRunner
+			});
+			if (result.outcome === "deny" && result.reason) return {
+				kind: "deny",
+				reason: formatDeny(result.reason.why, result.reason.next)
+			};
+			if (result.pendingConsume.length > 0) pending.set(exec, result.pendingConsume);
+			return next();
+		} catch (e) {
+			ctx.logger?.warn?.(`gitflow-guard: 门禁内部错误, 已放行: ${e.message}`);
+			return next();
+		}
+	});
+	ctx.on("tools/post-execute", async (exec, result, next) => {
+		try {
+			const toConsume = pending.get(exec);
+			if (!toConsume) return next();
+			pending.delete(exec);
+			const cwd = exec.agent?.session.header.cwd ?? process.cwd();
+			const repoRoot = await findRepoRoot(gitRunner, cwd);
+			if (!repoRoot || result.isError !== false) return next();
+			const store = await openPermitStore(stateFile(repoRoot));
+			for (const p of toConsume) {
+				const used = await store.consume(p.kind, p.feature);
+				await appendAudit(repoRoot, {
+					time: Date.now(),
+					event: used ? "consume" : "remind",
+					feature: p.feature,
+					kind: p.kind
+				});
+				ctx.logger?.info?.(`gitflow-guard: ${used ? "已消费" : "未找到"}特许 ${p.kind} for ${p.feature}`);
+			}
+			return next();
+		} catch (e) {
+			ctx.logger?.warn?.(`gitflow-guard: 特许消费失败: ${e.message}`);
+			return next();
+		}
+	});
+	ctx.on("session/event", async (session, event) => {
+		try {
+			if (event.type !== "user/message") return;
+			const data = event.data;
+			if (data.source?.kind !== "user") return;
+			const text = messageText(data);
+			if (!text) return;
+			const cwd = session.header.cwd ?? process.cwd();
+			const repoRoot = await findRepoRoot(gitRunner, cwd);
+			if (!repoRoot) return;
+			const { config } = await loadConfig(repoRoot);
+			if (!config?.enabled) return;
+			const parsed = parseConfirmation(text, config);
+			if (!parsed) return;
+			await (await openPermitStore(stateFile(repoRoot))).grant(parsed.kind, parsed.feature, pluginConfig.permitTtlMs != null ? { ttlMs: pluginConfig.permitTtlMs } : void 0);
+			await appendAudit(repoRoot, {
+				time: Date.now(),
+				event: "grant",
+				feature: parsed.feature,
+				kind: parsed.kind
+			});
+			ctx.logger?.info?.(`gitflow-guard: 已记录特许 ${parsed.kind} for ${parsed.feature}`);
+		} catch (e) {
+			ctx.logger?.warn?.(`gitflow-guard: 确认解析失败: ${e.message}`);
+		}
+	});
+}
+//#endregion
+export { stateDir as a, gitRunner as c, loadConfig as d, name as i, isAncestor as l, apply as n, currentBranch as o, evaluateCommand as r, findRepoRoot as s, appendAudit as t, openPermitStore as u };