agents-gitflow-guard 0.0.18 → 0.0.20

package/lib/{src-BQYC4N6b.mjs → src-DPJRoEJq.mjs}

@@ -119,10 +119,12 @@ function classifySegment(segment, ctx) {
 }
 /** 分派: 已知命令直接解析; 包装器剥壳后递归(token 只减不增, 必然终止) */
 function classifyTokens(tokens, ctx) {
+	if (tokens.length === 0) return [{ kind: "other" }];
 	const rawCmd = tokens[0];
 	const cmd = rawCmd.includes("/") ? rawCmd.slice(rawCmd.lastIndexOf("/") + 1) : rawCmd;
 	if (SHELLS.has(cmd)) return classifyShellWrapped(tokens, ctx);
 	if (cmd === "env") return classifyTokens(stripEnvArgs(tokens.slice(1)), ctx);
+	if (cmd === "sudo") return classifyTokens(stripSudoArgs(tokens.slice(1)), ctx);
 	if (WRAPPERS.has(cmd)) return classifyTokens(stripWrapperArgs(tokens.slice(1)), ctx);
 	if (/^[\w-][\w.-]*=/.test(rawCmd)) return classifyTokens(tokens.slice(1), ctx);
 	if (cmd === "git") return classifyGit(tokens.slice(1), ctx);
@@ -168,6 +170,35 @@ function stripWrapperArgs(args) {
 	while (i < args.length && (args[i].startsWith("-") || /^\d+$/.test(args[i]) || /^[\w-]+=/.test(args[i]))) i++;
 	return args.slice(i);
 }
+/**
+* sudo 参数剥离: 旗标与 VAR=x 赋值逐个消费; -u/-g/-p(及长旗标)消费下一个参数;
+* `--` 之后即命令本体。仅剥壳不出新语义, 递归分类必然终止。
+*/
+function stripSudoArgs(args) {
+	const WITH_VALUE = /* @__PURE__ */ new Set([
+		"-u",
+		"--user",
+		"-g",
+		"--group",
+		"-p",
+		"--prompt"
+	]);
+	let i = 0;
+	while (i < args.length) {
+		const a = args[i];
+		if (a === "--") return args.slice(i + 1);
+		if (WITH_VALUE.has(a)) {
+			i += args[i + 1] != null ? 2 : 1;
+			continue;
+		}
+		if (a.startsWith("-") || /^[\w-]+=/.test(a)) {
+			i++;
+			continue;
+		}
+		break;
+	}
+	return args.slice(i);
+}
 /** 分词: 引号内的空格不拆分 */
 function tokenize(segment) {
 	return segment.match(/"[^"]*"|'[^']*'|\S+/g)?.map((t) => t.replace(/^['"]|['"]$/g, "")) ?? [];
@@ -181,6 +212,8 @@ function classifyGit(args, ctx) {
 	if (sub === "checkout" || sub === "switch") return parseCheckout(rest);
 	if (sub === "send-pack") return parseSendPack(rest);
 	if (sub === "update-ref") return parseUpdateRef(rest);
+	if (sub === "symbolic-ref") return parseSymbolicRef(rest);
+	if (sub === "cherry-pick" || sub === "revert") return parseCherryPickLike(rest);
 	if (sub === "reset" || sub === "filter-branch") return [{ kind: "ref-move" }];
 	if (sub === "rebase") return parseRebase(rest);
 	if (sub === "commit") return parseCommit(rest);
@@ -203,6 +236,21 @@ function parseCommit(args) {
 	if (args.some((a) => a === "--amend")) return [{ kind: "ref-move" }];
 	return [{ kind: "other" }];
 }
+/**
+* cherry-pick/revert 会在当前分支上新提交 → 改写当前 tip, 收编为 ref-move
+* (受保护分支上拒绝, 与 reset/rebase 同型);
+* -n/--no-commit 只改工作树与索引(不移动 tip)与恢复类旗标(abort/continue 等)放行。
+*/
+function parseCherryPickLike(args) {
+	const RESUME = /* @__PURE__ */ new Set([
+		"--abort",
+		"--continue",
+		"--skip",
+		"--quit"
+	]);
+	if (args.some((a) => a === "-n" || a === "--no-commit" || RESUME.has(a))) return [{ kind: "other" }];
+	return [{ kind: "ref-move" }];
+}
 /** 剥离子命令前的全局选项(-C <path> / -c <k=v> / --git-dir 等), 否则 git -C . push 会被判 other */
 function stripGlobalOptions(args) {
 	const WITH_VALUE = /* @__PURE__ */ new Set([
@@ -238,20 +286,44 @@ function stripGlobalOptions(args) {
 	}
 	return args.slice(i);
 }
-/** 分支切换: 门禁放行, 分支状态由 evaluateCommand 按段模拟 */
+/**
+* 分支切换: 普通切换/-b/-c(switch -c)新建 → checkout(放行, 分支状态由 evaluateCommand 模拟);
+* -B/-C 强制重建会静默移动/重建既有 ref(可波及受保护分支), 目标名单独送 ref-update 门禁,
+* 门禁放行后仍按 checkout 模拟切换(两段任一 deny 即整体拦截, 与 push 歧义双解释同机制)。
+* 短旗标簇(-Bf/-bt 等)扫描 b/B/c/C 视同对应形态。
+*/
 function parseCheckout(args) {
 	const first = args[0];
 	if (first === "--") return [{
 		kind: "checkout",
 		branch: null
 	}];
+	const name = args[1];
+	const validName = name != null && !name.startsWith("-");
 	if (first === "-b" || first === "-B" || first === "-c" || first === "-C") {
-		const name = args[1];
+		if (!validName) return [{
+			kind: "checkout",
+			branch: null
+		}];
+		if (first === "-B" || first === "-C") return forceRecreateOut(name);
 		return [{
 			kind: "checkout",
-			branch: name && !name.startsWith("-") ? name : null
+			branch: name
 		}];
 	}
+	if (first != null && first.startsWith("-") && !first.startsWith("--") && first.length > 1) {
+		const clusterForce = first.includes("B") || first.includes("C");
+		if (clusterForce || first.includes("b") || first.includes("c")) {
+			if (!validName) return [{
+				kind: "checkout",
+				branch: null
+			}];
+			return clusterForce ? forceRecreateOut(name) : [{
+				kind: "checkout",
+				branch: name
+			}];
+		}
+	}
 	if (first && !first.startsWith("-")) return [{
 		kind: "checkout",
 		branch: first
@@ -261,6 +333,17 @@ function parseCheckout(args) {
 		branch: null
 	}];
 }
+/** -B/-C(及含 B/C 的旗标簇)的产出: 目标 ref 送 ref-update, 再按 checkout 模拟切换 */
+function forceRecreateOut(name) {
+	return [{
+		kind: "ref-update",
+		branch: stripRefPrefix(name),
+		delete: false
+	}, {
+		kind: "checkout",
+		branch: name
+	}];
+}
 function parsePush(args, ctx) {
 	let force = false;
 	let isDelete = false;
@@ -404,6 +487,36 @@ function parseUpdateRef(args) {
 	}
 	return [{ kind: "other" }];
 }
+/**
+* git symbolic-ref 直改 symbolic refs(plumbing 绕行面):
+* - 查询形态(symbolic-ref <name> / --short 等单参)不改变任何 ref → other;
+* - 双参重定向(symbolic-ref <name> <ref>)把 name 指向别处, 目标名送 ref-update;
+* - -d/--delete 删除该 ref, 同样送 ref-update。
+*/
+function parseSymbolicRef(args) {
+	let isDelete = false;
+	const nonFlag = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (a === "-d" || a === "--delete") {
+			isDelete = true;
+			continue;
+		}
+		if (a === "-m" || a === "--message") {
+			i++;
+			continue;
+		}
+		if (a.startsWith("-")) continue;
+		nonFlag.push(a);
+	}
+	if (!isDelete && nonFlag.length < 2) return [{ kind: "other" }];
+	if (isDelete && nonFlag.length === 0) return [{ kind: "other" }];
+	return [{
+		kind: "ref-update",
+		branch: stripRefPrefix(nonFlag[0]),
+		delete: isDelete
+	}];
+}
 function parseMerge(args) {
 	if (args.some((a) => a === "--abort")) return [{ kind: "other" }];
 	return [{
@@ -526,9 +639,9 @@ const en = {
 	"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.",
-	"refUpdateProtected.why": (v) => `Protected branch "${v.branch}" forbids direct ref updates (update-ref)`,
+	"refUpdateProtected.why": (v) => `Protected branch "${v.branch}" forbids direct ref updates (update-ref / symbolic-ref / branch -m|-f / checkout -B)`,
 	"refUpdateProtected.next": () => "Update protected branches via PR/MR; they are managed by you.",
-	"refMoveProtected.why": () => "Rewriting history on a protected branch (reset / rebase / commit --amend / filter-branch) is not allowed",
+	"refMoveProtected.why": () => "Rewriting history on a protected branch (reset / rebase / commit --amend / filter-branch / cherry-pick / revert) is not allowed",
 	"refMoveProtected.next": () => "Do history rewrites on a feature branch; protected branches advance via PR/MR and are managed by you.",
 	"pushAll.why": () => "--all/--mirror push would include protected branches",
 	"pushAll.next": () => "Push branch by branch with an explicit refspec.",
@@ -575,6 +688,31 @@ const en = {
 	"cli.auditEmpty": () => "  No audit entries yet",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check internal error, allowed through: ${v.msg}`,
 	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] guard disabled: invalid config: ${v.err}`,
+	"cli.wireUnknownClient": (v) => `unknown client: ${v.client} (expected dsh|claude|codex|opencode|antigravity|pi)`,
+	"cli.wireNeedRepo": () => "project scope needs a git repository — run inside a repo or pass --repo <path>",
+	"cli.wireScopeAsk": () => "Scope — project (this repo only) or global (all repos on this machine)? [project/global] ",
+	"cli.wireScopeInvalid": () => "invalid scope (expected project or global)",
+	"cli.wireTarget": (v) => `${v.client}: wiring → ${v.path}`,
+	"cli.wireAlready": (v) => `${v.client}: hook already wired (${v.path})`,
+	"cli.wireCreated": (v) => `${v.client}: hook written → ${v.path}`,
+	"cli.wireRemoved": (v) => `${v.client}: hook removed → ${v.path}`,
+	"cli.wireNotWired": (v) => `${v.client}: no hook entry found (${v.path})`,
+	"cli.wireConfirmWrite": (v) => `Write ${v.path}? [y/N] `,
+	"cli.wireRefuseGlobal": () => "Refusing to modify a global config without confirmation — pass --yes to allow",
+	"cli.wireDshGuide": () => "DSH is an in-process plugin — no hook file to write. Mount it with: dsh plugin --profile web add agents-gitflow-guard",
+	"cli.wirePiGuide": () => "Pi is an in-process extension — no hook file to write. Copy pi/gitflow-guard.ts into .pi/extensions/ and list it in .pi/settings.json (see README).",
+	"cli.wireExperimental": (v) => `${v.client}: experimental support — verify the hook on a real device before relying on it`,
+	"cli.wireDryRunAdd": (v) => `${v.client}: [dry-run] would add hook → ${v.path}`,
+	"cli.wireDryRunRemove": (v) => `${v.client}: [dry-run] would remove hook → ${v.path}`,
+	"cli.wireDryRunNoOp": (v) => `${v.client}: [dry-run] nothing to do (${v.path})`,
+	"cli.statusUsingDefaults": () => "Config: built-in defaults (no gitflow-guard.config.json) — integration=develop, archive=main",
+	"cli.statusMainProtected": () => "  main is protected by default. Trunk / single-branch users: create gitflow-guard.config.json with \"enabled\": false, or map your own branches.",
+	"cli.statusWireHints": () => "Wiring:",
+	"cli.statusWireHint": (v) => `  ${v.client}: not wired — run: gitflow-guard wire --client ${v.client}`,
+	"cli.setupIntro": () => "gitflow-guard setup — wire one client for this project. (Ctrl+C to cancel)",
+	"cli.setupClientAsk": () => "Which client? [dsh|claude|codex|opencode|antigravity|pi] ",
+	"cli.setupClientInvalid": () => "invalid client (expected dsh|claude|codex|opencode|antigravity|pi)",
+	"cli.setupNoTty": () => "setup needs an interactive terminal — use: gitflow-guard wire --client <name> --yes",
 	"guardStrictConfigBroken.why": () => "Guard config is invalid while strict mode is enabled",
 	"guardStrictConfigBroken.next": () => "Fix gitflow-guard.config.json (or remove \"strict\": true) before retrying.",
 	"guardStrictInternalError.why": (v) => `Guard internal error while strict mode is enabled: ${v.msg}`,
@@ -585,13 +723,18 @@ Usage:
   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 wire --client <dsh|claude|codex|opencode|antigravity|pi> [--project|--global] [--unwire] [--dry-run] [--yes] [--repo <path>] [--locale <en|zh>]
+  gitflow-guard setup [--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.`
+  codex/antigravity JSON on stdout) and is meant for pre/post hooks of AI agents.
+  wire writes each client's hook config into the project (default) or global scope; dsh/pi are
+  in-process and only print guidance. No config file needed — built-in defaults (develop+main)
+  apply out of the box; create gitflow-guard.config.json to override, or set "enabled": false to turn off.`
 };
 const zh = {
 	"role.integration": () => "集成分支",
@@ -603,9 +746,9 @@ const zh = {
 	"head.unknown": () => "当前分支",
 	"denyDeleteOrForce.why": (v) => `受保护分支「${v.branch}」禁止删除或强推`,
 	"denyDeleteOrForce.next": () => "删除/强推请到受保护分支外的 feature 分支上操作; 受保护分支由用户亲手管理",
-	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref)`,
+	"refUpdateProtected.why": (v) => `受保护分支「${v.branch}」禁止直接改写 refs(update-ref / symbolic-ref / branch -m|-f / checkout -B)`,
 	"refUpdateProtected.next": () => "请通过 PR/MR 更新受保护分支; 受保护分支由用户亲手管理",
-	"refMoveProtected.why": () => "受保护分支禁止本地改写历史(reset / rebase / commit --amend / filter-branch)",
+	"refMoveProtected.why": () => "受保护分支禁止本地改写历史(reset / rebase / commit --amend / filter-branch / cherry-pick / revert)",
 	"refMoveProtected.next": () => "历史改写请在 feature 分支上进行; 受保护分支仅经 PR/MR 推进, 由用户亲手管理",
 	"pushAll.why": () => "--all/--mirror 推送会包含受保护分支",
 	"pushAll.next": () => "请逐分支推送并显式指定 refspec",
@@ -652,6 +795,31 @@ const zh = {
 	"cli.auditEmpty": () => "  暂无审计记录",
 	"cli.checkInternalError": (v) => `[gitflow-guard] check 内部错误, 已放行: ${v.msg}`,
 	"cli.guardDisabledInvalidConfig": (v) => `[gitflow-guard] 守卫未启用: 配置无效: ${v.err}`,
+	"cli.wireUnknownClient": (v) => `未知客户端: ${v.client}(应为 dsh|claude|codex|opencode|antigravity|pi)`,
+	"cli.wireNeedRepo": () => "项目级作用域需要一个 git 仓库 — 请在仓库内运行, 或传 --repo <路径>",
+	"cli.wireScopeAsk": () => "作用域 — project(仅当前仓库) 还是 global(本机所有仓库)? [project/global] ",
+	"cli.wireScopeInvalid": () => "无效作用域(应为 project 或 global)",
+	"cli.wireTarget": (v) => `${v.client}: 接线 → ${v.path}`,
+	"cli.wireAlready": (v) => `${v.client}: hook 已接线(${v.path})`,
+	"cli.wireCreated": (v) => `${v.client}: hook 已写入 → ${v.path}`,
+	"cli.wireRemoved": (v) => `${v.client}: hook 已移除 → ${v.path}`,
+	"cli.wireNotWired": (v) => `${v.client}: 未找到 hook 条目(${v.path})`,
+	"cli.wireConfirmWrite": (v) => `写入 ${v.path}? [y/N] `,
+	"cli.wireRefuseGlobal": () => "拒绝在未确认时改动全局配置 — 传 --yes 允许",
+	"cli.wireDshGuide": () => "DSH 是进程内插件, 无需写入 hook 文件。挂载: dsh plugin --profile web add agents-gitflow-guard",
+	"cli.wirePiGuide": () => "Pi 是进程内扩展, 无需写入 hook 文件。把 pi/gitflow-guard.ts 拷到 .pi/extensions/ 并在 .pi/settings.json 登记(见 README)",
+	"cli.wireExperimental": (v) => `${v.client}: 实验支持 — 请在真机核验后再依赖它`,
+	"cli.wireDryRunAdd": (v) => `${v.client}: [dry-run] 将添加 hook → ${v.path}`,
+	"cli.wireDryRunRemove": (v) => `${v.client}: [dry-run] 将移除 hook → ${v.path}`,
+	"cli.wireDryRunNoOp": (v) => `${v.client}: [dry-run] 无需改动(${v.path})`,
+	"cli.statusUsingDefaults": () => "配置: 内置默认(无 gitflow-guard.config.json)— integration=develop, archive=main",
+	"cli.statusMainProtected": () => "  main 默认受保护。Trunk/单分支用户: 创建 gitflow-guard.config.json 写 \"enabled\": false, 或自行映射分支",
+	"cli.statusWireHints": () => "接线:",
+	"cli.statusWireHint": (v) => `  ${v.client}: 未接线 — 运行: gitflow-guard wire --client ${v.client}`,
+	"cli.setupIntro": () => "gitflow-guard setup — 为本项目接线一个客户端。(Ctrl+C 取消)",
+	"cli.setupClientAsk": () => "选哪个客户端? [dsh|claude|codex|opencode|antigravity|pi] ",
+	"cli.setupClientInvalid": () => "无效客户端(应为 dsh|claude|codex|opencode|antigravity|pi)",
+	"cli.setupNoTty": () => "setup 需要交互终端 — 请用: gitflow-guard wire --client <名字> --yes",
 	"guardStrictConfigBroken.why": () => "守卫配置无效, 且已启用 strict 模式",
 	"guardStrictConfigBroken.next": () => "请先修复 gitflow-guard.config.json(或移除 \"strict\": true)后重试",
 	"guardStrictInternalError.why": (v) => `守卫内部错误, 且已启用 strict 模式: ${v.msg}`,
@@ -662,13 +830,17 @@ const zh = {
   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 wire --client <dsh|claude|codex|opencode|antigravity|pi> [--project|--global] [--unwire] [--dry-run] [--yes] [--repo <路径>] [--locale <en|zh>]
+  gitflow-guard setup [--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 调用。`
+  供 Claude Code / Codex / OpenCode 等 agent 的 pre/post hook 调用。
+  wire 把各客户端默认 hook 写入工程(默认)或全局作用域; dsh/pi 为进程内接入, 仅打印引导。
+  无需配置文件 — 内置默认(develop+main)开箱即用; 建 gitflow-guard.config.json 可覆盖, 或写 "enabled": false 关闭。`
 };
 /** 内置文案注册表: en 为兜底语言; 下游可经 registerLocale 追加 */
 const dicts = /* @__PURE__ */ new Map([["en", en], ["zh", zh]]);
@@ -708,10 +880,26 @@ function resolveLocale(v) {
 //#endregion
 //#region src/config.ts
 const CONFIG_FILE = "gitflow-guard.config.json";
-/** 默认配置(分支角色必须由项目显式配置, 无默认) */
+/**
+* 内置默认配置(零门槛开箱即用): 没有 gitflow-guard.config.json 也生效。
+* 默认保护 develop(integration, 只走 PR/MR) + main(archive, 归档合并在人)。
+* 用户 config 存在时按字段深度合并覆盖——只写想改的字段, 其余沿用默认。
+*/
 const DEFAULT_CONFIG = {
-	enabled: false,
+	enabled: true,
 	featurePattern: "feature/[\\w-]+",
+	branches: {
+		integration: {
+			branches: ["develop"],
+			update: "pr",
+			mergeBy: "anyone"
+		},
+		archive: {
+			branches: ["main"],
+			update: "pr",
+			mergeBy: "user"
+		}
+	},
 	ci: { enabled: true },
 	locale: "en"
 };
@@ -769,32 +957,30 @@ function mergeConfig(raw) {
 	if (typeof raw !== "object" || raw === null) return {
 		config: null,
 		errors: ["Config file must be a JSON object"],
-		warnings
+		warnings,
+		usingDefaults: false
 	};
 	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"
-		} }
-	};
+	const config = structuredClone(DEFAULT_CONFIG);
 	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");
+	if (typeof r.ci === "object" && r.ci !== null) {
+		const ci = r.ci;
+		if (typeof ci.enabled === "boolean") config.ci.enabled = ci.enabled;
+	}
+	if (r.branches !== void 0 && (typeof r.branches !== "object" || r.branches === null)) errors.push("branches must be an object");
 	const b = r.branches ?? {};
 	if ("integration" in b) {
 		const { role, errors: e } = normalizeRole(b.integration, "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, "preview", "pr", "anyone");
 		config.branches.preview = role;
@@ -810,14 +996,13 @@ function mergeConfig(raw) {
 		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,
+		usingDefaults: false,
 		...strict !== void 0 ? { strict } : {}
 	};
 }
@@ -847,21 +1032,23 @@ function validateConfig(config) {
 	}
 	return errors;
 }
-/** 从项目根加载配置; 无文件 = 未启用(opt-in) */
+/** 从项目根加载配置; 无文件 = 使用内置默认配置(开箱即用, develop/main 已受保护) */
 async function loadConfig(repoRoot) {
 	let text;
 	try {
 		text = await readFile(join(repoRoot, CONFIG_FILE), "utf8");
 	} catch (e) {
 		if (e.code === "ENOENT") return {
-			config: null,
+			config: structuredClone(DEFAULT_CONFIG),
 			errors: [],
-			warnings: []
+			warnings: [],
+			usingDefaults: true
 		};
 		return {
 			config: null,
 			errors: [`Failed to read config file: ${e.message}`],
-			warnings: []
+			warnings: [],
+			usingDefaults: false
 		};
 	}
 	let raw;
@@ -873,6 +1060,7 @@ async function loadConfig(repoRoot) {
 			config: null,
 			errors: [`Failed to read config file: ${e.message}`],
 			warnings: [],
+			usingDefaults: false,
 			...strict ? { strict } : {}
 		};
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.18",
-  "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — integration/preview/production/archive, each with its own update rules",
+  "version": "0.0.20",
+  "description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — zero-config defaults (develop+main) out of the box, deep-merge override, and per-client native hooks via gitflow-guard wire/setup; integration/preview/production/archive, each with its own update rules",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,11 @@
     "git",
     "workflow",
     "guard",
-    "agent"
+    "agent",
+    "zero-config",
+    "onboarding",
+    "wire",
+    "setup"
   ],
   "repository": {
     "type": "git",