agents-gitflow-guard 0.0.11 → 0.0.12

package/README.md

@@ -42,7 +42,7 @@ You define your own branches —
 # installs the latest release
 dsh plugin --profile web add agents-gitflow-guard
 # ...or pin an exact known-good version (recommended; also bypasses stale registry caches)
-dsh plugin --profile web add agents-gitflow-guard@0.0.9
+dsh plugin --profile web add agents-gitflow-guard@0.0.12
 ```
 
 > **Version gotcha**: a bare `add` resolves whatever `latest` is at install time — on machines behind a stale npm/pnpm registry cache or mirror it may install an old version. If the installed version looks wrong, pin it explicitly. The peer-dependency *warning* pnpm may print is expected: DSH supplies `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools` through its shared profile module fallback at startup (the plugin works normally).
@@ -256,7 +256,7 @@ archive (optional; you archive after release)
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // optional
     "archive":     ["main"]                                      // optional
   },
-  "locale": "en",                      // optional: message language ('en' default, or 'zh')
+  "locale": "en",                      // optional: message language — any registered locale ('en'/'zh' built-in); unknown values warn in status and fall back to English
   "strict": false,                     // optional: fail-closed — invalid config / internal errors block instead of warn-and-allow
   "ci": { "enabled": true }            // optional: gh pr checks logged as reference
 }
@@ -265,8 +265,10 @@ archive (optional; you archive after release)
 - Roles accept either an **array** (shorthand) or an **object** `{ branches, update?, mergeBy? }`.
 - `update`: `pr` (default) = updates only via PR/MR; `flexible` = allow direct/local merges (small teams).
 - `mergeBy` (production): `user` (default) = only you click merge; `anyone` = allow PR merge through.
-- Each branch entry is an exact name or a regex (auto-detected).
-- **Language**: messages are English by default; add `"locale": "zh"` for Chinese.
+- Each branch entry is an exact name or a regex (auto-detected). **Regex safety**: branch patterns are authored by you and compiled as-is — avoid catastrophic-backtracking constructs (e.g. nested quantifiers like `(\w+)+`) in `featurePattern` and branch entries.
+- **Language**: messages are English by default; add `"locale": "zh"` for Chinese, or pass `--locale <en|zh>` to any `gitflow-guard` subcommand (priority: CLI flag > project config > English). All user-facing text follows the locale — including CLI framework messages such as `--help`, unknown-command notices, and the empty-audit line.
+- **Custom locales**: downstream packages can add a language at runtime — `import { registerLocale } from 'agents-gitflow-guard'`, call `registerLocale('fr', frDict)` with a dictionary covering exactly the same keys as built-in English (validated on registration), then set `"locale": "fr"` in the project config to activate it.
+- **Unknown locales**: an unregistered `"locale"` value falls back to English during interception (by design — hooks never stall on wording), so a typo is easy to miss; the one-line warning shows up in `gitflow-guard status`.
 - **Validation**: `integration` is required; overlapping role entries are rejected; invalid regex is rejected. **Any error disables the plugin for that project** (reported) rather than applying a half-guessed setup.
 - **Strict mode**: by default a broken config warns on stderr once and lets the command pass (fail-open, so a typo can't wedge your tooling). `"strict": true` flips config errors and internal errors to **block** (fail-closed) — for high-risk repos. A missing file or explicit `enabled: false` stays silent either way.
 
@@ -301,7 +303,7 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 **From the npm registry** — the standard path, already covered in [Quick Start](#quick-start--30-seconds-to-a-guarded-repo):
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.9    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.12    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -421,7 +423,7 @@ The blocks are reserved for: (1) direct writes to protected role branches, and (
 
 ### What if my config has a mistake?
 
-The plugin prefers failing closed: any validation error disables the guard for that project and reports the errors, so a half-guessed setup never applies by accident.
+A half-guessed setup is never applied by accident: any validation error disables the guard for that project and reports the errors.
 
 Common mistakes: missing `integration` (required), overlapping a branch across two roles (rejected explicitly), and a `featurePattern` that doesn't compile (rejected as invalid regex). The failure is loud and the file is one JSON object, so the fix is usually a thirty-second correction.
 
@@ -483,7 +485,7 @@ npm install
 npm test          # unit tests: classify / gate / config / cli / repo / platform
 npm run typecheck     # tsc --noEmit, 0 errors
 npm run build         # tsdown → lib/ (CLI and plugin share the build)
-npm run verify:matrix # continuous cross-agent regression: DSH logic + Claude Code / Codex / antigravity hook wiring
+npm run verify:matrix # continuous cross-agent regression: DSH logic + zh-locale regression + Claude Code / Codex / OpenCode / Antigravity hook wiring
 ```
 
 **Rule**: any logic change must pass a 0-error build + all green tests + a green `verify:matrix` before done.

