@tobq/boardclip 0.0.0-stage → 2.1.108

package/lib/diagnostics.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+
+const DEFAULT_MAX_EVENTS = 500;
+const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_TAIL_BYTES = 256 * 1024;
+
+function sanitize(value, depth = 0) {
+  if (value == null) return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value.length > 500 ? `${value.slice(0, 500)}...` : value;
+  if (depth > 3) return '[depth]';
+  if (Array.isArray(value)) return value.slice(0, 50).map(item => sanitize(item, depth + 1));
+  if (typeof value === 'object') {
+    const result = {};
+    for (const [key, inner] of Object.entries(value).slice(0, 80)) {
+      result[key] = sanitize(inner, depth + 1);
+    }
+    return result;
+  }
+  return String(value);
+}
+
+class Diagnostics {
+  constructor({ filePath, enabled = false, maxEvents = DEFAULT_MAX_EVENTS, maxFileBytes = DEFAULT_MAX_FILE_BYTES } = {}) {
+    this.filePath = filePath;
+    this.enabled = !!enabled;
+    this.maxEvents = maxEvents;
+    this.maxFileBytes = maxFileBytes;
+    this.events = [];
+    this.startedAt = new Date().toISOString();
+    this.fileTrimmedAt = 0;
+  }
+
+  setEnabled(enabled) {
+    const next = !!enabled;
+    if (this.enabled === next) return;
+    this.enabled = next;
+    this.record('diagnostics.toggle', { enabled: next }, { forceFile: true });
+  }
+
+  isEnabled() {
+    return this.enabled;
+  }
+
+  record(event, details = {}, { forceFile = false } = {}) {
+    const entry = {
+      ts: new Date().toISOString(),
+      event,
+      ...sanitize(details),
+    };
+    this.events.push(entry);
+    if (this.events.length > this.maxEvents) this.events.splice(0, this.events.length - this.maxEvents);
+    if (this.enabled || forceFile) this.append(entry);
+    return entry;
+  }
+
+  slow(event, ms, details = {}, thresholdMs = 100) {
+    if (ms < thresholdMs) return null;
+    return this.record(event, { ...details, ms: Math.round(ms), slow: true }, { forceFile: true });
+  }
+
+  append(entry) {
+    if (!this.filePath) return;
+    try {
+      fs.appendFileSync(this.filePath, `${JSON.stringify(entry)}${os.EOL}`);
+      this.trimFileIfNeeded();
+    } catch {}
+  }
+
+  trimFileIfNeeded() {
+    if (!this.filePath || Date.now() - this.fileTrimmedAt < 30000) return;
+    this.fileTrimmedAt = Date.now();
+    try {
+      const stats = fs.statSync(this.filePath);
+      if (stats.size <= this.maxFileBytes) return;
+      const keepBytes = Math.floor(this.maxFileBytes / 2);
+      const fd = fs.openSync(this.filePath, 'r');
+      const buffer = Buffer.alloc(keepBytes);
+      fs.readSync(fd, buffer, 0, keepBytes, stats.size - keepBytes);
+      fs.closeSync(fd);
+      fs.writeFileSync(this.filePath, buffer.toString('utf8').replace(/^[^\n]*\n?/, ''));
+      fs.appendFileSync(this.filePath, `${JSON.stringify({ ts: new Date().toISOString(), event: 'diagnostics.truncated' })}${os.EOL}`);
+    } catch {}
+  }
+
+  fileTail(maxBytes = DEFAULT_TAIL_BYTES) {
+    if (!this.filePath) return '';
+    try {
+      const stats = fs.statSync(this.filePath);
+      const bytes = Math.min(stats.size, maxBytes);
+      const fd = fs.openSync(this.filePath, 'r');
+      const buffer = Buffer.alloc(bytes);
+      fs.readSync(fd, buffer, 0, bytes, stats.size - bytes);
+      fs.closeSync(fd);
+      return buffer.toString('utf8');
+    } catch {
+      return '';
+    }
+  }
+
+  snapshot(extra = {}) {
+    let file = { path: this.filePath || null, exists: false };
+    try {
+      const stats = fs.statSync(this.filePath);
+      file = { path: this.filePath, exists: true, size: stats.size, mtime: stats.mtime.toISOString() };
+    } catch {}
+    return {
+      generated_at: new Date().toISOString(),
+      started_at: this.startedAt,
+      enabled: this.enabled,
+      file,
+      recent_events: [...this.events],
+      ...sanitize(extra),
+    };
+  }
+}
+
+module.exports = { Diagnostics, sanitize };

