agents-gitflow-guard 0.0.8 → 0.0.10

package/README.md

@@ -36,12 +36,16 @@ You define your own branches —
 
 ## Quick Start — 30 seconds to a guarded repo
 
-**Step 1 — install**, one command, then restart DSH (plugins load at process startup):
+**Step 1 — install**, then restart DSH (plugins load at process startup):
 
 ```bash
+# 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
 ```
 
+> **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).
 **Step 2 — configure**, create `gitflow-guard.config.json` in your **project root**:
 
 ```jsonc
@@ -204,7 +208,7 @@ archive (optional; you archive after release)
 | **integration** | `branches.integration` | always | no direct push (default `pr`); features merge in via PR/MR |
 | **preview** | `branches.preview` (array) | optional | no direct push; updates via PR/MR only (env endpoints) |
 | **production** | `branches.production` (array) | optional | PR/MR only; merge by user only (`mergeBy: "user"`) |
-| **archive** | `branches.archive` (array) | optional | user-hand only — agents cannot even create a PR |
+| **archive** | `branches.archive` (array) | optional | archive PR/MR may be created by agents; the merge stays user-hand only |
 
 ### Customizing branch names & rules — any naming works
 
@@ -274,7 +278,7 @@ archive (optional; you archive after release)
 | direct push / force-push / delete integration / preview / production / archive | 🚫 block (integration/preview `flexible` direct push allowed) |
 | PR/MR: feature → integration / preview | ✅ allow |
 | PR/MR: feature → production | ✅ allow to create; **merge blocked** (you merge in UI) |
-| PR/MR targeting archive | 🚫 block |
+| PR/MR into archive | ✅ create allowed; 🚫 merge blocked (you merge in UI) |
 | local `git merge feature/x` while on integration / preview | 🚫 block (PR/MR required); `update: flexible` allows |
 | chained commands (`checkout develop && merge feature/x`) | 🚫 blocked — branch switches are simulated per segment, no bypass |
 
@@ -295,7 +299,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
+dsh plugin --profile web add agents-gitflow-guard@0.0.9    # pin recommended, see note above
 ```
 
 Then restart DSH. Upgrades are the same command, followed by another restart.

package/README.zh.md

@@ -35,12 +35,16 @@
 
 ## 快速开始——30 秒用上
 
-**第 1 步——安装**,一条命令,然后重启 DSH(插件在进程启动时加载):
+**第 1 步——安装**,然后重启 DSH(插件在进程启动时加载):
 
 ```bash
+# 安装最新版
 dsh plugin --profile web add agents-gitflow-guard
+# ...或锁定已知良好版本(推荐; 同时绕开 registry 陈旧缓存)
+dsh plugin --profile web add agents-gitflow-guard@0.0.9
 ```
 
+> **版本坑**: 裸 `add` 装的是安装时刻的 `latest`——在 npm/pnpm 注册表缓存或镜像陈旧的机器上可能拿到旧版本。看到版本不对就锁版本。pnpm 打印的 peer 依赖 *警告* 属预期: DSH 启动时经共享模块回退提供 `@deepseek-ai/cordis` / `@deepseek-ai/dsh-tools`(插件正常工作)。
 **第 2 步——配置**,在**项目根目录**创建 `gitflow-guard.config.json`:
 
 ```jsonc
@@ -201,7 +205,7 @@ archive(可选, 发布后你亲手归档)
 | **integration** | `branches.integration` | 必填 | 禁直推(默认 `pr`);feature 只经 PR/MR 合入 |
 | **preview** | `branches.preview`(数组) | 可选 | 禁直推;只走 PR/MR(环境终点) |
 | **production** | `branches.production`(数组) | 可选 | 只走 PR/MR;合并仅限你(`mergeBy: "user"`) |
-| **archive** | `branches.archive`(数组) | 可选 | 仅用户——agent 连建 PR 都不行 |
+| **archive** | `branches.archive`(数组) | 可选 | 允许 agent 创建指向它的 PR/MR; 合并仍限用户亲手 |
 
 ### 自定义分支名与规则——任何命名都可以
 
@@ -292,7 +296,7 @@ PR/MR 目标通过 `gh pr view`(GitHub)或 `glab mr view`(GitLab)解析;没有
 **从 npm registry**——标准路径,已在[快速开始](#快速开始30-秒用上)覆盖:
 
 ```bash
