@tobq/boardclip 0.0.0-stage → 2.1.108

package/lib/build-info.js

@@ -0,0 +1,89 @@
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Read-only git, never holding a lock: `git status` otherwise refreshes the
+// index under .git/index.lock, and the 1 s timeout below kills a slow run with
+// the lock still on disk (seen 2026-10-07/08 on a busy machine) - every later
+// commit, and the auto-updater's pull in an install, then fails.
+function runGit(baseDir, args) {
+  try {
+    return execFileSync('git', ['--no-optional-locks', ...args], {
+      cwd: baseDir,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveGitDirs(baseDir) {
+  const dotGit = path.join(baseDir, '.git');
+  try {
+    if (fs.statSync(dotGit).isDirectory()) return [dotGit];
+  } catch {}
+
+  try {
+    const text = fs.readFileSync(dotGit, 'utf-8').trim();
+    const match = text.match(/^gitdir:\s*(.+)$/);
+    if (!match) return [];
+
+    const gitDir = path.resolve(baseDir, match[1]);
+    try {
+      const commonDir = path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf-8').trim());
+      return [...new Set([gitDir, commonDir])];
+    } catch {
+      return [gitDir];
+    }
+  } catch {
+    return [];
+  }
+}
+
+function readCommitFromGitFiles(baseDir) {
+  const gitDirs = resolveGitDirs(baseDir);
+  if (!gitDirs.length) return null;
+
+  try {
+    const head = fs.readFileSync(path.join(gitDirs[0], 'HEAD'), 'utf-8').trim();
+    if (!head.startsWith('ref: ')) return head;
+
+    const ref = head.slice(5);
+    for (const gitDir of gitDirs) {
+      try {
+        return fs.readFileSync(path.join(gitDir, ref), 'utf-8').trim();
+      } catch {}
+    }
+
+    for (const gitDir of gitDirs) {
+      try {
+        for (const line of fs.readFileSync(path.join(gitDir, 'packed-refs'), 'utf-8').split(/\r?\n/)) {
+          if (line.endsWith(` ${ref}`)) return line.slice(0, 40);
+        }
+      } catch {}
+    }
+  } catch {}
+  return null;
+}
+
+function getBuildInfo(baseDir) {
+  const envCommit = process.env.CLIPBOARD_TRAY_COMMIT || process.env.GIT_COMMIT || process.env.COMMIT_SHA;
+  const envTag = process.env.CLIPBOARD_TRAY_TAG || process.env.GIT_TAG;
+  const fullCommit = envCommit || runGit(baseDir, ['rev-parse', 'HEAD']) || readCommitFromGitFiles(baseDir);
+  const fullCommitSha = fullCommit ? fullCommit.trim() : null;
+  const commit = fullCommitSha ? fullCommitSha.slice(0, 7) : null;
+  const tag = envTag || runGit(baseDir, ['describe', '--tags', '--exact-match', 'HEAD']);
+  // Only TRACKED changes count as "dirty" (matches update.bat's guard). Untracked
+  // runtime/data files (clipboard-RECOVERED/, PRE-RECOVERY backups, edit-archive, etc.)
+  // must NOT mark the checkout dirty, or they silently block the auto-updater
+  // (canAutoUpdate refuses a dirty checkout) after any recovery leaves files behind.
+  const dirty = !!runGit(baseDir, ['status', '--porcelain', '--untracked-files=no']);
+  const commitLabel = commit ? `${commit}${dirty ? '-dirty' : ''}` : null;
+  const label = tag && commitLabel ? `${tag} (${commitLabel})` : (commitLabel || tag || 'unknown');
+
+  return { tag, commit, fullCommit: fullCommitSha, dirty, label };
+}
+
+module.exports = getBuildInfo;

package/lib/clip-blob-store.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const { makeBlobFieldStore, DEFAULT_THRESHOLD_BYTES } = require('./blob-field-store');
+
+// Every payload blob a text clip can carry, in one place. main.js drives storage,
+// sync and p2p off this list, so adding a format touches this file and nothing
+// else. `text` stays first: it is the identity payload (a clip's id is the hash
+// of its text) and the only one with a preview.
+const TEXT_BLOB_DIRNAME = 'clipboard-text';
+const HTML_BLOB_DIRNAME = 'clipboard-html';
+const RTF_BLOB_DIRNAME = 'clipboard-rtf';
+const TEXT_PREVIEW_CHARS = 1024;
+
+const text = makeBlobFieldStore({
+  field: 'text',
+  dirname: TEXT_BLOB_DIRNAME,
+  ext: 'txt',
+  previewChars: TEXT_PREVIEW_CHARS,
+  thresholdBytes: DEFAULT_THRESHOLD_BYTES,
+});
+
+const html = makeBlobFieldStore({
+  field: 'html',
+  dirname: HTML_BLOB_DIRNAME,
+  ext: 'html',
+  previewChars: 0,
+  dropWhenEmpty: true,
+  thresholdBytes: DEFAULT_THRESHOLD_BYTES,
+});
+
+const rtf = makeBlobFieldStore({
+  field: 'rtf',
+  dirname: RTF_BLOB_DIRNAME,
+  ext: 'rtf',
+  previewChars: 0,
+  dropWhenEmpty: true,
+  thresholdBytes: DEFAULT_THRESHOLD_BYTES,
+});
+
+const FIELD_STORES = [text, html, rtf];
+const RICH_FIELD_STORES = [html, rtf];
+const BY_FIELD = new Map(FIELD_STORES.map(store => [store.field, store]));
+
+// Callers may pass either the full { text, html, rtf } directory map or, for the
+// legacy text-only call shape, a bare text directory string. A store handed no
+// directory no-ops rather than resolving a relative path.
+function dirFor(dirs, field) {
+  if (!dirs) return '';
+  if (typeof dirs === 'string') return field === 'text' ? dirs : '';
+  return dirs[field] || '';
+}
+
+function hydrateItem(item, dirs) {
+  for (const store of FIELD_STORES) store.hydrateItem(item, dirFor(dirs, store.field));
+  return item;
+}
+
+function hydrateHistory(items, dirs) {
+  if (!Array.isArray(items)) return [];
+  for (const item of items) hydrateItem(item, dirs);
+  return items;
+}
+
+function prepareItemForStorage(item, dirs, options = {}) {
+  let current = item;
+  for (const store of FIELD_STORES) {
+    current = store.prepareItemForStorage(current, dirFor(dirs, store.field), options);
+  }
+  return current;
+}
+
+function prepareHistoryForStorage(items, dirs, options = {}) {
+  return (Array.isArray(items) ? items : []).map(item => prepareItemForStorage(item, dirs, options));
+}
+
+function removeUnreferencedBlobs(item, items, dirs) {
+  for (const store of FIELD_STORES) {
+    store.removeLocalBlobIfUnreferenced(item, items, dirFor(dirs, store.field));
+  }
+}
+
+// The rich payloads a newly captured clip can donate to an existing entry. A
+// re-copy of identical text is deduped by id, so without this the second copy's
+// formatting would be silently dropped.
+function richPayloadOf(item) {
+  const payload = {};
+  if (!item || item.type === 'image') return payload;
+  for (const store of RICH_FIELD_STORES) {
+    const { value, hash, ref, size } = store.names;
+    if (item[value]) payload[value] = item[value];
+    if (item[hash]) payload[hash] = item[hash];
+    if (item[ref]) payload[ref] = item[ref];
+    if (item[size]) payload[size] = item[size];
+  }
+  return payload;
+}
+
+function hasRichPayload(item, field) {
+  const store = BY_FIELD.get(field);
+  if (!store || !item || item.type === 'image') return false;
+  return !!(item[store.names.value] || item[store.names.ref] || item[store.names.hash]);
+}
+
+// A payload is USABLE only when the bytes are actually reachable. An item can
+// advertise a format (htmlRef/htmlHash present) while hydrate failed to resolve
+// the blob — synced metadata whose blob has not arrived yet. That is metadata,
+// not content, so a fresh capture carrying the real bytes must be allowed to
+// replace it. An UNHYDRATED item carries no flag and is treated as usable,
+// which is the safe default: never discard a payload not proven missing.
+function richPayloadUsable(item, field) {
+  const store = BY_FIELD.get(field);
+  if (!store || !hasRichPayload(item, field)) return false;
+  return !store.isBlobMissing(item);
+}
+
+// Copy rich payloads from `source` onto `target` for formats the target lacks.
+// Never downgrades a usable payload to absent: the older clip may hold the only
+// copy of a blob, and a plain-text re-copy of the same words is not evidence the
+// formatting is gone. Returns true when anything changed.
+function adoptRichPayload(target, source) {
+  if (!target || !source || target.type === 'image' || source.type === 'image') return false;
+  let changed = false;
+  for (const store of RICH_FIELD_STORES) {
+    if (!richPayloadUsable(source, store.field)) continue;
+    if (richPayloadUsable(target, store.field)) continue;
+    // Clear the whole group first. Replacing a missing-blob payload leaves a
+    // stale ref/hash beside the new inline value otherwise, which describes
+    // different content — prepareItemForStorage would then judge the new value
+    // unverified and refuse to store it.
+    store.clearField(target);
+    for (const key of [store.names.value, store.names.hash, store.names.ref, store.names.size]) {
+      if (source[key] === undefined) continue;
+      target[key] = source[key];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+module.exports = {
+  TEXT_BLOB_DIRNAME,
+  HTML_BLOB_DIRNAME,
+  RTF_BLOB_DIRNAME,
+  TEXT_PREVIEW_CHARS,
+  FIELD_STORES,
+  RICH_FIELD_STORES,
+  text,
+  html,
+  rtf,
+  storeFor: field => BY_FIELD.get(field),
+  dirFor,
+  hydrateItem,
+  hydrateHistory,
+  prepareItemForStorage,
+  prepareHistoryForStorage,
+  removeUnreferencedBlobs,
+  richPayloadOf,
+  hasRichPayload,
+  richPayloadUsable,
+  adoptRichPayload,
+};

package/lib/clip-revision.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Optimistic concurrency for clip mutations. Every update/delete of a clip -
+// from the app UI, the MCP tools or any other caller - carries the rev of the
+// version it read (clipboard-model.clipRevision). If the clip has changed since
+// (another device's sync, another window, a concurrent AI edit) the mutation is
+// refused with a RevisionConflict instead of silently clobbering the change.
+//
+// Error messages are "revision_conflict:<code>" so the code survives transports
+// that only carry a message (Electron IPC); .code/.details carry it structured.
+//   rev_required   - no rev supplied
+//   not_found      - no clip with that id (deleted)
+//   superseded     - the clip was edited and now lives at details.currentId
+//   stale_revision - the clip changed; details.currentRev is its rev now
+
+const model = require('./clipboard-model');
+
+const CONFLICT_PREFIX = 'revision_conflict:';
+
+class RevisionConflict extends Error {
+  constructor(code, details = {}) {
+    super(`${CONFLICT_PREFIX}${code}`);
+    this.name = 'RevisionConflict';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function findItem(history, id) {
+  return (Array.isArray(history) ? history : []).find(item => item && model.itemKey(item) === id) || null;
+}
+
+function checkRevision(history, id, expectedRev, { supersedes } = {}) {
+  const key = String(id == null ? '' : id);
+  const rev = typeof expectedRev === 'string' ? expectedRev.trim() : '';
+  if (!rev) return { ok: false, code: 'rev_required', id: key };
+  const item = key ? findItem(history, key) : null;
+  if (!item) {
+    const currentId = model.supersedeMap(supersedes).get(key);
+    if (currentId && currentId !== key && findItem(history, currentId)) {
+      return { ok: false, code: 'superseded', id: key, currentId };
+    }
+    return { ok: false, code: 'not_found', id: key };
+  }
+  const currentRev = model.clipRevision(item);
+  if (currentRev !== rev) return { ok: false, code: 'stale_revision', id: key, expectedRev: rev, currentRev };
+  return { ok: true, id: key, item };
+}
+
+function conflictFrom(result, extra = {}) {
+  const { ok, item, code, ...details } = result;
+  return new RevisionConflict(code, { ...details, ...extra });
+}
+
+function assertRevision(history, id, expectedRev, options) {
+  const result = checkRevision(history, id, expectedRev, options);
+  if (!result.ok) throw conflictFrom(result);
+  return result.item;
+}
+
+// Batch form: targets are [{ id, rev }]. All-or-nothing - every target is
+// checked before the caller changes anything; one conflict refuses the batch.
+function assertRevisions(history, targets, options) {
+  const resolved = [];
+  const failures = [];
+  for (const target of Array.isArray(targets) ? targets : []) {
+    const result = checkRevision(history, target && target.id, target && target.rev, options);
+    if (result.ok) resolved.push({ id: result.id, item: result.item });
+    else failures.push(result);
+  }
+  if (failures.length) {
+    throw conflictFrom(failures[0], { conflicts: failures.map(({ ok, ...f }) => f) });
+  }
+  return resolved;
+}
+
+function isRevisionConflict(err) {
+  return !!err && String(err.message || '').includes(CONFLICT_PREFIX);
+}
+
+module.exports = { RevisionConflict, CONFLICT_PREFIX, checkRevision, assertRevision, assertRevisions, isRevisionConflict };

package/lib/clipboard-capture.js

@@ -0,0 +1,95 @@
+'use strict';
+
+const windowsClipboard = require('./windows-clipboard');
+
+function formatsKey(formats) {
+  return (Array.isArray(formats) ? formats : [])
+    .map(format => String(format || ''))
+    .filter(Boolean)
+    .sort((a, b) => a.localeCompare(b))
+    .join('|');
+}
+
+function safeAvailableFormats(clipboard) {
+  try { return clipboard.availableFormats(); } catch { return []; }
+}
+
+function formatsSuggestImage(formatsOrKey) {
+  const key = Array.isArray(formatsOrKey) ? formatsKey(formatsOrKey) : String(formatsOrKey || '');
+  return /image|png|tiff|bitmap|dib|filedrop|filename|filecontents|filegroupdescriptor|shell idlist|uri-list/i.test(key);
+}
+
+function formatsSuggestFileTransfer(formatsOrKey) {
+  const key = Array.isArray(formatsOrKey) ? formatsKey(formatsOrKey) : String(formatsOrKey || '');
+  return /filedrop|filename|filecontents|filegroupdescriptor|shell idlist|uri-list/i.test(key);
+}
+
+function imageFromNativeImage(image, source) {
+  if (!image || image.isEmpty()) return null;
+  const buffer = image.toPNG();
+  if (!buffer || !buffer.length) return null;
+  const size = image.getSize();
+  if (!size || !size.width || !size.height) return null;
+  return { buffer, width: size.width, height: size.height, source };
+}
+
+function imageFromBuffer(nativeImage, buffer, source, extra) {
+  if (!buffer || !buffer.length || !nativeImage || typeof nativeImage.createFromBuffer !== 'function') return null;
+  const image = nativeImage.createFromBuffer(buffer);
+  const captured = imageFromNativeImage(image, source);
+  return captured ? { ...captured, ...(extra || {}) } : null;
+}
+
+function readElectronImage(clipboard) {
+  try { return clipboard.readImage(); } catch { return null; }
+}
+
+function readClipboardImage(options) {
+  const opts = options || {};
+  const clipboard = opts.clipboard;
+  const nativeImage = opts.nativeImage;
+  const platform = opts.platform || process.platform;
+  const win = opts.windowsClipboard || windowsClipboard;
+  const formats = opts.formats || safeAvailableFormats(clipboard);
+  const key = formatsKey(formats);
+  if (!formatsSuggestImage(key)) return null;
+
+  if (platform === 'win32' && formatsSuggestFileTransfer(key) && win && typeof win.readImageCandidate === 'function') {
+    const candidate = win.readImageCandidate();
+    if (candidate && candidate.buffer) {
+      const fromCandidate = imageFromBuffer(nativeImage, candidate.buffer, candidate.source || 'win32-fallback', { path: candidate.path });
+      if (fromCandidate) return { ...fromCandidate, formats, formatsKey: key };
+    }
+  }
+
+  const electronImage = imageFromNativeImage(readElectronImage(clipboard), 'electron-readImage');
+  if (electronImage) return { ...electronImage, formats, formatsKey: key };
+
+  if (platform === 'win32' && win && typeof win.readImageCandidate === 'function') {
+    const candidate = win.readImageCandidate();
+    if (candidate && candidate.buffer) {
+      const fromCandidate = imageFromBuffer(nativeImage, candidate.buffer, candidate.source || 'win32-fallback', { path: candidate.path });
+      if (fromCandidate) return { ...fromCandidate, formats, formatsKey: key };
+    }
+  }
+
+  return null;
+}
+
+function clipboardChangeToken(formats) {
+  const sequence = windowsClipboard.getSequenceNumber();
+  if (sequence) return `winseq:${sequence}`;
+  return `formats:${Array.isArray(formats) ? formatsKey(formats) : String(formats || '')}`;
+}
+
+module.exports = {
+  formatsKey,
+  formatsSuggestImage,
+  formatsSuggestFileTransfer,
+  readClipboardImage,
+  clipboardChangeToken,
+  _private: {
+    imageFromNativeImage,
+    imageFromBuffer,
+  },
+};

package/lib/clipboard-follow.js

@@ -0,0 +1,98 @@
+'use strict';
+
+// Keeps an open editor's note and the system clipboard in step. While the
+// clipboard holds the note's text, every save of the note also puts the new
+// text on the clipboard, so a pasted copy is never stale and the user never has
+// to re-copy from the editor. It only ever writes over its OWN text: before each
+// write it checks the clipboard still holds what it last saw there, and if the
+// user copied something else in between it stops following instead of
+// clobbering it. Pure + injected (readText/writeText), so it is unit-tested
+// without Electron; main.js owns one per editor session.
+//
+// The clipboard "holds the note" when its text equals one of the note's
+// current versions (the live draft or the last saved text), line endings
+// ignored - Windows apps hand back CRLF for text the editor keeps as LF.
+
+function normalizeEol(text) {
+  return String(text == null ? '' : text).replace(/\r\n?/g, '\n');
+}
+
+function sameText(a, b) {
+  return normalizeEol(a) === normalizeEol(b);
+}
+
+function createClipboardFollower({ readText, writeText } = {}) {
+  let following = false;
+  let lastSeen = null; // exact clipboard text last seen/written while following
+
+  function read() {
+    try { const text = readText(); return String(text == null ? '' : text); } catch { return null; }
+  }
+  function holdsNote(clip, texts) {
+    return (texts || []).some(text => String(text || '').trim() && sameText(clip, text));
+  }
+  function result(event) {
+    return { following, event };
+  }
+  function stop() {
+    following = false;
+    lastSeen = null;
+    return result('stopped');
+  }
+
+  // The clipboard may have changed (a copy anywhere, the editor regaining
+  // focus, the editor opening). `texts` = the note's current versions.
+  // `clipText` lets a caller that already read the clipboard pass it in.
+  function observe(texts, clipText) {
+    const clip = clipText !== undefined ? String(clipText == null ? '' : clipText) : read();
+    if (clip == null) return result('unknown');
+    if (holdsNote(clip, texts) || (following && clip === lastSeen)) {
+      const started = !following;
+      following = true;
+      lastSeen = clip;
+      return result(started ? 'started' : 'following');
+    }
+    return following ? stop() : result('idle');
+  }
+
+  // The note was saved: `prevText` was its previous saved text, `text` the new.
+  // Follows the save onto the clipboard if the clipboard holds this note.
+  function afterSave(prevText, text) {
+    const clip = read();
+    if (clip == null) return result('unknown');
+    const ours = (following && clip === lastSeen) || holdsNote(clip, [prevText, text]);
+    if (!ours) return following ? stop() : result('idle');
+    const started = !following;
+    following = true;
+    if (sameText(clip, text)) {
+      lastSeen = clip;
+      return result(started ? 'started' : 'following');
+    }
+    if (!writeText(String(text || ''))) {
+      // Not written (e.g. a paste sequence holds the clipboard). Still ours,
+      // so the next save retries.
+      lastSeen = clip;
+      return result('write_failed');
+    }
+    lastSeen = String(text || '');
+    return result('written');
+  }
+
+  // The editor's Copy button: put the note on the clipboard and follow it.
+  function adopt(text) {
+    if (!String(text || '').trim()) return result(following ? 'following' : 'idle');
+    if (!writeText(String(text))) return result('write_failed');
+    following = true;
+    lastSeen = String(text);
+    return result('adopted');
+  }
+
+  return {
+    observe,
+    afterSave,
+    adopt,
+    isFollowing: () => following,
+  };
+}
+
+module.exports = { createClipboardFollower, normalizeEol, sameText };