harveyz-skill 0.2.1 → 0.4.0

package/skills/harness/git-workflow-init/references/render_docs.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+git-workflow-init Step 7 渲染器
+从 workflow-config.yml 动态生成 docs/reference/git-workflow.md
+"""
+import sys, re, os
+
+def load_config(path):
+    """简单 YAML 解析（只处理此 skill 使用的字段，无需完整 YAML 库）"""
+    content = open(path).read()
+
+    def extract_list_under(key, text):
+        """提取某个 key 下的列表项（- value 或 - "value"）"""
+        pattern = rf'{re.escape(key)}:\s*\n((?:[ \t]+- .+\n?)+)'
+        m = re.search(pattern, text)
+        if not m:
+            # 尝试行内列表 [a, b, c]
+            m2 = re.search(rf'{re.escape(key)}:\s*\[([^\]]+)\]', text)
+            if m2:
+                return [v.strip().strip('"') for v in m2.group(1).split(',')]
+            return []
+        return [re.sub(r'^[ \t]+- ', '', l).strip().strip('"')
+                for l in m.group(1).splitlines() if l.strip().startswith('- ')]
+
+    # 提取 branches.protected
+    protected = []
+    in_protected = False
+    current = None
+    for line in content.splitlines():
+        if re.match(r'\s+protected:', line):
+            in_protected = True
+            continue
+        if in_protected:
+            m = re.match(r'\s{4}- name:\s+(\S+)', line)
+            if m:
+                if current:
+                    protected.append(current)
+                current = {'name': m.group(1), 'allow_direct_commit': False, 'merge_from': []}
+            elif current and re.match(r'\s+allow_direct_commit:\s*(true|false)', line):
+                current['allow_direct_commit'] = 'true' in line
+            elif current and re.match(r'\s+merge_from:', line):
+                pass  # next lines are the list
+            elif current and re.match(r'\s{8}- ', line):
+                val = line.strip().lstrip('- ').strip('"')
+                current['merge_from'].append(val)
+            elif line.strip() and not line.startswith(' '):
+                in_protected = False
+    if current:
+        protected.append(current)
+
+    # branch_naming
+    naming_patterns = extract_list_under('allowed_patterns', content)
+    naming_exempt   = extract_list_under('exempt', content)
+
+    # commit_message
+    fmt_m = re.search(r'format:\s*(\S+)', content)
+    fmt = fmt_m.group(1) if fmt_m else 'none'
+    types = extract_list_under('types', content)
+    pattern_m = re.search(r'pattern:\s*"([^"]+)"', content)
+    regex_pattern = pattern_m.group(1) if pattern_m else ''
+    max_len_m = re.search(r'max_subject_length:\s*(\d+)', content)
+    max_len = int(max_len_m.group(1)) if max_len_m else 72
+
+    return {
+        'protected': protected,
+        'naming_patterns': naming_patterns,
+        'naming_exempt': naming_exempt,
+        'commit_format': fmt,
+        'commit_types': types,
+        'commit_regex': regex_pattern,
+        'max_subject_length': max_len,
+    }
+
+
+def branch_purpose(name):
+    mapping = {
+        'main': '生产就绪代码', 'master': '生产就绪代码',
+        'staging': '集成 / 预发布', 'develop': '开发集成',
+    }
+    if name in mapping:
+        return mapping[name]
+    if name.startswith('release'):
+        return '发版准备'
+    return '—'
+
+
+def pattern_to_prefix(p):
+    """^feature/.+ → feature/"""
+    m = re.match(r'^\^?([a-z]+)/', p)
+    return m.group(1) + '/' if m else p
+
+
+def pattern_purpose(prefix):
+    mapping = {
+        'feature/': ('新功能', 'feature/user-auth、feature/dark-mode'),
+        'fix/':     ('Bug 修复', 'fix/login-crash、fix/null-pointer'),
+        'chore/':   ('维护、依赖升级等', 'chore/upgrade-deps、chore/ci-timeout'),
+        'doc/':     ('文档更新', 'doc/api-reference、doc/onboarding'),
+        'docs/':    ('文档更新', 'docs/api-reference、docs/onboarding'),
+        'release/': ('发版切点', 'release/1.2.0'),
+        'hotfix/':  ('紧急热修复', 'hotfix/login-crash'),
+    }
+    return mapping.get(prefix, ('—', f'{prefix}example'))
+
+
+def render(config, template):
+    c = config
+    protected = c['protected']
+
+    # ── BRANCH_TOPOLOGY_ASCII ──────────────────────────────────────
+    # 找主分支（没有其他受保护分支 merge_from 到它的最顶层）
+    all_names = {b['name'] for b in protected}
+    merge_targets = set()
+    for b in protected:
+        for mf in b['merge_from']:
+            # mf 可能是 glob，提取固定前缀
+            base = mf.rstrip('/*')
+            if base in all_names:
+                merge_targets.add(base)
+
+    # 拓扑：逐级展开
+    def build_tree(root, depth=0):
+        b = next((x for x in protected if x['name'] == root), None)
+        if not b:
+            return ''
+        indent = '  ' * depth
+        lines = [indent + root]
+        for src in b['merge_from']:
+            src_base = src.rstrip('/*')
+            if src_base in all_names:
+                lines.append(build_tree(src_base, depth + 1))
+            else:
+                lines.append('  ' * (depth + 1) + f'<- {src}')
+        return '\n'.join(l for l in lines if l)
+
+    roots = [b['name'] for b in protected if b['name'] not in merge_targets]
+    ascii_lines = []
+    for r in roots:
+        for src in next(x for x in protected if x['name'] == r)['merge_from']:
+            src_base = src.rstrip('/*')
+            if src_base in all_names:
+                sub = next((x for x in protected if x['name'] == src_base), None)
+                ascii_lines.append(f'{r}')
+                ascii_lines.append(f'  <- {src_base}')
+                for subsrc in (sub['merge_from'] if sub else []):
+                    ascii_lines.append(f'        <- {subsrc}')
+            else:
+                ascii_lines.append(f'{r}')
+                ascii_lines.append(f'  <- {src}')
+    topology_ascii = '\n'.join(ascii_lines) if ascii_lines else ' <- '.join(b['name'] for b in protected)
+
+    # ── BRANCH_TABLE ───────────────────────────────────────────────
+    rows = ['| 分支 | 用途 | 合并目标 |', '|------|------|---------|']
+    for b in protected:
+        target = roots[0] if b['name'] != roots[0] else '—'
+        rows.append(f'| `{b["name"]}` | {branch_purpose(b["name"])} | `{target}` |')
+    for p in c['naming_patterns']:
+        prefix = pattern_to_prefix(p)
+        purpose, _ = pattern_purpose(prefix)
+        target_branch = next((b['name'] for b in protected if b['name'] not in roots), roots[0] if roots else '—')
+        rows.append(f'| `{prefix}<名称>` | {purpose} | `{target_branch}` |')
+    branch_table = '\n'.join(rows)
+
+    # ── PROTECTION_RULES ──────────────────────────────────────────
+    rule_lines = []
+    for b in protected:
+        sources = '、'.join(f'`{s}`' for s in b['merge_from'])
+        if b['allow_direct_commit']:
+            rule_lines.append(f'- **`{b["name"]}`** — 直接提交时发出警告（不阻断）。合并来源建议为 {sources}。')
+        else:
+            rule_lines.append(f'- **`{b["name"]}`** — 禁止直接提交。只接受来自 {sources} 的合并。')
+    protection_rules = '\n'.join(rule_lines)
+
+    # ── WORKFLOW EXAMPLES ─────────────────────────────────────────
+    integration = next((b['name'] for b in protected if b['name'] not in roots), roots[0] if roots else 'staging')
+    main_branch = roots[0] if roots else 'main'
+    checkout_ex = f'git checkout {integration}'
+    merge_ex     = f'git checkout {integration}\ngit merge feature/my-feature'
+    release_ex   = f'git checkout {main_branch}\ngit merge {integration}       # 或：git merge release/x.y.z\ngit push'
+
+    # ── NAMING_TABLE ──────────────────────────────────────────────
+    naming_rows = ['| 前缀 | 适用场景 | 示例 |', '|------|---------|------|']
+    for p in c['naming_patterns']:
+        prefix = pattern_to_prefix(p)
+        purpose, example = pattern_purpose(prefix)
+        naming_rows.append(f'| `{prefix}` | {purpose} | `{example}` |')
+    naming_table = '\n'.join(naming_rows)
+
+    # ── NAMING_EXEMPT ─────────────────────────────────────────────
+    naming_exempt = '、'.join(f'`{e}`' for e in c['naming_exempt']) or '无'
+
+    # ── COMMIT_FORMAT_SECTION ─────────────────────────────────────
+    if c['commit_format'] == 'conventional':
+        types_line = ' | '.join(f'`{t}`' for t in c['commit_types'])
+        commit_section = f"""遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```
+<类型>(<范围>): <简短描述>
+
+[可选正文]
+
+[可选 footer]
+```
+
+**类型：** {types_line}
+
+**首行长度限制：** {c['max_subject_length']} 个字符"""
+    elif c['commit_format'] == 'regex':
+        commit_section = f"""提交信息首行必须匹配正则：
+
+```
+{c['commit_regex']}
+```
+
+**首行长度限制：** {c['max_subject_length']} 个字符"""
+    else:
+        commit_section = '本项目无提交信息格式要求。'
+
+    # ── FAQ_SECTION ───────────────────────────────────────────────
+    faq = []
+    if integration != main_branch:
+        faq.append(f'**Q：在 {integration} 上提交被拒绝怎么办？**\n'
+                   f'A：你正在直接向 {integration} 提交。请新建分支，在新分支提交后再合并回 {integration}。')
+    release_p = [p for p in c['naming_patterns'] if 'release' in p]
+    if release_p:
+        faq.append(f'**Q：需要紧急热修复直接上 {main_branch} 怎么办？**\n'
+                   f'A：从 {main_branch} 切一个 `release/*` 分支，修复后合并到 {main_branch}，再反向合并到 {integration}。')
+    faq_section = '\n\n'.join(faq)
+
+    # ── 替换占位符 ─────────────────────────────────────────────────
+    result = template
+    result = result.replace('{{BRANCH_TOPOLOGY_ASCII}}',    topology_ascii)
+    result = result.replace('{{BRANCH_TABLE}}',             branch_table)
+    result = result.replace('{{PROTECTION_RULES}}',         protection_rules)
+    result = result.replace('{{WORKFLOW_CHECKOUT_EXAMPLE}}', checkout_ex)
+    result = result.replace('{{WORKFLOW_MERGE_EXAMPLE}}',   merge_ex)
+    result = result.replace('{{WORKFLOW_RELEASE_EXAMPLE}}', release_ex)
+    result = result.replace('{{NAMING_TABLE}}',             naming_table)
+    result = result.replace('{{NAMING_EXEMPT}}',            naming_exempt)
+    result = result.replace('{{COMMIT_FORMAT_SECTION}}',    commit_section)
+    result = result.replace('{{FAQ_SECTION}}',              faq_section + '\n\n' if faq_section else '')
+    return result
+
+
+if __name__ == '__main__':
+    config_path   = sys.argv[1]
+    template_path = sys.argv[2]
+    output_path   = sys.argv[3]
+
+    config   = load_config(config_path)
+    template = open(template_path).read()
+    rendered = render(config, template)
+
+    # 差量写入
+    existing = open(output_path).read() if os.path.exists(output_path) else None
+    if existing == rendered:
+        print('UNCHANGED')
+    else:
+        os.makedirs(os.path.dirname(output_path), exist_ok=True)
+        open(output_path, 'w').write(rendered)
+        print('UPDATED' if existing else 'NEW')

package/skills/harness/git-workflow-init/references/workflow-config.yml

@@ -0,0 +1,99 @@
+# workflow-config.yml
+# Git 工作流配置文件 — 由 /git-workflow-init skill 读取、审核并部署
+#
+# 使用方式：将此文件复制到项目根目录，按需修改后运行 /git-workflow-init
+#
+# 每个节对应一个 git hook，注释掉整节 = 不安装该 hook
+
+# ── 元信息 ────────────────────────────────────────────────────────────────────
+meta:
+  name: "my-project-workflow"
+  version: "1.0.0"
+  # preset 决定各节的默认值，可在下方局部覆盖
+  # 可选值：gitflow | github-flow | trunk-based | custom
+  preset: gitflow
+
+# ── 分支拓扑与保护（生成 pre-commit hook）────────────────────────────────────
+#
+# allow_direct_commit: false → 直接提交时 exit 1（硬拦截）
+# allow_direct_commit: true  → 直接提交时仅打印警告，不阻断
+# merge_from 使用 shell glob 语法（* 匹配任意字符，不含 /）
+branches:
+  protected:
+    - name: main
+      allow_direct_commit: false
+      merge_from:
+        - staging
+        - "release/*"
+
+    - name: staging
+      allow_direct_commit: false
+      merge_from:
+        - "feature/*"
+        - "fix/*"
+        - "chore/*"
+        - "doc/*"
+
+# ── 分支命名规范（生成 post-checkout hook）───────────────────────────────────
+#
+# enforce: true  → 切换到不合规分支时打印警告（advisory，不阻断）
+# enforce: false → 跳过，不安装此 hook
+# allowed_patterns 使用 POSIX ERE 语法
+branch_naming:
+  enforce: true
+  allowed_patterns:
+    - "^feature/.+"
+    - "^fix/.+"
+    - "^chore/.+"
+    - "^doc/.+"
+    - "^release/[0-9]+\\.[0-9]+\\.[0-9]+(-.+)?$"
+  exempt:                      # 永远豁免命名检查的分支
+    - main
+    - staging
+
+# ── 提交信息格式（生成 commit-msg hook）──────────────────────────────────────
+#
+# format 可选值：
+#   conventional → 使用下方 conventional 节的设置
+#   regex        → 使用自定义 pattern 字段（需同时填写 pattern）
+#   none         → 不检查格式（但若 enforce: true 会安装空 hook）
+commit_message:
+  enforce: true
+  format: conventional
+  # format: regex 时启用此行：
+  # pattern: "^(JIRA-\\d+|NOJIRA): .{1,80}"
+  conventional:
+    types:
+      - feat
+      - fix
+      - chore
+      - docs
+      - refactor
+      - test
+      - style
+      - perf
+    require_scope: false         # true = feat(scope): msg 中 scope 必填
+    max_subject_length: 80
+
+# ── Tag 命名规范（生成 pre-push hook 的 tag 段）───────────────────────────────
+#
+# push_guard: true → 推送不合规 tag 时 exit 1
+# allowed_patterns 使用 POSIX ERE 语法，满足其中一个即通过
+# require_annotated: true → 强制使用 git tag -a，拒绝 lightweight tag
+tags:
+  enforce: true
+  push_guard: true
+  allowed_patterns:
+    - "^v[0-9]+\\.[0-9]+\\.[0-9]+$"           # 正式版：v1.2.3
+    - "^v[0-9]+\\.[0-9]+\\.[0-9]+-.+$"         # 预发布：v1.2.3-beta.1、v1.2.3-rc.2
+  require_annotated: true
+
+# ── 推送限制（生成 pre-push hook 的分支段）───────────────────────────────────
+#
+# block_force_push 列出的分支，force push 时 exit 1
+# enforce: false 时整节跳过，不安装 pre-push hook（除非 tags 节已启用）
+push_rules:
+  enforce: true
+  block_force_push:
+    - main
+    - staging

package/skills-index.json

@@ -8,7 +8,7 @@
   "bundleMeta": {
     "analysis": "分析工具（skill-analyzer）",
     "brainstorming": "设计与规划工具（brainstorming + writing-plans）",
-    "dev": "开发工作流（executing-plans + systematic-debugging + using-git-worktrees）",
+    "dev": "开发工作流（executing-plans + systematic-debugging + using-git-worktrees + git-workflow-init）",
     "document": "文档工具（diataxis-docs）",
     "harness": "测试工具（full-stack-debug-env）",
     "task": "任务管理（pm-task-dispatch + task-close）",
@@ -20,6 +20,7 @@
     { "path": "harness/diataxis-docs", "bundle": "document" },
     { "path": "harness/full-stack-debug-env", "bundle": "harness" },
     { "path": "superpowers-fork/brainstorming", "bundle": "brainstorming" },
+    { "path": "harness/git-workflow-init", "bundle": "dev" },
     { "path": "superpowers-fork/executing-plans", "bundle": "dev" },
     { "path": "superpowers-fork/systematic-debugging", "bundle": "dev" },
     { "path": "superpowers-fork/using-git-worktrees", "bundle": "dev" },

package/tools/p-launch/p-launch.sh

@@ -68,18 +68,43 @@ _launch() {
   local path="$1"
   local name="${path:t}"
   local display="${path/$HOME/~}"
-  local cursor_ok=false ghostty_ok=false
+  local cursor_ok=false ghostty_ok=false ghostty_err="not installed"
 
-  # Cursor IDE
+  # Cursor IDE — CLI first, fall back to .app
   if command -v cursor &>/dev/null; then
     cursor "$path" &>/dev/null &
     cursor_ok=true
+  elif [[ -d "/Applications/Cursor.app" ]]; then
+    /usr/bin/open -na "Cursor" --args "$path" && cursor_ok=true
   fi
 
-  # Ghostty — force a new window at the project directory
-  if [[ -d "/Applications/Ghostty.app" ]]; then
-    open -na "Ghostty" --args --working-directory="$path"
-    ghostty_ok=true
+  # Ghostty — find app via Spotlight (handles /Applications, ~/Applications,
+  # or any custom install path), then invoke "New Ghostty Window Here" service
+  # via NSPerformService — same code path as Finder right-click service.
+  local ghostty_app
+  ghostty_app=$(mdfind "kMDItemCFBundleIdentifier == 'com.mitchellh.ghostty'" 2>/dev/null | /usr/bin/head -1)
+  if [[ -z "$ghostty_app" ]]; then
+    # mdfind can miss apps before first Spotlight index; fall back to known paths
+    for _p in "/Applications/Ghostty.app" "$HOME/Applications/Ghostty.app"; do
+      [[ -d "$_p" ]] && { ghostty_app="$_p"; break }
+    done
+  fi
+
+  if [[ -n "$ghostty_app" ]]; then
+    ghostty_err="failed to open"
+    # Ghostty's service handler does dirname on the path, so pass a child of
+    # the target dir — dirname(target/child) == target.
+    local _child service_path
+    _child=$(/bin/ls -1A "$path" 2>/dev/null | /usr/bin/head -1)
+    service_path="${path}/${_child}"
+    ${_OSASCRIPT:-/usr/bin/osascript} 2>/dev/null <<OSASCRIPT && ghostty_ok=true
+use framework "AppKit"
+use scripting additions
+set thePboard to current application's NSPasteboard's generalPasteboard()
+thePboard's clearContents()
+thePboard's setPropertyList:{"${service_path}"} forType:"NSFilenamesPboardType"
+return current application's NSPerformService("New Ghostty Window Here", thePboard)
+OSASCRIPT
   fi
 
   # ── Launch Report ──────────────────────────────────────────────────────────
@@ -96,7 +121,7 @@ _launch() {
   if $ghostty_ok; then
     printf "  ${C[gr]}✓${C[rs]} Ghostty  new window opened\n"
   else
-    printf "  ${C[yl]}⚠${C[rs]} Ghostty  /Applications/Ghostty.app not found\n"
+    printf "  ${C[yl]}⚠${C[rs]} Ghostty  %s\n" "$ghostty_err"
   fi
 
   printf '\n'

package/tools/p-launch/tests/unit.bats

@@ -6,7 +6,8 @@ setup() {
   SCRIPT="$(cd "${BATS_TEST_DIRNAME}/.." && pwd)/p-launch.sh"
   TEST_DIR="$(mktemp -d)"
   MOCK_HOME="${TEST_DIR}/home"
-  mkdir -p "${MOCK_HOME}"
+  MOCK_BIN="${TEST_DIR}/bin"
+  mkdir -p "${MOCK_HOME}" "${MOCK_BIN}"
 }
 
 teardown() {
@@ -149,3 +150,79 @@ _src() {
   [ "$status" -eq 0 ]
   [ "${#lines[@]}" -eq 2 ]
 }
+
+# ── _launch: Cursor ────────────────────────────────────────────────────────────
+
+_launch_src() {
+  local code="$1"
+  # _OSASCRIPT lets tests inject a mock without relying on PATH,
+  # since p-launch.sh calls /usr/bin/osascript via full path.
+  local mock_osascript="${MOCK_BIN}/osascript"
+  local osascript_override=""
+  [[ -x "$mock_osascript" ]] && osascript_override="export _OSASCRIPT='${mock_osascript}'"
+  zsh -c "
+    export _P_LAUNCH_TEST=1
+    export HOME='${MOCK_HOME}'
+    export PATH='${MOCK_BIN}:${PATH}'
+    ${osascript_override}
+    source '${SCRIPT}'
+    ${code}
+  "
+}
+
+@test "_launch: reports ✓ Cursor when cursor CLI is in PATH" {
+  printf '#!/bin/sh\nexit 0\n' > "${MOCK_BIN}/cursor"
+  chmod +x "${MOCK_BIN}/cursor"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"✓"*"Cursor"* ]]
+}
+
+@test "_launch: reports ⚠ Cursor when CLI absent and Cursor.app not found" {
+  [[ ! -d "/Applications/Cursor.app" ]] || skip "Cursor.app installed — cannot test absence"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"⚠"*"Cursor"* ]]
+}
+
+# ── _launch: Ghostty ───────────────────────────────────────────────────────────
+
+@test "_launch: reports ✓ Ghostty when osascript succeeds" {
+  [[ -d "/Applications/Ghostty.app" ]] || skip "Ghostty.app not installed"
+  printf '#!/bin/sh\nexit 0\n' > "${MOCK_BIN}/osascript"
+  chmod +x "${MOCK_BIN}/osascript"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"✓"*"Ghostty"* ]]
+}
+
+@test "_launch: reports ⚠ Ghostty when osascript fails" {
+  [[ -d "/Applications/Ghostty.app" ]] || skip "Ghostty.app not installed"
+  printf '#!/bin/sh\nexit 1\n' > "${MOCK_BIN}/osascript"
+  chmod +x "${MOCK_BIN}/osascript"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"⚠"*"Ghostty"* ]]
+}
+
+@test "_launch: reports ⚠ Ghostty when Ghostty.app not found" {
+  [[ ! -d "/Applications/Ghostty.app" ]] || skip "Ghostty.app installed — cannot test absence"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"⚠"*"Ghostty"* ]]
+}
+
+@test "_launch: osascript receives working directory in script" {
+  [[ -d "/Applications/Ghostty.app" ]] || skip "Ghostty.app not installed"
+  printf '#!/bin/sh\nprintf "ARGS:%%s\n" "$@"\nexit 0\n' \
+    > "${MOCK_BIN}/osascript"
+  chmod +x "${MOCK_BIN}/osascript"
+
+  run _launch_src "_launch '${TEST_DIR}'"
+  [[ "$output" == *"${TEST_DIR}"* ]]
+}