agents-gitflow-guard 0.0.1 → 0.0.2

package/lib/src-Dv6jKDsO.mjs

@@ -0,0 +1,716 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+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 === "glab") return classifyGlab(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, ["--base", "-B"]);
+	if (action === "merge") return parsePrMerge(rest);
+	return [{ kind: "other" }];
+}
+/** GitLab: glab mr create --target-branch <b> / glab mr merge <id> */
+function classifyGlab(args) {
+	const [sub, action, ...rest] = args;
+	if (sub !== "mr") return [{ kind: "other" }];
+	if (action === "create") return parsePrCreate(rest, ["--target-branch"]);
+	if (action === "merge") return parsePrMerge(rest);
+	return [{ kind: "other" }];
+}
+function parsePrCreate(args, targetFlags) {
+	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];
+		const flag = targetFlags.find((f) => a === f || a.startsWith(`${f}=`));
+		if (!flag) continue;
+		if (a === flag) {
+			const value = args[i + 1];
+			if (value && !value.startsWith("-")) out.target = value;
+		} else out.target = a.slice(flag.length + 1) || 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) {
+	if (args[0] === "status") return "status";
+	return "other";
+}
+//#endregion
+//#region src/config.ts
+const CONFIG_FILE = "gitflow-guard.config.json";
+/** 默认配置(分支角色必须由项目显式配置, 无默认) */
+const DEFAULT_CONFIG = {
+	enabled: false,
+	featurePattern: "feature/[\\w-]+",
+	ci: { enabled: true }
+};
+const REGEX_CHARS = /[\\^$.*+?()[\]{}|]/;
+/** 一条分支条目: 含正则元字符按正则对待, 否则精确匹配 */
+function matchBranchSpec(branch, spec) {
+	if (REGEX_CHARS.test(spec)) try {
+		return new RegExp(`^(?:${spec})$`).test(branch);
+	} catch {
+		return false;
+	}
+	return branch === spec;
+}
+/** 判断分支是否命中某个角色(任一分支条目) */
+function roleMatches(branch, role) {
+	if (!branch) return false;
+	return role.branches.some((spec) => matchBranchSpec(branch, spec));
+}
+/** 规范化用户输入的某个角色: 数组 或 {branches:[...], update?, mergeBy?} */
+function normalizeRole(raw, defaultUpdate, defaultMergeBy) {
+	const errors = [];
+	let arr;
+	let update = void 0;
+	let mergeBy = void 0;
+	if (Array.isArray(raw)) arr = raw;
+	else if (typeof raw === "object" && raw !== null) {
+		const o = raw;
+		arr = o.branches;
+		update = o.update;
+		mergeBy = o.mergeBy;
+	} else return {
+		role: { branches: [] },
+		errors: ["分支角色必须是数组或 { branches: [...] }"]
+	};
+	if (!Array.isArray(arr) || arr.length === 0 || !arr.every((x) => typeof x === "string" && x !== "")) errors.push("branches 必须是非空字符串数组");
+	const role = { branches: (Array.isArray(arr) ? arr : []).filter((x) => typeof x === "string" && x !== "") };
+	if (update === void 0 || update === "pr" || update === "flexible") role.update = update === void 0 ? defaultUpdate : update;
+	else errors.push("update 必须是 \"pr\" 或 \"flexible\"");
+	if (mergeBy === void 0 || mergeBy === "user" || mergeBy === "anyone") role.mergeBy = mergeBy === void 0 ? defaultMergeBy : mergeBy;
+	else errors.push("mergeBy 必须是 \"user\" 或 \"anyone\"");
+	return {
+		role,
+		errors
+	};
+}
+/** 合并默认值并校验; 任何校验错误都会导致未启用 */
+function mergeConfig(raw) {
+	const errors = [];
+	if (typeof raw !== "object" || raw === null) return {
+		config: null,
+		errors: ["配置文件必须是 JSON 对象"]
+	};
+	const r = raw;
+	const config = {
+		...DEFAULT_CONFIG,
+		ci: { ...DEFAULT_CONFIG.ci },
+		branches: { integration: {
+			branches: [],
+			update: "pr",
+			mergeBy: "anyone"
+		} }
+	};
+	if (typeof r.enabled === "boolean") config.enabled = r.enabled;
+	if (typeof r.featurePattern === "string" && r.featurePattern !== "") config.featurePattern = r.featurePattern;
+	const b = r.branches ?? {};
+	if ("integration" in b) {
+		const { role, errors: e } = normalizeRole(b.integration, "pr", "anyone");
+		config.branches.integration = role;
+		errors.push(...e);
+	} else errors.push("branches.integration 必填");
+	if (b.preview !== void 0) {
+		const { role, errors: e } = normalizeRole(b.preview, "pr", "anyone");
+		config.branches.preview = role;
+		errors.push(...e);
+	}
+	if (b.production !== void 0) {
+		const { role, errors: e } = normalizeRole(b.production, "pr", "user");
+		config.branches.production = role;
+		errors.push(...e);
+	}
+	if (b.archive !== void 0) {
+		const { role, errors: e } = normalizeRole(b.archive, "pr", "user");
+		config.branches.archive = role;
+		errors.push(...e);
+	}
+	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
+	};
+}
+/** 配置校验: 角色分支重叠 / 正则合法等 */
+function validateConfig(config) {
+	const errors = [];
+	if (config.branches.integration.branches.length === 0) errors.push("branches.integration.branches 必填");
+	try {
+		new RegExp(config.featurePattern);
+	} catch {
+		errors.push(`featurePattern 不是合法正则: ${config.featurePattern}`);
+	}
+	const allRoles = [
+		"integration",
+		"preview",
+		"production",
+		"archive"
+	];
+	for (let i = 0; i < allRoles.length; i++) {
+		const a = config.branches[allRoles[i]];
+		if (!a) continue;
+		for (let j = i + 1; j < allRoles.length; j++) {
+			const bb = config.branches[allRoles[j]];
+			if (!bb) continue;
+			if (a.branches.some((s) => bb.branches.includes(s))) errors.push(`branches.${allRoles[i]} 与 branches.${allRoles[j]} 含有相同条目`);
+		}
+	}
+	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 = "当前分支";
+const PROTECTED_ROLES = /* @__PURE__ */ new Set([
+	"integration",
+	"preview",
+	"production",
+	"archive"
+]);
+/** 判定分支角色: 优先角色配置, 其次 featurePattern, 其余 other */
+function roleOfBranch(branch, config) {
+	if (!branch) return "other";
+	if (config.branches.production && roleMatches(branch, config.branches.production)) return "production";
+	if (config.branches.preview && roleMatches(branch, config.branches.preview)) return "preview";
+	if (config.branches.integration && roleMatches(branch, config.branches.integration)) return "integration";
+	if (config.branches.archive && roleMatches(branch, config.branches.archive)) return "archive";
+	try {
+		if (new RegExp(config.featurePattern).test(branch)) return "feature";
+	} catch {}
+	return "other";
+}
+function isProtected(role) {
+	return PROTECTED_ROLES.has(role);
+}
+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(roleOfBranch(classified.branch, config)) ? deny(`受保护分支「${classified.branch}」禁止删除或强推`, "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理") : { kind: "allow" };
+		case "guard-cli": return { 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 <分支名>");
+	const role = roleOfBranch(dst, config);
+	if (isProtected(role)) {
+		const flexRole = role === "integration" ? config.branches.integration : config.branches.preview;
+		if ((role === "integration" || role === "preview") && flexRole?.update === "flexible" && !c.delete) return { kind: "allow" };
+		return deny(c.delete ? `受保护分支「${dst}」禁止删除` : `受保护分支「${dst}」禁止直推${c.force ? "(含强推)" : ""}`, branchNext(dst, config));
+	}
+	return { kind: "allow" };
+}
+function decideMerge(c, facts, config) {
+	const currentRole = roleOfBranch(facts.currentBranch, config);
+	const source = c.source;
+	const sourceRole = source ? roleOfBranch(source, config) : null;
+	if (currentRole === "production" || currentRole === "archive") return deny(`合入${roleLabel(currentRole, facts.currentBranch)}仅允许用户亲手执行`, "请在你自己终端(或 UI)完成该合并; agent 不能替你操作");
+	if (currentRole === "integration" || currentRole === "preview") {
+		if (source == null) return { kind: "allow" };
+		if (sourceRole != null && isProtected(sourceRole)) return { kind: "allow" };
+		if ((currentRole === "integration" ? config.branches.integration : config.branches.preview)?.update === "flexible") return { kind: "allow" };
+		return deny(`${roleLabel(currentRole, facts.currentBranch)}(${facts.currentBranch})禁止本地合入 feature: 须通过 PR/MR`, `先推 feature 分支, 再创建指向 ${facts.currentBranch} 的 PR/MR`);
+	}
+	return { kind: "allow" };
+}
+function decidePrCreate(c, facts, config) {
+	if (c.target == null) return deny("无法确定 PR/MR 目标分支", `请显式指定 --base/--target-branch(如 gh pr create --base ${config.branches.integration.branches[0]})`);
+	const targetRole = roleOfBranch(c.target, config);
+	const head = facts.currentBranch;
+	const headRole = roleOfBranch(head, config);
+	if (targetRole === "archive") return deny("归档分支(archive)仅用户亲手操作, 不允许创建指向它的 PR/MR", "发布/归档由你自己在终端或 UI 完成");
+	if (targetRole === "integration" || targetRole === "preview" || targetRole === "production") {
+		if (headRole !== "feature") return deny(`当前分支(${head ?? FEATURE_UNKNOWN})不是 feature 分支, 不能作为指向${roleLabel(targetRole, c.target)}的 PR/MR 源`, "请从 feature/topic 分支上创建指向集成/预览/生产分支的 PR/MR");
+		return { kind: "allow" };
+	}
+	return { kind: "allow" };
+}
+function decidePrMerge(c, facts, config) {
+	const resolved = facts.resolvePrTarget?.(c.pr) ?? null;
+	const role = resolved?.role ?? null;
+	const head = resolved?.head ?? facts.currentBranch;
+	if (role === "production") {
+		if (config.branches.production?.mergeBy === "user") return deny("合入生产(production)分支仅允许用户亲手点合并", "请在 GitLab/GitHub 的 MR/PR 页面上由你本人点击合并");
+		return { kind: "allow" };
+	}
+	if (role === "archive") return deny("合入归档分支(archive)仅允许用户亲手执行", "请让用户在自己终端或 UI 完成归档合并");
+	if (role === "integration" || role === "preview") return { kind: "allow" };
+	if (role === "feature" || role === "other") return { kind: "allow" };
+	if (head == null) return deny("无法确认 PR/MR 的目标分支", "请确认 gh/glab 可用后重试, 或让用户亲手处理");
+	if (roleOfBranch(head, config) === "feature") return { kind: "allow" };
+	return deny("无法确认 PR/MR 目标, 且 head 不是 feature 分支", "请确认平台 CLI 可用, 或让用户亲手处理");
+}
+function deny(reason, next) {
+	return {
+		kind: "deny",
+		reason,
+		next
+	};
+}
+function roleLabel(role, branch) {
+	const map = {
+		integration: "集成分支",
+		preview: "预览分支",
+		production: "生产分支",
+		archive: "归档分支",
+		feature: "feature 分支",
+		other: "普通分支"
+	};
+	return branch ? `${map[role]}(${branch})` : map[role];
+}
+/** 受保护分支被拦后的下一步引导 */
+function branchNext(branch, config) {
+	if (branch == null) return "请明确目标分支后重试";
+	const base = config.branches.integration.branches[0] ?? "集成分支";
+	switch (roleOfBranch(branch, config)) {
+		case "integration": return `集成分支(${branch})由 PR/MR 合入 feature: 先推 feature 分支, 再 gh pr create --base ${branch} / glab mr create --target-branch ${branch}`;
+		case "preview": return `预览分支(${branch})只收 PR/MR: 从 feature/发布分支创建指向它的 PR/MR(${base} 等集成分支内容先进 feature 发布分支)`;
+		case "production": return `生产分支(${branch})只能 PR/MR, 且合并由你亲手点击`;
+		default: return `归档分支(${branch})仅用户亲手操作`;
+	}
+}
+//#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");
+/** GitHub 适配器: gh */
+const ghRunner = makeRunner("gh");
+/** GitLab 适配器: glab */
+const glabRunner = makeRunner("glab");
+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;
+}
+/** gh pr view: 返回 base/head 分支名; PR 不存在或 gh 不可用 → null */
+async function ghPrInfo(runner, cwd, pr) {
+	return viewPrInfo(runner, pr ? [
+		"pr",
+		"view",
+		pr,
+		"--json",
+		"baseRefName,headRefName"
+	] : [
+		"pr",
+		"view",
+		"--json",
+		"baseRefName,headRefName"
+	], cwd, ["baseRefName", "headRefName"]);
+}
+/** glab mr view: 返回 target(基地)/source(源) 分支名; 失败返回 null */
+async function glabMrInfo(runner, cwd, mr) {
+	const args = mr ? [
+		"mr",
+		"view",
+		mr,
+		"--output",
+		"json"
+	] : [
+		"mr",
+		"view",
+		"--output",
+		"json"
+	];
+	const r = await runner.run(args, cwd);
+	if (r.code !== 0) return null;
+	try {
+		const j = JSON.parse(r.stdout);
+		if (typeof j.target_branch === "string" && typeof j.source_branch === "string") return {
+			base: j.target_branch,
+			head: j.source_branch
+		};
+		return null;
+	} catch {
+		return null;
+	}
+}
+async function viewPrInfo(runner, args, cwd, fields) {
+	const r = await runner.run(args, cwd);
+	if (r.code !== 0) return null;
+	try {
+		const j = JSON.parse(r.stdout);
+		if (typeof j[fields[0]] === "string" && typeof j[fields[1]] === "string") return {
+			base: j[fields[0]],
+			head: j[fields[1]]
+		};
+		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/MR 的 base(target) 分支映射为角色; 无法解析返回 null */
+function resolvePrTarget(info, config) {
+	if (!info) return null;
+	return {
+		target: info.base,
+		role: roleOfBranch(info.base, config),
+		head: info.head
+	};
+}
+//#endregion
+//#region src/index.ts
+const name = "gitflow-guard";
+function stateDir(repoRoot) {
+	return join(repoRoot, ".git", "gitflow-guard");
+}
+/** 审计留痕; 失败不阻断门禁 */
+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 glab = opts.glabRunner ?? glabRunner;
+	const { config } = await loadConfig(opts.repoRoot);
+	if (!config?.enabled) return {
+		outcome: "skipped",
+		segmentCount: 0
+	};
+	const branch = opts.currentBranch ?? await currentBranch(runner, opts.repoRoot);
+	const env = {
+		repoRoot: opts.repoRoot,
+		config,
+		branch,
+		runner,
+		gh,
+		glab
+	};
+	const segments = classify(command, { currentBranch: branch });
+	let simulatedBranch = branch;
+	for (const seg of segments) {
+		const { facts } = 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
+			};
+		}
+		await logCiReference(seg, env);
+		if (seg.kind === "checkout" && seg.branch != null) simulatedBranch = seg.branch;
+	}
+	return {
+		outcome: "allow",
+		segmentCount: segments.length
+	};
+}
+/** 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",
+		command: seg.pr ?? void 0,
+		role: state
+	});
+}
+/** 按段预取 git 事实(异步 I/O 全部前置, 门禁保持纯函数) */
+async function factsFor(seg, env) {
+	const { config, repoRoot, branch } = env;
+	let head = null;
+	let prRes = null;
+	if (seg.kind === "pr-merge") {
+		prRes = resolvePrTarget(await ghPrInfo(env.gh, repoRoot, seg.pr), config);
+		if (!prRes) prRes = resolvePrTarget(await glabMrInfo(env.glab, repoRoot, seg.pr), config);
+		head = prRes?.head ?? branch;
+	}
+	return {
+		head,
+		facts: {
+			currentBranch: branch,
+			...prRes ? { resolvePrTarget: () => prRes } : {}
+		}
+	};
+}
+function commandText(exec) {
+	const args = exec.arguments;
+	return typeof args?.command === "string" ? args.command : "";
+}
+function formatDeny(why, next) {
+	return `[gitflow-guard] 已拦截: ${why}\n下一步: ${next}`;
+}
+function apply(ctx, pluginConfig = {}) {
+	const toolNames = new Set(pluginConfig.toolNames ?? ["pwsh", "bash"]);
+	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)
+			};
+			return next();
+		} catch (e) {
+			ctx.logger?.warn?.(`gitflow-guard: 门禁内部错误, 已放行: ${e.message}`);
+			return next();
+		}
+	});
+}
+//#endregion
+export { name as a, findRepoRoot as c, roleMatches as d, classify as f, formatDeny as i, gitRunner as l, apply as n, stateDir as o, evaluateCommand as r, currentBranch as s, appendAudit as t, loadConfig as u };