package/README.zh.md

@@ -41,7 +41,7 @@
 # 安装最新版
 dsh plugin --profile web add agents-gitflow-guard
 # ...或锁定已知良好版本(推荐; 同时绕开 registry 陈旧缓存)
-dsh plugin --profile web add agents-gitflow-guard@0.0.9
+dsh plugin --profile web add agents-gitflow-guard@0.0.12
 ```
 
 > **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
@@ -253,7 +253,7 @@ archive(可选, 发布后你亲手归档)
     "production":  { "branches": ["prd"], "update": "pr", "mergeBy": "user" }, // 可选
     "archive":     ["main"]                                      // 可选
   },
-  "locale": "en",                      // 可选: 文案语言('en' 默认, 或 'zh')
+  "locale": "en",                      // 可选: 文案语言——任意已注册 locale('en'/'zh' 内置); 未注册值在 status 告警并回退英文
   "strict": false,                     // 可选: fail-closed —— 配置异常/内部错误改为拦截, 而非告警放行
   "ci": { "enabled": true }            // 可选: gh pr checks 作参考日志
 }
@@ -262,8 +262,10 @@ archive(可选, 发布后你亲手归档)
 - 每个角色既可用**数组**(简写),也可用**对象** `{ branches, update?, mergeBy? }`。
 - `update`:`pr`(默认)= 只能 PR/MR 合入;`flexible` = 允许直推/本地合入(小团队)。
 - `mergeBy`(生产):`user`(默认)= 只能你点合并;`anyone` = 放行 PR 合并。
-- 每条分支条目是精确名或正则(自动识别)。
-- **文案语言**:默认英文;加 `"locale": "zh"` 切中文。
+- 每条分支条目是精确名或正则(自动识别)。**正则安全**:分支正则由项目作者提供并按原样编译——`featurePattern` 与分支条目请避免灾难性回溯写法(如 `(\w+)+` 这类嵌套量词)。
+- **文案语言**:默认英文;加 `"locale": "zh"` 切中文,或给任意 `gitflow-guard` 子命令传 `--locale <en|zh>`(优先级:CLI 旗标 > 项目配置 > 英文)。全部用户可见文案都跟随 locale——包括 `--help`、未知子命令提示、审计为空的提示等 CLI 框架文案。
+- **自定义语言**:下游包可在运行时追加语言——`import { registerLocale } from 'agents-gitflow-guard'`,调用 `registerLocale('fr', frDict)` 注册一份与内置英文键完全一致的字典(注册时校验),再在项目配置写 `"locale": "fr"` 即生效。
+- **未注册语言**:拦截路径对未注册的 `"locale"` 静默回退英文(设计如此——hook 不因文案缺失卡死),笔误因此容易被忽略;一行告警在 `gitflow-guard status` 中可见。
 - **校验**:`integration` 必填;角色条目重叠会被拒;非法正则会报错。**任何错误都会让该项目的插件禁用并上报**(而不是用半吊子配置)。
 - **strict 模式**:默认配置损坏时 stderr 告警一次后放行(fail-open,避免一个笔误卡死工具管道);`"strict": true` 把配置异常与内部错误翻转为**拦截**(fail-closed)——供高风险仓库选用。文件不存在或显式 `enabled: false` 两种模式下都保持静默。
 
@@ -298,7 +300,7 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 **从 npm registry**——标准路径,已在[快速开始](#快速开始30-秒用上)覆盖:
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard@0.0.9    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.12    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -418,7 +420,7 @@ hooks:
 
 ### 配置写错了会怎样?
 
-插件偏好 fail-closed:任何校验错误都会让该项目的守卫禁用并上报错误,半吊子配置绝不会意外生效。
+半吊子配置绝不会意外生效:任何校验错误都会让该项目的守卫禁用并上报错误。
 
 常见错误:`integration` 缺失(必填)、同一个分支被配到两个角色里(显式拒绝)、`featurePattern` 写不成合法正则(报错)。失败提示很明确,文件又是一个 JSON 对象,通常三十秒改好。
 
@@ -480,9 +482,10 @@ npm install
 npm test          # 单测: classify / gate / config / cli / repo / platform
 npm run typecheck     # tsc --noEmit, 0 Error
 npm run build         # tsdown → lib/(CLI 与插件共用)
+npm run verify:matrix # 连续复测矩阵: DSH 逻辑 + zh 文案回归 + Claude Code / Codex / OpenCode / Antigravity hook 编码
 ```
 
