feat: create or update Release to support chained auto-release flow

The legacy flow (caller triggered on release: published) always has a
pre-existing Release, so update-release.sh could assume gh release edit.
The chained flow (auto-release.yml -> release.yml via workflow_call)
pushes a tag but no Release exists yet; edit fails.

Probe with gh release view; edit if present, create otherwise. On the
create path, target the Release at $GITHUB_SHA (or git rev-parse HEAD),
falling back to gh's default when neither resolves.

Extends the bats fixture with a GH_RELEASE_MODE switch and adds three
tests covering the create, edit, and missing-SHA branches.

Author: TheCryptoDonkey

steps/update-release.sh

@@ -1,15 +1,25 @@
 #!/usr/bin/env bash
-# update-release.sh — update the GitHub Release body from CHANGELOG.md.
+# update-release.sh — create or update the GitHub Release body from CHANGELOG.md.
 #
-# We do NOT create the release — the maintainer does that manually as the
-# trigger. This step runs after publish succeeds and replaces the release
-# body with the section from CHANGELOG.md, so the release notes on GitHub
-# match exactly what was published.
+# Runs after publish succeeds and stamps the Release body with the
+# CHANGELOG section for the published version plus the tarball integrity
+# block. Two call paths:
+#
+#   Manual path (caller triggered on release: published): the maintainer
+#     already created the Release; we edit the body.
+#   Chained path (auto-release.yml -> release.yml via workflow_call):
+#     auto-release pushed a tag but no Release object exists yet; we
+#     create the Release and stamp it.
+#
+# The create-or-update decision is probed via `gh release view` — if it
+# succeeds, edit; otherwise create.
 #
 # Env:
 #   GIT_TAG          release tag to edit (default: $GITHUB_REF_NAME)
 #   CHANGELOG_FILE   path to CHANGELOG.md (default: CHANGELOG.md)
 #   GITHUB_TOKEN     auth for gh (GitHub provides this automatically)
+#   GITHUB_SHA       commit SHA to target a new Release at (default:
+#                    `git rev-parse HEAD`; only used on the create path)
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source-path=SCRIPTDIR
@@ -151,9 +161,35 @@ else
   log "no tarball meta at $meta_file — skipping integrity block"
 fi
 
-log "updating release $tag"
-if ! gh release edit "$tag" --notes "$notes"; then
-  die "gh release edit failed"
+# Create-or-update logic. The legacy flow (caller triggered on
+# release: published) always has a pre-existing Release -- the event is
+# the trigger, so `gh release view` succeeds and we edit. The chained
+# flow (auto-release.yml calls release.yml via workflow_call) pushed a
+# tag but no human created a Release, so `gh release view` returns
+# non-zero and we create. `gh release view` distinguishes 404 (absent)
+# from auth/network failure by exit code 1 vs other non-zero. We treat
+# any non-zero as "missing" and let `gh release create` surface real
+# auth failures itself -- simpler than parsing stderr for "not found".
+if gh release view "$tag" >/dev/null 2>&1; then
+  log "updating release $tag"
+  if ! gh release edit "$tag" --notes "$notes"; then
+    die "gh release edit failed"
+  fi
+else
+  log "creating release $tag"
+  # --target pins the Release to a specific SHA. In the chained flow the
+  # publish job checks out the tag, so either $GITHUB_SHA (set by the
+  # runner) or `git rev-parse HEAD` resolves to the tagged commit. When
+  # neither is available (e.g. running outside a git checkout, as in
+  # bats fixtures), we omit --target and let gh default.
+  target_sha="${GITHUB_SHA:-$(git rev-parse HEAD 2>/dev/null || true)}"
+  create_args=(release create "$tag" --title "$tag" --notes "$notes")
+  if [[ -n "$target_sha" ]]; then
+    create_args+=(--target "$target_sha")
+  fi
+  if ! gh "${create_args[@]}"; then
+    die "gh release create failed"
+  fi
 fi
 
 # Upload the canonical tarball as a release asset so consumers have a

test/update-release.bats

@@ -33,12 +33,27 @@ setup() {
   cat > "$bin_dir/gh" <<'GH'
 #!/usr/bin/env bash
 # Fake gh: log all args (including the multi-line --notes value) to
-# a file the test can grep against. Always exits 0.
+# a file the test can grep against. Exit behaviour for `release view`
+# is driven by $GH_RELEASE_MODE so tests can exercise both the
+# create-or-update branches in update-release.sh:
+#   (unset|existing) - all commands succeed (legacy / pre-existing Release)
+#   missing          - `release view` exits 1 (chained flow / 404 case)
+#   error            - `release view` exits 2 (non-404 error)
+# All other subcommands always exit 0 so tests can inspect the call log.
 {
   printf 'GH_CALL: '
   printf '%s ' "$@"
   printf '\n'
 } >> "$GH_LOG"
+
+if [[ "${1:-}" == "release" && "${2:-}" == "view" ]]; then
+  case "${GH_RELEASE_MODE:-existing}" in
+    missing) exit 1 ;;
+    error)   exit 2 ;;
+    *)       exit 0 ;;
+  esac
+fi
+
 exit 0
 GH
   chmod +x "$bin_dir/gh"
