@seanyao/roll 2026.505.1 → 2026.505.3

package/README.md

@@ -48,8 +48,7 @@ roll setup
 To update:
 
 ```bash
-npm install -g @seanyao/roll@latest
-roll setup
+roll update
 ```
 
 > **For contributors** (working on roll itself): `git clone https://github.com/seanyao/roll.git && cd roll && ./install.sh`
@@ -65,6 +64,7 @@ Unified behavioral conventions for Claude Code / Gemini CLI / Cursor / Codex —
 | Command | Description |
 |---------|-------------|
 | `roll setup` | First-time install on this machine, or re-sync after editing `~/.roll/config.yaml` (use `--force` to overwrite local cache) |
+| `roll update` | One-step upgrade: `npm install -g @seanyao/roll@latest` + re-sync via `roll setup` |
 | `roll init` | New project: create `AGENTS.md` + `BACKLOG.md` + `docs/features/` |
 | `roll hook install` | Optional: global git hook that tags commits with the active AI client |
 | `roll status` | Show sync state, skill links, and detected AI tools |
@@ -80,8 +80,8 @@ roll setup
 cd my-app
 roll init
 
-# 3. Re-sync after editing ~/.roll/config.yaml or after upgrading
-roll setup
+# 3. Upgrade to a new release
+roll update
 
 # 4. Optional: tag commits with AI client name
 roll hook install

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.505.1"
+VERSION="2026.505.3"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -177,18 +177,18 @@ safe_copy() {
     fi
     echo ""
     warn "File exists and differs: ${dst/#$HOME/~}  文件已存在且内容不同: ${dst/#$HOME/~}"
-    echo -e "  ${BOLD}Overwrite?${NC} [y/N/d(iff)] "
+    echo -e "  ${BOLD}Overwrite?${NC} [Y/n/d(iff)] "
     read -r answer
     case "$answer" in
       d|D|diff)
         diff --color=auto "$dst" "$src" || true
         echo ""
-        echo -e "  ${BOLD}Overwrite?${NC} [y/N] "
+        echo -e "  ${BOLD}Overwrite?${NC} [Y/n] "
         read -r answer2
-        [[ "$answer2" =~ ^[Yy]$ ]] || { info "Skipped: ${dst/#$HOME/\~}  已跳过: ${dst/#$HOME/\~}"; return; }
+        [[ "$answer2" =~ ^[Nn]$ ]] && { info "Skipped: ${dst/#$HOME/\~}  已跳过: ${dst/#$HOME/\~}"; return; }
         ;;
-      y|Y) ;;
-      *) info "Skipped: ${dst/#$HOME/~}  已跳过: ${dst/#$HOME/~}"; return ;;
+      n|N) info "Skipped: ${dst/#$HOME/~}  已跳过: ${dst/#$HOME/~}"; return ;;
+      *) ;;  # empty answer or 'y' / 'Y' → overwrite (default Yes)
     esac
   fi
 
@@ -541,6 +541,27 @@ cmd_setup() {
   info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
 }
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# COMMAND: update
+# Thin wrapper: upgrade the npm-installed package, then re-sync via setup.
+# Equivalent to: npm install -g @seanyao/roll@latest && roll setup
+# ═══════════════════════════════════════════════════════════════════════════════
+cmd_update() {
+  info "Current version: roll v${VERSION}  当前版本: roll v${VERSION}"
+  info "Upgrading via npm...  正在通过 npm 升级..."
+  echo ""
+
+  if ! npm install -g @seanyao/roll@latest; then
+    err "npm install failed. Check network/proxy and try again.  npm 安装失败，请检查网络/代理后重试。"
+    exit 1
+  fi
+
+  echo ""
+  info "Re-syncing to AI tools...  正在重新同步到 AI 工具..."
+  echo ""
+  cmd_setup
+}
+
 # ─── Helper: merge global AGENTS.md into project (no type prompt) ────────────
 # Fresh project: copies global AGENTS.md.
 # Existing AGENTS.md: appends any ## sections missing from global.
