@dream-encode/secret-santa-hat-build-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [NEXT_VERSION] - [UNRELEASED]
+* BUG: Example fix description.
+
+## [0.1.0] - 2026-07-16
+* FEA: Initial release. Ships the `ssh-release` command, a JavaScript-tailored port of the `gcrq` (`git_create_release_quiet`) bash flow: branch and changelog guards, version bump across `package.json` and `public/manifest.json`, `[NEXT_VERSION]` placeholder replacement, changelog finalize and re-seed, release branch and tag, GitHub release with a compare link, merge to the default branch, and a service-worker version reset. Includes a postinstall that offers to wire a `release` script into the consuming project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Baumwald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Secret Santa Hat Build Tools
+
+Release tooling for the Secret Santa Hat JavaScript repositories. Ships the
+`ssh-release` command, a JS-tailored port of the `gcrq`
+(`git_create_release_quiet`) bash flow, so every repo releases the same way
+without depending on a personal shell profile.
+
+## What it does
+
+Running `ssh-release` from a repo on the `development` (or `hotfix`) branch:
+
+1. Verifies the branch and that `CHANGELOG.md` has a
+   `## [NEXT_VERSION] - [UNRELEASED]` section at the top.
+2. Bumps the version (interactive menu, or `patch`/`minor`/`major`/`hotfix`):
+   - `package.json`
+   - `public/manifest.json` (if present)
+   - any file containing the `[NEXT_VERSION]` placeholder
+3. Commits the bump, then rewrites the changelog `NEXT_VERSION` header to the
+   new version and date and commits that.
+4. Pushes, creates a `release/<version>` branch, and tags `v<version>`.
+5. Creates a GitHub release from the changelog notes and appends a
+   **Full Changelog** compare link.
+6. Merges the release branch into the default branch (`main`/`master`) and
+   pushes it.
+7. Re-seeds a fresh `NEXT_VERSION` changelog section and resets
+   `public/sw.js` `APP_VERSION` back to `[NEXT_VERSION]`, then returns to the
+   working branch.
+
+JSON edits are done with `node` (always present in a Node project), so `jq` is
+not required.
+
+## Requirements
+
+- **git**
+- **gh** (GitHub CLI), authenticated: `gh auth login`
+- **bash** — Git Bash on Windows; already present on macOS/Linux
+- **node** — provided by the project itself
+
+Check everything with:
+
+```bash
+ssh-release --check-tools
+```
+
+## Install
+
+```bash
+# yarn (classic)
+yarn add --dev @dream-encode/secret-santa-hat-build-tools
+
+# npm
+npm install --save-dev @dream-encode/secret-santa-hat-build-tools
+```
+
+After install, wire the `release` script into the project:
+
+```bash
+npx @dream-encode/secret-santa-hat-build-tools setup          # interactive
+npx @dream-encode/secret-santa-hat-build-tools setup --force  # no prompts
+```
+
+This sets `"release": "ssh-release"`. Any existing custom release script is
+backed up as `release-backup`. An existing `prerelease` script is left alone.
+
+## `yarn release` = prerelease + release
+
+yarn (classic) and npm run a `prerelease` script automatically before
+`release`. Keep each repo's pre-flight checks in its own `prerelease` script,
+and `yarn release` runs them and then the release flow:
+
+```jsonc
+{
+  "scripts": {
+    // repo-specific pre-flight (tests, lint, build, browserslist refresh, ...)
+    "prerelease": "yarn maintenance && yarn test:unit",
+    // the shared release flow
+    "release": "ssh-release"
+  }
+}
+```
+
+```bash
+yarn release          # prerelease, then interactive release
+yarn release --dry-run
+```
+
+## Usage
+
+```bash
+ssh-release                 # interactive version selection
+ssh-release patch           # 1.0.0 -> 1.0.1
+ssh-release minor           # 1.0.0 -> 1.1.0
+ssh-release major           # 1.0.0 -> 2.0.0
+ssh-release hotfix          # 1.0.0 -> 1.0.0.1
+ssh-release --dry-run minor # preview without making changes
+ssh-release --check-tools   # verify git + gh
+ssh-release --help
+```
+
+Because `release` passes arguments through, `yarn release patch` and
+`yarn release --dry-run` work too.
+
+## Configuration
+
+Optional. Copy `bin/config/release.conf.example` to `bin/config/release.conf`
+inside the installed package to override defaults:
+
+- `SSH_RELEASE_MAIN_BRANCH` — the branch releases merge into (auto-detected as
+  `main`, then `master`, when unset).
+
+## Notes
+
+- Releases are allowed only from `development` or `hotfix`.
+- The version bump commit runs `git add .`, so the working tree should hold
+  only what you intend to ship.
+- The re-seeded `NEXT_VERSION` changelog section and the `sw.js` reset are left
+  uncommitted on the working branch, ready for the next cycle.

