agents-gitflow-guard 0.0.1 → 0.0.3

package/lib/src-LvZrsHEn.mjs

@@ -0,0 +1,890 @@
+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 },
+	locale: "en"
+};
+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: ["Branch role must be an array or { branches: [...] }"]
+	};
+	if (!Array.isArray(arr) || arr.length === 0 || !arr.every((x) => typeof x === "string" && x !== "")) errors.push("branches must be a non-empty array of strings");
+	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 must be \"pr\" or \"flexible\"");
+	if (mergeBy === void 0 || mergeBy === "user" || mergeBy === "anyone") role.mergeBy = mergeBy === void 0 ? defaultMergeBy : mergeBy;
+	else errors.push("mergeBy must be \"user\" or \"anyone\"");
+	return {
+		role,
+		errors
+	};
+}
+/** 合并默认值并校验; 任何校验错误都会导致未启用 */
+function mergeConfig(raw) {
+	const errors = [];
+	if (typeof raw !== "object" || raw === null) return {
+		config: null,
+		errors: ["Config file must be a JSON object"]
+	};
+	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;
+	if (r.locale === "en" || r.locale === "zh") config.locale = r.locale;
+	else if (r.locale !== void 0) errors.push("locale must be \"en\" or \"zh\"");
+	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 is required");
+	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 is required");
+	try {
+		new RegExp(config.featurePattern);
+	} catch {
+		errors.push(`featurePattern is not a valid regex: ${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]} and branches.${allRoles[j]} share the same entries`);
+		}
+	}
+	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: [`Failed to read config file: ${e.message}`]
+		};
+	}
+}
+//#endregion
+//#region src/i18n.ts
+const en = {
+	"role.integration": () => "integration branch",
+	"role.preview": () => "preview branch",
+	"role.production": () => "production branch",
+	"role.archive": () => "archive branch",
+	"role.feature": () => "feature branch",
+	"role.other": () => "other branch",
+	"head.unknown": () => "current branch",
+	"denyDeleteOrForce.why": (v) => `Protected branch "${v.branch}" may not be deleted or force-pushed`,
+	"denyDeleteOrForce.next": () => "Delete/force-push on a feature branch outside the protected branches; protected branches are managed by you.",
+	"pushAll.why": () => "--all/--mirror push would include protected branches",
+	"pushAll.next": () => "Push branch by branch with an explicit refspec.",
+	"pushDetached.why": () => "Cannot determine the push target (detached HEAD?)",
+	"pushDetached.next": () => "Specify the refspec explicitly, e.g. `git push origin <branch>`.",
+	"pushProtectedDelete.why": (v) => `Protected branch "${v.branch}" may not be deleted`,
+	"pushProtectedDirect.why": (v) => `Protected branch "${v.branch}" forbids direct push`,
+	"pushProtectedDirectForce.why": (v) => `Protected branch "${v.branch}" forbids direct push (force)`,
+	"mergeProtected.why": (v) => `Merging into ${v.role} is allowed only by the user`,
+	"mergeProtected.next": () => `Do the merge in your own terminal (or UI); the agent can't do it for you.`,
+	"mergeFeature.why": (v) => `${v.role} forbids local merge of a feature: use PR/MR`,
+	"mergeFeature.next": (v) => `Push the feature branch first, then open a PR/MR into ${v.branch}.`,
+	"prCreateNoTarget.why": () => "Cannot determine the PR/MR target branch",
+	"prCreateNoTarget.next": (v) => `Specify --base/--target-branch explicitly (e.g. \`gh pr create --base ${v.base}\`).`,
+	"prCreateArchive.why": () => "Archive branches are user-managed; PRs/MRs into them are not allowed",
+	"prCreateArchive.next": () => "Do the release/archive yourself in your terminal or UI.",
+	"prCreateHead.why": (v) => `Current branch (${v.head}) is not a feature branch, so it cannot be the source of a PR/MR into ${v.role}`,
+	"prCreateHead.next": () => "Open the PR/MR into integration/preview/production from a feature/topic branch.",
+	"prMergeProduction.why": () => "Merging into production is allowed only by you (click merge)",
+	"prMergeProduction.next": () => "Click merge yourself on the PR/MR page.",
+	"prMergeArchive.why": () => "Merging into an archive branch is allowed only by the user",
+	"prMergeArchive.next": () => "Let the user do the archive merge in their terminal or UI.",
+	"prMergeUnknown.why": () => "Cannot confirm the PR/MR target branch",
+	"prMergeUnknown.next": () => "Retry once gh/glab is available, or let the user handle it.",
+	"prMergeHead.why": () => "Cannot confirm the PR/MR target, and the head is not a feature branch",
+	"prMergeHead.next": () => "Confirm the platform CLI is available, or let the user handle it.",
+	"next.integration": (v) => `Integration branch (${v.branch}) is updated via PR/MR from a feature branch: push the feature first, then \`gh pr create --base ${v.branch}\` / \`glab mr create --target-branch ${v.branch}\`.`,
+	"next.preview": (v) => `Preview branch (${v.branch}) only accepts PR/MRs: open a PR/MR into it from a feature/release branch (content of ${v.base} etc. first goes into a feature release branch).`,
+	"next.production": (v) => `Production branch (${v.branch}) is PR/MR-only, and you click the merge yourself.`,
+	"next.archive": (v) => `Archive branch (${v.branch}) is user-managed only.`,
+	"next.unspecified": () => "Retry once the target branch is clear.",
+	"deny.header": (v) => `[gitflow-guard] blocked: ${v.why}`,
+	"deny.next": (v) => `Next: ${v.next}`,
+	"cli.unknownCommand": (v) => `[gitflow-guard] unknown subcommand: ${v.cmd}`,
+	"cli.cannotLocate": () => "Cannot locate a git repository",
+	"cli.statusTitle": (v) => `[gitflow-guard] status — ${v.repo}`,
+	"cli.statusDisabled": () => "Config: not enabled (no gitflow-guard.config.json or enabled=false)",
+	"cli.statusConfigError": (v) => `  config error: ${v.err}`,
+	"cli.statusEnabled": (v) => `Config: enabled | featurePattern: ${v.pattern}`,
+	"cli.statusIntegration": (v) => `Integration: ${v.list} (update=${v.mode})`,
+	"cli.statusPreview": (v) => `Preview: ${v.list} (update=${v.mode})`,
+	"cli.statusProduction": (v) => `Production: ${v.list} (update=${v.mode}, merge=${v.merge})`,
+	"cli.statusArchive": (v) => `Archive: ${v.list}`,
+	"cli.statusCurrentBranch": (v) => `Current branch: ${v.branch}`,
+	"cli.statusUnknownBranch": () => "(unknown)",
+	"cli.statusLocalBranches": () => "Local branches (by role):",
+	"cli.auditEmpty": () => "  No audit entries yet",
+	"cli.checkInternalError": (v) => `[gitflow-guard] check internal error, allowed through: ${v.msg}`,
+	"usage.text": () => `gitflow-guard — GitFlow guard CLI
+
+Usage:
+  gitflow-guard status [--repo <path>]
+  gitflow-guard audit [--lines <count>] [--repo <path>]
+  gitflow-guard check [--platform <claude|auto>] [--command "<cmd>"] [--repo <path>]
+  gitflow-guard --help
+
+Notes:
+  status/audit are read-only; the agent can self-inspect.
+  check reads the hook payload on stdin (exit 0 = allow / 2 = block) and is meant for
+  pre/post hooks of agents such as Claude Code.`
+};
+const zh = {
+	"role.integration": () => "集成分支",
+	"role.preview": () => "预览分支",
+	"role.production": () => "生产分支",
+	"role.archive": () => "归档分支",
+	"role.feature": () => "feature 分支",
+	"role.other": () => "普通分支",
+	"head.unknown": () => "当前分支",
+	"denyDeleteOrForce.why": (v) => `受保护分支「${v.branch}」禁止删除或强推`,
+	"denyDeleteOrForce.next": () => "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理",
+	"pushAll.why": () => "--all/--mirror 推送会包含受保护分支",
+	"pushAll.next": () => "请逐分支推送并显式指定 refspec",
+	"pushDetached.why": () => "无法确定推送目标分支(可能处于 detached HEAD)",
+	"pushDetached.next": () => "请显式指定 refspec, 如 git push origin <分支名>",
+	"pushProtectedDelete.why": (v) => `受保护分支「${v.branch}」禁止删除`,
+	"pushProtectedDirect.why": (v) => `受保护分支「${v.branch}」禁止直推`,
+	"pushProtectedDirectForce.why": (v) => `受保护分支「${v.branch}」禁止直推(含强推)`,
+	"mergeProtected.why": (v) => `合入${v.role}仅允许用户亲手执行`,
+	"mergeProtected.next": () => "请在你自己终端(或 UI)完成该合并; agent 不能替你操作",
+	"mergeFeature.why": (v) => `${v.role}禁止本地合入 feature: 须通过 PR/MR`,
+	"mergeFeature.next": (v) => `先推 feature 分支, 再创建指向 ${v.branch} 的 PR/MR`,
+	"prCreateNoTarget.why": () => "无法确定 PR/MR 目标分支",
+	"prCreateNoTarget.next": (v) => `请显式指定 --base/--target-branch(如 gh pr create --base ${v.base})`,
+	"prCreateArchive.why": () => "归档分支(archive)仅用户亲手操作, 不允许创建指向它的 PR/MR",
+	"prCreateArchive.next": () => "发布/归档由你自己在终端或 UI 完成",
+	"prCreateHead.why": (v) => `当前分支(${v.head})不是 feature 分支, 不能作为指向${v.role}的 PR/MR 源`,
+	"prCreateHead.next": () => "请从 feature/topic 分支上创建指向集成/预览/生产分支的 PR/MR",
+	"prMergeProduction.why": () => "合入生产(production)分支仅允许用户亲手点合并",
+	"prMergeProduction.next": () => "请在 GitLab/GitHub 的 MR/PR 页面上由你本人点击合并",
+	"prMergeArchive.why": () => "合入归档分支(archive)仅允许用户亲手执行",
+	"prMergeArchive.next": () => "请让用户在自己终端或 UI 完成归档合并",
+	"prMergeUnknown.why": () => "无法确认 PR/MR 的目标分支",
+	"prMergeUnknown.next": () => "请确认 gh/glab 可用后重试, 或让用户亲手处理",
+	"prMergeHead.why": () => "无法确认 PR/MR 目标, 且 head 不是 feature 分支",
+	"prMergeHead.next": () => "请确认平台 CLI 可用, 或让用户亲手处理",
+	"next.integration": (v) => `集成分支(${v.branch})由 PR/MR 合入 feature: 先推 feature 分支, 再 gh pr create --base ${v.branch} / glab mr create --target-branch ${v.branch}`,
+	"next.preview": (v) => `预览分支(${v.branch})只收 PR/MR: 从 feature/发布分支创建指向它的 PR/MR(${v.base} 等集成分支内容先进 feature 发布分支)`,
+	"next.production": (v) => `生产分支(${v.branch})只能 PR/MR, 且合并由你亲手点击`,
+	"next.archive": (v) => `归档分支(${v.branch})仅用户亲手操作`,
+	"next.unspecified": () => "请明确目标分支后重试",
+	"deny.header": (v) => `[gitflow-guard] 已拦截: ${v.why}`,
+	"deny.next": (v) => `下一步: ${v.next}`,
+	"cli.unknownCommand": (v) => `[gitflow-guard] 未知子命令: ${v.cmd}`,
+	"cli.cannotLocate": () => "无法定位 git 仓库",
+	"cli.statusTitle": (v) => `[gitflow-guard] status — ${v.repo}`,
+	"cli.statusDisabled": () => "配置: 未启用(不存在 gitflow-guard.config.json 或 enabled=false)",
+	"cli.statusConfigError": (v) => `  配置错误: ${v.err}`,
+	"cli.statusEnabled": (v) => `配置: 已启用 | featurePattern: ${v.pattern}`,
+	"cli.statusIntegration": (v) => `集成分支: ${v.list} (update=${v.mode})`,
+	"cli.statusPreview": (v) => `预览分支: ${v.list} (update=${v.mode})`,
+	"cli.statusProduction": (v) => `生产分支: ${v.list} (update=${v.mode}, 合并=${v.merge})`,
+	"cli.statusArchive": (v) => `归档分支: ${v.list}`,
+	"cli.statusCurrentBranch": (v) => `当前分支: ${v.branch}`,
+	"cli.statusUnknownBranch": () => "(未知)",
+	"cli.statusLocalBranches": () => "本地分支(按角色):",
+	"cli.auditEmpty": () => "  暂无审计记录",
+	"cli.checkInternalError": (v) => `[gitflow-guard] check 内部错误, 已放行: ${v.msg}`,
+	"usage.text": () => `gitflow-guard — GitFlow 流程守卫 CLI
+
+用法:
+  gitflow-guard status [--repo <路径>]
+  gitflow-guard audit [--lines <数量>] [--repo <路径>]
+  gitflow-guard check [--platform <claude|auto>] [--command "<cmd>"] [--repo <路径>]
+  gitflow-guard --help
+
+说明:
+  status/audit 只读, agent 可自查。
+  check 读 stdin hook payload 做门禁(exit 0=放行 / 2=拦截), 供 Claude Code 等 agent 的 pre/post hook 调用。`
+};
+const MESSAGE_KEYS = Object.keys(en);
+/** key 合法性与 en/zh 双字典完整性检查(开发期一次) */
+if (Object.keys(zh).length !== MESSAGE_KEYS.length || MESSAGE_KEYS.some((k) => !(k in zh))) throw new Error("i18n: en/zh 字典键不一致");
+/**
+* 生成翻译函数。未知 key 回退英文原文(开发/防御性)。
+*/
+function makeT(locale) {
+	const dict = locale === "zh" ? zh : en;
+	return (key, vars = {}) => {
+		const entry = dict[key] ?? en[key];
+		if (!entry) return key;
+		try {
+			return entry(vars);
+		} catch {
+			return key;
+		}
+	};
+}
+/** 解析配置里的 locale 值: 仅 'zh' 视为中文, 其余(含未定义)一律英文 */
+function resolveLocale(v) {
+	return v === "zh" ? "zh" : "en";
+}
+//#endregion
+//#region src/gate.ts
+const PROTECTED_ROLES = /* @__PURE__ */ new Set([
+	"integration",
+	"preview",
+	"production",
+	"archive"
+]);
+/** 判别的默认英文(纯函数裸调用/测试时默认; 运行时由 evaluateCommand 按配置 locale 注入) */
+const defaultT = makeT("en");
+/** 判定分支角色: 优先角色配置, 其次 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 deny(why, next) {
+	return {
+		kind: "deny",
+		reason: why,
+		next
+	};
+}
+/** 角色名展示: 集成分支(main) 等 */
+function roleLabel(role, t, branch) {
+	const label = t(`role.${role}`);
+	return branch ? `${label}(${branch})` : label;
+}
+function decide(classified, facts, config, t = defaultT) {
+	switch (classified.kind) {
+		case "push": return decidePush(classified, facts, config, t);
+		case "local-merge": return decideMerge(classified, facts, config, t);
+		case "pr-create": return decidePrCreate(classified, facts, config, t);
+		case "pr-merge": return decidePrMerge(classified, facts, config, t);
+		case "branch-delete": return isProtected(roleOfBranch(classified.branch, config)) ? deny(t("denyDeleteOrForce.why", { branch: classified.branch ?? "" }), t("denyDeleteOrForce.next")) : { kind: "allow" };
+		case "guard-cli": return { kind: "allow" };
+		case "checkout": return { kind: "allow" };
+		default: return { kind: "allow" };
+	}
+}
+function decidePush(c, facts, config, t) {
+	if (c.all) return deny(t("pushAll.why"), t("pushAll.next"));
+	const dst = c.dst ?? facts.currentBranch;
+	if (dst == null) return deny(t("pushDetached.why"), t("pushDetached.next"));
+	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" };
+		if (c.delete) return deny(t("pushProtectedDelete.why", { branch: dst }), branchNext(dst, config, t));
+		return deny(t(c.force ? "pushProtectedDirectForce.why" : "pushProtectedDirect.why", { branch: dst }), branchNext(dst, config, t));
+	}
+	return { kind: "allow" };
+}
+function decideMerge(c, facts, config, t) {
+	const currentRole = roleOfBranch(facts.currentBranch, config);
+	const source = c.source;
+	const sourceRole = source ? roleOfBranch(source, config) : null;
+	if (currentRole === "production" || currentRole === "archive") return deny(t("mergeProtected.why", { role: roleLabel(currentRole, t, facts.currentBranch) }), t("mergeProtected.next"));
+	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(t("mergeFeature.why", { role: roleLabel(currentRole, t, facts.currentBranch) }), t("mergeFeature.next", { branch: facts.currentBranch ?? "" }));
+	}
+	return { kind: "allow" };
+}
+function decidePrCreate(c, facts, config, t) {
+	if (c.target == null) return deny(t("prCreateNoTarget.why"), t("prCreateNoTarget.next", { 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(t("prCreateArchive.why"), t("prCreateArchive.next"));
+	if (targetRole === "integration" || targetRole === "preview" || targetRole === "production") {
+		if (headRole !== "feature") return deny(t("prCreateHead.why", {
+			head: head ?? t("head.unknown"),
+			role: roleLabel(targetRole, t, c.target)
+		}), t("prCreateHead.next"));
+		return { kind: "allow" };
+	}
+	return { kind: "allow" };
+}
+function decidePrMerge(c, facts, config, t) {
+	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(t("prMergeProduction.why"), t("prMergeProduction.next"));
+		return { kind: "allow" };
+	}
+	if (role === "archive") return deny(t("prMergeArchive.why"), t("prMergeArchive.next"));
+	if (role === "integration" || role === "preview") return { kind: "allow" };
+	if (role === "feature" || role === "other") return { kind: "allow" };
+	if (head == null) return deny(t("prMergeUnknown.why"), t("prMergeUnknown.next"));
+	if (roleOfBranch(head, config) === "feature") return { kind: "allow" };
+	return deny(t("prMergeHead.why"), t("prMergeHead.next"));
+}
+/** 受保护分支被拦后的下一步引导 */
+function branchNext(branch, config, t) {
+	if (branch == null) return t("next.unspecified");
+	const base = config.branches.integration.branches[0] ?? "";
+	switch (roleOfBranch(branch, config)) {
+		case "integration": return t("next.integration", { branch });
+		case "preview": return t("next.preview", {
+			branch,
+			base
+		});
+		case "production": return t("next.production", { branch });
+		default: return t("next.archive", { 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,
+		locale: "en"
+	};
+	const locale = resolveLocale(config.locale);
+	const t = makeT(locale);
+	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, t);
+		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,
+				locale
+			};
+		}
+		await logCiReference(seg, env);
+		if (seg.kind === "checkout" && seg.branch != null) simulatedBranch = seg.branch;
+	}
+	return {
+		outcome: "allow",
+		segmentCount: segments.length,
+		locale
+	};
+}
+/** 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(locale, why, next) {
+	const t = makeT(locale);
+	return `${t("deny.header", { why })}\n${t("deny.next", { 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.locale, 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, resolveLocale as d, loadConfig as f, formatDeny as i, gitRunner as l, classify as m, apply as n, stateDir as o, roleMatches as p, evaluateCommand as r, currentBranch as s, appendAudit as t, makeT as u };