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

package/bin/lib/release-functions.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+
+# The release orchestrator for secret-santa-hat-build-tools.
+#
+# Ported from git_create_release_quiet (gcrq). Given a JS project on the
+# development or hotfix branch with a NEXT_VERSION changelog section, it bumps
+# the version, finalizes and re-seeds the changelog, tags and pushes a release
+# branch, publishes a GitHub release, merges into the default branch, and
+# leaves the working branch ready for the next cycle.
+#
+# Honours DRY_RUN (set by the --dry-run flag): when true, it performs every
+# read-only check and computes the target version but makes no changes.
+
+# Clean, intentional abort. Clears the ERR trap first so a controlled failure
+# does not print the "failed unexpectedly" backstop message, then exits.
+function _release_abort() {
+    trap - ERR 2>/dev/null || true
+
+    exit 1
+}
+
+function ssh_create_release() {
+    local version_bump="$1"
+
+    local PACKAGE_MANAGER CURRENT_VERSION CURRENT_BRANCH DEFAULT_BRANCH
+    PACKAGE_MANAGER=$(get_package_manager_for_project)
+    CURRENT_VERSION=$(get_package_json_version)
+    CURRENT_BRANCH=$(get_current_branch)
+    DEFAULT_BRANCH=$(get_default_branch)
+
+    # --- Guards -------------------------------------------------------------
+    if ! is_git_repo; then
+        echo "❌ Error: not inside a git repository."
+
+        _release_abort
+    fi
+
+    if [ ! -f "package.json" ]; then
+        echo "❌ Error: no package.json found in $(pwd)."
+
+        _release_abort
+    fi
+
+    if [ "$CURRENT_BRANCH" != "development" ] && [ "$CURRENT_BRANCH" != "hotfix" ]; then
+        echo "❌ Error: releases can only be created from 'development' or 'hotfix'."
+        echo "   Current branch: $CURRENT_BRANCH"
+
+        _release_abort
+    fi
+
+    if ! changelog_check_next_version; then
+        echo "❌ Error: the top CHANGELOG.md entry is not '## [NEXT_VERSION] - [UNRELEASED]'."
+        echo "   Update CHANGELOG.md before releasing."
+
+        _release_abort
+    fi
+
+    # --- Determine the target version --------------------------------------
+    local NEW_VERSION=""
+    local do_bump="true"
+
+    if [ -n "$version_bump" ]; then
+        NEW_VERSION=$(calculate_new_version "$CURRENT_VERSION" "$version_bump")
+    else
+        echo ""
+        printf "  🔢 Version selection required (current: %s)\n" "$CURRENT_VERSION"
+
+        local options=(
+            "patch - Bug fixes (${CURRENT_VERSION} -> $(calculate_new_version "$CURRENT_VERSION" "patch"))"
+            "minor - New features (${CURRENT_VERSION} -> $(calculate_new_version "$CURRENT_VERSION" "minor"))"
+            "major - Breaking changes (${CURRENT_VERSION} -> $(calculate_new_version "$CURRENT_VERSION" "major"))"
+            "hotfix - Critical fixes (${CURRENT_VERSION} -> $(calculate_new_version "$CURRENT_VERSION" "hotfix"))"
+            "custom - Enter a custom version"
+            "stay - Stay at current version (${CURRENT_VERSION})"
+        )
+
+        local selected
+        selected=$(interactive_menu_select "Choose the version for this release:" "${options[@]}")
+
+        if [ -z "$selected" ]; then
+            echo "❌ Version selection cancelled. Aborting release."
+
+            _release_abort
+        fi
+
+        local action
+        action=$(echo "$selected" | cut -d' ' -f1)
+        printf "  ✅ Selected: %s\n" "$selected"
+
+        case "$action" in
+            stay)
+                do_bump="false"
+                NEW_VERSION="$CURRENT_VERSION"
+                ;;
+            custom)
+                read -r -e -p "Enter custom version: " -i "$CURRENT_VERSION" NEW_VERSION
+                if [ -z "$NEW_VERSION" ]; then
+                    echo "❌ No version supplied. Aborting release."
+
+                    _release_abort
+                fi
+                ;;
+            *)
+                NEW_VERSION=$(calculate_new_version "$CURRENT_VERSION" "$action")
+                ;;
+        esac
+    fi
+
+    # --- Dry run: report the plan and stop ---------------------------------
+    if [ "${DRY_RUN:-false}" = "true" ]; then
+        echo ""
+        echo "🧪 Dry run - no changes will be made."
+        echo "    - Package manager:  $PACKAGE_MANAGER"
+        echo "    - Current branch:   $CURRENT_BRANCH"
+        echo "    - Default branch:   $DEFAULT_BRANCH"
+        echo "    - Current version:  $CURRENT_VERSION"
+
+        if [ "$do_bump" = "true" ]; then
+            echo "    - Target version:   $NEW_VERSION"
+        else
+            echo "    - Target version:   $CURRENT_VERSION (staying)"
+        fi
+
+        echo ""
+        echo "  Would then: bump versions, replace [NEXT_VERSION] placeholders, commit,"
+        echo "  finalize the changelog, push, create release/$NEW_VERSION, tag v$NEW_VERSION,"
+        echo "  publish a GitHub release, merge into $DEFAULT_BRANCH, and re-seed the changelog."
+        echo ""
+        echo "  ✅ Dry run complete."
+
+        return 0
+    fi
+
+    # --- Apply the version bump --------------------------------------------
+    if [ "$do_bump" = "true" ]; then
+        set_json_version "package.json" "$NEW_VERSION"
+        echo "    - Updated package.json."
+
+        if [ -f "public/manifest.json" ]; then
+            set_json_version "public/manifest.json" "$NEW_VERSION"
+            echo "    - Updated public/manifest.json."
+        fi
+
+        replace_next_version_placeholders "$NEW_VERSION"
+
+        git add . >/dev/null 2>&1
+        git commit -m "Version $NEW_VERSION bump." >/dev/null 2>&1
+        echo "    - Committed version bump."
+    fi
+
+    # Refresh version in case it changed.
+    CURRENT_VERSION=$(get_package_json_version)
+
+    # --- Finalize the changelog for this version ---------------------------
+    changelog_update_current_version "$CURRENT_VERSION"
+    echo "    - Finalized changelog for v$CURRENT_VERSION."
+
+    # --- Push, branch, tag -------------------------------------------------
+    git push -q >/dev/null 2>&1
+
+    git checkout -b "release/$CURRENT_VERSION" >/dev/null 2>&1
+    git push -q --set-upstream origin "release/$CURRENT_VERSION" >/dev/null 2>&1
+    echo "    - Release branch created."
+
+    git tag -a "v$CURRENT_VERSION" -m "Version $CURRENT_VERSION" >/dev/null 2>&1
+    git push -q -u origin "v$CURRENT_VERSION" >/dev/null 2>&1
+    echo "    - Tagged v$CURRENT_VERSION."
+
+    # --- GitHub release ----------------------------------------------------
+    if ! github_create_release "$CURRENT_VERSION"; then
+        echo "❌ Error: GitHub release creation failed. Aborting." >&2
+
+        _release_abort
+    fi
+
+    if ! github_release_add_compare_link "$CURRENT_VERSION"; then
+        echo "⚠️  Warning: failed to add compare link to the release." >&2
+    fi
+
+    echo "    - GitHub release created."
+
+    # --- Merge into the default branch -------------------------------------
+    git checkout "$DEFAULT_BRANCH" >/dev/null 2>&1
+    git merge "release/$CURRENT_VERSION" --no-ff -m "Merge release/$CURRENT_VERSION into $DEFAULT_BRANCH" >/dev/null 2>&1
+    git push -q origin "$DEFAULT_BRANCH" >/dev/null 2>&1
+    echo "    - Merged release/$CURRENT_VERSION into $DEFAULT_BRANCH."
+
+    # --- Re-seed for the next cycle ----------------------------------------
+    # These changes are left uncommitted and carried back to the working branch
+    # by the checkout below, matching the gcrq end state.
+    changelog_add_next_version_template --quiet
+    update_service_worker_next_version_template
+
+    git checkout "$CURRENT_BRANCH" >/dev/null 2>&1
+
+    echo ""
+    echo "  ✅ Release v$CURRENT_VERSION created."
+}