@@ -551,25 +572,49 @@ _merge_global_to_project() {
 
   [[ -f "$src" ]] || { warn "Global AGENTS.md not found at ${src/#$HOME/~}"; return; }
 
+  # Detect project type — controls which sections are included
+  local project_type skip_frontend=false
+  project_type="$(scan_project_type_from_files "$project_dir")"
+  case "$project_type" in
+    cli|backend-service|unknown) skip_frontend=true ;;
+  esac
+
   if [[ ! -f "$dst" ]]; then
-    cp "$src" "$dst"
+    # Fresh create: write sections filtered by project type
+    local fc_h="" fc_b="" fc_pre=true fc_want=true
+    while IFS= read -r fc_line; do
+      if [[ "$fc_line" =~ ^##\  ]]; then
+        if [[ -n "$fc_h" && "$fc_want" == "true" ]]; then
+          printf '%s\n%s' "$fc_h" "$fc_b" >> "$dst"
+        fi
+        fc_h="$fc_line"; fc_b=""; fc_pre=false
+        fc_want=true
+        [[ "$skip_frontend" == "true" && "$fc_h" == "## 7. Frontend Default Stack" ]] && fc_want=false
+      elif [[ "$fc_pre" == "true" ]]; then
+        printf '%s\n' "$fc_line" >> "$dst"
+      else
+        fc_b+="$fc_line"$'\n'
+      fi
+    done < "$src"
+    if [[ -n "$fc_h" && "$fc_want" == "true" ]]; then
+      printf '%s\n%s' "$fc_h" "$fc_b" >> "$dst"
+    fi
     ok "Created: AGENTS.md"
     _ROLL_MERGE_SUMMARY+=("created|AGENTS.md")
     return
   fi
 
-  if diff -q "$src" "$dst" &>/dev/null; then
-    _ROLL_MERGE_SUMMARY+=("unchanged|AGENTS.md")
-    return
-  fi
-
   # Section-merge: append any ## sections from global missing in project
   local added=0 cur_h="" cur_b=""
   while IFS= read -r line; do
     if [[ "$line" =~ ^##\  ]]; then
       if [[ -n "$cur_h" ]] && ! grep -qF "$cur_h" "$dst" 2>/dev/null; then
-        printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$dst"
-        added=$((added + 1))
+        local skip_sec=false
+        [[ "$skip_frontend" == "true" && "$cur_h" == "## 7. Frontend Default Stack" ]] && skip_sec=true
+        if [[ "$skip_sec" == "false" ]]; then
+          printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$dst"
+          added=$((added + 1))
+        fi
       fi
       cur_h="$line"; cur_b=""
     elif [[ -n "$cur_h" ]]; then
@@ -577,8 +622,12 @@ _merge_global_to_project() {
     fi
   done < "$src"
   if [[ -n "$cur_h" ]] && ! grep -qF "$cur_h" "$dst" 2>/dev/null; then
-    printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$dst"
-    added=$((added + 1))
+    local skip_sec=false
+    [[ "$skip_frontend" == "true" && "$cur_h" == "## 7. Frontend Default Stack" ]] && skip_sec=true
+    if [[ "$skip_sec" == "false" ]]; then
+      printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$dst"
+      added=$((added + 1))
+    fi
   fi
 
   if [[ $added -gt 0 ]]; then
@@ -589,6 +638,52 @@ _merge_global_to_project() {
   fi
 }
 
+_merge_claude_to_project() {
+  local project_dir="$1"
+  local project_type
+  project_type="$(scan_project_type_from_files "$project_dir")"
+
+  local tpl_file="$ROLL_TEMPLATES/$project_type/CLAUDE.md"
+  [[ -f "$tpl_file" ]] || return 0  # No template for this project type
+
+  local claude_dir="$project_dir/.claude"
+  local out_file="$claude_dir/CLAUDE.md"
+
+  mkdir -p "$claude_dir"
+
+  if [[ ! -f "$out_file" ]]; then
+    cp "$tpl_file" "$out_file"
+    ok "Created: .claude/CLAUDE.md"
+    _ROLL_MERGE_SUMMARY+=("created|.claude/CLAUDE.md")
+    return
+  fi
+
+  # Append any ## sections from template missing in project file
+  local added=0 cur_h="" cur_b=""
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^##\  ]]; then
+      if [[ -n "$cur_h" ]] && ! grep -qF "$cur_h" "$out_file" 2>/dev/null; then
+        printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$out_file"
+        added=$((added + 1))
+      fi
+      cur_h="$line"; cur_b=""
+    elif [[ -n "$cur_h" ]]; then
+      cur_b+="$line"$'\n'
+    fi
+  done < "$tpl_file"
+  if [[ -n "$cur_h" ]] && ! grep -qF "$cur_h" "$out_file" 2>/dev/null; then
+    printf '\n%s\n%s' "$cur_h" "$cur_b" >> "$out_file"
+    added=$((added + 1))
+  fi
+
+  if [[ $added -gt 0 ]]; then
+    ok "Merged: .claude/CLAUDE.md ($added new sections)"
+    _ROLL_MERGE_SUMMARY+=("merged|.claude/CLAUDE.md")
+  else
+    _ROLL_MERGE_SUMMARY+=("unchanged|.claude/CLAUDE.md")
+  fi
+}
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # COMMAND: init
 # Initialize or re-merge a project. Always operates on the current directory.
@@ -612,6 +707,7 @@ cmd_init() {
   fi
 
   _merge_global_to_project "$project_dir"
+  _merge_claude_to_project "$project_dir"
   _write_backlog "$project_dir/BACKLOG.md"
   _ensure_features_dir "$project_dir/docs/features"
   print_merge_summary
@@ -1179,12 +1275,14 @@ usage() {
   echo ""
   echo "Commands:"
   echo "  setup [-f]             [Machine] First-time install or re-sync             首次安装或重新同步"
+  echo "  update                 [Upgrade] npm install latest + re-sync             一键升级到最新版"
   echo "  init                   [Project] Create AGENTS.md + BACKLOG.md + docs/     初始化项目工作流文件"
   echo "  hook [install|remove]  [Optional] Manage global git hook                  管理全局 git hook"
   echo "  status                 [Diagnostic] Show current state                    显示当前状态"
   echo ""
   echo "Examples / 示例:"
-  echo "  roll setup                    # New machine, or re-sync after npm update    新机器或更新后重新同步"
+  echo "  roll setup                    # New machine: first-time install            新机器首次安装"
+  echo "  roll update                   # Upgrade to latest version + re-sync         升级到最新版并重新同步"
   echo "  roll init                     # New or re-merge project (run in project)   新建或重新合并（项目目录）"
   echo "  roll hook install             # Optional: tag commits with AI client       可选：提交时标记 AI 工具"
 }
@@ -1195,6 +1293,7 @@ main() {
 
   case "$cmd" in
     setup)         cmd_setup "$@" ;;
+    update)        cmd_update "$@" ;;
     init)          cmd_init "$@" ;;
     hook)          cmd_hook "$@" ;;
     status)        cmd_status "$@" ;;
@@ -1233,7 +1332,7 @@ _notify_update() {
   local latest; latest=$(awk '{print $2}' "$cache" 2>/dev/null || true)
   [[ -z "$latest" || "$latest" == "$VERSION" ]] && return
   echo ""
-  warn "v${latest} available — run 'npm install -g @seanyao/roll@latest && roll setup' to upgrade  有新版本 v${latest} — 运行 'npm install -g @seanyao/roll@latest && roll setup' 升级"
+  warn "v${latest} available — run 'roll update' to upgrade  有新版本 v${latest} — 运行 'roll update' 升级"
 }
 
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then

package/conventions/templates/cli/CLAUDE.md

@@ -4,10 +4,9 @@
 
 ## Stack
 
-- Node.js / TypeScript
-- CLI framework: commander or citty
-- Testing: Vitest + execa (CLI integration tests)
-- Distribution: npm package with bin entry
+- Runtime / Language: {e.g. Node.js / TypeScript, Go, Python, Bash}
+- Test framework: {e.g. Vitest, pytest, bats}
+- Distribution: {e.g. npm, Homebrew, binary release}
 
 ## Claude Code Notes
 
@@ -15,4 +14,3 @@
 - Test commands by running them in Bash, not just unit tests.
 - Use `$roll-design` to plan command structure and options before implementation.
 - Verify `--help` output is clear and complete for each command.
-- Run `npm run build && node dist/index.js --help` before pushing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.505.1",
+  "version": "2026.505.3",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "find tests/unit tests/integration -name '*.bats' | sort | xargs ./tests/helpers/bats-core/bin/bats"