superskills-upgrade

/superskills-upgrade

将 superskills 升级到最新版本。

步骤

步骤 1：查找安装目录

支持两种安装方式：

• 规范安装 — 仓库克隆在 ~/.claude/skills/superskills （或 OpenCode 对应的目录）中，并从该目录运行了 ./setup。
• 开发仓库安装 — 仓库位于其他位置（例如 ~/Sites/superskills）， 且 ./setup 已将技能符号链接回工具。这种方式常见于维护者 和贡献者。~/.claude/skills/superskills 下没有克隆仓库；我们会通过将技能符号链接解析回其源位置， 找到真实仓库。

INSTALL_DIR=""
INSTALL_KIND=""

if [ -d "$HOME/.claude/skills/superskills/.git" ]; then
  INSTALL_DIR="$HOME/.claude/skills/superskills"; INSTALL_KIND="canonical"
elif [ -d "$HOME/.config/opencode/skills/superskills/.git" ]; then
  INSTALL_DIR="$HOME/.config/opencode/skills/superskills"; INSTALL_KIND="canonical"
else
  # Dev-repo install: follow a known skill symlink back to its source checkout.
  for probe in "$HOME/.claude/skills/superskills-upgrade/SKILL.md" \
               "$HOME/.config/opencode/skills/superskills-upgrade/SKILL.md"; do
    [ -L "$probe" ] || continue
    target=$(readlink "$probe")
    # Resolve relative symlink targets against the link's own directory.
    case "$target" in /*) : ;; *) target="$(dirname "$probe")/$target" ;; esac
    root=$(git -C "$(dirname "$target")" rev-parse --show-toplevel 2>/dev/null) || continue
    if [ -f "$root/setup" ] && [ -f "$root/VERSION" ]; then
      INSTALL_DIR="$root"; INSTALL_KIND="dev-repo"; break
    fi
  done
fi

if [ -z "$INSTALL_DIR" ]; then
  echo "ERROR: superskills git install not found"
  echo "Expected a clone at $HOME/.claude/skills/superskills, or skills symlinked from a source checkout."
  echo "Re-install: git clone https://github.com/ariadoss/superskills.git ~/.claude/skills/superskills && cd ~/.claude/skills/superskills && ./setup"
  exit 1
fi
echo "INSTALL_DIR=$INSTALL_DIR"
echo "INSTALL_KIND=$INSTALL_KIND"
REMOTE_URL=$(git -C "$INSTALL_DIR" remote get-url origin 2>/dev/null || echo "unknown")
echo "REMOTE_URL=$REMOTE_URL"

步骤 2：记录当前版本

OLD_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "unknown")
echo "Current version: $OLD_VERSION"

步骤 3：同步到最新版本并重新运行 setup

具体行为取决于 INSTALL_KIND：

• canonical — 这是用户不会在其中进行开发的托管克隆。无论历史记录是否被重写或强制推送， 或用户是否就地编辑了技能，都始终切换到 origin/main。单纯运行 git pull --ff-only 并不够（出现分歧或本地修改时会中止），因此通过硬重置作为后备方案， 确保完成同步。
• dev-repo — 这是用户自己的工作副本。处理时会格外谨慎：绝不硬重置，也绝不丢弃提交。只会在干净的快进更新期间暂存未提交的更改；如果分支已分歧，则停止并让用户 手动解决。

cd "$INSTALL_DIR"
git fetch origin
REMOTE_VERSION=$(git show origin/main:VERSION 2>/dev/null | tr -d '[:space:]' || echo "unknown")
echo "Remote version: $REMOTE_VERSION"

if [ "$OLD_VERSION" = "$REMOTE_VERSION" ] && [ "$REMOTE_VERSION" != "unknown" ]; then
  echo "ALREADY_LATEST=true"
  # Still re-link in case new skills were added within the same version.
  ./setup -q
else
  # Preserve uncommitted local edits so nothing is lost.
  STASHED=0
  if ! git diff --quiet || ! git diff --cached --quiet; then
    if git stash push -u -m "superskills-upgrade autostash" >/dev/null 2>&1; then
      STASHED=1
      echo "Stashed local changes before upgrade."
    fi
  fi

  # Try the clean fast-forward first (preserves local commits if any).
  if git pull --ff-only origin main 2>/dev/null; then
    echo "SYNC=fast-forward"
  elif [ "$INSTALL_KIND" = "dev-repo" ]; then
    # Maintainer's working repo — do NOT discard their commits.
    echo "SYNC=diverged-dev"
    echo "Your dev checkout has diverged from origin/main and can't fast-forward."
    echo "Resolve manually (e.g. 'git rebase origin/main' or 'git merge origin/main'), then re-run ./setup."
    [ "$STASHED" = "1" ] && git stash pop >/dev/null 2>&1 && echo "Restored stashed changes."
    exit 0
  else
    # Canonical install — force-match origin/main (handles force-pushed history).
    echo "Fast-forward not possible; resetting to origin/main."
    git reset --hard origin/main
    echo "SYNC=reset"
  fi

  # Re-apply stashed edits; if they conflict, leave them in the stash.
  if [ "$STASHED" = "1" ]; then
    if git stash pop >/dev/null 2>&1; then
      echo "Re-applied stashed local changes."
    else
      echo "STASH_CONFLICT=true  (your edits are safe in 'git stash list')"
    fi
  fi

  ./setup -q
  NEW_VERSION=$(cat "$INSTALL_DIR/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "unknown")
  echo "NEW_VERSION=$NEW_VERSION"
fi

步骤 4：报告结果

如果 ALREADY_LATEST=true： 告知用户：

superskills is already up to date (v{OLD_VERSION}).

如果已运行升级： 告知用户：

superskills upgraded: v{OLD_VERSION} → v{NEW_VERSION}

如果 OLD_VERSION 等于 NEW_VERSION，请说明 setup 已重新运行，但版本未发生变化（可能获取了同一版本中的技能更新）。

如果出现 SYNC=reset： 本地克隆与上游已分歧（通常是因为已发布的历史记录被重写）。本地克隆已强制匹配到 origin/main。如果用户有本地提交，这些提交已被丢弃——只有未提交的编辑会自动保留。（仅 canonical 安装会出现这种情况。）

如果出现 SYNC=diverged-dev： 这是一个 dev-repo 安装（用户自己的工作副本），其中包含不在 origin/main 上的提交，因此无法快进更新。没有任何内容被丢弃。告知用户自行协调分支，然后重新运行 setup：

cd "$INSTALL_DIR" && git rebase origin/main   # or: git merge origin/main
cd "$INSTALL_DIR" && ./setup -q

（使用步骤 1 中的 INSTALL_DIR 值）

如果出现 STASH_CONFLICT=true： 用户的本地编辑无法干净地重新应用到新版本之上。这些更改是安全的——告知用户使用以下命令恢复：

cd "$INSTALL_DIR" && git stash list   # find the 'superskills-upgrade autostash' entry
cd "$INSTALL_DIR" && git stash pop     # or: git stash show -p stash@{0} to inspect

（使用步骤 1 中的 INSTALL_DIR 值）