luminae-helper 1.0.3 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -17,7 +17,7 @@ description: 用户要求 Git 提交、推送或提交前审查时使用;普
|
|
|
17
17
|
## 执行
|
|
18
18
|
|
|
19
19
|
1. 确认仓库、当前分支、工作区及暂存区;读工作区与暂存区 diff,识别用户指定文件或改动块。已有无关改动和暂存内容保持原样。
|
|
20
|
-
2.
|
|
20
|
+
2. 审查目标改动及必要的直接上下文,执行项目要求且与范围相称的检查。发现敏感信息、公共受控副本、依赖/构建契约限制时遵循项目边界。改动涉及样式、布局或交互,且渲染结果无法通过静态检查确认时,先本地启动页面截图自检并随审查结论附截图,再进入提交——agent 看不见渲染结果的 UI 交付,约 70% 问题本可在这一步拦截(用户估算,2026-09 复盘)。项目需要登录态、启动成本高或改动可通过静态检查确认时,跳过截图,在审查结论中注明「未经渲染验证」,由用户决定是否补验。
|
|
21
21
|
3. 提交前核实实际提交范围恰好是用户授权范围。不使用无差别暂存;文件中混有其他改动时按块隔离。无法安全隔离或无法确认归属时询问,不擅自清空他人暂存内容。
|
|
22
22
|
4. 按主要变更意图生成 Conventional Commit:`<type>(<scope>): <subject>`。scope 可省略,body 用中文解释背景和关键改动;不要仅凭文件扩展名判定类型。
|
|
23
23
|
5. 只执行已授权动作。推送前确认目标 remote、branch/upstream 和将被推送的提交集合;不能只看最新一个提交。目标不明或包含未授权提交时先确认。禁止擅自强推、切分支、改历史或处理远端冲突。
|
package/package.json
CHANGED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: git-flow
|
|
3
|
+
description: Create, check out, or finish Git Flow feature, release, and hotfix branches; not for generic Git operations or read-only Git questions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Git Flow
|
|
7
|
+
|
|
8
|
+
此流程与原始 Git Flow 不同:三类新分支都从最新生产主干创建,finish 都发布到生产主干并合入 `develop`。生产主干是仓库实际使用的 `master` 或 `main`;先确认 remote 和主干,不自行切换发布线或创建 worktree。用户本次的明确限制优先于本 skill;流程描述本身不替代当前任务对提交、远端写入和删除的授权。
|
|
9
|
+
|
|
10
|
+
| 类型 | 新分支 | finish 的 Tag |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| feature | `feature/<功能简称>` | 远端生产主干可达的最高 `X.Y.Z` Tag → `X.(Y+1).0` |
|
|
13
|
+
| release | `release/X.Y.Z`;未提供目标版本时询问 | 分支名中的 `X.Y.Z` |
|
|
14
|
+
| hotfix | `hotfix/X.Y.Z`;创建时按远端 Tag 与 hotfix 分支计算 | 远端生产主干可达的最高 `X.Y.Z` Tag → `X.Y.(Z+1)`,可能与分支名不同 |
|
|
15
|
+
|
|
16
|
+
版本按三个数字段比较,只接受严格的 `X.Y.Z`。使用 [版本计算脚本](scripts/version.py) 获取创建 hotfix、release 校验及三类 finish 的候选版本;先获取最新远端生产主干、分支和 Tag,再在仓库根目录运行。脚本只读本地 Git 和实时远端引用,输出一行 JSON,不创建分支、提交或 Tag。`status=error` 时停止并处理原因;`status=needs_review` 时展示依据并暂停确认,不自行改算。没有合格 Tag、版本线或格式约定不明时暂停核对;不得猜测、覆盖 Tag 或重写历史。release 目标版本须高于远端生产主干的最高版本 Tag。
|
|
17
|
+
|
|
18
|
+
## 按任务读取
|
|
19
|
+
|
|
20
|
+
- 新建或检出已有分支:读 [创建与检出](references/create.md)。
|
|
21
|
+
- 完成分支:读 [Finish](references/finish.md)。
|
|
22
|
+
|
|
23
|
+
结束时报告实际分支、版本 Tag、已推送及已删除的引用;失败时列明已完成和未完成的步骤。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# 创建与检出
|
|
2
|
+
|
|
3
|
+
## 已有分支
|
|
4
|
+
|
|
5
|
+
用户要求检出已有分支时,确认本地、远端和现有 worktree 的占用状态,检出指定本地分支或跟踪同名远端分支。不要生成新版本、新分支或推送。切换可能覆盖改动时暂停;不自动 stash、reset 或覆盖。
|
|
6
|
+
|
|
7
|
+
## 新分支
|
|
8
|
+
|
|
9
|
+
1. 确认仓库、remote、生产主干、工作区和暂存区干净,且无未完成的 Git 操作或同名本地分支。获取最新远端生产主干、远端分支和 Tag。若本地生产主干落后,只允许快进到远端提交;若超前、分叉、有未提交改动或更新失败,暂停,不把未发布提交混入起点。三类分支均从核实后的最新生产主干提交创建,不从 `develop` 或旧 Tag 创建。
|
|
10
|
+
2. feature 使用用户给出的功能简称。release 使用用户指定的目标 `X.Y.Z`;未指定时先询问,不自动递增。hotfix 和 release 的版本计算/校验调用 `scripts/version.py`(路径相对本 skill 目录):
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
python3 "$skill_dir/scripts/version.py" create-hotfix --repo . --remote origin --production master
|
|
14
|
+
python3 "$skill_dir/scripts/version.py" create-release --repo . --remote origin --production master --branch release/1.2.3
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
将 `skill_dir` 设为本 skill 的绝对目录,并将示例中的 remote、生产主干、release 版本替换为当前仓库的实际值。
|
|
18
|
+
|
|
19
|
+
hotfix 候选取远端生产主干可达的最高 `X.Y.Z` Tag 与远端严格匹配 `hotfix/X.Y.Z` 的最高分支版本,按数字比较并对较大者的补丁段加 1。展示脚本返回的依据与候选名;未事先明确版本时创建前取得确认,已明确版本时核对它符合规则而不重复询问。脚本 `needs_review` 或版本线、占用状态不明时暂停;`error` 时不要绕过脚本自行猜版本。创建阶段不写 CHANGELOG 占位内容或发布 Tag。
|
|
20
|
+
3. 用 `git check-ref-format --branch` 校验完整名称,确认本地与远端均无同名分支,然后创建并检出。再次确认远端同名 ref **明确不存在**;查询或认证失败不能当作不存在。除非用户本次限定仅本地,创建后立即只新建同名远端 ref:
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
git push --porcelain --no-follow-tags --force-with-lease=refs/heads/<分支名>: <remote> HEAD:refs/heads/<分支名>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
空的 lease 期望值要求远端 ref 仍不存在;不得添加 `--force` 或 `+`,也不能换成普通 push。仅 porcelain `*` 表示新建成功;`=` 也按重名处理。成功后回读远端 SHA,设置同名 upstream。若已存在或并发抢先创建,保留本地分支,停止推送,告知用户该名称可能被他人占用并需换名;不覆盖、接管或自行改名。
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Finish
|
|
2
|
+
|
|
3
|
+
按以下顺序执行。任何本次请求中的明确限制优先于默认流程。
|
|
4
|
+
|
|
5
|
+
1. **预检与定版:** 确认源分支、remote、生产主干、`develop`、工作区/暂存区、待合并提交及未完成 Git 操作。获取最新远端分支和 Tag;本地目标落后时只快进,有分叉或未发布本地提交时暂停查明。确认远端源分支未被他人推进。按源分支类型运行 `scripts/version.py`(路径相对本 skill 目录),使用其 `candidate` 作为 Tag,不自行重新计算:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
python3 "$skill_dir/scripts/version.py" finish-feature --repo . --remote origin --production master --branch feature/shop_notice
|
|
9
|
+
python3 "$skill_dir/scripts/version.py" finish-hotfix --repo . --remote origin --production master --branch hotfix/1.2.4
|
|
10
|
+
python3 "$skill_dir/scripts/version.py" finish-release --repo . --remote origin --production master --branch release/1.3.0
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
将 `skill_dir` 设为本 skill 的绝对目录,并将示例中的 remote、生产主干、源分支替换为当前仓库的实际值。
|
|
14
|
+
|
|
15
|
+
脚本 `error` 时停止,`needs_review` 时暂停确认;随后检查本地是否也存在同名 Tag、重复合并或发布。hotfix 的最终 Tag 可与创建时的分支名不同;若候选 Tag 对应其他进行中的 hotfix/release 或版本线不明,暂停询问。
|
|
16
|
+
2. **在源分支完成 CHANGELOG:** 首次合并前核对本次实际变化和 `CHANGELOG.md`,尤其是开发期间写入的 `[Unreleased]`。文件不存在时新建最小日志,以 `# Changelog` 和 `## [X.Y.Z] - YYYY-MM-DD` 起始,其中版本取第 1 步结果、日期取本次发布日期;只记录从本次发布起可核实的变化,不追溯补写此前版本、日期或条目。feature 记录实际功能或行为变化(如 `Added`、`Changed`),hotfix 记录实际修复(如 `Fixed`),release 汇总自上一生产 Tag 以来本版本尚未记录的显著变化;优化表述、分类、去重,不照搬分支名或提交日志。release 若已有与 `release/X.Y.Z` 一致且内容正确的版本节,保留版本号;若缺失、仍为 `[Unreleased]` 或写错版本号,把属于本次发布的内容整理到正确的 `[X.Y.Z]` 节,并按项目格式填写发布日期。其他未来版本内容留在 `[Unreleased]`;已有目标节则合并去重,不创建重复标题。内容或归属无法核实、其他改动无法安全隔离时暂停询问;无显著变化时不编造条目。
|
|
17
|
+
|
|
18
|
+
**合并门槛:** 若需改动,保持检出源分支,只暂存 `CHANGELOG.md` 并创建一个独立提交;核对当前分支、提交 SHA 和该提交的文件清单,仅包含预期 CHANGELOG 改动后才可切换目标分支。不得在目标分支补写,也不得携带未提交的 CHANGELOG 改动进入合并。无需改动时不制造空提交。
|
|
19
|
+
3. **先完成两次本地合并:** 确认生产主干仍是远端最新提交,以 `git merge --no-ff <源分支>` 合入生产主干;在该合并提交创建附注版本 Tag;单行 message 使用 `Release <版本> <摘要>`,摘要依据本次 CHANGELOG 和实际改动概括主要内容,不得只写 `Release <版本>`;整条 message 不超过 50 个字符(含空格、标点)。创建后回读 message、长度和 Tag 指向,再运行相关项目检查。再更新本地 `develop` 到远端最新提交,以 `git merge --no-ff <同一源分支>` 合入,核对它包含源提交并运行相关检查。在两次合并和检查都成功前,不推送任一目标分支或 Tag。
|
|
20
|
+
4. **依次发布:** 再次核对远端目标 ref 和 Tag 未变化。先推送 `develop` 并回读确认,再推送生产主干和 Tag 并回读确认;生产主干与 Tag 优先原子推送,不支持时逐项核对。不得强推或覆盖已有 Tag。
|
|
21
|
+
5. **处理失败:** 任一合并冲突立即暂停并保留现场,报告目标、冲突文件、`git status` 摘要及已完成的提交、Tag、推送;不自动解冲突、abort、继续发布或删除源分支。检查或推送失败也暂停,报告已改变的引用和剩余步骤;已推送的引用不自动回滚。用户处理后重新核查远端状态再继续。
|
|
22
|
+
6. **清理源分支:** 仅当生产主干、Tag 和 `develop` 全部推送且回读验证后,自动删除远端及本地源分支,无需再次询问。先确认远端两个目标分支都包含源提交并读取远端源 ref 的确切 SHA;仅在它仍等于该 SHA 时条件删除,例如 `git push --force-with-lease=refs/heads/<源分支>:<SHA> <remote> :refs/heads/<源分支>`,不得加 `--force` 或 `+`。远端删除成功后用 `git branch -d <源分支>` 删除本地;任一验证或删除失败则停止并报告保留的引用,不强制删除。
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Calculate company Git Flow versions from live remote refs; never write Git state."""
|
|
3
|
+
|
|
4
|
+
import argparse
|
|
5
|
+
import json
|
|
6
|
+
import re
|
|
7
|
+
import subprocess
|
|
8
|
+
import sys
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
VERSION = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+\Z")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def git(repo, *args):
|
|
16
|
+
result = subprocess.run(
|
|
17
|
+
["git", "-C", str(repo), *args], capture_output=True, text=True, check=False
|
|
18
|
+
)
|
|
19
|
+
if result.returncode:
|
|
20
|
+
raise ValueError(result.stderr.strip() or f"git {' '.join(args)} failed")
|
|
21
|
+
return result.stdout.strip()
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def version(text):
|
|
25
|
+
return tuple(map(int, text.split("."))) if VERSION.fullmatch(text) else None
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def render(parts):
|
|
29
|
+
return ".".join(map(str, parts))
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def calculate(args):
|
|
33
|
+
if args.production not in ("main", "master"):
|
|
34
|
+
raise ValueError("production must be main or master")
|
|
35
|
+
if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._/-]*", args.remote):
|
|
36
|
+
raise ValueError("invalid remote name")
|
|
37
|
+
|
|
38
|
+
repo = Path(args.repo).resolve()
|
|
39
|
+
if Path(git(repo, "rev-parse", "--show-toplevel")).resolve() != repo:
|
|
40
|
+
raise ValueError("repo must be the repository root")
|
|
41
|
+
|
|
42
|
+
refs = git(repo, "ls-remote", "--heads", "--tags", args.remote).splitlines()
|
|
43
|
+
live = {}
|
|
44
|
+
for line in refs:
|
|
45
|
+
sha, ref = line.split("\t", 1)
|
|
46
|
+
live[ref] = sha
|
|
47
|
+
|
|
48
|
+
production_ref = f"refs/heads/{args.production}"
|
|
49
|
+
production_sha = live.get(production_ref)
|
|
50
|
+
if not production_sha:
|
|
51
|
+
raise ValueError(f"remote {production_ref} is missing")
|
|
52
|
+
tracking_ref = f"refs/remotes/{args.remote}/{args.production}"
|
|
53
|
+
if git(repo, "rev-parse", "--verify", tracking_ref) != production_sha:
|
|
54
|
+
raise ValueError("local remote-tracking production branch is stale; fetch and retry")
|
|
55
|
+
|
|
56
|
+
merged_tags = set(git(repo, "tag", "--merged", tracking_ref).splitlines())
|
|
57
|
+
local_tags = dict(
|
|
58
|
+
line.split("\t", 1)
|
|
59
|
+
for line in git(repo, "for-each-ref", "--format=%(refname)%09%(objectname)", "refs/tags").splitlines()
|
|
60
|
+
)
|
|
61
|
+
reachable = []
|
|
62
|
+
for ref, sha in live.items():
|
|
63
|
+
if not ref.startswith("refs/tags/") or ref.endswith("^{}"):
|
|
64
|
+
continue
|
|
65
|
+
name = ref.removeprefix("refs/tags/")
|
|
66
|
+
parsed = version(name)
|
|
67
|
+
if parsed is None:
|
|
68
|
+
continue
|
|
69
|
+
if local_tags.get(ref) != sha:
|
|
70
|
+
raise ValueError(f"local tag {name} differs from remote; fetch and retry")
|
|
71
|
+
if name in merged_tags:
|
|
72
|
+
reachable.append((parsed, name))
|
|
73
|
+
if not reachable:
|
|
74
|
+
raise ValueError("no X.Y.Z tag reachable from remote production branch")
|
|
75
|
+
|
|
76
|
+
tag_number, tag_name = max(reachable)
|
|
77
|
+
result = {
|
|
78
|
+
"status": "ok",
|
|
79
|
+
"mode": args.mode,
|
|
80
|
+
"production": args.production,
|
|
81
|
+
"production_sha": production_sha,
|
|
82
|
+
"base_tag": tag_name,
|
|
83
|
+
}
|
|
84
|
+
hotfixes = []
|
|
85
|
+
for ref in live:
|
|
86
|
+
if ref.startswith("refs/heads/hotfix/"):
|
|
87
|
+
name = ref.removeprefix("refs/heads/hotfix/")
|
|
88
|
+
parsed = version(name)
|
|
89
|
+
if parsed is not None:
|
|
90
|
+
hotfixes.append((parsed, name))
|
|
91
|
+
|
|
92
|
+
if args.mode == "create-hotfix":
|
|
93
|
+
highest_hotfix = max(hotfixes) if hotfixes else None
|
|
94
|
+
result["highest_remote_hotfix"] = highest_hotfix[1] if highest_hotfix else None
|
|
95
|
+
base = max(tag_number, highest_hotfix[0]) if highest_hotfix else tag_number
|
|
96
|
+
candidate = render((base[0], base[1], base[2] + 1))
|
|
97
|
+
result["candidate"] = f"hotfix/{candidate}"
|
|
98
|
+
if highest_hotfix and highest_hotfix[0] > tag_number and highest_hotfix[0][:2] != tag_number[:2]:
|
|
99
|
+
result["status"] = "needs_review"
|
|
100
|
+
result["reason"] = "highest hotfix uses a newer version line than the production tag"
|
|
101
|
+
if f"refs/heads/hotfix/{candidate}" in live:
|
|
102
|
+
raise ValueError("candidate hotfix branch already exists on remote")
|
|
103
|
+
elif args.mode == "finish-feature":
|
|
104
|
+
result["candidate"] = render((tag_number[0], tag_number[1] + 1, 0))
|
|
105
|
+
elif args.mode == "finish-hotfix":
|
|
106
|
+
result["candidate"] = render((tag_number[0], tag_number[1], tag_number[2] + 1))
|
|
107
|
+
else:
|
|
108
|
+
if not args.branch or not args.branch.startswith("release/"):
|
|
109
|
+
raise ValueError("release mode requires --branch release/X.Y.Z")
|
|
110
|
+
target = args.branch.removeprefix("release/")
|
|
111
|
+
parsed = version(target)
|
|
112
|
+
if parsed is None or parsed <= tag_number:
|
|
113
|
+
raise ValueError("release version must be X.Y.Z and higher than production tag")
|
|
114
|
+
result["candidate"] = target
|
|
115
|
+
|
|
116
|
+
if args.mode == "create-release":
|
|
117
|
+
if f"refs/heads/{args.branch}" in live:
|
|
118
|
+
raise ValueError("candidate release branch already exists on remote")
|
|
119
|
+
|
|
120
|
+
if args.mode.startswith("finish-") or args.mode == "create-release":
|
|
121
|
+
candidate = result["candidate"]
|
|
122
|
+
if f"refs/tags/{candidate}" in live:
|
|
123
|
+
raise ValueError(f"remote tag {candidate} already exists")
|
|
124
|
+
other = [
|
|
125
|
+
f"{kind}/{candidate}" for kind in ("hotfix", "release")
|
|
126
|
+
if f"refs/heads/{kind}/{candidate}" in live and f"{kind}/{candidate}" != args.branch
|
|
127
|
+
]
|
|
128
|
+
if other:
|
|
129
|
+
result["status"] = "needs_review"
|
|
130
|
+
result["reason"] = "candidate version has another remote branch: " + ", ".join(other)
|
|
131
|
+
return result
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def main():
|
|
135
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
136
|
+
parser.add_argument("mode", choices=("create-hotfix", "create-release", "finish-feature", "finish-hotfix", "finish-release"))
|
|
137
|
+
parser.add_argument("--repo", default=".")
|
|
138
|
+
parser.add_argument("--remote", required=True)
|
|
139
|
+
parser.add_argument("--production", required=True)
|
|
140
|
+
parser.add_argument("--branch", help="source branch; required for release modes")
|
|
141
|
+
args = parser.parse_args()
|
|
142
|
+
try:
|
|
143
|
+
print(json.dumps(calculate(args), ensure_ascii=False, separators=(",", ":")))
|
|
144
|
+
except (ValueError, OSError) as exc:
|
|
145
|
+
print(json.dumps({"status": "error", "reason": str(exc)}, ensure_ascii=False), file=sys.stderr)
|
|
146
|
+
return 2
|
|
147
|
+
return 0
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
if __name__ == "__main__":
|
|
151
|
+
sys.exit(main())
|