agents-gitflow-guard 0.0.13 → 0.0.15

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.13
+dsh plugin --profile web add agents-gitflow-guard@0.0.15
 ```
 
 > **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).
@@ -132,7 +132,7 @@ Nobody has to remember the rules — the rules are enforced.
 - **Role-driven, fully configurable**: `integration` is the only required role; `preview` / `production` / `archive` are optional arrays of branch names or regexes, each with its own update rules (`pr` / `flexible`, `mergeBy`).
 - **Merge-by-user where it matters**: production & archive merges stay in your hands — the plugin blocks the agent from clicking merge, so your action *is* the confirmation.
 - **Works with any naming**: branch names are mapped by your config, never hard-coded (see [Configuration](#configuration-reference)).
-- **Fully audited**: every deny is written to `.git/gitflow-guard/audit.jsonl` — inside `.git`, never committed.
+- **Fully audited**: every deny is appended to an audit log under your user state directory (`~/.local/state/gitflow-guard/`, `%LOCALAPPDATA%\gitflow-guard` on Windows) — outside the repository, never committed, outside the agent's writable sandbox, and shared across all linked worktrees of one repository.
 - **Platform-agnostic core**: pure local git; optionally consults `gh` (GitHub) or `glab` (GitLab) for PR/MR target resolution, and works fine without them.
 
 ---
@@ -168,7 +168,7 @@ Why this matters: branch protection answers *"can this push happen at all?"*; th
 
 1. An agent calls a shell tool (`pwsh` / `bash`) with a git command.
 2. The plugin classifies the command, resolves the branch roles from `gitflow-guard.config.json`, and applies the gate matrix.
-3. Violation → the tool call is **denied before it runs**, with a reason and the next step. Allowed → the command proceeds; every deny is audited to `.git/gitflow-guard/audit.jsonl`.
+3. Violation → the tool call is **denied before it runs**, with a reason and the next step. Allowed → the command proceeds; every deny is audited to the user-level log (`~/.local/state/gitflow-guard/repos/<repo>-<hash>/audit.jsonl`).
 
 No chat-confirmation or permit store: sensitive merges (production / archive) are simply **user-only** — an agent may prepare the PR/MR, but the merge click stays yours.
 
@@ -302,7 +302,7 @@ The PR/MR target is resolved via `gh pr view` (GitHub) or `glab mr view` (GitLab
 ## Where the human stays in control
 
 - **Production merge** and **archive** are user-only by default: an agent may help prepare the PR/MR, but **you click the merge button** — that click *is* the confirmation. There is no separate permit store to outsource that decision.
-- Every deny is written to `.git/gitflow-guard/audit.jsonl` for review (`gitflow-guard audit`).
+- Every deny is appended to the user-level audit log for review (`gitflow-guard audit`).
 
 ---
 ## Installation in detail
@@ -312,7 +312,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.13    # pin recommended, see note above
+dsh plugin --profile web add agents-gitflow-guard@0.0.15    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.
@@ -471,7 +471,7 @@ If it saves your team from a shortcut gone wrong, the coffee button at the top o
 ## Roadmap
 
 - **i18n — localized block messages** ✅ (0.0.3): English by default, `"locale": "zh"` for Chinese.
-- **v2 — audit sync**: sync `.git/gitflow-guard/audit.jsonl` across machines (audit is local-only today).
+- **v2 — audit sync**: sync the user-level audit log across machines (audit is local-only today).
 - **v2 — more pre-built templates**: ready-made config templates for common flows (solo `develop`, multi-env enterprise) as community-contributed presets.
 - **v2 — CI hard-gating research**: whether `pr checks` could become a real gate without hurting the platform-agnostic core.
 

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.13
+dsh plugin --profile web add agents-gitflow-guard@0.0.15
 ```
 
 > **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
