docs: add Sparkle HTML release notes

2025-12-25 04:27:20 +01:00
parent 57090d4f8d
commit b549307ccf
4 changed files with 153 additions and 23 deletions
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -32,7 +32,7 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag

 5) **macOS app (Sparkle)**
 - [ ] Build + sign the macOS app, then zip it for distribution.
- [ ] Generate the Sparkle signature and update `appcast.xml`.
+- [ ] Generate the Sparkle appcast (HTML notes via `scripts/make_appcast.sh`) and update `appcast.xml`.
 - [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
 - [ ] Follow `docs/mac/release.md` for the exact commands and required env vars.

--- a/docs/mac/release.md
+++ b/docs/mac/release.md
@@ -49,28 +49,12 @@ ditto -c -k --keepParent apps/macos/.build/release/Clawdis.app.dSYM dist/Clawdis
 ```

 ## Appcast entry
-1. Generate the ed25519 signature (requires `SPARKLE_PRIVATE_KEY_FILE`):
-   ```bash
-   SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key \
-   apps/macos/.build/artifacts/sparkle/Sparkle/bin/sign_update dist/Clawdis-0.1.0.zip
-   ```
-   Copy the reported signature and file size.
-2. Edit `appcast.xml` (root of repo), add a new `<item>` at the top pointing to the GitHub release asset. Example snippet to adapt:
-   ```xml
-   <item>
-     <title>Clawdis 0.1.0</title>
-     <sparkle:releaseNotesLink>https://github.com/steipete/clawdis/releases/tag/v0.1.0</sparkle:releaseNotesLink>
-     <pubDate>Sun, 07 Dec 2025 12:00:00 +0000</pubDate>
-     <enclosure url="https://github.com/steipete/clawdis/releases/download/v0.1.0/Clawdis-0.1.0.zip"
-                sparkle:edSignature="<signature from sign_update>"
-                sparkle:version="0.1.0"
-                sparkle:shortVersionString="0.1.0"
-                length="<zip byte size>"
-                type="application/octet-stream" />
-   </item>
-   ```
-   Keep the newest item first; leave the channel metadata intact.
-3. Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.
+Use the release note generator so Sparkle renders formatted HTML notes:
+```bash
+SPARKLE_PRIVATE_KEY_FILE=/Users/steipete/Library/CloudStorage/Dropbox/Backup/Sparkle/ed25519-private-key scripts/make_appcast.sh dist/Clawdis-0.1.0.zip   https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml
+```
+Generates HTML release notes from `CHANGELOG.md` (via `scripts/changelog-to-html.sh`) and embeds them in the appcast entry.
+Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when publishing.

 ## Publish & verify
 - Upload `Clawdis-0.1.0.zip` (and `Clawdis-0.1.0.dSYM.zip`) to the GitHub release for tag `v0.1.0`.
--- a/scripts/changelog-to-html.sh
+++ b/scripts/changelog-to-html.sh
@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION=${1:-}
+CHANGELOG_FILE=${2:-}
+
+if [[ -z "$VERSION" ]]; then
+  echo "Usage: $0 <version> [changelog_file]" >&2
+  exit 1
+fi
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+if [[ -z "$CHANGELOG_FILE" ]]; then
+  if [[ -f "$SCRIPT_DIR/../CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="$SCRIPT_DIR/../CHANGELOG.md"
+  elif [[ -f "CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="CHANGELOG.md"
+  elif [[ -f "../CHANGELOG.md" ]]; then
+    CHANGELOG_FILE="../CHANGELOG.md"
+  else
+    echo "Error: Could not find CHANGELOG.md" >&2
+    exit 1
+  fi
+fi
+
+if [[ ! -f "$CHANGELOG_FILE" ]]; then
+  echo "Error: Changelog file '$CHANGELOG_FILE' not found" >&2
+  exit 1
+fi
+
+extract_version_section() {
+  local version=$1
+  local file=$2
+  awk -v version="$version" '
+    BEGIN { found=0 }
+    /^## / {
+      if ($0 ~ "^##[[:space:]]+" version "([[:space:]].*|$)") { found=1; next }
+      if (found) { exit }
+    }
+    found { print }
+  ' "$file"
+}
+
+markdown_to_html() {
+  local text=$1
+  text=$(echo "$text" | sed 's/^### \(.*\)$/<h3>\1<\/h3>/')
+  text=$(echo "$text" | sed 's/^## \(.*\)$/<h2>\1<\/h2>/')
+  text=$(echo "$text" | sed 's/^- \*\*\([^*]*\)\*\*\(.*\)$/<li><strong>\1<\/strong>\2<\/li>/')
+  text=$(echo "$text" | sed 's/^- \([^*].*\)$/<li>\1<\/li>/')
+  text=$(echo "$text" | sed 's/\*\*\([^*]*\)\*\*/<strong>\1<\/strong>/g')
+  text=$(echo "$text" | sed 's/`\([^`]*\)`/<code>\1<\/code>/g')
+  text=$(echo "$text" | sed 's/\[\([^]]*\)\](\([^)]*\))/<a href="\2">\1<\/a>/g')
+  echo "$text"
+}
+
+version_content=$(extract_version_section "$VERSION" "$CHANGELOG_FILE")
+if [[ -z "$version_content" ]]; then
+  echo "<h2>Clawdis $VERSION</h2>"
+  echo "<p>Latest Clawdis update.</p>"
+  echo "<p><a href=\"https://github.com/steipete/clawdis/blob/main/CHANGELOG.md\">View full changelog</a></p>"
+  exit 0
+fi
+
+echo "<h2>Clawdis $VERSION</h2>"
+
+in_list=false
+while IFS= read -r line; do
+  if [[ "$line" =~ ^- ]]; then
+    if [[ "$in_list" == false ]]; then
+      echo "<ul>"
+      in_list=true
+    fi
+    markdown_to_html "$line"
+  else
+    if [[ "$in_list" == true ]]; then
+      echo "</ul>"
+      in_list=false
+    fi
+    if [[ -n "$line" ]]; then
+      markdown_to_html "$line"
+    fi
+  fi
+done <<< "$version_content"
+
+if [[ "$in_list" == true ]]; then
+  echo "</ul>"
+fi
+
+echo "<p><a href=\"https://github.com/steipete/clawdis/blob/main/CHANGELOG.md\">View full changelog</a></p>"
--- a/scripts/make_appcast.sh
+++ b/scripts/make_appcast.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "$0")/.." && pwd)
+ZIP=${1:?"Usage: $0 Clawdis-<ver>.zip"}
+FEED_URL=${2:-"https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml"}
+PRIVATE_KEY_FILE=${SPARKLE_PRIVATE_KEY_FILE:-}
+if [[ -z "$PRIVATE_KEY_FILE" ]]; then
+  echo "Set SPARKLE_PRIVATE_KEY_FILE to your ed25519 private key (Sparkle)." >&2
+  exit 1
+fi
+if [[ ! -f "$ZIP" ]]; then
+  echo "Zip not found: $ZIP" >&2
+  exit 1
+fi
+
+ZIP_DIR=$(cd "$(dirname "$ZIP")" && pwd)
+ZIP_NAME=$(basename "$ZIP")
+ZIP_BASE="${ZIP_NAME%.zip}"
+VERSION=${SPARKLE_RELEASE_VERSION:-}
+if [[ -z "$VERSION" ]]; then
+  if [[ "$ZIP_NAME" =~ ^Clawdis-([0-9]+(\.[0-9]+){1,2}([-.][^.]*)?)\.zip$ ]]; then
+    VERSION="${BASH_REMATCH[1]}"
+  else
+    echo "Could not infer version from $ZIP_NAME; set SPARKLE_RELEASE_VERSION." >&2
+    exit 1
+  fi
+fi
+
+NOTES_HTML="${ZIP_DIR}/${ZIP_BASE}.html"
+KEEP_NOTES=${KEEP_SPARKLE_NOTES:-0}
+if [[ -x "$ROOT/scripts/changelog-to-html.sh" ]]; then
+  "$ROOT/scripts/changelog-to-html.sh" "$VERSION" >"$NOTES_HTML"
+else
+  echo "Missing scripts/changelog-to-html.sh; cannot generate HTML release notes." >&2
+  exit 1
+fi
+if [[ "$KEEP_NOTES" != "1" ]]; then
+  trap 'rm -f "$NOTES_HTML"' EXIT
+fi
+
+DOWNLOAD_URL_PREFIX=${SPARKLE_DOWNLOAD_URL_PREFIX:-"https://github.com/steipete/clawdis/releases/download/v${VERSION}/"}
+
+export PATH="$ROOT/apps/macos/.build/artifacts/sparkle/Sparkle/bin:$PATH"
+if ! command -v generate_appcast >/dev/null; then
+  echo "generate_appcast not found in PATH. Build Sparkle tools via SwiftPM." >&2
+  exit 1
+fi
+
+generate_appcast \
+  --ed-key-file "$PRIVATE_KEY_FILE" \
+  --download-url-prefix "$DOWNLOAD_URL_PREFIX" \
+  --embed-release-notes \
+  --link "$FEED_URL" \
+  "$ZIP_DIR"
+
+echo "Appcast generated (appcast.xml). Upload alongside $ZIP at $FEED_URL"