package/bin/lib/tool-checker.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+
+# Tool availability checker for secret-santa-hat-build-tools.
+#
+# The JS repos only need git and an authenticated GitHub CLI. JSON edits are
+# done with node, which is always present in a Node project, so jq is not
+# required.
+
+if ! command -v get_platform >/dev/null 2>&1; then
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    # shellcheck disable=SC1091
+    source "$SCRIPT_DIR/platform-utils.sh"
+fi
+
+# Check a single tool and print its version.
+function check_tool() {
+    local tool="$1"
+    local description="$2"
+
+    if command_exists "$tool"; then
+        local version
+        version=$("$tool" --version 2>/dev/null | head -1 || echo "available")
+        echo "✅ $tool: $version"
+
+        return 0
+    fi
+
+    echo "❌ $tool: not found - $description"
+
+    return 1
+}
+
+# Check that the GitHub CLI is authenticated.
+function check_gh_auth() {
+    if ! command_exists "gh"; then
+        echo "❌ gh: not installed - GitHub CLI (required for releases)"
+
+        return 1
+    fi
+
+    if gh auth status >/dev/null 2>&1; then
+        echo "✅ gh: authenticated"
+
+        return 0
+    fi
+
+    echo "⚠️  gh: not authenticated (run 'gh auth login')"
+
+    return 1
+}
+
+# Check all required tools. Pass "true" to suppress the per-tool output.
+function check_all_tools() {
+    local quiet_mode="${1:-false}"
+    local failed=0
+
+    if ! check_tool "git" "Version control (required)"; then
+        failed=$((failed + 1))
+    fi
+
+    if ! check_tool "node" "Node.js runtime (required for JSON edits)"; then
+        failed=$((failed + 1))
+    fi
+
+    if ! check_gh_auth; then
+        failed=$((failed + 1))
+    fi
+
+    if [ "$quiet_mode" != "true" ]; then
+        echo ""
+        echo "📋 Platform: $(get_platform)"
+    fi
+
+    if [ "$failed" -gt 0 ]; then
+        return 1
+    fi
+
+    return 0
+}
+
+# Silent pass/fail check for use as a gate.
+function quick_tool_check() {
+    check_all_tools "true" >/dev/null 2>&1
+
+    return $?
+}