package/bin/config/release.conf.example

@@ -0,0 +1,8 @@
+# secret-santa-hat-build-tools release configuration (optional).
+#
+# Copy this file to release.conf in the same directory to override defaults.
+# It is sourced by release.sh before the release runs.
+
+# Branch that releases are merged into. Auto-detected (main, then master) when
+# unset.
+# SSH_RELEASE_MAIN_BRANCH="main"

package/bin/lib/general-functions.sh

@@ -0,0 +1,284 @@
+#!/bin/bash
+
+# General helpers for secret-santa-hat-build-tools.
+#
+# JSON reads/writes go through node rather than jq: node is guaranteed present
+# in a Node project and preserves the 2-space formatting these repos use.
+
+# Detect the package manager for the current project.
+function get_package_manager_for_project() {
+    if [ -f yarn.lock ]; then
+        echo "yarn"
+    else
+        echo "npm"
+    fi
+}
+
+# Read a version field from a JSON file. Usage: get_json_version <file>
+function get_json_version() {
+    local file="$1"
+
+    node -e "process.stdout.write(String(JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).version || ''))" "$file" 2>/dev/null
+}
+
+# Read the project version from package.json.
+function get_package_json_version() {
+    get_json_version "package.json"
+}
+
+# Write a version field to a JSON file, preserving 2-space formatting and a
+# trailing newline. Usage: set_json_version <file> <version>
+function set_json_version() {
+    local file="$1"
+    local version="$2"
+
+    node -e "const fs=require('fs');const f=process.argv[1];const v=process.argv[2];const j=JSON.parse(fs.readFileSync(f,'utf8'));j.version=v;fs.writeFileSync(f, JSON.stringify(j,null,2)+'\n');" "$file" "$version"
+}
+
+# Calculate a new version from a bump type. Supports X.X.X and X.X.X.X.
+function calculate_new_version() {
+    local current_version="$1"
+    local bump_type="$2"
+
+    IFS='.' read -ra VERSION_PARTS <<< "$current_version"
+
+    local major=${VERSION_PARTS[0]}
+    local minor=${VERSION_PARTS[1]}
+    local patch=${VERSION_PARTS[2]}
+    local hotfix=${VERSION_PARTS[3]:-}
+
+    case $bump_type in
+        "patch")
+            patch=$((patch + 1))
+            hotfix=""
+            ;;
+        "minor")
+            minor=$((minor + 1))
+            patch=0
+            hotfix=""
+            ;;
+        "major")
+            major=$((major + 1))
+            minor=0
+            patch=0
+            hotfix=""
+            ;;
+        "hotfix")
+            if [ -z "$hotfix" ]; then
+                hotfix=1
+            else
+                hotfix=$((hotfix + 1))
+            fi
+            ;;
+        *)
+            echo "Invalid bump type: $bump_type. Use patch, minor, major, or hotfix." >&2
+
+            return 1
+            ;;
+    esac
+
+    if [ -n "$hotfix" ]; then
+        echo "$major.$minor.$patch.$hotfix"
+    else
+        echo "$major.$minor.$patch"
+    fi
+}
+
+# Interactive menu selection with fzf/whiptail/numbered fallbacks.
+function interactive_menu_select() {
+    local prompt="$1"
+    shift
+    local options=("$@")
+
+    if command -v fzf >/dev/null 2>&1; then
+        local result
+        result=$(printf '%s\n' "${options[@]}" | fzf --height=12 --layout=reverse --border --prompt="Select: " --header="$prompt")
+
+        if [ $? -eq 0 ] && [ -n "$result" ]; then
+            echo "$result"
+
+            return 0
+        fi
+
+        return 1
+    fi
+
+    if command -v whiptail >/dev/null 2>&1; then
+        local menu_items=()
+        local i
+        for i in "${!options[@]}"; do
+            menu_items+=("$((i+1))" "${options[i]}")
+        done
+
+        local choice
+        choice=$(whiptail --title "Version Bump" --menu "$prompt" 18 90 8 "${menu_items[@]}" 3>&1 1>&2 2>&3)
+
+        if [ $? -eq 0 ] && [ -n "$choice" ]; then
+            echo "${options[$((choice-1))]}"
+
+            return 0
+        fi
+
+        return 1
+    fi
+
+    echo "$prompt" >&2
+    echo "" >&2
+
+    local i
+    for i in "${!options[@]}"; do
+        echo "  $((i+1))) ${options[i]}" >&2
+    done
+    echo "" >&2
+
+    while true; do
+        read -r -p "Enter your choice (1-${#options[@]}): " choice
+        if [[ "$choice" =~ ^[0-9]+$ ]] && [ "$choice" -ge 1 ] && [ "$choice" -le "${#options[@]}" ]; then
+            echo "${options[$((choice-1))]}"
+
+            return 0
+        fi
+
+        echo "Invalid choice. Please enter a number between 1 and ${#options[@]}." >&2
+    done
+}
+
+# Changelog helpers.
+function changelog_exists() {
+    [ -f "CHANGELOG.md" ]
+}
+
+# True when CHANGELOG.md has a NEXT_VERSION / UNRELEASED section at the top.
+function changelog_check_next_version() {
+    if changelog_exists && grep -q "## \[NEXT_VERSION\] - \[UNRELEASED\]" CHANGELOG.md; then
+        return 0
+    fi
+
+    return 1
+}
+
+# Extract the bullet notes for a version from CHANGELOG.md, as GitHub release
+# body. Supports X.X.X and X.X.X.X.
+function extract_version_updates_from_changelog() {
+    local RELEASE_VERSION="$1"
+    local CHANGELOG_FILE="CHANGELOG.md"
+
+    if [ ! -f "$CHANGELOG_FILE" ]; then
+        return 1
+    fi
+
+    awk -v ver="$RELEASE_VERSION" '
+        $0 ~ "^## \\[" ver "\\]" { print "## Changelog"; version_found=1; next }
+        /^## \[/ && version_found { exit }
+        version_found && /^\*/' "$CHANGELOG_FILE"
+}
+
+# Replace the NEXT_VERSION section header with the released version and date,
+# then commit that changelog change.
+function changelog_update_current_version() {
+    local CURRENT_VERSION="${1:-$(get_package_json_version)}"
+
+    if changelog_exists && grep -q "## \[NEXT_VERSION\]" CHANGELOG.md; then
+        local CURRENT_DATE
+        CURRENT_DATE=$(date +%Y-%m-%d)
+
+        sed_inplace "s/^## \[NEXT_VERSION\] - \[UNRELEASED\]$/## [$CURRENT_VERSION] - $CURRENT_DATE/" CHANGELOG.md
+
+        git add CHANGELOG.md >/dev/null 2>&1
+        git commit -m "Update changelog for v$CURRENT_VERSION" >/dev/null 2>&1
+    fi
+}
+
+# Re-seed a fresh NEXT_VERSION section above the just-released version.
+function changelog_add_next_version_template() {
+    local CURRENT_VERSION=""
+    local QUIET_MODE="false"
+
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --quiet)
+                QUIET_MODE="true"
+                shift
+                ;;
+            --version)
+                CURRENT_VERSION="$2"
+                shift 2
+                ;;
+            *)
+                echo "❌ Error: unknown argument '$1' for changelog_add_next_version_template" >&2
+
+                return 1
+                ;;
+        esac
+    done
+
+    if [ -z "$CURRENT_VERSION" ]; then
+        CURRENT_VERSION=$(get_package_json_version)
+    fi
+
+    if changelog_exists; then
+        sed_inplace "s/^## \[$CURRENT_VERSION\]/## [NEXT_VERSION] - [UNRELEASED]\n* BUG: Example fix description.\n\n## [$CURRENT_VERSION]/" CHANGELOG.md
+
+        if [ "$QUIET_MODE" != "true" ]; then
+            echo "✅ Template changelog entry added to CHANGELOG.md"
+        fi
+    fi
+}
+
+# Replace [NEXT_VERSION] placeholders across project files (skipping the
+# changelog, shell scripts, binaries, and dependency directories).
+function replace_next_version_placeholders() {
+    local new_version="$1"
+
+    if ! command -v grep >/dev/null 2>&1; then
+        return 0
+    fi
+
+    local files
+    files=$(grep -r -l "\[NEXT_VERSION\]" . \
+        --exclude-dir=node_modules \
+        --exclude-dir=vendor \
+        --exclude-dir=.git \
+        --exclude-dir=dist \
+        --exclude-dir=build \
+        --exclude="*.zip" \
+        --exclude="*.tar.gz" \
+        --exclude="*.jpg" \
+        --exclude="*.jpeg" \
+        --exclude="*.png" \
+        --exclude="*.gif" \
+        --exclude="*.ico" \
+        --exclude="*.svg" \
+        --exclude="*.webp" \
+        --exclude="*.pdf" \
+        --exclude="*.woff" \
+        --exclude="*.woff2" \
+        --exclude="*.ttf" \
+        --exclude="*.eot" \
+        --exclude="*.mp4" \
+        --exclude="*.mp3" \
+        --exclude="*.wav" \
+        --exclude="*.lock" \
+        --exclude="*.sh" \
+        --exclude="CHANGELOG.md" \
+        2>/dev/null || true)
+
+    if [ -n "$files" ]; then
+        echo "$files" | while IFS= read -r file; do
+            if [ -f "$file" ]; then
+                sed_inplace "s/\[NEXT_VERSION\]/$new_version/g" "$file"
+            fi
+        done
+
+        echo "    - Replaced [NEXT_VERSION] with $new_version in files."
+    fi
+}
+
+# Reset the service worker APP_VERSION back to the [NEXT_VERSION] template.
+function update_service_worker_next_version_template() {
+    if [ -f "public/sw.js" ]; then
+        sed_inplace "s/const APP_VERSION *= *'[^']*'/const APP_VERSION = '[NEXT_VERSION]'/g" public/sw.js
+
+        echo "    - Updated service worker version template."
+    fi
+}

