@davmash/bygone 0.8.4 → 0.8.6

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.8.6
+
+- Added optional authored-tour `windowTitle` labels and context-aware desktop and VS Code window titles
+- Fixed tour presenter windows so authored `windowTitle` values appear in the native title instead of staying on the default `Bygone Tour` label
+
+## 0.8.5
+
+- Fixed Homebrew cask `bygone` CLI launch on Apple Silicon by routing through a bundle-aware launcher script inside the app
+- Documented the macOS **“app is damaged”** workaround for unsigned desktop downloads (README, releasing docs, PR Tour Guide skill)
+
+**macOS install:** Desktop builds are unsigned. If Gatekeeper reports the app is damaged, run `xattr -cr /Applications/Bygone.app` then open the app.
+
 ## 0.8.4
 
 - Clarified PR Tour Guide skill install commands for project scope and agent-specific global installs

package/README.md

@@ -137,6 +137,19 @@ Contributors should consult the internal [product surface overview](./docs/produ
 
 The desktop app also includes `Help -> Install Command Line Tools...` for non-npm installs. Homebrew cask installs can provide the `bygone` command automatically.
 
+### macOS says the app is damaged
+
+Downloads from GitHub or Homebrew are **unsigned** (no Apple Developer ID signature yet). macOS Gatekeeper then shows a misleading **“damaged”** dialog.
+
+**Workaround (unsigned desktop builds):**
+
+```bash
+xattr -cr /Applications/Bygone.app
+open /Applications/Bygone.app
+```
+
+Or right-click the app → **Open** once, or allow it under **System Settings → Privacy & Security**.
+
 ## Package For External Use
 
 This repo is set up for local/private packaging. A typical release flow is:

package/cli/present.js

@@ -3,6 +3,7 @@ const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
 const { loadTourSource } = require('./tourFile.js');
 
@@ -39,6 +40,10 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         process.stdout.write(`Wrote change-tour manifest to ${resolvedOutput}\n`);
     }
 
+    const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
+    const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
+    let presenterIndexTemplate;
+
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
         if (requestUrl.pathname === '/tour.json') {
@@ -49,6 +54,21 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             response.end(serializedManifest);
             return;
         }