-**铁律**:任何逻辑改动必须 0 Error 构建 + 单测全绿后才算完成。
+**铁律**:任何逻辑改动必须 0 Error 构建 + 单测全绿 + 连续复测矩阵(`verify:matrix`)全绿后才算完成。
 
 ---
 

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { c as findRepoRoot, d as resolveLocale, f as loadConfig, i as formatDeny, l as gitRunner, m as classify, o as stateDir, p as roleMatches, r as evaluateCommand, s as currentBranch, u as makeT } from "./src-DTg5WMog.mjs";
+import { c as findRepoRoot, d as roleMatches, f as makeT, h as classify, i as formatDeny, l as gitRunner, m as resolveLocale, o as stateDir, r as evaluateCommand, s as currentBranch, u as loadConfig } from "./src-CPX1Ks_Z.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts
@@ -94,31 +94,45 @@ function parseFlags(argv) {
 		else if (a === "--lines") flags.lines = Number(next());
 		else if (a === "--platform") flags.platform = next();
 		else if (a === "--command") flags.command = next();
+		else if (a === "--locale") flags.locale = next();
 		else if (a.startsWith("--repo=")) flags.repo = a.slice(7);
 		else if (a.startsWith("--lines=")) flags.lines = Number(a.slice(8));
 		else if (a.startsWith("--platform=")) flags.platform = a.slice(11);
 		else if (a.startsWith("--command=")) flags.command = a.slice(10);
+		else if (a.startsWith("--locale=")) flags.locale = a.slice(9);
 	}
 	return flags;
 }