package/lib/drag-files.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// File names for image clips dragged out of BoardClip (popup rows, the image
+// viewer). The drag hands the OS a temporary COPY named after the clip's title
+// (else "BoardClip image <local date time>"), never the content-addressed
+// original: a drop into a folder on the same drive is a MOVE by default, which
+// would pull the image out from under its clip. Pure, so it is unit-tested.
+
+const pad = (n) => String(n).padStart(2, '0');
+
+function localStamp(tsSeconds) {
+  const d = new Date((Number(tsSeconds) || 0) * 1000);
+  if (!Number.isFinite(d.getTime())) return 'unknown time';
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}.${pad(d.getMinutes())}.${pad(d.getSeconds())}`;
+}
+
+// Windows-safe: no reserved characters, no trailing dots/spaces, no reserved
+// device names, bounded length.
+function safeBaseName(text) {
+  let s = String(text || '')
+    .replace(/[\u0000-\u001f<>:"/\\|?*]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 80)
+    .replace(/[. ]+$/, '');
+  if (/^(con|prn|aux|nul|com\d|lpt\d)$/i.test(s)) s = `${s} image`;
+  return s;
+}
+
+function extensionOf(item) {
+  const m = /\.([a-z0-9]{1,5})$/i.exec(String(item && item.image || ''));
+  return m ? `.${m[1].toLowerCase()}` : '.png';
+}
+
+// One name per item, unique (case-insensitively) within the drag.
+function dragFileNames(items) {
+  const used = new Set();
+  return (items || []).map((item) => {
+    const base = safeBaseName(item && item.title) || `BoardClip image ${localStamp(item && item.ts)}`;
+    const ext = extensionOf(item);
+    let name = `${base}${ext}`;
+    for (let n = 2; used.has(name.toLowerCase()); n += 1) name = `${base} (${n})${ext}`;
+    used.add(name.toLowerCase());
+    return name;
+  });
+}
+
+module.exports = { dragFileNames, safeBaseName, localStamp };

package/lib/ensure-directory.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function pathPartsFromRoot(targetPath) {
+  const resolved = path.resolve(targetPath);
+  const parsed = path.parse(resolved);
+  const rel = path.relative(parsed.root, resolved);
+  if (!rel) return [];
+  return rel.split(path.sep).filter(Boolean).reduce((parts, part) => {
+    parts.push(path.join(parts.length ? parts[parts.length - 1] : parsed.root, part));
+    return parts;
+  }, []);
+}
+
+function findDirectoryBlocker(targetDir) {
+  for (const part of pathPartsFromRoot(targetDir)) {
+    try {
+      if (fs.existsSync(part) && !fs.statSync(part).isDirectory()) return part;
+    } catch {}
+  }
+  return '';
+}
+
+function moveFileAside(filePath) {
+  const target = `${filePath}.file-conflict-${Date.now()}`;
+  fs.renameSync(filePath, target);
+  return target;
+}
+
+function ensureDirectory(dir) {
+  try {
+    if (fs.existsSync(dir)) {
+      if (fs.statSync(dir).isDirectory()) return { ok: true };
+      const moved = moveFileAside(dir);
+      fs.mkdirSync(dir, { recursive: true });
+      return { ok: true, moved, repaired: true };
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    return { ok: true };
+  } catch (error) {
+    if (!error || error.code !== 'ENOTDIR') throw error;
+    const blocker = findDirectoryBlocker(dir);
+    if (!blocker) throw error;
+    const moved = moveFileAside(blocker);
+    fs.mkdirSync(dir, { recursive: true });
+    return { ok: true, moved, repaired: true };
+  }
+}
+
+module.exports = {
+  ensureDirectory,
+  findDirectoryBlocker,
+  pathPartsFromRoot,
+};

package/lib/fork-names.js

@@ -0,0 +1,35 @@
+'use strict';
+// Single source of truth for recognizing Google Drive "forked" copies of the
+// sync files. When a rename-over-existing lands in a Drive-synced folder, Drive
+// orphans the old object and creates a duplicate, disambiguating the name
+// DIFFERENTLY per client:
+//   macOS / Drive web:          "clipboard-history (1).json"     (parenthesized)
+//   Windows Drive File Stream:  "clipboard-history 2.json"       (space+number, before ext)
+//                               "clipboard-history.json 2.json"  (space+number, after ext)
+// plus leaked atomic-write temps ("<name>.json.<pid>.<ts>.tmp"). The heal MUST
+// match EVERY variant or a device stays permanently split (matching only the
+// parenthesized form once stranded thousands of Windows-forked clips). These
+// patterns NEVER match the canonical "<name>.json".
+function forkFileRe(base) {
+  const b = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const dup = '(?:\\(\\d+\\)|\\d+)'; // "(1)" (mac/web) or "2" (Windows File Stream)
+  return new RegExp(`^${b} ${dup}\\.json$|^${b}\\.json ${dup}\\.json$`);
+}
+function leakedTmpRe(base) {
+  const b = base.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${b}\\.json\\.\\d+\\.\\d+(?: (?:\\(\\d+\\)|\\d+))?\\.tmp$`);
+}
+
+const FORK_HISTORY_RE = forkFileRe('clipboard-history');
+const FORK_SETTINGS_RE = forkFileRe('clipboard-settings');
+const LEAKED_HISTORY_TMP_RE = leakedTmpRe('clipboard-history');
+const LEAKED_SETTINGS_TMP_RE = leakedTmpRe('clipboard-settings');
+
+const isHistoryFork = (n) => FORK_HISTORY_RE.test(n) || LEAKED_HISTORY_TMP_RE.test(n);
+const isSettingsFork = (n) => FORK_SETTINGS_RE.test(n) || LEAKED_SETTINGS_TMP_RE.test(n);
+
+module.exports = {
+  forkFileRe, leakedTmpRe,
+  FORK_HISTORY_RE, FORK_SETTINGS_RE, LEAKED_HISTORY_TMP_RE, LEAKED_SETTINGS_TMP_RE,
+  isHistoryFork, isSettingsFork,
+};