@@ -54,6 +69,8 @@ teardown() {
   unset TARBALL_META_DIR
   unset GH_LOG
   unset GIT_TAG
+  unset GH_RELEASE_MODE
+  unset GITHUB_SHA
 }
 
 write_meta_for() {
@@ -153,3 +170,84 @@ EOF
   # idempotency.
   grep -q "release upload v1.5.0 ${meta_dir}/nsec-tree-1.5.0.tgz --clobber" "$GH_LOG"
 }
+
+# ---------------------------------------------------------------------
+# Create-or-update branch coverage (see update-release.sh header).
+# The legacy tests above all run under the default $GH_RELEASE_MODE
+# (= existing), exercising the edit branch. The tests below force the
+# missing and error modes.
+# ---------------------------------------------------------------------
+
+@test "update-release: creates a Release when none exists (chained flow)" {
+  command -v jq >/dev/null 2>&1 || skip "jq not available"
+
+  write_package_json '{"name":"nsec-tree","version":"1.5.0","files":["dist"]}'
+  write_file "CHANGELOG.md" '## 1.5.0
+
+- changes
+'
+  write_meta_for "nsec-tree-1.5.0.tgz"
+  export GIT_TAG="v1.5.0"
+  export GH_RELEASE_MODE="missing"
+  export GITHUB_SHA="deadbeefcafef00d1234567890abcdef12345678"
+
+  run "$ACTION_ROOT/steps/update-release.sh"
+  [ "$status" -eq 0 ]
+
+  # On the missing branch we must call `release create`, not `release edit`.
+  grep -q "GH_CALL: release create v1.5.0" "$GH_LOG"
+  ! grep -q "GH_CALL: release edit" "$GH_LOG"
+
+  # --target must be passed and equal $GITHUB_SHA. --notes contains
+  # multi-line content so the whole call may span several log lines;
+  # check for --target and the SHA individually rather than on one line.
+  grep -q -- "--target" "$GH_LOG"
+  grep -q "$GITHUB_SHA" "$GH_LOG"
+
+  # Asset upload still runs after create.
+  grep -q "release upload v1.5.0" "$GH_LOG"
+}
+
+@test "update-release: edits existing Release (legacy flow)" {
+  command -v jq >/dev/null 2>&1 || skip "jq not available"
+
+  write_package_json '{"name":"nsec-tree","version":"1.5.0","files":["dist"]}'
+  write_file "CHANGELOG.md" '## 1.5.0
+
+- changes
+'
+  write_meta_for "nsec-tree-1.5.0.tgz"
+  export GIT_TAG="v1.5.0"
+  export GH_RELEASE_MODE="existing"
+
+  run "$ACTION_ROOT/steps/update-release.sh"
+  [ "$status" -eq 0 ]
+
+  # On the existing branch we must call `release edit`, not `release create`.
+  grep -q "GH_CALL: release edit v1.5.0" "$GH_LOG"
+  ! grep -q "GH_CALL: release create" "$GH_LOG"
+}
+
+@test "update-release: create omits --target when no SHA resolvable" {
+  command -v jq >/dev/null 2>&1 || skip "jq not available"
+
+  write_package_json '{"name":"nsec-tree","version":"1.5.0","files":["dist"]}'
+  write_file "CHANGELOG.md" '## 1.5.0
+
+- changes
+'
+  write_meta_for "nsec-tree-1.5.0.tgz"
+  export GIT_TAG="v1.5.0"
+  export GH_RELEASE_MODE="missing"
+  # GITHUB_SHA deliberately unset; fixture has no git repo so git
+  # rev-parse HEAD also fails. Script should omit --target rather
+  # than pass an empty string.
+  unset GITHUB_SHA
+
+  run "$ACTION_ROOT/steps/update-release.sh"
+  [ "$status" -eq 0 ]
+
+  grep -q "GH_CALL: release create v1.5.0" "$GH_LOG"
+  # --target must NOT appear in any create call when no SHA is available.
+  ! grep -qE "release create v1\.5\.0[^\n]*--target" "$GH_LOG"
+}