latex-stickies 1.3.6 → 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.
 
@@ -146,6 +149,7 @@ npm test         # unit suites
 npm run vendor   # rebuild the bundled libraries
 npm run icon     # rebuild the app icon from assets/icon-master.png
 npm run demo     # re-record assets/demo.gif from the real app (needs ffmpeg)
+npm run verify   # install the packed tarball and check what a user gets
 npm run dist     # build a macOS .app and .dmg
 ```
 
@@ -158,6 +162,7 @@ node scripts/smoke.js --lifecycle # closing every note behaves per platform
 node scripts/render-check.js      # the first-run note renders correctly
 node scripts/ghost-check.js       # autocomplete suggests, and Tab accepts
 node scripts/snapshot-check.js    # a long note is captured whole
+node scripts/verify-install.js    # the install path, end to end (macOS)
 ```
 
 The renderer loads over `file://` under a strict content-security policy, so

package/bin/latex-stickies.js

@@ -10,26 +10,32 @@
 const { spawn } = require('child_process');
 const path = require('path');
 
-let electron;
+// 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 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 {
-  electron = require('electron');
-} catch (_) {
-  console.error(
-    'Could not find the Electron runtime.\n' +
-    'Reinstall with: npm install -g latex-stickies'
-  );
-  process.exit(1);
+  electron = require('../scripts/brand-electron.js').ensure();
+} catch (err) {
+  console.error(`could not brand the app: ${err.message}`);
 }
 
-// Name the Electron shell before launching it, not only at install time.
-// 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.
-try {
-  require('../scripts/brand-electron.js');
-} catch (_) { /* cosmetic: never block a launch over the name */ }
+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, '..');
 const child = spawn(electron, [appDir, ...process.argv.slice(2)], {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "latex-stickies",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Sticky notes for your desktop that render LaTeX and Markdown.",
   "main": "src/main.js",
   "scripts": {
     "start": "electron .",
     "test": "node scripts/test.js",
+    "verify": "node scripts/verify-install.js",
     "vendor": "node scripts/vendor.js",
     "icon": "node scripts/make-icon.js",
     "demo": "node scripts/make-demo.js",

package/scripts/brand-electron.js

@@ -1,152 +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;
+  }
+}
+
+function setPlist(plist, key, value) {
+  try {
+    run('plutil', ['-replace', key, '-string', value, plist]);
+  } catch (_) {
+    run('plutil', ['-insert', key, '-string', value, plist]);
+  }
 }
 
-function main() {
-  if (process.platform !== 'darwin') return; // only macOS names apps this way
+/**
+ * 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 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)) {
-    // Already named, so 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}`);
-    }
-
-    // The bundle icon is what shows before the app can set its own.
-    const icon = path.join(__dirname, '..', 'build', 'icon.icns');
-    const target = path.join(appPath, 'Contents', 'Resources', 'electron.icns');
-    if (fs.existsSync(icon) && fs.existsSync(target)) fs.copyFileSync(icon, target);
-
-    // Required: the edits above invalidate the ad-hoc signature, and macOS
-    // refuses to launch a bundle whose signature does not match its contents.
-    execFileSync('codesign', ['--force', '--deep', '--sign', '-', appPath], {
-      stdio: 'ignore',
-    });
-    execFileSync('codesign', ['--verify', appPath], { stdio: 'ignore' });
-
-    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();

package/src/main.js

@@ -473,11 +473,23 @@ let quitting = false;
  */
 function prepareToExit() {
   quitting = true;
-  if (stopWatchingNotes) {
-    stopWatchingNotes();
-    stopWatchingNotes = null;
+  // Nothing here may throw. The caller's next statement is process.exit(), and
+  // an exception thrown on the way out skips it -- leaving exactly the
+  // invisible, unreachable process this whole path exists to prevent. Saving
+  // is worth attempting; it is not worth staying alive for.
+  try {
+    if (stopWatchingNotes) {
+      stopWatchingNotes();
+      stopWatchingNotes = null;
+    }
+  } catch (err) {
+    console.error('could not stop watching the notes folder', err);
+  }
+  try {
+    store.saveNow();
+  } catch (err) {
+    console.error('could not save on the way out', err);
   }
-  store.saveNow();
 }
 
 function watchNotesFolder() {
@@ -490,12 +502,16 @@ function watchNotesFolder() {
 }
 
 app.whenReady().then(async () => {
-  // Run from npm there is no .app bundle to carry the icon, so macOS would show
-  // the generic Electron atom in the Dock. Set it explicitly.
-  // Only when running from source or from npm. A packaged app already carries
-  // its icon in the bundle, and build/ is not shipped inside it -- trying
-  // anyway logged a missing-file error on every launch of the built app.
-  if (!app.isPackaged && process.platform === 'darwin' && app.dock) {
+  // Run from npm there is no .app bundle of our own to carry the icon, so
+  // macOS would show the generic Electron atom in the Dock. Set it explicitly.
+  //
+  // Keyed on the file existing, not on app.isPackaged. Naming the Dock entry
+  // means renaming the executable inside the vendored Electron.app, and
+  // isPackaged is derived from that executable's name -- so an npm install
+  // started reporting itself as packaged, this branch stopped running, and
+  // fixing the name cost the icon. A packaged build has no build/ directory
+  // inside it, which is the same condition, tested directly.
+  if (process.platform === 'darwin' && app.dock && fs.existsSync(ICON)) {
     try {
       const image = nativeImage.createFromBuffer(fs.readFileSync(ICON));
       if (!image.isEmpty()) app.dock.setIcon(image);

package/src/store.js

@@ -20,7 +20,16 @@ const { app } = require('electron');
 const fs = require('fs');
 const path = require('path');
 
-const DIR = path.join(app.getPath('documents'), 'LaTeX Stickies');
+/**
+ * Where the notes live.
+ *
+ * The override exists for harnesses. On macOS Electron resolves the documents
+ * folder through the OS rather than $HOME, so a test that redirects HOME still
+ * reads and writes the real notes -- which is how a verification run ended up
+ * touching them.
+ */
+const DIR = process.env.LATEX_STICKIES_NOTES_DIR
+  || path.join(app.getPath('documents'), 'LaTeX Stickies');
 const INDEX = path.join(DIR, '.stickies.json');
 /** The old single-file store, migrated from once and then left alone. */
 const LEGACY = path.join(app.getPath('userData'), 'notes.json');