-dsh plugin --profile web add agents-gitflow-guard
+dsh plugin --profile web add agents-gitflow-guard@0.0.9    # 建议锁版本, 见上文提示
 ```
 
 然后重启 DSH。升级用同一命令,再重启一次。
@@ -438,7 +442,7 @@ MIT,免费,无条件。随便用、随便改、随便发,唯一义务是保留
 | **integration** | 集成分支,唯一必填角色(`branches.integration`);feature 经 PR/MR 合入;受保护 |
 | **preview** | 可选环境终点分支(`branches.preview`,数组);只走 PR/MR 更新 |
 | **production** | 可选生产分支(`branches.production`,数组);PR/MR + 合并仅限用户 |
-| **archive** | 可选发布后归档分支(`branches.archive`);仅用户亲手 |
+| **archive** | `branches.archive`(数组) | 可选 | 允许 agent 创建指向它的 PR/MR; 合并仍限用户亲手 |
 | **feature 分支** | 你的工作分支,由 `featurePattern` 识别;自由区 |
 | **门禁矩阵** | 把每条被分类的命令映射为放行/拦截的判定表 |
 | **pre-execute** | 工具管线中拦截发生的钩子——在命令运行之前 |

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-2TtpUFC9.mjs";
+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-CeEqUVQP.mjs";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 //#region src/platform.ts

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-2TtpUFC9.mjs";
+import { a as name, i as formatDeny, n as apply, o as stateDir, r as evaluateCommand, t as appendAudit } from "./src-CeEqUVQP.mjs";
 export { appendAudit, apply, evaluateCommand, formatDeny, name, stateDir };

package/lib/{src-2TtpUFC9.mjs → src-CeEqUVQP.mjs}

@@ -97,6 +97,7 @@ function parsePush(args, ctx) {
 	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 === "--tags") return [{ kind: "other" }];
 	else if (a.startsWith("-")) {} else nonFlag.push(a);
 	if (all) return [{
 		kind: "push",
@@ -113,10 +114,15 @@ function parsePush(args, ctx) {
 		delete: false
 	}];
 	return refspecs.map((ref) => {
+		let refForce = force;
+		if (ref.startsWith("+")) {
+			refForce = true;
+			ref = ref.slice(1);
+		}
 		if (ref.startsWith(":")) return {
 			kind: "push",
 			dst: stripRefPrefix(ref.slice(1)) || null,
-			force,
+			force: refForce,
 			delete: true
 		};
 		const colon = ref.indexOf(":");
@@ -126,20 +132,20 @@ function parsePush(args, ctx) {
 			return {
 				kind: "push",
 				dst: dst ? stripRefPrefix(dst) : null,
-				force,
+				force: refForce,
 				delete: deleteTarget || isDelete
 			};
 		}
 		if (ref === "HEAD") return {
 			kind: "push",
 			dst: ctx.currentBranch ?? null,
-			force,
+			force: refForce,
 			delete: isDelete
 		};
 		return {
 			kind: "push",
 			dst: stripRefPrefix(ref),
-			force,
+			force: refForce,
 			delete: isDelete
 		};
 	});
@@ -379,8 +385,6 @@ const en = {
 	"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)",
@@ -449,8 +453,6 @@ const zh = {
 	"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)分支仅允许用户亲手点合并",
@@ -598,7 +600,6 @@ function decidePrCreate(c, facts, config, t) {
 	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"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-gitflow-guard",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "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",