-async function resolveRepo(flags) {
+async function resolveRepo(flags, runner) {
 	if (flags.repo) return flags.repo;
-	return await findRepoRoot(gitRunner, process.cwd());
+	return await findRepoRoot(runner, process.cwd());
+}
+/** CLI 文案 locale 解析(P2-1): --locale 旗标 > 项目 config.locale > en; 白名单外一律 en */
+function cliLocale(flags, configLocale) {
+	return resolveLocale(flags.locale ?? configLocale);
+}
+/** 无 config 在手时的 locale 解析(help / unknownCommand 等框架路径): 旗标优先, 否则定位仓库读配置 */
+async function resolveFrameworkLocale(flags, runner) {
+	if (flags.locale != null) return resolveLocale(flags.locale);
+	const repoRoot = await resolveRepo(flags, runner);
+	if (!repoRoot) return "en";
+	const { config } = await loadConfig(repoRoot);
+	return resolveLocale(config?.locale);
 }
 async function main(argv, opts = {}) {
 	const runner = opts.runner ?? gitRunner;
-	const usage = makeT("en")("usage.text");
 	const [cmd, ...rest] = argv;
+	const flags = parseFlags(rest);
 	if (cmd === "--help" || cmd === "help" || cmd === void 0) {
-		console.log(usage);
+		console.log(makeT(await resolveFrameworkLocale(flags, runner))("usage.text"));
 		return 0;
 	}
-	const flags = parseFlags(rest);
 	try {
 		if (cmd === "status") return await status(flags, runner);
 		if (cmd === "audit") return await audit(flags);
 		if (cmd === "check") return await check(flags);
-		console.error(`${makeT("en")("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${usage}`);
+		const t = makeT(await resolveFrameworkLocale(flags, runner));
+		console.error(`${t("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${t("usage.text")}`);
 		return 1;
 	} catch (e) {
 		console.error(`[gitflow-guard] ${e.message}`);
@@ -126,20 +140,22 @@ async function main(argv, opts = {}) {
 	}
 }
 async function status(flags, runner) {
-	const repoRoot = await resolveRepo(flags);
+	const repoRoot = await resolveRepo(flags, runner);
 	if (!repoRoot) {
-		console.error(makeT("en")("cli.cannotLocate"));
+		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
 		return 1;
 	}
-	const { config, errors } = await loadConfig(repoRoot);
+	const { config, errors, warnings } = await loadConfig(repoRoot);
 	const enabled = config?.enabled === true;
-	const t = makeT(resolveLocale(config?.locale));
+	const t = makeT(cliLocale(flags, config?.locale));
 	console.log(t("cli.statusTitle", { repo: repoRoot }));
 	if (!enabled) {
 		console.log(t("cli.statusDisabled"));
 		for (const e of errors) console.log(t("cli.statusConfigError", { err: e }));
+		for (const w of warnings) console.log(t("cli.statusConfigWarning", { warn: w }));
 		return 0;
 	}
+	for (const w of warnings) console.log(t("cli.statusConfigWarning", { warn: w }));
 	const branch = await currentBranch(runner, repoRoot);
 	const c = config;
 	console.log(t("cli.statusEnabled", { pattern: c.featurePattern }));
@@ -177,22 +193,24 @@ async function status(flags, runner) {
 	return 0;
 }
 async function audit(flags) {
-	const repoRoot = await resolveRepo(flags);
+	const repoRoot = await resolveRepo(flags, gitRunner);
 	if (!repoRoot) {
-		console.error(makeT("en")("cli.cannotLocate"));
+		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
 		return 1;
 	}
+	const { config } = await loadConfig(repoRoot);
+	const t = makeT(cliLocale(flags, config?.locale));
 	const lines = flags.lines != null && Number.isFinite(flags.lines) && flags.lines > 0 ? Math.floor(flags.lines) : 20;
 	try {
 		const all = (await readFile(join(stateDir(repoRoot), "audit.jsonl"), "utf8")).split("\n").filter(Boolean);
 		for (const line of all.slice(-lines)) try {
 			const e = JSON.parse(line);
-			console.log(`  ${new Date(e.time).toLocaleString()} ${e.event} ${e.role ?? ""}${e.command ? ` | ${e.command.slice(0, 80)}` : ""}${e.reason ? ` | ${e.reason.slice(0, 60)}` : ""}`);
+			console.log(`  ${new Date(e.time).toISOString()} ${e.event} ${e.role ?? ""}${e.command ? ` | ${e.command.slice(0, 80)}` : ""}${e.reason ? ` | ${e.reason.slice(0, 60)}` : ""}`);
 		} catch {
 			console.log(`  ${line}`);
 		}
 	} catch {
-		console.log(makeT("en")("cli.auditEmpty"));
+		console.log(t("cli.auditEmpty"));
 	}
 	return 0;
 }
@@ -217,8 +235,10 @@ async function check(flags) {
 	const platformFlag = flags.platform ?? "auto";
 	let raw = "";
 	let strict = false;
+	let denyPlatform = "claude";
 	try {
 		raw = flags.command != null ? "" : await readStdin();
+		denyPlatform = platformFlag === "auto" ? detectPlatform(raw) : platformFlag;
 		const payload = flags.command != null ? {
 			command: flags.command,
 			cwd: flags.repo,
@@ -235,21 +255,23 @@ async function check(flags) {
 		if (!loaded.config?.enabled) {
 			if (loaded.errors.length > 0) {
 				const t = makeT("en");
-				if (strict) return emitDeny(platformFlag === "auto" ? detectPlatform(raw) : platformFlag, t("guardStrictConfigBroken.why"), t("guardStrictConfigBroken.next"));
+				if (strict) return emitDeny(denyPlatform, t("guardStrictConfigBroken.why"), t("guardStrictConfigBroken.next"));
 				process.stderr.write(`${t("cli.guardDisabledInvalidConfig", { err: loaded.errors.join("; ") })}\n`);
 			}
 			return 0;
 		}
 		const config = loaded.config;
-		const hookPlatform = platformFlag === "auto" ? detectPlatform(raw) : platformFlag;
-		const locale = resolveLocale(config.locale);
-		const result = await evaluateCommand(payload.command, { repoRoot });
-		if (result.outcome === "deny" && result.reason) return emitDeny(hookPlatform, result.reason.why, result.reason.next, locale);
+		const locale = flags.locale != null ? resolveLocale(flags.locale) : resolveLocale(config.locale);
+		const result = await evaluateCommand(payload.command, {
+			repoRoot,
+			locale
+		});
+		if (result.outcome === "deny" && result.reason) return emitDeny(denyPlatform, result.reason.why, result.reason.next, locale);
 		return 0;
 	} catch (e) {
 		if (strict) {
 			const t = makeT("en");
-			return emitDeny(platformFlag === "auto" ? detectPlatform(raw) : platformFlag, t("guardStrictInternalError.why", { msg: e.message }), t("guardStrictInternalError.next"));
+			return emitDeny(denyPlatform, t("guardStrictInternalError.why", { msg: e.message }), t("guardStrictInternalError.next"));
 		}
 		process.stderr.write(`${makeT("en")("cli.checkInternalError", { msg: e.message })}\n`);
 		return 0;

package/lib/index.d.mts

@@ -1,8 +1,21 @@
 import { t as Runner } from "./repo-DrgptHl1.mjs";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/types.d.ts
-/** 文案语言: 默认 en; 'zh' 切中文 */
-type Locale = 'en' | 'zh';
+/** 文案语言: 默认 en; 'zh' 切中文; 可经 registerLocale 运行时扩展(保留字面量提示的宽字符串) */
+type Locale = 'en' | 'zh' | (string & {});
+//#endregion
+//#region src/i18n.d.ts
+/** 可插值变量(分支名/角色名等) */
+type I18nVars = Record<string, string>;
+/** 单一文案条目: (vars) => 最终文本 */
+type Entry = (v: I18nVars) => string;
+/** 一门语言的文案字典: key 集合必须与内置 en 完全一致(registerLocale / 加载期校验) */
+type Dict = Record<string, Entry>;
+/**
+ * 注册一门新语言(运行时扩展点, P2-2): key 集合必须与内置 en 完全一致, 否则抛英文异常。
+ * 注册后 makeT/resolveLocale 即接受该 locale; 未注册的 locale 一律回退英文。
+ */
+declare function registerLocale(name: string, dict: Dict): void;
 //#endregion
 //#region src/index.d.ts
 declare const name = "gitflow-guard";
@@ -19,6 +32,8 @@ interface EvaluateOptions {
   glabRunner?: Runner;
   /** 当前分支(缺省时内部查询) */
   currentBranch?: string | null;
+  /** 覆盖文案 locale(CLI --locale 旗标用, P2-1); 缺省按项目 config.locale 解析 */
+  locale?: Locale;
 }
 interface EvaluateResult {
   outcome: 'allow' | 'deny' | 'skipped';
@@ -45,4 +60,4 @@ declare function evaluateCommand(command: string, opts: EvaluateOptions): Promis
 declare function formatDeny(locale: Locale, why: string, next: string): string;
 declare function apply(ctx: Context, pluginConfig?: PluginConfig): void;
 //#endregion
-export { AuditEntry, EvaluateOptions, EvaluateResult, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };
+export { AuditEntry, type Dict, EvaluateOptions, EvaluateResult, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, i as formatDeny, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-DTg5WMog.mjs";
-export { appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };
+import { a as name, i as formatDeny, n as apply, o as stateDir, p as registerLocale, r as evaluateCommand, t as appendAudit } from "./src-CPX1Ks_Z.mjs";
+export { appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };

package/lib/{src-DTg5WMog.mjs → src-CPX1Ks_Z.mjs}

@@ -444,166 +444,6 @@ function guardSub(args) {
 	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
-	};
-}
-/** 合并默认值并校验; 任何校验错误都会导致未启用(strict 位仍从原文提取, 供 fail-closed 判定) */
-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 strict = r.strict === true ? true : r.strict === false ? false : void 0;
-	if (r.strict !== void 0 && typeof r.strict !== "boolean") errors.push("strict must be a boolean");
-	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;
-	if (strict !== void 0) config.strict = strict;
-	errors.push(...validateConfig(config));
-	return {
-		config: errors.length > 0 ? null : config,
-		errors,
-		...strict !== void 0 ? { strict } : {}
-	};
-}
-/** 配置校验: 角色分支重叠 / 正则合法等 */
-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) {
-	let text;
-	try {
-		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
-	} catch (e) {
-		if (e.code === "ENOENT") return {
-			config: null,
-			errors: []
-		};
-		return {
-			config: null,
-			errors: [`Failed to read config file: ${e.message}`]
-		};
-	}
-	let raw;
-	try {
-		raw = JSON.parse(text);
-	} catch (e) {
-		const strict = /"strict"\s*:\s*true/.test(text) || void 0;
-		return {
-			config: null,
-			errors: [`Failed to read config file: ${e.message}`],
-			...strict ? { strict } : {}
-		};
-	}
-	return mergeConfig(raw);
-}
-//#endregion
 //#region src/i18n.ts
 const en = {
 	"role.integration": () => "integration branch",
@@ -650,6 +490,7 @@ const en = {
 	"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.statusConfigWarning": (v) => `  config warning: ${v.warn}`,
 	"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})`,
@@ -668,13 +509,14 @@ const en = {
 	"usage.text": () => `gitflow-guard — GitFlow guard CLI
 
 Usage:
-  gitflow-guard status [--repo <path>]
-  gitflow-guard audit [--lines <count>] [--repo <path>]
-  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>]
+  gitflow-guard status [--repo <path>] [--locale <en|zh>]
+  gitflow-guard audit [--lines <count>] [--repo <path>] [--locale <en|zh>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <path>] [--locale <en|zh>]
   gitflow-guard --help
 
 Notes:
   status/audit are read-only; the agent can self-inspect.
+  --locale overrides the message language for this invocation (flag > project config > English).
   check reads the hook payload on stdin (platform-specific protocol: claude/opencode exit 2,
   codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.`
 };
@@ -723,6 +565,7 @@ const zh = {
 	"cli.statusTitle": (v) => `[gitflow-guard] status — ${v.repo}`,
 	"cli.statusDisabled": () => "配置: 未启用(不存在 gitflow-guard.config.json 或 enabled=false)",
 	"cli.statusConfigError": (v) => `  配置错误: ${v.err}`,
+	"cli.statusConfigWarning": (v) => `  配置警告: ${v.warn}`,
 	"cli.statusEnabled": (v) => `配置: 已启用 | featurePattern: ${v.pattern}`,
 	"cli.statusIntegration": (v) => `集成分支: ${v.list} (update=${v.mode})`,
 	"cli.statusPreview": (v) => `预览分支: ${v.list} (update=${v.mode})`,
@@ -741,24 +584,38 @@ const zh = {
 	"usage.text": () => `gitflow-guard — GitFlow 流程守卫 CLI
 
 用法:
-  gitflow-guard status [--repo <路径>]
-  gitflow-guard audit [--lines <数量>] [--repo <路径>]
-  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>]
+  gitflow-guard status [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard audit [--lines <数量>] [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard check [--platform <auto|claude|codex|opencode|antigravity>] [--command "<cmd>"] [--repo <路径>] [--locale <en|zh>]
   gitflow-guard --help
 
 说明:
   status/audit 只读, agent 可自查。
+  --locale 可临时覆盖本次调用的文案语言(旗标 > 项目配置 > 英文)。
   check 读 stdin hook payload 做门禁(平台协议: claude/opencode exit 2, codex/antigravity stdout JSON),
   供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。`
 };
+/** 内置文案注册表: en 为兜底语言; 下游可经 registerLocale 追加 */
+const dicts = /* @__PURE__ */ new Map([["en", en], ["zh", zh]]);
 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 字典键不一致");
+/** 字典键一致性校验(与内置 en 完全一致), 失败抛英文异常(P0-2: 异常信息遵循语言规范) */
+function assertDictKeys(name, dict) {
+	if (Object.keys(dict).length !== MESSAGE_KEYS.length || MESSAGE_KEYS.some((k) => !(k in dict))) throw new Error(`i18n: locale "${name}" dictionary keys mismatch the built-in "en" dictionary`);
+}
+assertDictKeys("zh", zh);
 /**
-* 生成翻译函数。未知 key 回退英文原文(开发/防御性)。
+* 注册一门新语言(运行时扩展点, P2-2): key 集合必须与内置 en 完全一致, 否则抛英文异常。
+* 注册后 makeT/resolveLocale 即接受该 locale; 未注册的 locale 一律回退英文。
+*/
+function registerLocale(name, dict) {
+	assertDictKeys(name, dict);
+	dicts.set(name, dict);
+}
+/**
+* 生成翻译函数。未注册 locale / 未知 key 均回退英文(开发/防御性)。
 */
 function makeT(locale) {
-	const dict = locale === "zh" ? zh : en;
+	const dict = dicts.get(locale) ?? en;
 	return (key, vars = {}) => {
 		const entry = dict[key] ?? en[key];
 		if (!entry) return key;
@@ -769,9 +626,177 @@ function makeT(locale) {
 		}
 	};
 }
-/** 解析配置里的 locale 值: 仅 'zh' 视为中文, 其余(含未定义)一律英文 */
+/** 解析配置里的 locale 值: 白名单语义 = 已注册语言原样通过, 其余(含未定义)一律英文(P2-2 后白名单随注册表扩展) */
 function resolveLocale(v) {
-	return v === "zh" ? "zh" : "en";
+	return typeof v === "string" && dicts.has(v) ? v : "en";
+}
+//#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
+	};
+}
+/** 合并默认值并校验; 任何校验错误都会导致未启用(strict 位仍从原文提取, 供 fail-closed 判定) */
+function mergeConfig(raw) {
+	const errors = [];
+	const warnings = [];
+	if (typeof raw !== "object" || raw === null) return {
+		config: null,
+		errors: ["Config file must be a JSON object"],
+		warnings
+	};
+	const r = raw;
+	const strict = r.strict === true ? true : r.strict === false ? false : void 0;
+	if (r.strict !== void 0 && typeof r.strict !== "boolean") errors.push("strict must be a boolean");
+	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 (typeof r.locale === "string" && r.locale !== "") {
+		config.locale = r.locale;
+		if (resolveLocale(r.locale) !== r.locale) warnings.push(`unknown locale "${r.locale}"; falling back to en`);
+	} else if (r.locale !== void 0) errors.push("locale must be a string");
+	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;
+	if (strict !== void 0) config.strict = strict;
+	errors.push(...validateConfig(config));
+	return {
+		config: errors.length > 0 ? null : config,
+		errors,
+		warnings,
+		...strict !== void 0 ? { strict } : {}
+	};
+}
+/** 配置校验: 角色分支重叠 / 正则合法等 */
+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) {
+	let text;
+	try {
+		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
+	} catch (e) {
+		if (e.code === "ENOENT") return {
+			config: null,
+			errors: [],
+			warnings: []
+		};
+		return {
+			config: null,
+			errors: [`Failed to read config file: ${e.message}`],
+			warnings: []
+		};
+	}
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (e) {
+		const strict = /"strict"\s*:\s*true/.test(text) || void 0;
+		return {
+			config: null,
+			errors: [`Failed to read config file: ${e.message}`],
+			warnings: [],
+			...strict ? { strict } : {}
+		};
+	}
+	return mergeConfig(raw);
 }
 //#endregion
 //#region src/gate.ts
@@ -1030,7 +1055,7 @@ async function evaluateCommand(command, opts) {
 		segmentCount: 0,
 		locale: "en"
 	};
-	const locale = resolveLocale(config.locale);
+	const locale = opts.locale != null ? resolveLocale(opts.locale) : resolveLocale(config.locale);
 	const t = makeT(locale);
 	const branch = opts.currentBranch ?? await currentBranch(runner, opts.repoRoot);
 	const env = {
@@ -1133,10 +1158,10 @@ function apply(ctx, pluginConfig = {}) {
 			};
 			return next();
 		} catch (e) {
-			ctx.logger?.warn?.(`gitflow-guard: 门禁内部错误, 已放行: ${e.message}`);
+			ctx.logger?.warn?.(`gitflow-guard: gate internal error, allowed through: ${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 };
+export { name as a, findRepoRoot as c, roleMatches as d, makeT as f, classify as h, formatDeny as i, gitRunner as l, resolveLocale as m, apply as n, stateDir as o, registerLocale as p, evaluateCommand as r, currentBranch as s, appendAudit as t, loadConfig as u };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity) — integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "main": "lib/index.mjs",
   "types": "lib/index.d.mts",
   "exports": {
@@ -42,6 +43,13 @@
     "type": "git",
     "url": "https://github.com/FeatureAgents/AgentsGitFlowController.git"
   },
+  "bugs": {
+    "url": "https://github.com/FeatureAgents/AgentsGitFlowController/issues"
+  },
+  "homepage": "https://github.com/FeatureAgents/AgentsGitFlowController#readme",
+  "engines": {
+    "node": ">=22"
+  },
   "dsh": {
     "bundle": {
       "patch": "./patch.yml"