latex-stickies 1.3.7 → 1.3.8

package/README.md

@@ -24,7 +24,10 @@ latex-stickies
 ```
 
 Requires Node 22.12 or newer. The first run downloads the Electron runtime
-(~230 MB), so give it a minute; later launches are instant. On a Mac you can
+(~230 MB), so give it a minute; later launches are instant. On a Mac it also
+keeps a copy of the runtime carrying this app's name and icon in
+`~/Library/Application Support/latex-stickies/` -- on APFS that is a
+copy-on-write clone, so it costs almost no disk. On a Mac you can
 download a `.dmg` from [Releases](https://github.com/kev-nj/latex-stickies/releases)
 instead and skip Node entirely.
 

package/bin/latex-stickies.js

@@ -10,36 +10,31 @@
 const { spawn } = require('child_process');
 const path = require('path');
 
-// Name the Electron shell before resolving it, not only at install time.
+// Brand before resolving anything: this returns the path to a copy of the
+// Electron shell carrying our name and icon, kept outside node_modules so it
+// survives npx cache churn and npm ci. Falls back to the plain shell, which
+// runs identically and only looks wrong in the Dock.
 //
-// postinstall scripts are increasingly blocked -- npm warns about them by
-// default now, and plenty of people and companies set ignore-scripts -- and a
-// user who installs with them off gets "Electron" in their Dock. Doing it here
-// as well means the name is right by the time macOS reads the bundle, whatever
-// happened during the install. It returns immediately once done.
-//
-// Strictly before require('electron'): branding renames the executable and
-// rewrites the path.txt that require reads, so a path captured first points at
-// a file that no longer exists and the launch fails with ENOENT. That cost a
-// release -- every first launch after upgrading failed, and only the second
-// worked.
+// postinstall cannot be relied on for this -- npm 11 warns about install
+// scripts by default and blocks them outright for global installs, and plenty
+// of people and companies turn them off.
+let electron = null;
 try {
-  require('../scripts/brand-electron.js');
-} catch (_) { /* cosmetic: never block a launch over the name */ }
+  electron = require('../scripts/brand-electron.js').ensure();
+} catch (err) {
+  console.error(`could not brand the app: ${err.message}`);
+}
 
-let electron;
-try {
-  // Branding resolved the electron module itself, so it is already in Node's
-  // module cache holding the path from before the rename. Drop it and read it
-  // again, or the launch spawns a file that no longer exists.
-  delete require.cache[require.resolve('electron')];
-  electron = require('electron');
-} catch (_) {
-  console.error(
-    'Could not find the Electron runtime.\n' +
-    'Reinstall with: npm install -g latex-stickies'
-  );
-  process.exit(1);
+if (!electron) {
+  try {
+    electron = require('electron');
+  } catch (_) {
+    console.error(
+      'Could not find the Electron runtime.\n' +
+      'Reinstall with: npm install -g latex-stickies'
+    );
+    process.exit(1);
+  }
 }
 
 const appDir = path.join(__dirname, '..');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "latex-stickies",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "description": "Sticky notes for your desktop that render LaTeX and Markdown.",
   "main": "src/main.js",
   "scripts": {

package/scripts/brand-electron.js

@@ -1,180 +1,198 @@
 #!/usr/bin/env node
 /**
- * Gives the Electron shell this app's name and icon, on macOS.
+ * Gives this app its own macOS bundle, so the Dock shows our name and icon.
  *
- * Run from source or from npm there is no .app bundle of our own, so macOS
- * takes the Dock name and icon from the shell being launched -- which is called
- * "Electron" and wears the atom logo. app.setName() cannot change that: the
- * Dock reads it from the bundle before any of our code runs.
+ * Run from source or from npm there is no .app of our own: macOS takes the
+ * Dock name and icon from the Electron shell being launched, which is called
+ * "Electron" and wears the atom logo. app.setName() cannot help -- the Dock
+ * reads the bundle before any of our code runs.
  *
- * Editing Info.plist invalidates the bundle's ad-hoc signature, so it is
- * re-signed afterwards. That matters: an unsigned bundle will not launch on
- * Apple Silicon at all, which is a far worse outcome than a wrong name. If
- * anything here fails, the original Info.plist goes back and the install
- * continues quietly -- a cosmetic nicety must never break someone's install.
+ * So the shell is cloned to a stable path of our own and branded there:
+ *
+ *   ~/Library/Application Support/latex-stickies/LaTeX Stickies.app
+ *
+ * Cloning rather than editing node_modules in place, for three reasons. npx
+ * installs under a fresh cache hash every time, so in-place work is redone
+ * constantly and thrown away by any cache prune or npm ci. A path macOS has
+ * already registered as "Electron" tends to keep serving that name back from
+ * the LaunchServices database however correct the plist becomes -- a path it
+ * has never seen has no such record. And `npm update electron` would silently
+ * revert every rename we made.
+ *
+ * On APFS the clone is copy-on-write: near-instant, and it costs almost no
+ * disk until the files diverge.
+ *
+ * Everything here is best-effort. A wrong name in the Dock is a blemish; a
+ * failed launch is not, so any error falls back to the unbranded shell.
  */
 const { execFileSync } = require('child_process');
+const crypto = require('crypto');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
 const NAME = 'LaTeX Stickies';
 /**
  * Our own bundle identifier, matching the packaged builds.
  *
- * The Electron shell ships as com.github.Electron, and LaunchServices keys its
- * database by identifier rather than by path. So on a machine that has seen any
- * other Electron -- another project's node_modules, an old npx copy, a
- * different Electron app entirely -- the Dock can serve that record's name,
- * "Electron", however carefully this script renames our copy. Taking our own
- * identifier is what stops the collision; renaming alone cannot.
+ * The shell ships as com.github.Electron, and LaunchServices keys its database
+ * by identifier as well as by path -- so on a machine that has seen any other
+ * Electron, that shared identifier can resolve to someone else's record and
+ * serve its name, "Electron", however carefully this bundle is renamed.
  */
 const APP_ID = 'com.kevinjusak.latexsticky';
 
-/**
- * Makes LaunchServices re-read a bundle.
- *
- * It caches an app's name from the first time it sees the path, and npm
- * extracts Electron under a directory macOS indexes -- so it can record
- * "Electron" before this script ever runs, and then keep showing that in the
- * Dock however right the plist is. Renaming alone is not enough.
- */
-function refreshLaunchServices(appPath) {
+const ROOT = path.join(__dirname, '..');
+const ICON = path.join(ROOT, 'build', 'icon.icns');
+
+/** Overridable so a test can brand somewhere disposable. */
+const HOME = process.env.LATEX_STICKIES_APP_DIR
+  || path.join(os.homedir(), 'Library', 'Application Support', 'latex-stickies');
+const TARGET = path.join(HOME, `${NAME}.app`);
+const STAMP = path.join(HOME, '.branded.json');
+
+const LSREGISTER = '/System/Library/Frameworks/CoreServices.framework/Frameworks'
+  + '/LaunchServices.framework/Support/lsregister';
+
+const run = (cmd, args, opts = {}) =>
+  execFileSync(cmd, args, { stdio: 'ignore', timeout: 120000, ...opts });
+
+/** The Electron shell npm installed, and the version we would be cloning. */
+function source() {
+  const dir = path.dirname(require.resolve('electron/package.json', { paths: [ROOT] }));
+  const binary = require(path.join(dir, 'index.js'));
+  // .../Electron.app/Contents/MacOS/Electron -> .../Electron.app
+  const app = path.resolve(path.dirname(binary), '..', '..');
+  const { version } = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  return { app, version };
+}
+
+const sha = (file) => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+/** What the branded copy was built from, so it can be rebuilt when that moves. */
+function stamp(version) {
+  return JSON.stringify({
+    electron: version,
+    icon: fs.existsSync(ICON) ? sha(ICON) : '',
+    name: NAME,
+    id: APP_ID,
+  });
+}
+
+function isCurrent(version) {
   try {
-    execFileSync(
-      '/System/Library/Frameworks/CoreServices.framework/Frameworks'
-      + '/LaunchServices.framework/Support/lsregister',
-      ['-f', appPath],
-      { stdio: 'ignore', timeout: 10000 }
-    );
-  } catch (_) { /* the name is still right; only the cache is stale */ }
+    return fs.existsSync(path.join(TARGET, 'Contents', 'MacOS', NAME))
+      && fs.readFileSync(STAMP, 'utf8') === stamp(version);
+  } catch (_) {
+    return false;
+  }
 }
 
-/**
- * Puts our icon in the bundle, and says whether it had to.
- *
- * The bundle icon is what macOS shows before the app is running -- in Finder,
- * in Cmd-Tab, and in the Dock at launch -- so app.dock.setIcon() alone is not
- * enough. Compared byte for byte rather than copied blindly, because a copy
- * invalidates the signature and costs a re-sign every launch.
- */
-function copyIcon(appPath) {
-  const icon = path.join(__dirname, '..', 'build', 'icon.icns');
-  const target = path.join(appPath, 'Contents', 'Resources', 'electron.icns');
-  if (!fs.existsSync(icon) || !fs.existsSync(target)) return false;
-  if (fs.readFileSync(icon).equals(fs.readFileSync(target))) return false;
-  fs.copyFileSync(icon, target);
-  return true;
+function setPlist(plist, key, value) {
+  try {
+    run('plutil', ['-replace', key, '-string', value, plist]);
+  } catch (_) {
+    run('plutil', ['-insert', key, '-string', value, plist]);
+  }
 }
 
 /**
- * Re-signs the bundle. Required, not optional: any edit under Contents/
- * invalidates the ad-hoc signature, and macOS refuses to launch a bundle whose
- * signature does not match its contents.
+ * Builds the branded copy.
+ *
+ * The executable is renamed as well as the plist keys: macOS takes the Dock
+ * label from the running executable, which is why packaged builds have always
+ * been right -- electron-builder renames it -- and every npm install was not.
  */
-function resign(appPath) {
-  execFileSync('codesign', ['--force', '--deep', '--sign', '-', appPath], {
-    stdio: 'ignore',
-  });
-  execFileSync('codesign', ['--verify', appPath], { stdio: 'ignore' });
-}
-
-function main() {
-  if (process.platform !== 'darwin') return; // only macOS names apps this way
+function build(app, version) {
+  fs.mkdirSync(HOME, { recursive: true });
+  fs.rmSync(TARGET, { recursive: true, force: true });
 
-  let appPath;
+  // -c asks APFS for a copy-on-write clone; plain copy on any filesystem
+  // that cannot, which is slower but correct.
   try {
-    const binary = require(require.resolve('electron', { paths: [path.join(__dirname, '..')] }));
-    // .../Electron.app/Contents/MacOS/Electron -> .../Electron.app
-    appPath = path.resolve(path.dirname(binary), '..', '..');
+    run('cp', ['-cR', app, TARGET]);
   } catch (_) {
-    return; // no runtime installed; nothing to brand
+    run('cp', ['-R', app, TARGET]);
   }
 
-  const plist = path.join(appPath, 'Contents', 'Info.plist');
-  if (!fs.existsSync(plist)) return;
-
-  const read = (key) => {
-    try {
-      return execFileSync('plutil', ['-extract', key, 'raw', plist]).toString().trim();
-    } catch (_) {
-      return '';
-    }
-  };
-
-  const binary = path.join(appPath, 'Contents', 'MacOS', NAME);
-  if (read('CFBundleName') === NAME
-      && read('CFBundleIdentifier') === APP_ID
-      && fs.existsSync(binary)) {
-    // Named already, but the icon may still be an old one: someone who
-    // installed an earlier version has a bundle branded with that version's
-    // artwork, and every upgrade since has taken this path and left it there.
-    if (copyIcon(appPath)) {
-      resign(appPath);
-      refreshLaunchServices(appPath);
-      console.log('updated the icon on the Electron shell');
-      return;
-    }
-    // Otherwise a wrong name in the Dock can only be a stale cache.
-    refreshLaunchServices(appPath);
-    // Say so rather than exiting in silence. A user reporting "the Dock still
-    // says Electron" needs to know whether the rename failed or whether they
-    // are looking at an older instance still holding the single-instance lock.
-    if (process.env.LATEX_STICKIES_VERBOSE) {
-      console.log(`the Electron shell is already named "${NAME}"`);
-    }
-    return;
+  const plist = path.join(TARGET, 'Contents', 'Info.plist');
+  setPlist(plist, 'CFBundleName', NAME);
+  setPlist(plist, 'CFBundleDisplayName', NAME);
+  setPlist(plist, 'CFBundleIdentifier', APP_ID);
+  setPlist(plist, 'CFBundleExecutable', NAME);
+
+  const from = path.join(TARGET, 'Contents', 'MacOS', 'Electron');
+  const to = path.join(TARGET, 'Contents', 'MacOS', NAME);
+  if (fs.existsSync(from)) fs.renameSync(from, to);
+
+  // The bundle icon is what Finder, Cmd-Tab and the Dock show before the app
+  // is running; app.dock.setIcon() cannot stand in for it.
+  const icon = path.join(TARGET, 'Contents', 'Resources', 'electron.icns');
+  if (fs.existsSync(ICON) && fs.existsSync(icon)) fs.copyFileSync(ICON, icon);
+
+  // Re-signing is required: any edit under Contents/ invalidates the ad-hoc
+  // signature, and macOS will not launch a bundle whose signature does not
+  // match its contents. Only the outer bundle was touched, so the helpers keep
+  // their own signatures -- and --preserve-metadata keeps whatever
+  // entitlements the stock build shipped with, which --deep would discard.
+  run('codesign', [
+    '--force',
+    '--preserve-metadata=entitlements,requirements,flags',
+    '--sign', '-', TARGET,
+  ]);
+  run('codesign', ['--verify', TARGET]);
+
+  // Evict any record for this path before registering it, since lsregister -f
+  // refreshes an entry but does not replace a stale one.
+  try { run(LSREGISTER, ['-u', TARGET]); } catch (_) { /* nothing registered */ }
+  try { run(LSREGISTER, ['-f', TARGET]); } catch (_) { /* only the cache */ }
+
+  fs.writeFileSync(STAMP, stamp(version));
+  return to;
+}
+
+/**
+ * The binary to launch: the branded copy, or null to fall back to the shell.
+ */
+function ensure() {
+  if (process.platform !== 'darwin') return null;
+
+  let app;
+  let version;
+  try {
+    ({ app, version } = source());
+  } catch (err) {
+    report(`could not find the Electron runtime to brand (${first(err)})`);
+    return null;
   }
 
-  const backup = fs.readFileSync(plist);
   try {
-    const fields = [
-      ['CFBundleName', NAME],
-      ['CFBundleDisplayName', NAME],
-      ['CFBundleIdentifier', APP_ID],
-      ['CFBundleExecutable', NAME],
-    ];
-    for (const [key, value] of fields) {
-      try {
-        execFileSync('plutil', ['-replace', key, '-string', value, plist]);
-      } catch (_) {
-        execFileSync('plutil', ['-insert', key, '-string', value, plist]);
-      }
-    }
-
-    // Rename the executable too. macOS takes the Dock label from the running
-    // executable, not only from the plist -- which is why the packaged builds
-    // have always shown the right name (electron-builder renames it) while
-    // every npm install showed "Electron" however the plist was rewritten.
-    const oldBinary = path.join(appPath, 'Contents', 'MacOS', 'Electron');
-    if (fs.existsSync(oldBinary) && !fs.existsSync(binary)) {
-      fs.renameSync(oldBinary, binary);
-    }
-    // require('electron') reads this file for the path it returns, so it has
-    // to follow the rename or every launcher breaks.
-    const pathTxt = path.join(path.dirname(appPath), '..', 'path.txt');
-    if (fs.existsSync(pathTxt)) {
-      fs.writeFileSync(pathTxt, `Electron.app/Contents/MacOS/${NAME}`);
-    }
-
-    copyIcon(appPath);
-    resign(appPath);
-    refreshLaunchServices(appPath);
-
-    console.log(`named the Electron shell "${NAME}"`);
+    if (isCurrent(version)) return path.join(TARGET, 'Contents', 'MacOS', NAME);
+    const binary = build(app, version);
+    report(`branded ${TARGET}`, true);
+    return binary;
   } catch (err) {
-    fs.writeFileSync(plist, backup);
-    try {
-      execFileSync('codesign', ['--force', '--deep', '--sign', '-', appPath], {
-        stdio: 'ignore',
-      });
-    } catch (_) { /* leave it as found */ }
-    console.log(`could not rename the Electron shell (${err.message.split('\n')[0]})`);
+    // Leave nothing half-built: a bundle with a broken signature will not
+    // launch at all, which is far worse than the wrong name.
+    fs.rmSync(TARGET, { recursive: true, force: true });
+    report(`could not brand the app (${first(err)})`);
+    return null;
   }
 }
 
-try {
-  main();
-} catch (err) {
-  // Never fail an install over the name in the Dock.
-  console.log('skipped naming the Electron shell:', err.message.split('\n')[0]);
+const first = (err) => String(err && err.message).split('\n')[0];
+
+/**
+ * Failures are reported, successes only when asked.
+ *
+ * A silent failure is what made this so hard to diagnose from a user's
+ * terminal: "the Dock still says Electron" looked identical whether branding
+ * had failed, had never run, or had worked on a bundle nobody was launching.
+ */
+function report(message, quiet = false) {
+  if (!quiet || process.env.LATEX_STICKIES_VERBOSE) console.log(message);
 }
+
+module.exports = { ensure, TARGET, NAME, APP_ID };
+
+if (require.main === module) ensure();