vouchington-tooling 0.7.0 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/scripts/gha/backfill-slash-release-tags.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "usage: backfill-slash-release-tags.sh --package NAME [--package NAME]... [--dry-run] [--write] [--push] [--remote NAME]" >&2
+}
+
+packages=()
+explicit_dry=0
+do_write=0
+do_push=0
+remote=origin
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --package)
+      [ $# -ge 2 ] || { usage; exit 2; }
+      packages+=("$2")
+      shift 2
+      ;;
+    --dry-run)
+      explicit_dry=1
+      shift
+      ;;
+    --write)
+      do_write=1
+      shift
+      ;;
+    --push)
+      do_push=1
+      shift
+      ;;
+    --remote)
+      [ $# -ge 2 ] || { usage; exit 2; }
+      remote="$2"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 2
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [ "${#packages[@]}" -eq 0 ]; then
+  usage
+  exit 2
+fi
+
+if [ "$explicit_dry" -eq 1 ] && { [ "$do_write" -eq 1 ] || [ "$do_push" -eq 1 ]; }; then
+  echo "cannot combine --dry-run with --write or --push" >&2
+  exit 2
+fi
+
+dry_run=1
+if [ "$do_write" -eq 1 ] || [ "$do_push" -eq 1 ]; then
+  dry_run=0
+fi
+
+semver='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'
+push_refs=()
+
+for package in "${packages[@]}"; do
+  if [[ ! "$package" =~ ^[A-Za-z0-9._-]+$ ]]; then
+    echo "invalid package name: ${package}" >&2
+    exit 2
+  fi
+
+  while IFS= read -r hyphen_tag; do
+    [ -n "$hyphen_tag" ] || continue
+    version="${hyphen_tag#"${package}-v"}"
+    if [[ ! "$version" =~ $semver ]]; then
+      echo "hyphen tag ${hyphen_tag} is not <package>-v<semver>" >&2
+      exit 1
+    fi
+
+    slash_tag="${package}/v${version}"
+    commit="$(git rev-parse "refs/tags/${hyphen_tag}^{commit}")"
+
+    if git rev-parse -q --verify "refs/tags/${slash_tag}" >/dev/null; then
+      existing="$(git rev-parse "refs/tags/${slash_tag}^{commit}")"
+      if [ "$existing" != "$commit" ]; then
+        echo "slash tag ${slash_tag} points at ${existing}, expected ${commit}" >&2
+        exit 1
+      fi
+      echo "skip ${slash_tag} (already at ${commit})"
+      continue
+    fi
+
+    echo "create ${slash_tag} -> ${commit}"
+    if [ "$dry_run" -eq 0 ]; then
+      git tag -a "${slash_tag}" -m "${package} v${version}" "$commit"
+      push_refs+=("refs/tags/${slash_tag}")
+    fi
+  done < <(git tag --list "${package}-v*")
+done
+
+if [ "$do_push" -eq 0 ]; then
+  exit 0
+fi
+
+if [ "${#push_refs[@]}" -eq 0 ]; then
+  echo "nothing to push"
+  exit 0
+fi
+
+git push --atomic "$remote" "${push_refs[@]}"

package/skills/stacked-prs/SKILL.md

@@ -12,25 +12,32 @@ merge.
 
 A stack is a sequence of branches, each submitted as its own pull request, where every PR but the
 bottom-most one targets the PR below it as its base branch instead of targeting the default branch
-directly. That parent-branch base is the hazard: a mid-stack PR's base ref is an unmerged branch,
-not the default branch, so a generic "merge this PR" action taken on a mid-stack layer can land it
-into that unmerged parent instead of where it needs to go. Before treating any merge action on a
-stacked PR as safe, confirm its actual base branch, and treat a base that is not the default branch
-as a sign the PR is mid-stack.
+directly. GitHub tracks a chain like this as a single stack, and its own documentation on merging
+stacked pull requests is explicit about what a merge then does: "the selected pull request and all
+unmerged pull requests below it land on the base branch together as a single operation, ordered
+from the bottom up," and merging one is only possible once everything below it already satisfies
+whatever this repository requires to merge — you cannot merge an isolated middle layer on its own.
+That is dedicated stack-merge behavior, not the ordinary single-branch merge semantics a generic
+"merge this PR" action assumes, and it comes with its own restrictions: GitHub does not support
+auto-merge for stacked pull requests at all, and a plain, non-stack-aware merge mechanism is not
+guaranteed to reproduce this cascade correctly. A mid-stack PR's base ref being an unmerged branch,
+not the default branch, is the sign to slow down and confirm the merge path in use actually
+understands stacks before treating it as routine.
 
 Drain a stack from the bottom, one layer at a time, merging each bottom-most layer as soon as it
 becomes ready rather than waiting for every layer above it to be ready first. A stack should stay as
 short as it can be: every layer that remains unmerged keeps accumulating rebase surface, CI cost,
 and drift against the default branch, and that cost compounds for every layer still stacked above
-it.
+it. Because stacked pull requests do not auto-merge, draining only happens through a deliberate
+merge action taken each time a layer becomes ready — nothing lands on its own just because it is
+ready.
 
-Only merging the bottom-most layer into the default branch actually drains anything: that merge
-lands the bottom layer, and the parent-branch bases above it can now be retargeted onto the default
-branch as that layer closes. Merging a higher layer instead lands it into its own parent branch, not
-the default branch, and leaves every layer below it exactly as open and unmerged as before — no
-progress toward the default branch has been made, even though a PR closed. So whatever merge
-selector or target is used to drain the stack must name the bottom-most unmerged layer specifically,
-not an arbitrary or more convenient one.
+Merging a given layer lands that layer and every unmerged layer below it in the same operation, so
+whatever merge target is used must name the bottom-most unmerged layer specifically, not a higher
+one, to land exactly the increment intended for that drain step: naming a higher layer either merges
+more than intended, when everything below also happens to be ready, or is simply unavailable, when
+it is not. Once a layer merges, GitHub retargets the next unmerged layer onto the default branch
+directly, so it becomes the new bottom — treat it the same way on the next drain step.
 
 When a drain stalls — something on the stack needs human attention, or a layer closes without
 merging — but the bottom-most layer is otherwise ready to merge, stop before yielding: report the