@@ -129,7 +129,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 - **角色驱动、完全可配**:`integration` 是唯一必填;`preview` / `production` / `archive` 是可选数组(精确名或正则),每个角色独立 `update`(`pr` / `flexible`)与 `mergeBy`。
 - **在关键处保留人的操作权**:生产与归档合并始终在你手上——插件阻止 agent 点击合并,于是你的动作*就是*确认。
 - **任何命名都行**:分支名全由配置映射,绝无硬编码(见[配置参考](#配置参考))。
-- **全程审计**:每次拦截都写入 `.git/gitflow-guard/audit.jsonl`——在 `.git` 内,绝不进版本库。
+- **全程审计**:每次拦截都追加到用户级状态目录(macOS/Linux `~/.local/state/gitflow-guard/`,Windows `%LOCALAPPDATA%\gitflow-guard`)下的审计日志——在仓库外、绝不进版本库、位于 agent 可写沙箱之外,且同一仓库的所有 worktree 共享一份日志。
 - **平台无关核心**:纯本地 git;可选调用 `gh`(GitHub)或 `glab`(GitLab)做 PR/MR 目标解析,没有它们照样工作。
 
 ---
@@ -165,7 +165,7 @@ AI 编码 agent 在你的仓库里工作。它通过系统提示词、项目智
 
 1. agent 调用 shell 工具(`pwsh`/`bash`)执行一条 git 命令。
 2. 插件分类该命令,从 `gitflow-guard.config.json` 解析分支角色,套用门禁矩阵。
-3. 违规 → 工具调用在**运行前被拒绝**,附原因和下一步;放行 → 命令照常执行,每次拦截都写入 `.git/gitflow-guard/audit.jsonl`。
+3. 违规 → 工具调用在**运行前被拒绝**,附原因和下一步;放行 → 命令照常执行,每次拦截都写入用户级日志(`~/.local/state/gitflow-guard/repos/<repo>-<hash>/audit.jsonl`)。
 
 没有聊天确认、也没有特许库:敏感合并(生产/归档)就是**仅用户**——agent 可以帮你准备 PR/MR,但点合并的始终是你。
 
@@ -298,7 +298,7 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 ## 人保持控制权的地方
 
 - **生产合并与归档**默认仅用户:agent 可以帮你准备 PR/MR,但**合并按钮由你点**——那个点击*就是*确认。没有独立特许库能把这决定外包出去。
-- 每次拦截都写入 `.git/gitflow-guard/audit.jsonl` 供查阅(`gitflow-guard audit`)。
+- 每次拦截都追加到用户级审计日志供查阅(`gitflow-guard audit`)。
 
 ---
 ## 安装详解
@@ -308,7 +308,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.13    # 建议锁版本, 见上文提示
+dsh plugin --profile web add agents-gitflow-guard@0.0.15    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -467,7 +467,7 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 ## 路线图
 
 - **i18n——拦截文案本地化** ✅(0.0.3):默认英文,`"locale": "zh"` 切中文。
-- **v2——审计同步**:跨机器同步 `.git/gitflow-guard/audit.jsonl`(现仅本地)。
+- **v2——审计同步**:跨机器同步用户级审计日志(现仅本地)。
 - **v2——更多预制模板**:常用流程(solo `develop`、多环境企业)的现成配置模板,由社区贡献。
 - **v2——CI 硬门槛研究**:`pr checks` 能否在不伤平台无关核心的前提下变成真实门槛。
 

package/lib/cli.mjs

@@ -1,4 +1,4 @@
-import { c as findRepoRoot, d as roleMatches, g as classify, h as resolveLocale, i as formatDeny, l as gitRunner, o as stateDir, p as makeT, r as evaluateCommand, s as currentBranch, u as loadConfig } from "./src-BHyQJ6hX.mjs";
+import { _ as classify, c as currentBranch, d as loadConfig, f as roleMatches, g as resolveLocale, i as formatDeny, l as findRepoRoot, m as makeT, o as stateDir, r as evaluateCommand, u as gitRunner } from "./src-p6q9dCIr.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts
@@ -129,7 +129,7 @@ async function main(argv, opts = {}) {
 	}
 	try {
 		if (cmd === "status") return await status(flags, runner);
-		if (cmd === "audit") return await audit(flags);
+		if (cmd === "audit") return await audit(flags, runner);
 		if (cmd === "check") return await check(flags);
 		const t = makeT(await resolveFrameworkLocale(flags, runner));
 		console.error(`${t("cli.unknownCommand", { cmd: cmd ?? "" })}\n\n${t("usage.text")}`);
@@ -192,7 +192,7 @@ async function status(flags, runner) {
 	for (const b of localBranches) console.log(`  ${b} → ${classifyBranch(b)}`);
 	return 0;
 }
-async function audit(flags) {
+async function audit(flags, runner) {
 	const repoRoot = await resolveRepo(flags, gitRunner);
 	if (!repoRoot) {
 		console.error(makeT(resolveLocale(flags.locale))("cli.cannotLocate"));
@@ -202,7 +202,7 @@ async function audit(flags) {
 	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);
+		const all = (await readFile(join(await stateDir(repoRoot, gitRunner), "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).toISOString()} ${e.event} ${e.role ?? ""}${e.command ? ` | ${e.command.slice(0, 80)}` : ""}${e.reason ? ` | ${e.reason.slice(0, 60)}` : ""}`);

package/lib/index.d.mts

@@ -53,12 +53,24 @@ interface AuditEntry {
   role?: string;
   reason?: string;
 }
-declare function stateDir(repoRoot: string): string;
+/**
+ * 用户级运行时状态根目录(仓库外): macOS/Linux 走 XDG state, Windows 走 %LOCALAPPDATA%。
+ * GITFLOW_GUARD_STATE_ROOT 显式覆盖所有平台默认值(测试/特殊部署用)。
+ */
+declare function userStateRoot(): string;
+/**
+ * 仓库运行时状态目录(审计流水等), 键为「仓库名-真实路径哈希」。
+ * 键由 git 权威解析(rev-parse --git-common-dir): linked worktree 与主仓库共用
+ * 同一状态目录(≤0.0.13 共享语义), 且天然规避 Windows 8.3 短名/大小写差异;
+ * git 查询不可用时回退 fs realpath。刻意放在仓库外、且在 agent 文件沙箱
+ * (workspace-write)可写区之外 —— 凡 agent 可写之处的状态都可能被伪造而自我授权。
+ */
+declare function stateDir(repoRoot: string, runner?: Runner): Promise<string>;
 /** 审计留痕; 失败不阻断门禁 */
-declare function appendAudit(repoRoot: string, entry: AuditEntry): Promise<void>;
+declare function appendAudit(repoRoot: string, entry: AuditEntry, runner?: Runner): Promise<void>;
 /** 解析一条命令: 分类 → git 事实 → 门禁 → allow/deny */
 declare function evaluateCommand(command: string, opts: EvaluateOptions): Promise<EvaluateResult>;
 declare function formatDeny(locale: Locale, why: string, next: string): string;
 declare function apply(ctx: Context, pluginConfig?: PluginConfig): void;
 //#endregion
-export { AuditEntry, type Dict, EvaluateOptions, EvaluateResult, MESSAGE_KEYS, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };
+export { AuditEntry, type Dict, EvaluateOptions, EvaluateResult, MESSAGE_KEYS, PluginConfig, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/index.mjs

@@ -1,2 +1,2 @@
-import { a as name, f as MESSAGE_KEYS, i as formatDeny, m as registerLocale, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-BHyQJ6hX.mjs";
-export { MESSAGE_KEYS, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir };
+import { a as name, h as registerLocale, i as formatDeny, n as apply, o as stateDir, p as MESSAGE_KEYS, r as evaluateCommand, s as userStateRoot, t as appendAudit } from "./src-p6q9dCIr.mjs";
+export { MESSAGE_KEYS, appendAudit, apply, evaluateCommand, formatDeny, name, registerLocale, stateDir, userStateRoot };

package/lib/{src-BHyQJ6hX.mjs → src-p6q9dCIr.mjs}

@@ -1,5 +1,8 @@
 import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
 import { execFile } from "node:child_process";
 //#region src/classify.ts
 /** 拆分命令为多段(&& / || / | / 分号 / 换行), 每段独立分类; 引号内的分隔符不算 */
@@ -1018,6 +1021,15 @@ async function findRepoRoot(runner, cwd) {
 	const r = await runner.run(["rev-parse", "--show-toplevel"], cwd);
 	return r.code === 0 ? r.stdout.trim() || null : null;
 }
+/** 共享 .git 目录(git 权威绝对路径): linked worktree 返回主仓库 .git, 主仓库返回自身 .git; 查询失败返回 null */
+async function commonGitDir(runner, cwd) {
+	const r = await runner.run([
+		"rev-parse",
+		"--path-format=absolute",
+		"--git-common-dir"
+	], 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;
@@ -1112,14 +1124,51 @@ function resolvePrTarget(info, config) {
 //#endregion
 //#region src/index.ts
 const name = "gitflow-guard";
-function stateDir(repoRoot) {
-	return join(repoRoot, ".git", "gitflow-guard");
+/**
+* 用户级运行时状态根目录(仓库外): macOS/Linux 走 XDG state, Windows 走 %LOCALAPPDATA%。
+* GITFLOW_GUARD_STATE_ROOT 显式覆盖所有平台默认值(测试/特殊部署用)。
+*/
+function userStateRoot() {
+	const override = process.env.GITFLOW_GUARD_STATE_ROOT?.trim();
+	if (override) return override;
+	if (process.platform === "win32") {
+		const local = process.env.LOCALAPPDATA?.trim() || join(homedir(), "AppData", "Local");
+		return join(local, "gitflow-guard");
+	}
+	const xdg = process.env.XDG_STATE_HOME?.trim();
+	return join(xdg || join(homedir(), ".local", "state"), "gitflow-guard");
+}
+/** fs 兜底规范化(仅当 git 查询不可用时使用; Windows 8.3 短名等以 git 输出为准) */
+function safeRealpath(p) {
+	try {
+		return realpathSync(p);
+	} catch {
+		return p;
+	}
+}
+/**
+* 仓库运行时状态目录(审计流水等), 键为「仓库名-真实路径哈希」。
+* 键由 git 权威解析(rev-parse --git-common-dir): linked worktree 与主仓库共用
+* 同一状态目录(≤0.0.13 共享语义), 且天然规避 Windows 8.3 短名/大小写差异;
+* git 查询不可用时回退 fs realpath。刻意放在仓库外、且在 agent 文件沙箱
+* (workspace-write)可写区之外 —— 凡 agent 可写之处的状态都可能被伪造而自我授权。
+*/
+async function stateDir(repoRoot, runner = gitRunner) {
+	let key = safeRealpath(repoRoot);
+	try {
+		const common = await commonGitDir(runner, repoRoot);
+		if (common) key = common.replace(/[/\\]\.git[/\\]?$/, "") || common;
+	} catch {}
+	const hash = createHash("sha256").update(key).digest("hex").slice(0, 12);
+	const name = basename(key).replace(/[^\w.-]+/g, "-") || "repo";
+	return join(userStateRoot(), "repos", `${name}-${hash}`);
 }
 /** 审计留痕; 失败不阻断门禁 */
-async function appendAudit(repoRoot, entry) {
+async function appendAudit(repoRoot, entry, runner = gitRunner) {
 	try {
-		await mkdir(stateDir(repoRoot), { recursive: true });
-		await appendFile(join(stateDir(repoRoot), "audit.jsonl"), `${JSON.stringify(entry)}\n`, "utf8");
+		const dir = await stateDir(repoRoot, runner);
+		await mkdir(dir, { recursive: true });
+		await appendFile(join(dir, "audit.jsonl"), `${JSON.stringify(entry)}\n`, "utf8");
 	} catch {}
 }
 /** 解析一条命令: 分类 → git 事实 → 门禁 → allow/deny */
@@ -1158,7 +1207,7 @@ async function evaluateCommand(command, opts) {
 				event: "deny",
 				command,
 				reason: decision.reason
-			});
+			}, env.runner);
 			return {
 				outcome: "deny",
 				reason: {
@@ -1189,7 +1238,7 @@ async function logCiReference(seg, env) {
 		event: "ci",
 		command: seg.pr ?? void 0,
 		role: state
-	});
+	}, env.runner);
 }
 /** 按段预取 git 事实(异步 I/O 全部前置, 门禁保持纯函数) */
 async function factsFor(seg, env) {
@@ -1242,4 +1291,4 @@ function apply(ctx, pluginConfig = {}) {
 	});
 }
 //#endregion
-export { name as a, findRepoRoot as c, roleMatches as d, MESSAGE_KEYS as f, classify as g, resolveLocale as h, formatDeny as i, gitRunner as l, registerLocale as m, apply as n, stateDir as o, makeT as p, evaluateCommand as r, currentBranch as s, appendAudit as t, loadConfig as u };
+export { classify as _, name as a, currentBranch as c, loadConfig as d, roleMatches as f, resolveLocale as g, registerLocale as h, formatDeny as i, findRepoRoot as l, makeT as m, apply as n, stateDir as o, MESSAGE_KEYS as p, evaluateCommand as r, userStateRoot as s, appendAudit as t, gitRunner as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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",
@@ -60,7 +60,9 @@
     "prepack": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
-    "verify:matrix": "npm run build && node scripts/verify-matrix.mjs"
+    "verify:matrix": "npm run build && node scripts/verify-matrix.mjs",
+    "check:pins": "node scripts/check-version-pins.mjs",
+    "prepublishOnly": "npm run check:pins"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",