package/bin/lib/git-functions.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+
+# Git and GitHub helpers for secret-santa-hat-build-tools.
+
+# True when the current directory is inside a git repository.
+function is_git_repo() {
+    git rev-parse --is-inside-work-tree >/dev/null 2>&1
+}
+
+# Print the current branch name.
+function get_current_branch() {
+    git branch --show-current
+}
+
+# Determine the default branch to merge releases into. Honours an override from
+# release.conf (SSH_RELEASE_MAIN_BRANCH), otherwise prefers main, then master.
+function get_default_branch() {
+    if [ -n "${SSH_RELEASE_MAIN_BRANCH:-}" ]; then
+        echo "$SSH_RELEASE_MAIN_BRANCH"
+
+        return 0
+    fi
+
+    if git show-ref --verify --quiet refs/heads/main; then
+        echo "main"
+    elif git show-ref --verify --quiet refs/heads/master; then
+        echo "master"
+    else
+        echo "main"
+    fi
+}
+
+# Print owner/name for the current repo via the GitHub CLI.
+function get_github_repo_info() {
+    gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null
+}
+
+# Create a GitHub release for the given version, using changelog notes.
+function github_create_release() {
+    local VERSION="$1"
+
+    if changelog_exists; then
+        local RELEASE_NOTES
+        RELEASE_NOTES=$(extract_version_updates_from_changelog "$VERSION")
+
+        if ! gh release create "v$VERSION" -n "$RELEASE_NOTES" -t "v$VERSION"; then
+            echo "Error: failed to create GitHub release v$VERSION" >&2
+
+            return 1
+        fi
+    else
+        if ! gh release create "v$VERSION" -t "v$VERSION" --generate-notes; then
+            echo "Error: failed to create GitHub release v$VERSION" >&2
+
+            return 1
+        fi
+    fi
+}
+
+# Generate a GitHub compare URL between two tags.
+function github_generate_tags_compare_link() {
+    local prev_tag="$1"
+    local current_tag="$2"
+    local repo
+    repo=$(get_github_repo_info)
+
+    echo "https://github.com/${repo}/compare/${prev_tag}...${current_tag}"
+}
+
+# Append a "Full Changelog" compare link to an existing GitHub release.
+function github_release_add_compare_link() {
+    local current_version="$1"
+    local current_tag="v${current_version}"
+    local prev_tag
+    prev_tag=$(git tag -l --sort=-version:refname "v*" | sed -n '2p')
+
+    if [ -z "$prev_tag" ]; then
+        return 0
+    fi
+
+    local compare_url
+    compare_url=$(github_generate_tags_compare_link "$prev_tag" "$current_tag")
+
+    local display="${prev_tag}...${current_tag}"
+    local compare_line="**Full Changelog:** [\`${display}\`](${compare_url})"
+
+    local existing_notes
+    existing_notes=$(gh release view "$current_tag" --json body -q '.body' 2>/dev/null)
+
+    local updated_notes="${existing_notes}"$'\n\n'"${compare_line}"
+
+    if ! gh release edit "$current_tag" --notes "$updated_notes"; then
+        echo "Warning: failed to add compare link to release $current_tag" >&2
+
+        return 1
+    fi
+}

package/bin/lib/platform-utils.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# Cross-platform helpers for secret-santa-hat-build-tools.
+
+# Detect the current platform.
+function get_platform() {
+    case "$OSTYPE" in
+        msys*|cygwin*|mingw*)
+            echo "windows"
+            ;;
+        darwin*)
+            echo "macos"
+            ;;
+        linux*)
+            echo "linux"
+            ;;
+        *)
+            echo "unknown"
+            ;;
+    esac
+}
+
+# File existence check.
+function file_exists() {
+    [ -f "$1" ]
+}
+
+# Command existence check.
+function command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Cross-platform sed in-place editing.
+function sed_inplace() {
+    local pattern="$1"
+    local file="$2"
+
+    if [[ "$(get_platform)" == "macos" ]]; then
+        sed -i '' "$pattern" "$file"
+    else
+        sed -i "$pattern" "$file"
+    fi
+}