package/bin/release.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+
+# Secret Santa Hat release script.
+#
+# A JavaScript-tailored port of the `git_create_release_quiet` (gcrq) bash
+# function. Handles version bumping, changelog management, git tagging, GitHub
+# releases, and the post-release merge/reseed cycle for the Secret Santa Hat
+# JS repositories.
+
+set -e
+
+trap 'printf "\n❌ Release failed unexpectedly on line %s (exit code: %s).\n" "$LINENO" "$?" >&2' ERR
+
+export LANG="${LANG:-en_US.UTF-8}"
+export LC_ALL="${LC_ALL:-en_US.UTF-8}"
+export TERM="${TERM:-xterm-256color}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+USER_PROJECT_DIR="$(pwd)"
+
+function show_help() {
+    cat << 'EOF'
+NAME
+    ssh-release - Secret Santa Hat release tool
+
+SYNOPSIS
+    ssh-release [OPTIONS] [VERSION_TYPE]
+
+DESCRIPTION
+    Creates a release for a Secret Santa Hat JavaScript project: bumps the
+    version, finalizes the changelog, tags the release, publishes a GitHub
+    release, merges into the default branch, and re-seeds the next changelog
+    section. Ported from the gcrq (git_create_release_quiet) bash flow.
+
+    Releases can only be created from the 'development' or 'hotfix' branch, and
+    CHANGELOG.md must have a "## [NEXT_VERSION] - [UNRELEASED]" section at the
+    top.
+
+OPTIONS
+    --check-tools      Check that git and gh (authenticated) are available
+    --dry-run          Walk through the release without pushing, tagging, or
+                       publishing anything (still shows the computed version)
+    --help, -h         Show this help message
+    --version, -v      Show version information
+
+VERSION_TYPE
+    patch              Bug fixes (1.0.0 -> 1.0.1)
+    minor              New features (1.0.0 -> 1.1.0)
+    major              Breaking changes (1.0.0 -> 2.0.0)
+    hotfix             Critical fixes (1.0.0 -> 1.0.0.1)
+
+    If no VERSION_TYPE is given, interactive mode prompts for the bump.
+
+EXAMPLES
+    ssh-release                 # Interactive mode
+    ssh-release patch           # Patch release
+    ssh-release --dry-run minor # Preview a minor release
+    ssh-release --check-tools   # Verify required tools
+
+REQUIREMENTS
+    - git   Version control
+    - gh    GitHub CLI, authenticated (gh auth login)
+    - node  Used for package.json / manifest.json edits (always present in a
+            Node project)
+
+FILES OPERATED ON
+    package.json           Version source of truth
+    CHANGELOG.md           Release notes, NEXT_VERSION section
+    public/manifest.json   Version, if present
+    public/sw.js           APP_VERSION reset to [NEXT_VERSION], if present
+    *                      Any file containing the [NEXT_VERSION] placeholder
+EOF
+}
+
+# Parse arguments.
+DRY_RUN=false
+CHECK_TOOLS=false
+VERSION_TYPE=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --help|-h)
+            show_help
+            exit 0
+            ;;
+        --version|-v)
+            echo "ssh-release (secret-santa-hat-build-tools)"
+            exit 0
+            ;;
+        --check-tools)
+            CHECK_TOOLS=true
+            shift
+            ;;
+        --dry-run)
+            DRY_RUN=true
+            shift
+            ;;
+        --quiet)
+            # Accepted for gcrq parity; the flow is quiet by default.
+            shift
+            ;;
+        patch|minor|major|hotfix)
+            if [ -n "$VERSION_TYPE" ]; then
+                echo "❌ Error: multiple version types specified."
+                exit 1
+            fi
+            VERSION_TYPE="$1"
+            shift
+            ;;
+        -*)
+            echo "❌ Error: unknown option '$1'. See 'ssh-release --help'."
+            exit 1
+            ;;
+        *)
+            echo "❌ Error: unexpected argument '$1'. See 'ssh-release --help'."
+            exit 1
+            ;;
+    esac
+done
+
+# Source configuration if present.
+if [ -f "$SCRIPT_DIR/config/release.conf" ]; then
+    # shellcheck disable=SC1091
+    source "$SCRIPT_DIR/config/release.conf"
+fi
+
+# Source helper libraries.
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/platform-utils.sh"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/tool-checker.sh"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/general-functions.sh"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/git-functions.sh"
+# shellcheck disable=SC1091
+source "$SCRIPT_DIR/lib/release-functions.sh"
+
+# Operate in the user's project directory.
+cd "$USER_PROJECT_DIR"
+
+if [ "$CHECK_TOOLS" = true ]; then
+    echo "🔧 Checking required tools..."
+    echo ""
+
+    if check_all_tools; then
+        echo ""
+        echo "✅ All required tools are available. Ready to run ssh-release."
+        exit 0
+    else
+        echo ""
+        echo "❌ Some required tools are missing or not configured."
+        echo "   • git: https://git-scm.com/downloads"
+        echo "   • gh:  https://cli.github.com/  (then run: gh auth login)"
+        exit 1
+    fi
+fi
+
+# Normal release workflow: verify tools first.
+if ! quick_tool_check; then
+    echo "🔧 Checking required tools..."
+    echo ""
+    check_all_tools || true
+    echo ""
+    echo "❌ Missing required tools. Install them before running ssh-release."
+    echo "   Run 'ssh-release --check-tools' for details."
+    exit 1
+fi
+
+if [ -n "$VERSION_TYPE" ]; then
+    ssh_create_release "$VERSION_TYPE"
+else
+    ssh_create_release
+fi