+        if (requestUrl.pathname === '/' || requestUrl.pathname === '/index.html') {
+            if (!presenterIndexTemplate) {
+                presenterIndexTemplate = readFileSync(presenterIndexPath, 'utf8');
+            }
+            const html = presenterIndexTemplate.replace(
+                /<title>Bygone Tour<\/title>/,
+                `<title>${escapeHtml(tourWindowTitle)}</title>`
+            );
+            response.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-store'
+            });
+            response.end(html);
+            return;
+        }
         const targetPath = resolveAssetPath(packageRoot, requestUrl.pathname);
         if (!targetPath) {
             respond(response, 404, 'Not found');
@@ -120,7 +140,7 @@ function parsePresentArgs(args) {
 
 function resolveAssetPath(packageRoot, requestPath) {
     if (requestPath === '/' || requestPath === '/index.html') {
-        return path.join(packageRoot, 'web', 'index.html');
+        return null;
     }
     if (!requestPath.startsWith('/web/') && !requestPath.startsWith('/media/')) {
         return null;
@@ -160,7 +180,16 @@ function respond(response, statusCode, message) {
     response.end(message);
 }
 
+function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+
 module.exports = {
     parsePresentArgs,
-    startPresentation
+    startPresentation,
+    escapeHtml
 };

package/docs/change-tour-format.md

@@ -35,11 +35,16 @@ contents, and diffs into the portable JSON manifest served by the presenter.
 Compilation fails if an anchor has no match or has multiple matches without an
 explicit `occurrence`.
 
+The optional `windowTitle` sets the native window title for the tour presenter.
+Use a short label such as a pull request number when several tours may be open at
+once. When omitted, the presenter falls back to `title`, then a generic tour label.
+
 ## Structure
 
 ```yaml
 version: 1
 title: A reviewer-facing title
+windowTitle: PR-1234
 sourceUrl: https://example.test/pull/123
 range:
   base: 0123456789abcdef

package/docs/releasing.md

@@ -190,6 +190,34 @@ That path must point at a local git checkout of the tap repo. The script writes:
 
 and then commits and pushes that tap repo.
 
+## macOS Unsigned Desktop Builds
+
+Published macOS desktop builds are currently **unsigned and not notarized**. After download, Gatekeeper often shows a misleading **“Bygone is damaged”** dialog.
+
+### End-user workaround
+
+```bash
+xattr -cr /Applications/Bygone.app
+open /Applications/Bygone.app
+```
+
+Or right-click the app → **Open** once, or allow it under **System Settings → Privacy & Security**.
+
+Document this for users in release notes when shipping desktop updates.
+
+### Future signing (not enabled)
+
+Signing helpers are shelved until Apple Developer Program membership is active. They are **not** wired into `release:publish` today.
+
+When ready to enable:
+
+- Config: `packaging/macos/electron-builder.signing.json`
+- Optional manual builds: `npm run package:desktop:mac:release`
+- Verification: `npm run release:verify-macos` or `node scripts/verify-macos-signing.mjs`
+- Re-enable checks in `scripts/release.mjs` (see git history)
+
+Credentials needed later: Developer ID Application cert (`CSC_NAME` / `CSC_LINK`) plus notarization (`APPLE_API_KEY` trio, or `APPLE_ID` + app-specific password + team ID).
+
 ## Recommended Release Flow
 
 ### Step 1. Confirm the version
@@ -223,7 +251,6 @@ This builds:
 - macOS desktop artifacts
 - Linux AppImage
 - Windows artifacts
-- Homebrew style validation, if `brew` is available
 
 If local packaging is partially unavailable, use the lower-level script:
 
@@ -312,6 +339,10 @@ node ./scripts/release.mjs --skip-dmg
 
 Then fix the local DMG toolchain before attempting a full publish.
 
+### macOS says the app is damaged after install
+
+This is expected for unsigned desktop builds. See [macOS Unsigned Desktop Builds](#macos-unsigned-desktop-builds).
+
 ### Windows packaging fails locally
 
 Use:

package/out/changeTour.js

@@ -239,6 +239,9 @@ function parseChangeTourManifest(value) {
   }
   requireString(value.title, "title");
   requireString(value.generatedAt, "generatedAt");
+  if (value.windowTitle !== void 0) {
+    requireString(value.windowTitle, "windowTitle");
+  }
   if (value.sourceUrl !== void 0) {
     requireString(value.sourceUrl, "sourceUrl");
   }
@@ -533,8 +536,9 @@ function parseChangeTourSource(value) {
   if (!isRecord2(value) || value.version !== CHANGE_TOUR_SOURCE_VERSION) {
     throw new Error("Unsupported or missing change-tour source version.");
   }
-  requireOnlyKeys(value, ["version", "title", "sourceUrl", "range", "anchors", "connections", "chapters", "coverage"], "source");
+  requireOnlyKeys(value, ["version", "title", "windowTitle", "sourceUrl", "range", "anchors", "connections", "chapters", "coverage"], "source");
   optionalString(value.title, "title");
+  optionalString(value.windowTitle, "windowTitle");
   optionalString(value.sourceUrl, "sourceUrl");
   if (value.range !== void 0) {
     if (!isRecord2(value.range)) throw new Error("range must be an object.");
@@ -1385,7 +1389,7 @@ var CHAPTERS = {
   packaging: { id: "packaging", title: "Packaging and dependencies", priority: 4 }
 };
 function buildChangeTourManifest(startPath, options = {}) {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e;
   const range = resolveBranchReviewRange(startPath, options.headRef, options.baseRef);
   const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_TOUR_FILE_BYTES;
   const maxLineBytes = options.maxLineBytes ?? DEFAULT_MAX_TOUR_LINE_BYTES;
@@ -1457,7 +1461,8 @@ function buildChangeTourManifest(startPath, options = {}) {
   const manifest = {
     version: CHANGE_TOUR_MANIFEST_VERSION,
     title: ((_a = options.source) == null ? void 0 : _a.title) || ((_b = options.story) == null ? void 0 : _b.title) || options.title || `${range.headRef} against ${range.baseRef}`,
-    sourceUrl: ((_c = options.source) == null ? void 0 : _c.sourceUrl) || ((_d = options.story) == null ? void 0 : _d.sourceUrl) || options.sourceUrl,
+    windowTitle: (_c = options.source) == null ? void 0 : _c.windowTitle,
+    sourceUrl: ((_d = options.source) == null ? void 0 : _d.sourceUrl) || ((_e = options.story) == null ? void 0 : _e.sourceUrl) || options.sourceUrl,
     generatedAt: options.generatedAt || (/* @__PURE__ */ new Date()).toISOString(),
     range: {
       baseRef: range.baseRef,