package/lib/fs-probe.js

@@ -0,0 +1,132 @@
+'use strict';
+
+// Bounded liveness for paths that may sit on a NETWORK or CLOUD mount.
+//
+// A wedged mount does not fail, it BLOCKS. On 2026-09-13 Google DriveFS hung and
+// `fs.existsSync('G:\\My Drive')` never returned: the calling thread sat in an
+// uninterruptible kernel wait (even `timeout 8 ls` could not kill it, and
+// PowerShell itself hung enumerating drives). On Electron's main thread that is
+// the whole app - BoardClip would not launch, the popup rendered blank, and one
+// sync pass held `insideSync` for 29 minutes while `sync.skip_inside_sync`
+// repeated every 30 s.
+//
+// Three rules, kept here so no call site has to remember them:
+//   1. never touch such a path synchronously;
+//   2. never wait on one without a deadline;
+//   3. never run two probes of the same path at once - a hung probe keeps a
+//      libuv threadpool thread for ever (there are 4 by default), so retrying a
+//      wedged mount is how one bad drive letter takes every async read down
+//      with it.
+
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_BACKOFF_MS = 30 * 1000;
+const DEFAULT_MAX_BACKOFF_MS = 5 * 60 * 1000;
+
+// Resolves true/false, never rejects, and never outlives `timeoutMs`. The
+// underlying stat may stay pending for ever on a wedged mount; that is the one
+// leaked threadpool thread `createPathHealth` then refuses to duplicate.
+function probePath(target, { timeoutMs = DEFAULT_TIMEOUT_MS, fsp = require('fs').promises } = {}) {
+  if (!target) return Promise.resolve(false);
+  return new Promise(resolve => {
+    let settled = false;
+    let timer = null;
+    const finish = value => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(value);
+    };
+    timer = setTimeout(() => finish(false), timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      fsp.stat(target).then(() => finish(true), () => finish(false));
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+// Tracks which paths are answering. Unknown paths are optimistically usable, so
+// a healthy machine behaves exactly as it always did; only a path that has
+// actually failed is hidden, and only until a single-flight probe says it is
+// back.
+function createPathHealth({
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  backoffMs = DEFAULT_BACKOFF_MS,
+  maxBackoffMs = DEFAULT_MAX_BACKOFF_MS,
+  now = Date.now,
+  probe = null,
+  onTransition = null,
+} = {}) {
+  const runProbe = probe || (target => probePath(target, { timeoutMs }));
+  const state = new Map();
+
+  function entry(target) {
+    let found = state.get(target);
+    if (!found) {
+      found = { healthy: true, failures: 0, retryAt: 0, pending: null };
+      state.set(target, found);
+    }
+    return found;
+  }
+
+  function transition(target, healthy, reason) {
+    const found = entry(target);
+    const was = found.healthy;
+    found.healthy = !!healthy;
+    if (found.healthy) {
+      found.failures = 0;
+      found.retryAt = 0;
+    } else {
+      found.failures += 1;
+      found.retryAt = now() + Math.min(maxBackoffMs, backoffMs * Math.pow(2, found.failures - 1));
+    }
+    if (was !== found.healthy && typeof onTransition === 'function') {
+      try {
+        onTransition({
+          path: target,
+          healthy: found.healthy,
+          failures: found.failures,
+          retryAt: found.retryAt,
+          reason: reason || '',
+        });
+      } catch {}
+    }
+    return found.healthy;
+  }
+
+  return {
+    // Synchronous, no I/O: safe to call on any hot path.
+    usable(target) {
+      const found = state.get(target);
+      return !found || found.healthy;
+    },
+    // Re-probes a failed path once its backoff has expired. Returns the current
+    // verdict immediately (never blocks) when a probe is already outstanding.
+    check(target) {
+      const found = entry(target);
+      if (found.pending) return Promise.resolve(found.healthy);
+      if (found.healthy) return Promise.resolve(true);
+      if (now() < found.retryAt) return Promise.resolve(false);
+      found.pending = Promise.resolve()
+        .then(() => runProbe(target))
+        .then(
+          ok => { found.pending = null; return transition(target, !!ok, 'probe'); },
+          error => { found.pending = null; return transition(target, false, (error && error.message) || 'probe failed'); }
+        );
+      return found.pending;
+    },
+    markFailure(target, reason) { return transition(target, false, reason); },
+    markSuccess(target) { return transition(target, true, 'ok'); },
+    forget(target) { state.delete(target); },
+    snapshot() {
+      const out = {};
+      for (const [target, found] of state) {
+        out[target] = { healthy: found.healthy, failures: found.failures, retryAt: found.retryAt, probing: !!found.pending };
+      }
+      return out;
+    },
+  };
+}
+
+module.exports = { probePath, createPathHealth, DEFAULT_TIMEOUT_MS };

package/lib/history-feed.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// Sends each popup renderer only what changed in history since the state it
+// already holds. Re-sending the whole history on every change cost the owner's
+// popup ~1 s per refresh (13.9k clips, 70 MB of text cloned over IPC and
+// re-indexed on the renderer's only thread), and a refresh fires on every
+// capture, sync merge and settings save - typing froze behind each one.
+//
+// The feed remembers, per renderer, the revision + per-clip stamps it last
+// sent. A request carrying exactly that revision gets a delta: the full id
+// order plus only the clips whose stamp changed. Anything else (a fresh or
+// reloaded renderer, a missed reply) gets a full snapshot, so a renderer can
+// never apply a delta to state it does not have.
+
+// Everything the renderer shows or acts on, minus the blob-sized bodies. Text
+// changes always change the id (content-addressed); rich formats count by size.
+function rendererStamp(item) {
+  if (!item) return '';
+  const { text, html, rtf, ...rest } = item;
+  rest.htmlLen = typeof html === 'string' ? html.length : 0;
+  rest.rtfLen = typeof rtf === 'string' ? rtf.length : 0;
+  return JSON.stringify(rest);
+}
+
+function createHistoryFeed() {
+  const sent = new Map(); // renderer key -> { revision, stamps: Map(id -> stamp) }
+
+  // items: the renderer view of history (each with id + rev), in history order.
+  function stateFor(key, knownRevision, revision, items) {
+    if (knownRevision === revision) return { revision, unchanged: true };
+    const list = items || [];
+    const stamps = new Map();
+    for (const item of list) stamps.set(item.id, rendererStamp(item));
+    const prev = sent.get(key);
+    sent.set(key, { revision, stamps });
+    if (!prev || prev.revision !== knownRevision) return { revision, items: list };
+    return {
+      revision,
+      delta: true,
+      order: list.map(item => item.id),
+      items: list.filter(item => prev.stamps.get(item.id) !== stamps.get(item.id)),
+    };
+  }
+
+  return { stateFor, forget: (key) => sent.delete(key) };
+}
+
+module.exports = { createHistoryFeed, rendererStamp };

package/lib/hmac-auth.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// Shared HMAC request authentication.
+//
+// Used by BOTH the LAN P2P sync server (main.js) and the local MCP control
+// channel (lib/control-server.js). Both are request/response channels that need
+// to prove "this caller knows the shared secret" and reject replayed/stale
+// requests, so the signing scheme lives here once instead of being duplicated.
+//
+// Signature is HMAC-SHA256 over `${method}\n${path}\n${timestamp}\n${bodyHash}`.
+// The body hash binds the signature to the exact payload; the timestamp window
+// bounds replay. Verification is constant-time.
+
+const crypto = require('crypto');
+
+const DEFAULT_WINDOW_MS = 60 * 1000;
+
+function bodyHash(buffer) {
+  return crypto.createHash('sha256').update(buffer || Buffer.alloc(0)).digest('hex');
+}
+
+function sign(secret, method, requestPath, timestamp, hashOfBody) {
+  return crypto
+    .createHmac('sha256', String(secret || ''))
+    .update(`${method}\n${requestPath}\n${timestamp}\n${hashOfBody || ''}`)
+    .digest('hex');
+}
+
+function timingSafeEqualHex(a, b) {
+  try {
+    const bufA = Buffer.from(String(a || ''), 'hex');
+    const bufB = Buffer.from(String(b || ''), 'hex');
+    if (bufA.length === 0 || bufA.length !== bufB.length) return false;
+    return crypto.timingSafeEqual(bufA, bufB);
+  } catch {
+    return false;
+  }
+}
+
+// Verify a signed request. `bodyHashHex` may be passed directly, or `body`
+// (a Buffer) to hash here. `now`/`windowMs` are injectable for testing.
+function verify(secret, {
+  method,
+  path: requestPath,
+  timestamp,
+  signature,
+  body,
+  bodyHashHex,
+  now = Date.now(),
+  windowMs = DEFAULT_WINDOW_MS,
+} = {}) {
+  const ts = Number(timestamp) || 0;
+  if (!ts || Math.abs(now - ts) > windowMs) return false;
+  const hashOfBody = bodyHashHex != null ? bodyHashHex : bodyHash(body || Buffer.alloc(0));
+  const expected = sign(secret, method, requestPath, ts, hashOfBody);
+  return timingSafeEqualHex(signature, expected);
+}
+
+// Build the headers a client sends. Mirrors the `x-boardclip-*` header names the
+// P2P client already uses, so both channels speak the same wire format.
+function signedHeaders(secret, deviceId, method, requestPath, body = Buffer.alloc(0), now = Date.now()) {
+  const timestamp = now;
+  const hashOfBody = bodyHash(body);
+  return {
+    'x-boardclip-device': deviceId || '',
+    'x-boardclip-ts': String(timestamp),
+    'x-boardclip-sig': sign(secret, method, requestPath, timestamp, hashOfBody),
+  };
+}
+
+module.exports = {
+  DEFAULT_WINDOW_MS,
+  bodyHash,
+  sign,
+  verify,
+  signedHeaders,
+  timingSafeEqualHex,
+};