package/bin/setup.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/*
+ * Entry point for `npx @dream-encode/secret-santa-hat-build-tools setup`.
+ * Delegates to the interactive project setup.
+ */
+
+const path = require( 'path' )
+
+const args = process.argv.slice( 2 )
+
+if ( args[ 0 ] === 'setup' ) {
+	process.argv = [ process.argv[ 0 ], process.argv[ 1 ], ...args.slice( 1 ) ]
+}
+
+require( path.join( __dirname, '..', 'scripts', 'setup-project.js' ) )

package/bin/ssh-release.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/*
+ * Node wrapper for ssh-release.
+ *
+ * Spawns the bundled bash release script so the tool works identically whether
+ * it is invoked through `yarn release`, `npm run release`, or `npx ssh-release`.
+ * Forcing UTF-8 locale here fixes the emoji display issues yarn causes on Windows.
+ */
+
+const { spawn } = require( 'child_process' )
+const path      = require( 'path' )
+
+const scriptDir     = __dirname
+const releaseScript = path.join( scriptDir, 'release.sh' )
+
+const isYarn    = process.env.npm_config_user_agent && process.env.npm_config_user_agent.includes( 'yarn' )
+const isWindows = process.platform === 'win32'
+
+if ( isYarn && isWindows ) {
+	console.log( '⚠️  Note: running via yarn on Windows may garble emoji output. If it looks wrong, use: npm run release' )
+	console.log( '' )
+}
+
+const child = spawn( 'bash', [ releaseScript, ...process.argv.slice( 2 ) ], {
+	stdio: 'inherit',
+	cwd: process.cwd(),
+	env: {
+		...process.env,
+		LANG: process.env.LANG || 'en_US.UTF-8',
+		LC_ALL: process.env.LC_ALL || 'en_US.UTF-8',
+		PYTHONIOENCODING: 'utf-8',
+		TERM: process.env.TERM || 'xterm-256color',
+		SSH_RELEASE_VIA_YARN: isYarn ? '1' : '0',
+	},
+} )
+
+child.on( 'error', ( err ) => {
+	console.error( '❌ Failed to launch the release script.' )
+
+	if ( err.code === 'ENOENT' ) {
+		console.error( '   `bash` was not found on your PATH. Install Git Bash (Windows) or bash (macOS/Linux).' )
+	} else {
+		console.error( `   ${ err.message }` )
+	}
+
+	process.exit( 1 )
+} )
+
+child.on( 'exit', ( code ) => {
+	process.exit( code === null ? 1 : code )
+} )

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dream-encode/secret-santa-hat-build-tools",
+  "version": "0.1.0",
+  "description": "Release build tools for Secret Santa Hat JavaScript repositories. Provides the `ssh-release` command, a JS-tailored port of the gcrq (git_create_release_quiet) release flow.",
+  "license": "MIT",
+  "author": "David Baumwald <david@dream-encode.com>",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "ssh-release": "bin/ssh-release.js",
+    "secret-santa-hat-build-tools": "bin/setup.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dream-encode/secret-santa-hat-build-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dream-encode/secret-santa-hat-build-tools/issues"
+  },
+  "homepage": "https://github.com/dream-encode/secret-santa-hat-build-tools#readme",
+  "keywords": [
+    "secret-santa-hat",
+    "release",
+    "build",
+    "changelog",
+    "versioning",
+    "git",
+    "github"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/*
+ * Postinstall for @dream-encode/secret-santa-hat-build-tools.
+ *
+ * After the package is installed into a project, notify that a "release"
+ * script can be wired in. It never edits package.json automatically here;
+ * wiring happens through the interactive `setup` command so installs stay
+ * side-effect free (and CI-safe).
+ */
+
+const fs   = require( 'fs' )
+const path = require( 'path' )
+const { analyzeCurrentSetup, findProjectRoot } = require( './setup-project' )
+
+const PACKAGE_NAME = '@dream-encode/secret-santa-hat-build-tools'
+
+const colors = {
+	green: '\x1b[32m',
+	yellow: '\x1b[33m',
+	blue: '\x1b[34m',
+	reset: '\x1b[0m',
+	bold: '\x1b[1m',
+	dim: '\x1b[2m',
+}
+
+function log( message, color = 'reset' ) {
+	console.log( `${ colors[ color ] }${ message }${ colors.reset }` )
+}
+
+function isInteractive() {
+	return process.stdout.isTTY && process.stdin.isTTY && ! process.env.CI
+}
+
+function isSelfInstall() {
+	try {
+		const pkg = JSON.parse( fs.readFileSync( path.join( process.cwd(), 'package.json' ), 'utf8' ) )
+
+		return pkg.name === PACKAGE_NAME
+	} catch {
+		return false
+	}
+}
+
+function shouldSkip() {
+	return !! ( process.env.CI || process.env.NO_SETUP || isSelfInstall() )
+}
+
+function main() {
+	if ( shouldSkip() ) {
+		return
+	}
+
+	try {
+		const projectRoot = findProjectRoot()
+
+		if ( ! projectRoot ) {
+			return
+		}
+
+		const pkg = JSON.parse( fs.readFileSync( path.join( projectRoot, 'package.json' ), 'utf8' ) )
+		const analysis = analyzeCurrentSetup( pkg )
+
+		if ( ! analysis.needsSetup ) {
+			return
+		}
+
+		log( '\n' + '='.repeat( 60 ), 'blue' )
+		log( '🎅 secret-santa-hat-build-tools installed', 'bold' )
+		log( '='.repeat( 60 ), 'blue' )
+
+		if ( analysis.hasReleaseScript ) {
+			log( `\n⚠️  Existing release script detected: "${ analysis.currentReleaseScript }"`, 'yellow' )
+			log( '   (setup will back it up as "release-backup")', 'dim' )
+		}
+
+		log( '\n💡 Wire in the release script with:', 'bold' )
+		log( `   npx ${ PACKAGE_NAME } setup          # interactive`, 'blue' )
+		log( `   npx ${ PACKAGE_NAME } setup --force  # no prompts`, 'blue' )
+		log( '\n   Then: yarn release   (runs your prerelease script, then the release flow)', 'dim' )
+		log( '='.repeat( 60 ) + '\n', 'blue' )
+
+		if ( ! isInteractive() ) {
+			log( `Run: npx ${ PACKAGE_NAME } setup`, 'yellow' )
+		}
+	} catch ( error ) {
+		if ( process.env.DEBUG ) {
+			console.error( 'secret-santa-hat-build-tools postinstall error:', error )
+		}
+	}
+}
+
+main()