chore(ci): generate consumer-facing release notes automatically (#17)

* chore(ci): generate consumer-facing release notes automatically

Mirror mobile's CI release-notes flow on desktop, and add a human-readable
summary on top.

- scripts/release-notes.mjs: deterministic (no network/API key) generator that
  turns conventional-commit subjects into a "## Highlights" summary (feat -> New,
  fix/perf -> Fixes), with prefixes stripped, PR refs removed, em dashes/curly
  quotes normalized to brand voice, de-duped. Internal commits (chore/ci/docs/
  test/refactor) stay out of the summary. Honest fallback for internal-only
  builds. The raw "## What's Changed" commit list and Full Changelog link follow.
  Reads prevTag..HEAD by default, optional end-ref so the same logic does CI and
  backfill.
- release.yml: the Generate-release-notes step calls the script; electron-builder
  creates the release with empty notes, so an Attach-release-notes step sets them
  via `gh release edit --notes-file` after publish.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(ci): address review - execFileSync for git, fix first-release changelog link

- Use execFileSync('git', [...]) instead of execSync with a shell command, so
  the range/refs are passed as args, never interpreted as command text.
- First release (no prior tag) links to the release tag instead of a v0.0.0
  compare URL that would 404.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: User <user@Users-MacBook-Pro-174.local>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.github/workflows/release.yml

@@ -94,6 +94,20 @@ jobs:
         run: npm ci
       - name: Build (typecheck + bundle)
         run: npm run build
+      # Same approach as mobile (.github/workflows/release.yml): collect the commits
+      # since the previous release tag into release-notes.md. Generated BEFORE publish
+      # so the tag electron-builder is about to create (v$VERSION) is not yet the
+      # "last tag" — git describe resolves to the PREVIOUS release. We drop the
+      # bot version-bump commit ([skip ci]) so notes are only real changes.
+      - name: Generate release notes
+        run: |
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          node scripts/release-notes.mjs \
+            "$LAST_TAG" \
+            "${{ needs.version.outputs.version }}" \
+            "${{ github.repository }}" \
+            > release-notes.md
+          cat release-notes.md
       - name: Package, sign, notarize & publish (DMG + auto-update metadata)
         env:
           CSC_LINK: ${{ secrets.CSC_LINK }}
@@ -126,3 +140,11 @@ jobs:
           # they follow latest-mac.yml. One-time bridge so no Pro user is orphaned.
           cp dist/latest-mac.yml dist/pro-mac.yml
           gh release upload "v$VERSION" dist/pro-mac.yml --clobber
+      # electron-builder creates the GitHub release with empty notes; attach the
+      # notes generated above (mobile sets them at create time via --notes-file; the
+      # desktop release is created by electron-builder, so we set them after).
+      - name: Attach release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.version.outputs.version }}
+        run: gh release edit "v$VERSION" --notes-file release-notes.md

scripts/release-notes.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Build consumer-facing release notes from conventional-commit subjects.
+//
+// Usage:
+//   node scripts/release-notes.mjs <prevTag> <version> <repo> [toRef]
+//   - prevTag: previous release tag, or "" for the first release
+//   - version: the version being released, WITHOUT the leading "v" (e.g. 0.0.33)
+//   - repo:    owner/name (for the Full Changelog compare link)
+//   - toRef:   end of the range (default HEAD). CI omits it; backfill passes the
+//              tag being documented (e.g. v0.0.25) so it reads prevTag..v0.0.25.
+//
+// Reads `git log <prevTag>..HEAD` itself, so it is the single source of truth for
+// both the CI step and the backfill. Output goes to stdout (the workflow redirects
+// it to release-notes.md). No network, no API key, deterministic.
+//
+// Shape:
+//   ## Highlights         <- the human-readable summary (grouped, plain language)
+//   **New** / **Fixes**
+//   ## What's Changed     <- the full commit list (same as before)
+//   **Full Changelog**: …
+
+import { execFileSync } from 'node:child_process'
+
+const [prevTag = '', version = '0.0.0', repo = '', toRef = 'HEAD'] = process.argv.slice(2)
+
+// Commit types that mean something to a person using the app. Everything else
+// (chore, ci, docs, test, refactor, style, build, wip, snapshot) is internal and
+// stays out of the human summary - it still shows in the raw commit list below.
+const TYPE_GROUP = { feat: 'New', fix: 'Fixes', perf: 'Fixes' }
+
+// Pass args to git directly (no shell) so the range/refs are never interpreted as
+// command text. %s subject, %h short hash, tab-separated. Skip the bot version bump.
+const range = prevTag ? `${prevTag}..${toRef}` : toRef
+const raw = execFileSync(
+  'git',
+  ['log', range, '--no-merges', '--invert-grep', '--grep=\\[skip ci\\]', '--pretty=format:%s\t%h'],
+  { encoding: 'utf8' },
+).trim()
+
+const commits = raw ? raw.split('\n').map((l) => {
+  const [subject, hash] = l.split('\t')
+  return { subject, hash }
+}) : []
+
+// Turn a conventional-commit subject into a plain sentence a user can read.
+function humanize(subject) {
+  const m = subject.match(/^(\w+)(?:\(([^)]+)\))?!?:\s*(.+)$/)
+  let text = m ? m[3] : subject
+  text = text
+    .replace(/\s*\(#\d+\)\s*$/, '')      // drop trailing PR refs: "(#11)"
+    .replace(/[—–]/g, ' - ')    // em/en dash -> " - " (brand voice)
+    .replace(/[‘’]/g, "'")      // curly -> straight
+    .replace(/[“”]/g, '"')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.charAt(0).toUpperCase() + text.slice(1)
+}
+
+function typeOf(subject) {
+  const m = subject.match(/^(\w+)(?:\([^)]+\))?!?:/)
+  return m ? m[1] : null
+}
+
+// Group the user-facing commits.
+const groups = { New: [], Fixes: [] }
+for (const c of commits) {
+  const group = TYPE_GROUP[typeOf(c.subject)]
+  if (group) groups[group].push(humanize(c.subject))
+}
+
+// De-dupe within a group (snapshots/rebases can repeat a subject).
+for (const k of Object.keys(groups)) groups[k] = [...new Set(groups[k])]
+
+const out = []
+out.push('## Highlights', '')
+
+const hasHighlights = groups.New.length || groups.Fixes.length
+if (hasHighlights) {
+  if (groups.New.length) {
+    out.push('**New**', '')
+    for (const line of groups.New) out.push(`- ${line}`)
+    out.push('')
+  }
+  if (groups.Fixes.length) {
+    out.push('**Fixes**', '')
+    for (const line of groups.Fixes) out.push(`- ${line}`)
+    out.push('')
+  }
+} else {
+  // Only internal commits (chore/ci/docs/test). Be honest about it.
+  out.push('Maintenance release. No user-facing changes this build.', '')
+}
+
+out.push('## What\'s Changed', '')
+if (commits.length) {
+  for (const c of commits) out.push(`- ${c.subject} (${c.hash})`)
+} else {
+  out.push('- No changes since the previous release.')
+}
+out.push('')
+// On the first release there's no prior tag to compare against (a v0.0.0 compare
+// link would 404), so point at the release tag itself.
+if (prevTag) {
+  out.push(`**Full Changelog**: https://github.com/${repo}/compare/${prevTag}...v${version}`)
+} else {
+  out.push(`**Full Changelog**: https://github.com/${repo}/releases/tag/v${version}`)
+}
+
+process.stdout.write(out.join('\n') + '\n')