@tobq/boardclip 0.0.0-stage → 2.1.108

package/lib/appearance.js

@@ -0,0 +1,183 @@
+'use strict';
+
+// Appearance settings, pure: validation, the one-time promotion of the old
+// debug-only axes, the synced merge and the window surface options. main.js
+// owns the live parts (OS accent watchers, window broadcasts); everything here
+// is data in, data out, so it is unit-tested without Electron.
+//
+// Which keys travel between devices:
+// - SYNCED (one choice the user makes once): theme_mode, accent_mode +
+//   accent_custom, ui_density, ui_corners. Each group carries a last-change stamp in
+//   appearance_stamps; a remote copy wins only with a NEWER stamp, so a device
+//   that never touched a setting (stamp 0, or an older build that sends no
+//   stamps) can never overwrite one that did. "System" accent is synced as the
+//   CHOICE; the colour it resolves to is read per device.
+// - PER MACHINE: surface_style (glass support is hardware-dependent),
+//   glass_scope, and the audit-only ui_borders.
+
+const ACCENT_MODES = ['system', 'blue', 'teal', 'mono', 'custom'];
+const ACCENT_PRESETS = ['blue', 'teal', 'mono'];
+const DENSITIES = ['normal', 'compact'];
+const CORNERS = ['soft', 'sharp'];
+const BORDERS = ['bordered', 'borderless'];
+const SURFACE_STYLES = ['auto', 'glass', 'solid'];
+const GLASS_SCOPES = ['popup', 'all'];
+
+// Synced groups -> the settings keys each stamp covers.
+const SYNCED_GROUPS = {
+  theme: ['theme_mode'],
+  accent: ['accent_mode', 'accent_custom'],
+  density: ['ui_density'],
+  corners: ['ui_corners'],
+};
+
+// '#rgb', '#rrggbb', '#rrggbbaa', or the same without '#' (Electron's
+// getAccentColor and 'accent-color-changed' give 'rrggbbaa') -> '#rrggbb'
+// lowercase, alpha dropped. Anything else -> null. ONE rule for main's
+// validator and the renderer's Custom field: the shared core's.
+const { normalizeHexColor: normalizeAccentHex } = require('../site/shared/clipboard-ui-core');
+
+// The accent a window paints with. preset = the token palette the CSS keys on
+// (data-accent); color = an explicit '#rrggbb' laid over it (System, Custom),
+// null when the preset alone applies or the colour is unknown.
+function resolveAccent({ mode, custom, system } = {}) {
+  const m = ACCENT_MODES.includes(mode) ? mode : 'system';
+  if (ACCENT_PRESETS.includes(m)) return { mode: m, preset: m, color: null };
+  const color = m === 'custom' ? normalizeAccentHex(custom) : normalizeAccentHex(system);
+  return { mode: m, preset: 'blue', color };
+}
+
+// Validators for every appearance key save-settings and the synced merge accept.
+const THEME_MODES = ['system', 'light', 'dark'];
+const VALIDATORS = {
+  theme_mode: (v) => (THEME_MODES.includes(v) ? v : undefined),
+  accent_mode: (v) => (ACCENT_MODES.includes(v) ? v : undefined),
+  // '' clears the custom colour.
+  accent_custom: (v) => (v === '' ? '' : (normalizeAccentHex(v) || undefined)),
+  ui_density: (v) => (DENSITIES.includes(v) ? v : undefined),
+  ui_corners: (v) => (CORNERS.includes(v) ? v : undefined),
+  ui_borders: (v) => (BORDERS.includes(v) ? v : undefined),
+  surface_style: (v) => (SURFACE_STYLES.includes(v) ? v : undefined),
+  glass_scope: (v) => (GLASS_SCOPES.includes(v) ? v : undefined),
+};
+const GROUP_OF = Object.fromEntries(Object.entries(SYNCED_GROUPS).flatMap(([g, keys]) => keys.map((k) => [k, g])));
+
+function stampOf(settings, group) {
+  const stamps = settings && settings.appearance_stamps;
+  const n = Number(stamps && typeof stamps === 'object' ? stamps[group] : 0);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+// A new stamps object (never the shared default's) in one key order, so two
+// devices holding the same stamps serialize them identically.
+function withStamps(settings, updates) {
+  const stamps = {};
+  for (const group of Object.keys(SYNCED_GROUPS)) {
+    const n = updates[group] !== undefined ? updates[group] : stampOf(settings, group);
+    if (n > 0) stamps[group] = n;
+  }
+  return stamps;
+}
+
+// Applies the appearance keys of a save-settings body to `settings` (mutated).
+// Invalid values are ignored. A synced group whose value changed gets a fresh
+// stamp. The old debug switcher's accent_variant is an alias for accent_mode.
+// -> { changed: [keys whose value changed], synced: true when a synced group changed }
+function applyAppearanceSettings(settings, body, { now = Date.now() } = {}) {
+  const changed = [];
+  const b = body && typeof body === 'object' ? body : {};
+  const input = { ...b };
+  if (input.accent_mode === undefined && ACCENT_PRESETS.includes(input.accent_variant)) input.accent_mode = input.accent_variant;
+  const stamped = new Set();
+  for (const [key, validate] of Object.entries(VALIDATORS)) {
+    if (input[key] === undefined) continue;
+    const value = validate(input[key]);
+    if (value === undefined || settings[key] === value) continue;
+    settings[key] = value;
+    changed.push(key);
+    if (GROUP_OF[key]) stamped.add(GROUP_OF[key]);
+  }
+  if (stamped.size) {
+    const updates = {};
+    for (const group of stamped) updates[group] = Math.max(now, stampOf(settings, group) + 1);
+    settings.appearance_stamps = withStamps(settings, updates);
+  }
+  return { changed, synced: stamped.size > 0 };
+}
+
+// Folds a remote device's synced appearance into `local` (mutated): per group,
+// the newer stamp wins, and only with values that validate. -> true if changed.
+function mergeSyncedAppearance(local, remote) {
+  if (!local || !remote || typeof remote !== 'object') return false;
+  let changed = false;
+  for (const [group, keys] of Object.entries(SYNCED_GROUPS)) {
+    const theirs = stampOf(remote, group);
+    if (!(theirs > stampOf(local, group))) continue;
+    const values = {};
+    let valid = true;
+    for (const key of keys) {
+      const value = remote[key] === undefined ? undefined : VALIDATORS[key](remote[key]);
+      if (value === undefined) { valid = false; break; }
+      values[key] = value;
+    }
+    if (!valid) continue;
+    Object.assign(local, values);
+    local.appearance_stamps = withStamps(local, { [group]: theirs });
+    changed = true;
+  }
+  return changed;
+}
+
+// One-time promotion of the old audit axes, run on the settings file AS READ
+// (before defaults fill it in). A file that already has accent_mode is done.
+// The old accent_variant / ui_density / ui_corners applied ONLY under
+// BOARDCLIP_DEBUG_VARIANTS, so a value left in a file from an audit session
+// was never on screen (the live install still held ui_corners 'sharp' from
+// 2026-09). Promoting such a value would change the look on upgrade and then
+// sync it to every device: the 2026-09-02 "looks different per machine" bug.
+// So they carry over only where the flag is on (where they WERE the look);
+// elsewhere the defaults apply, which is exactly what that machine showed.
+// 'blue' was the old default, indistinguishable from "never chosen", so it
+// becomes the new default (System) like an unset value. Migrated values get
+// no stamp: they stay on this device until the user picks something.
+function migrateAppearanceSettings(raw, { debugVariants = false } = {}) {
+  if (!raw || typeof raw !== 'object') return raw;
+  const out = { ...raw };
+  if (out.accent_mode === undefined) {
+    const legacy = out.accent_variant;
+    out.accent_mode = debugVariants && (legacy === 'teal' || legacy === 'mono') ? legacy : 'system';
+    if (!debugVariants) { delete out.ui_density; delete out.ui_corners; }
+  }
+  delete out.accent_variant;
+  return out;
+}
+
+// BrowserWindow options for a window's surface. support = 'vibrancy' (macOS)
+// | 'acrylic' (Windows 11) | 'none'. Windows uses acrylic (transparent stays
+// false) and switches it live on any window. On macOS transparency is fixed at
+// creation: a window that must switch glass <-> solid while open (live: the
+// popup) stays transparent:true and switches its vibrancy; one created solid
+// otherwise (a secondary window under "Glass on: Popup only") is an ordinary
+// OPAQUE window, which keeps the native shadow macOS gives opaque windows, and
+// a later scope change reaches it the next time it opens.
+function surfaceWindowOptions({ support, on, solidBackground, live = false }) {
+  if (support === 'vibrancy' && (on || live)) {
+    return { transparent: true, vibrancy: on ? 'popover' : undefined, visualEffectState: 'active', backgroundColor: '#00000000' };
+  }
+  if (support === 'acrylic' && on) return { backgroundMaterial: 'acrylic', backgroundColor: '#00000000' };
+  return { backgroundColor: solidBackground };
+}
+
+module.exports = {
+  ACCENT_MODES,
+  ACCENT_PRESETS,
+  DENSITIES,
+  CORNERS,
+  GLASS_SCOPES,
+  SYNCED_GROUPS,
+  normalizeAccentHex,
+  resolveAccent,
+  applyAppearanceSettings,
+  mergeSyncedAppearance,
+  migrateAppearanceSettings,
+  surfaceWindowOptions,
+};

package/lib/auto-update.js

@@ -0,0 +1,306 @@
+'use strict';
+
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const DEFAULT_REPO = {
+  owner: 'tobq',
+  repo: 'boardclip',
+  branch: 'main',
+};
+
+const DEFAULT_POLL_MS = 4 * 60 * 60 * 1000;
+const STARTUP_DELAY_MS = 90 * 1000;
+
+function requestJson(url, timeoutMs = 10000) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, {
+      headers: {
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'BoardClip auto-update',
+        'X-GitHub-Api-Version': '2022-11-28',
+      },
+      timeout: timeoutMs,
+    }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          reject(new Error(`GitHub returned ${res.statusCode}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(error);
+        }
+      });
+    });
+    req.on('timeout', () => req.destroy(new Error('GitHub request timed out')));
+    req.on('error', reject);
+  });
+}
+
+async function latestCommitSha(repo = DEFAULT_REPO) {
+  const url = `https://api.github.com/repos/${repo.owner}/${repo.repo}/commits/${encodeURIComponent(repo.branch)}`;
+  const data = await requestJson(url);
+  return data && data.sha ? String(data.sha) : null;
+}
+
+function updateScriptPath(appDir, platform = process.platform) {
+  return platform === 'win32'
+    ? path.win32.join(appDir, 'update.bat')
+    : path.posix.join(appDir, 'update.sh');
+}
+
+function updateSupport(appDir, buildInfo, platform = process.platform, { updateMode = 'production' } = {}) {
+  // The npm package (npm i -g @tobq/boardclip, npx @tobq/boardclip) lives in a node_modules
+  // folder and is updated by npm itself, not by git.
+  if (String(appDir).split(/[\\/]+/).includes('node_modules')) return { supported: false, reason: 'npm-install' };
+  if (!buildInfo || !buildInfo.fullCommit) return { supported: false, reason: 'unknown-build' };
+  if (!fs.existsSync(path.join(appDir, '.git'))) return { supported: false, reason: 'not-git-checkout' };
+  if (!fs.existsSync(updateScriptPath(appDir, platform))) return { supported: false, reason: 'missing-update-script' };
+  if (buildInfo.dirty && updateMode !== 'development') return { supported: false, reason: 'dirty-checkout' };
+  return { supported: true, reason: 'supported' };
+}
+
+function canAutoUpdate(appDir, buildInfo, platform = process.platform) {
+  return updateSupport(appDir, buildInfo, platform).supported;
+}
+
+function spawnAndCapture(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    let stdout = '';
+    let stderr = '';
+    if (child.stdout) child.stdout.on('data', chunk => { stdout += chunk; });
+    if (child.stderr) child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', error => resolve({ code: 1, stdout, stderr, error }));
+    child.on('close', code => resolve({ code, stdout, stderr }));
+  });
+}
+
+function runGit(appDir, args) {
+  return spawnAndCapture('git', args, {
+    cwd: appDir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+}
+
+async function gitHead(appDir) {
+  const result = await runGit(appDir, ['rev-parse', 'HEAD']);
+  return result.code === 0 ? result.stdout.trim() : null;
+}
+
+async function changedFilesBetween(appDir, before, after) {
+  if (!before || !after || before === after) return [];
+  const result = await runGit(appDir, ['diff', '--name-only', before, after]);
+  if (result.code !== 0) return [];
+  return result.stdout.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+}
+
+function canHotReloadFile(file) {
+  return file === 'index.html' || file.startsWith('site/shared/');
+}
+
+function updateModeForChangedFiles(files) {
+  if (!files.length) return 'none';
+  return files.every(canHotReloadFile) ? 'reload' : 'relaunch';
+}
+
+function updateEnvironment(baseEnv = process.env, { applyOnly = false, updateMode = 'production' } = {}) {
+  const env = { ...baseEnv };
+  // Never inherit control flags from the parent BoardClip process. Production
+  // must not accidentally inherit Development's dirty-checkout bypass, and a
+  // detached update must not inherit apply-only's no-start flag.
+  delete env.BOARDCLIP_UPDATE_ALLOW_DIRTY;
+  delete env.BOARDCLIP_UPDATE_NO_START;
+  if (applyOnly) env.BOARDCLIP_UPDATE_NO_START = '1';
+  if (updateMode === 'development') env.BOARDCLIP_UPDATE_ALLOW_DIRTY = '1';
+  return env;
+}
+
+function runUpdate(appDir, platform = process.platform, { applyOnly = false, updateMode = 'production' } = {}) {
+  const script = updateScriptPath(appDir, platform);
+  const env = updateEnvironment(process.env, { applyOnly, updateMode });
+  const command = platform === 'win32' ? 'cmd.exe' : 'sh';
+  const args = platform === 'win32' ? ['/c', script] : [script];
+  const options = platform === 'win32'
+    ? {
+        cwd: appDir,
+        detached: !applyOnly,
+        stdio: applyOnly ? ['ignore', 'pipe', 'pipe'] : 'ignore',
+        windowsHide: true,
+        env,
+      }
+    : {
+        cwd: appDir,
+        detached: !applyOnly,
+        stdio: applyOnly ? ['ignore', 'pipe', 'pipe'] : 'ignore',
+        env,
+      };
+
+  if (applyOnly) {
+    return spawnAndCapture(command, args, options);
+  }
+  const child = spawn(command, args, options);
+  child.unref();
+  return { detached: true };
+}
+
+function createAutoUpdater({
+  appDir,
+  buildInfo,
+  getBuildInfo = null,
+  repo = DEFAULT_REPO,
+  pollMs = DEFAULT_POLL_MS,
+  startupDelayMs = STARTUP_DELAY_MS,
+  logger = console,
+  onReload,
+  onRelaunch,
+  onBuildInfoChanged,
+  onEvent = null,
+  getUpdateMode = () => 'production',
+  // Injection seams for tests; production uses the real network + git + script.
+  fetchLatest = latestCommitSha,
+  readHead = gitHead,
+  readChangedFiles = changedFilesBetween,
+  applyUpdate = runUpdate,
+} = {}) {
+  let checking = false;
+  let updating = false;
+  let startupTimer = null;
+  let timer = null;
+  // The commit the RUNNING process was started from (or last hot-reloaded to).
+  // This, not the on-disk HEAD, is what "am I up to date" must compare against:
+  // update.bat pulls BEFORE it relaunches, so a script that pulls and then
+  // fails (2026-09-03..20: a :: comment inside a ( ) block aborted it with a
+  // parse error, exit 255) leaves disk at the new commit while the process
+  // still runs the old one. Comparing against disk then reports "current" on
+  // every later poll and the stale process runs until someone restarts it by
+  // hand. Comparing against the running commit retries the relaunch instead.
+  let currentCommit = buildInfo && buildInfo.fullCommit;
+
+  function emit(event) {
+    if (typeof onEvent !== 'function') return;
+    try { onEvent(event); } catch {}
+  }
+
+  function currentBuildInfo() {
+    return typeof getBuildInfo === 'function' ? (getBuildInfo() || buildInfo) : buildInfo;
+  }
+
+  async function check({ manual = false } = {}) {
+    if (checking || updating) return { ok: false, status: 'busy' };
+    const liveBuildInfo = currentBuildInfo();
+    const updateMode = getUpdateMode();
+    const support = updateSupport(appDir, liveBuildInfo, process.platform, { updateMode });
+    if (!support.supported) return { ok: false, status: 'unsupported', reason: support.reason };
+
+    checking = true;
+    let current = currentCommit || liveBuildInfo.fullCommit;
+    let latest = null;
+    try {
+      latest = await fetchLatest(repo);
+      if (!latest) return { ok: false, status: 'unknown' };
+      if (latest === current) return { ok: true, status: 'current', latest };
+
+      updating = true;
+      logger.log(`BoardClip update available: ${current.slice(0, 7)} -> ${latest.slice(0, 7)}`);
+      const updateResult = await applyUpdate(appDir, process.platform, { applyOnly: true, updateMode });
+      if (updateResult.code !== 0) {
+        const message = (updateResult.error ? updateResult.error.message : (updateResult.stderr || updateResult.stdout || 'update failed')).trim();
+        // The pull may already have landed: disk can now be ahead of the
+        // running process. Say so loudly - this is the state that used to
+        // go unnoticed for days.
+        const diskHead = await readHead(appDir);
+        emit({ type: 'apply_failed', from: current, to: latest, disk_head: diskHead, code: updateResult.code, message });
+        throw new Error(message);
+      }
+
+      const updatedHead = await readHead(appDir) || latest;
+      const changedFiles = await readChangedFiles(appDir, current, updatedHead);
+      const mode = updateModeForChangedFiles(changedFiles);
+      if (mode === 'none') {
+        // The pull changed nothing the running process isn't already on - e.g.
+        // a checkout AHEAD of GitHub main (a local commit not pushed yet), whose
+        // fast-forward pull is a no-op. Relaunching then restarted the app 90 s
+        // after every start for nothing; stay up instead.
+        updating = false;
+        emit({ type: 'unchanged', from: current, to: latest, disk_head: updatedHead });
+        return { ok: true, status: 'unchanged', latest, diskHead: updatedHead };
+      }
+      currentCommit = updatedHead;
+      if (onBuildInfoChanged) onBuildInfoChanged();
+      emit({ type: 'applied', from: current, to: updatedHead, mode, changed_files: changedFiles.length });
+
+      if (mode === 'reload' && onReload) {
+        await onReload({ latest: updatedHead, changedFiles });
+        updating = false;
+        return { ok: true, status: 'reloaded', latest: updatedHead, changedFiles, mode };
+      }
+
+      if (onRelaunch) {
+        await onRelaunch({ latest: updatedHead, changedFiles, mode });
+        return { ok: true, status: 'relaunching', latest: updatedHead, changedFiles, mode };
+      }
+
+      applyUpdate(appDir, process.platform, { updateMode });
+      return { ok: true, status: 'updating', latest: updatedHead, changedFiles, mode };
+    } catch (error) {
+      // A failed FETCH is routine (offline, rate limit) and stays quiet unless
+      // asked; a failed APPLY was already emitted above with full detail.
+      if (manual) logger.error(`BoardClip update check failed: ${error.message}`);
+      else if (latest) logger.error(`BoardClip update ${current.slice(0, 7)} -> ${latest.slice(0, 7)} failed: ${error.message}`);
+      updating = false;
+      return { ok: false, status: 'error', error };
+    } finally {
+      checking = false;
+    }
+  }
+
+  function start() {
+    if (startupTimer || timer) return;
+    // Always keep the schedule alive in a source checkout. Production mode may
+    // currently be blocked by tracked edits, but a developer can switch to
+    // Development later without restarting the app.
+    const baseSupport = updateSupport(appDir, currentBuildInfo(), process.platform, { updateMode: 'development' });
+    if (!baseSupport.supported) return;
+    startupTimer = setTimeout(() => {
+      startupTimer = null;
+      check();
+    }, startupDelayMs);
+    startupTimer.unref();
+    timer = setInterval(() => check(), pollMs);
+    timer.unref();
+  }
+
+  function stop() {
+    if (startupTimer) clearTimeout(startupTimer);
+    if (timer) clearInterval(timer);
+    startupTimer = null;
+    timer = null;
+  }
+
+  return { check, start, stop };
+}
+
+module.exports = {
+  DEFAULT_REPO,
+  DEFAULT_POLL_MS,
+  STARTUP_DELAY_MS,
+  canAutoUpdate,
+  changedFilesBetween,
+  createAutoUpdater,
+  gitHead,
+  latestCommitSha,
+  runUpdate,
+  updateSupport,
+  updateEnvironment,
+  updateScriptPath,
+  updateModeForChangedFiles,
+};

package/lib/backup-worker.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// Worker-thread entry for the history backup snapshot.
+//
+// The content-addressed snapshot hashes every stored item (~10k on a mature
+// history) and then runs retention over the pool. Done inline on the main
+// process that was 0.6s median / 2.4s p90 / 5.8s worst of blocking per
+// clipboard capture (measured 2026-09-02 on a 9.7k-item, 7.7MB history), and
+// every popup open queued behind it. The main process now hands over the
+// PREVIOUS on-disk history + settings JSON strings (the pre-write state the
+// time-machine records) and carries on; the result comes back as one message.
+//
+// Pure Node (fs + crypto via lib/backup.js); no Electron APIs, so it also runs
+// under plain `node` in tests.
+
+const { parentPort, workerData } = require('worker_threads');
+const backupStore = require('./backup');
+
+function parseJson(text) {
+  return JSON.parse(String(text || '').replace(/^\uFEFF/, ''));
+}
+
+function run(data) {
+  const { baseDir, historyJson, settingsJson, reason, createdAt, source, prune } = data;
+  const parsed = parseJson(historyJson);
+  const history = Array.isArray(parsed) ? parsed : [];
+  let settings = null;
+  if (settingsJson) {
+    try { settings = parseJson(settingsJson); } catch { settings = null; }
+  }
+  const result = backupStore.writeSnapshot(baseDir, {
+    history,
+    settings,
+    reason,
+    createdAt: new Date(createdAt),
+    source,
+  });
+  const pruned = prune ? backupStore.pruneBackups(baseDir, { ...prune, now: Date.now() }) : null;
+  return { manifestPath: result.manifestPath, count: result.manifest.count, pruned };
+}
+
+try {
+  parentPort.postMessage({ ok: true, ...run(workerData) });
+} catch (err) {
+  parentPort.postMessage({ ok: false, error: err && err.message ? err.message : String(err) });
+}