six-degrees 0.2.0

package/lib/companies.js

@@ -0,0 +1,241 @@
+import { readTitle, currentCompany } from './scoring.js';
+// Companies and industries across your network — what the Paths analyzer is
+// built on. Plain functions, no React, so tests/companies.test.mjs runs them.
+//
+// LinkedIn doesn't give an industry for a person, and this app stores none, so
+// industry is inferred from the company name and headline, and labelled
+// "inferred" wherever it is shown. Unclear stays unclear rather than guessed.
+
+// Merge company name variants
+export function normalizeCompany(name) {
+  const n = (name || '').trim().toLowerCase();
+  // Social / Media
+  if (n.includes('snap') && (n.includes('inc') || n === 'snap' || n === 'snapchat')) return 'Snap';
+  if (n.includes('meta') && (n.includes('platform') || n === 'meta' || n.includes('facebook'))) return 'Meta';
+  if (n.includes('tiktok') || n.includes('bytedance')) return 'TikTok';
+  if (n.includes('pinterest')) return 'Pinterest';
+  // Big Tech
+  if (n === 'google' || n.includes('alphabet') || (n.includes('google') && n.includes('llc'))) return 'Google';
+  if (n === 'apple' || n === 'apple inc' || n === 'apple inc.') return 'Apple';
+  if (n.includes('amazon') && !n.includes('amazon ')) return 'Amazon';
+  if (n.includes('microsoft')) return 'Microsoft';
+  // AI
+  if (n.includes('anthropic')) return 'Anthropic';
+  if (n.includes('openai') || n === 'open ai') return 'OpenAI';
+  if (n.includes('deepmind')) return 'DeepMind';
+  if (n.includes('cohere')) return 'Cohere';
+  if (n.includes('mistral')) return 'Mistral';
+  if (n.includes('hugging') && n.includes('face')) return 'Hugging Face';
+  // Fintech / Crypto
+  if (n.includes('stripe')) return 'Stripe';
+  if (n.includes('coinbase')) return 'Coinbase';
+  if (n.includes('polymarket')) return 'Polymarket';
+  if (n.includes('blackrock')) return 'BlackRock';
+  if (n.includes('robinhood')) return 'Robinhood';
+  // Growth / Commerce
+  if (n.includes('whatnot')) return 'Whatnot';
+  if (n.includes('shopify')) return 'Shopify';
+  if (n.includes('palantir')) return 'Palantir';
+  if (n.includes('anduril')) return 'Anduril';
+  if (n.includes('netflix')) return 'Netflix';
+  if (n.includes('spotify')) return 'Spotify';
+  if (n.includes('tesla')) return 'Tesla';
+  if (n.includes('spacex')) return 'SpaceX';
+  if (n.includes('nvidia')) return 'NVIDIA';
+  // Defense / Aerospace
+  if (n.includes('lockheed')) return 'Lockheed Martin';
+  if (n.includes('northrop')) return 'Northrop Grumman';
+  if (n.includes('boeing')) return 'Boeing';
+  if (n.includes('l3harris') || n.includes('l3 harris')) return 'L3Harris';
+  if (n.includes('leidos')) return 'Leidos';
+  if (n.includes('nasa')) return 'NASA';
+  if (n.includes('sandia')) return 'Sandia National Labs';
+  if (n.includes('blue origin')) return 'Blue Origin';
+  if (n.includes('raytheon')) return 'Raytheon';
+  if (n.includes('general dynamics')) return 'General Dynamics';
+  if (n.includes('bae systems')) return 'BAE Systems';
+  // Finance
+  if (n.includes('goldman')) return 'Goldman Sachs';
+  if (n.includes('jpmorgan') || n.includes('jp morgan')) return 'JPMorgan Chase';
+  if (n.includes('wells fargo')) return 'Wells Fargo';
+  if (n.includes('citi') && !n.includes('citizen')) return 'Citi';
+  if (n.includes('mastercard')) return 'Mastercard';
+  if (n.includes('visa') && n.length < 15) return 'Visa';
+  if (n.includes('paypal')) return 'PayPal';
+  if (n.includes('bny') || n.includes('bank of new york') || n.includes('mellon')) return 'BNY Mellon';
+  if (n.includes('deloitte')) return 'Deloitte';
+  if (n.includes('bain')) return 'Bain & Company';
+  if (n.includes('bloomberg')) return 'Bloomberg';
+  if (n.includes('usaa')) return 'USAA';
+  if (n.includes('navy federal')) return 'Navy Federal';
+  if (n.includes('raymond james')) return 'Raymond James';
+  if (n.includes('geico')) return 'GEICO';
+  // Enterprise / Industrial
+  if (n.includes('oracle')) return 'Oracle';
+  if (n.includes('ibm')) return 'IBM';
+  if (n.includes('servicenow')) return 'ServiceNow';
+  if (n.includes('siemens')) return 'Siemens';
+  if (n.includes('texas instruments')) return 'Texas Instruments';
+  if (n.includes('qualcomm')) return 'Qualcomm';
+  if (n.includes('databricks')) return 'Databricks';
+  if (n.includes('together.ai') || n.includes('together ai')) return 'Together AI';
+  if (n.includes('zoox')) return 'Zoox';
+  // Entertainment
+  if (n.includes('nbcuniversal') || n.includes('nbc universal')) return 'NBCUniversal';
+  if (n.includes('universal destinations')) return 'Universal Destinations';
+  // Other
+  if (n.includes('humana')) return 'Humana';
+  if (n.includes('booz allen')) return 'Booz Allen Hamilton';
+  if (n.includes('abbott')) return 'Abbott';
+  if (n.includes('walmart')) return 'Walmart';
+  if (n.includes('publix')) return 'Publix';
+  if (n.includes('mitsubishi')) return 'Mitsubishi Power';
+  if (n.includes('oscar health')) return 'Oscar Health';
+  if (n.includes('ford') && n.length < 15) return 'Ford';
+  if (n.includes('coca') && n.includes('cola')) return 'Coca-Cola';
+  if (n.includes('nike')) return 'Nike';
+  if (n.includes('disney')) return 'Disney';
+  if (n.includes('ucf') || n.includes('university of central florida')) return 'UCF';
+  return (name || '').trim();
+}
+
+// Seniority for grouping and filters, read by lib/scoring.js so Paths and the
+// power score never disagree about someone's level (0 intern/student … 6 C-suite).
+export function getSeniority(headline) {
+  const t = readTitle(headline);
+  return { key: t.key, label: t.label, level: t.level };
+}
+
+/** The company someone works at now: a company scan's, else their current role's (lib/scoring.js). */
+export function companyOf(c) {
+  const co = currentCompany(c);
+  return co ? normalizeCompany(co) || co : null;
+}
+
+// Order matters: the first industry whose words match wins, checked against the
+// company name first (it is the stronger signal), then the headline.
+export const INDUSTRIES = [
+  { key: 'defense', label: 'Government, Defense & Aerospace', color: '#7f8c8d',
+    words: /\b(government|federal|state of|county|city of|defen[cs]e|army|navy|air force|marine corps|military|dod|nasa|aerospace|lockheed|northrop|boeing|raytheon|l3harris|leidos|anduril|sandia|blue origin|spacex|public sector)\b/i },
+  { key: 'finance', label: 'Finance, VC & Crypto', color: '#2ecc71',
+    words: /\b(bank|banking|capital|ventures?|vc|investments?|investor|fund|private equity|asset management|wealth|trading|trader|hedge|crypto|blockchain|web3|defi|fintech|stripe|coinbase|blackrock|robinhood|polymarket|goldman|morgan stanley|jpmorgan|chase|bny|mellon|wells fargo|citi|citigroup|capital one|fidelity|vanguard|schwab|visa|mastercard|amex|american express|paypal|insurance|accounting|cpa|financial)\b/i },
+  { key: 'health', label: 'Healthcare & Biotech', color: '#e74c3c',
+    words: /\b(health|healthcare|medical|medicine|hospital|clinic|pharma|pharmaceutical|biotech|nurse|nursing|physician|doctor|dental|therapy|therapist|wellness)\b/i },
+  { key: 'education', label: 'Education', color: '#f1c40f',
+    words: /\b(university|college|school|education|student|professor|teacher|academy|ucf|phd|faculty|alumni)\b/i },
+  { key: 'media', label: 'Marketing, Media & Creator', color: '#e67e22',
+    words: /\b(marketing|brand|branding|advertising|agency|media|content|social media|creative|creator|influencer|pr|public relations|communications|snap|snapchat|tiktok|pinterest|youtube|lens|ar|growth)\b/i },
+  { key: 'entertainment', label: 'Entertainment & Gaming', color: '#9b59b6',
+    words: /\b(entertainment|film|movie|music|records|gaming|games?|esports|studio|studios|netflix|disney|spotify|hollywood|theater|theatre|sports)\b/i },
+  { key: 'tech', label: 'Tech, Software & AI', color: '#3498db',
+    words: /\b(software|saas|engineer|engineering|developer|tech|technology|technologies|ai|artificial intelligence|machine learning|ml|data|cloud|cyber|security|devops|product manager|google|microsoft|apple|meta|amazon|nvidia|openai|anthropic|palantir|salesforce|oracle|ibm|intel|app|apps|startup|platform|labs?)\b/i },
+  { key: 'consulting', label: 'Consulting, Legal & Services', color: '#1abc9c',
+    words: /\b(consulting|consultant|consultancy|deloitte|accenture|mckinsey|kpmg|pwc|ey|bain|bcg|legal|law|lawyer|attorney|paralegal|recruiting|recruiter|staffing|talent)\b/i },
+  { key: 'realestate', label: 'Real Estate & Construction', color: '#d35400',
+    words: /\b(real estate|realtor|realty|property|properties|construction|architecture|architect|mortgage|homes|housing|builders?)\b/i },
+  { key: 'consumer', label: 'Retail, Consumer & Hospitality', color: '#ff79c6',
+    words: /\b(retail|e-?commerce|shopify|consumer|cpg|fashion|apparel|beauty|cosmetics|food|beverage|restaurant|hospitality|hotel|travel|tourism|coca-cola|nike|whatnot|store|shop)\b/i },
+  { key: 'industry', label: 'Manufacturing, Energy & Logistics', color: '#95a5a6',
+    words: /\b(manufacturing|energy|oil|gas|solar|utilities|automotive|tesla|siemens|ge|general electric|honeywell|3m|logistics|supply chain|shipping|freight|fedex|ups|industrial|mining|chemicals?)\b/i },
+  { key: 'nonprofit', label: 'Nonprofit & Community', color: '#bdc3c7',
+    words: /\b(nonprofit|non-profit|foundation|charity|ngo|church|ministry|volunteer)\b/i },
+];
+export const UNKNOWN_INDUSTRY = { key: 'unknown', label: 'Unclear', color: '#555c66' };
+const BY_KEY = Object.fromEntries([...INDUSTRIES, UNKNOWN_INDUSTRY].map((i) => [i.key, i]));
+export const industryByKey = (key) => BY_KEY[key] || UNKNOWN_INDUSTRY;
+
+/** The inferred industry for a company name, then a headline. */
+export function industryOf(company, headline) {
+  for (const text of [company, headline]) {
+    if (!text) continue;
+    const hit = INDUSTRIES.find((i) => i.words.test(text));
+    if (hit) return hit;
+  }
+  return UNKNOWN_INDUSTRY;
+}
+
+export const isSenior = (headline) => getSeniority(headline).level >= 4;
+
+/**
+ * Every company in the network with the people there.
+ * @returns Map name -> { name, industry, people, d1, d2, d3, S, A, senior }
+ * People are kept once (by profile URL), at their closest degree.
+ */
+export function buildCompanyIndex(rows = []) {
+  const best = new Map();
+  for (const r of rows) {
+    const key = r.profile_url || `id:${r.id}`;
+    const prev = best.get(key);
+    if (!prev || (r.degree || 9) < (prev.degree || 9)) best.set(key, r);
+  }
+  const index = new Map();
+  for (const r of best.values()) {
+    const name = companyOf(r);
+    if (!name) continue;
+    let co = index.get(name);
+    if (!co) {
+      co = { name, people: [], d1: 0, d2: 0, d3: 0, S: 0, A: 0, senior: 0, votes: {} };
+      index.set(name, co);
+    }
+    co.people.push(r);
+    if (r.degree === 1) co.d1++; else if (r.degree === 2) co.d2++; else co.d3++;
+    if (r.tier === 'S') co.S++;
+    if (r.tier === 'A') co.A++;
+    if (isSenior(r.headline)) co.senior++;
+    const ind = industryOf(name, r.headline).key;
+    co.votes[ind] = (co.votes[ind] || 0) + 1;
+  }
+  for (const co of index.values()) {
+    // The company name decides when it can; otherwise the most common headline industry.
+    const byName = industryOf(co.name, null);
+    if (byName !== UNKNOWN_INDUSTRY) co.industry = byName;
+    else {
+      const [top] = Object.entries(co.votes).filter(([k]) => k !== 'unknown').sort((a, b) => b[1] - a[1]);
+      co.industry = top ? industryByKey(top[0]) : UNKNOWN_INDUSTRY;
+    }
+    delete co.votes;
+  }
+  return index;
+}
+
+/**
+ * How companies connect through your people: one of your connections at A
+ * whose circle includes people at B is a way from A into B.
+ * @returns [{ a, b, weight, via: Set of bridge ids }] with a < b.
+ */
+export function companyLinks(degree1 = [], degree2 = []) {
+  const bridgeCompany = new Map();
+  for (const c of degree1) {
+    const co = companyOf(c);
+    if (co) bridgeCompany.set(c.id, co);
+  }
+  const links = new Map();
+  for (const r of degree2) {
+    const a = bridgeCompany.get(r.source_connection_id);
+    const b = companyOf(r);
+    if (!a || !b || a === b) continue;
+    const [x, y] = a < b ? [a, b] : [b, a];
+    const k = `${x}\u0000${y}`;
+    let l = links.get(k);
+    if (!l) { l = { a: x, b: y, weight: 0, via: new Set() }; links.set(k, l); }
+    l.weight++;
+    l.via.add(r.source_connection_id);
+  }
+  return [...links.values()];
+}
+
+/** Who can get you into a company: direct connections there, then bridges who know people there. */
+export function waysInto(company, degree1 = [], degree2 = []) {
+  const direct = degree1.filter((c) => companyOf(c) === company);
+  const counts = new Map();
+  for (const r of degree2) {
+    if (companyOf(r) !== company) continue;
+    counts.set(r.source_connection_id, (counts.get(r.source_connection_id) || 0) + 1);
+  }
+  const byId = new Map(degree1.map((c) => [c.id, c]));
+  const bridges = [...counts.entries()]
+    .map(([id, n]) => ({ bridge: byId.get(id), n }))
+    .filter((b) => b.bridge)
+    .sort((x, y) => y.n - x.n || (Number(y.bridge.power_score) || 0) - (Number(x.bridge.power_score) || 0));
+  return { direct, bridges };
+}

package/lib/csv.js

@@ -0,0 +1,172 @@
+import { scorePerson } from './scoring.js';
+// LinkedIn Connections.csv import — parsed ENTIRELY in the browser.
+//
+// Nothing is uploaded and nothing is written to the database: an imported
+// network lives in sessionStorage and disappears when the tab closes. That
+// keeps other people's connection lists off this deployment's Supabase.
+//
+// The official export carries six usable columns — First Name, Last Name,
+// URL, Company, Position, Connected On. It has NO profile photos and no rich
+// headline, so imported people render as tier-colored initials and scores come
+// from role + company only. The Email Address column is deliberately never read.
+
+const STORAGE_KEY = 'six-degrees-csv-network';
+
+// ── CSV parsing ────────────────────────────────────────────────────────────
+// Hand-rolled so the import needs no dependencies. Handles quoted fields,
+// escaped quotes ("") and both CRLF and LF line endings.
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++; }
+        else inQuotes = false;
+      } else field += ch;
+      continue;
+    }
+    if (ch === '"') { inQuotes = true; continue; }
+    if (ch === ',') { row.push(field); field = ''; continue; }
+    if (ch === '\r') continue;
+    if (ch === '\n') { row.push(field); rows.push(row); row = []; field = ''; continue; }
+    field += ch;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+export class ConnectionsCsvError extends Error {}
+
+// ── Scoring: the same model as everything else (lib/scoring.js), from the
+// export's bare position and company, so there is no reach bonus to find. ──
+export function scoreRecord(headline, company) {
+  const s = scorePerson({ headline, company });
+  return { seniority_score: s.title.points, company_prestige_score: s.companyScore, power_score: s.power, tier: s.tier };
+}
+
+// Stable id from the profile URL so re-importing keeps node identity.
+function hashId(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) h = ((h << 5) + h + input.charCodeAt(i)) | 0;
+  return `csv-${Math.abs(h).toString(36)}`;
+}
+
+// ── The importer ───────────────────────────────────────────────────────────
+export function parseConnectionsCsv(text) {
+  const rows = parseCsv(text);
+
+  // LinkedIn prefixes the file with a "Notes:" preamble of varying length, so
+  // find the header row by content rather than assuming a line number.
+  const headerIndex = rows.findIndex((r) => {
+    const cells = r.map((c) => c.trim().toLowerCase());
+    return cells.includes('first name') && cells.includes('last name');
+  });
+  if (headerIndex === -1) {
+    throw new ConnectionsCsvError(
+      'Could not find the Connections.csv header row (expected columns like "First Name, Last Name, URL, Company, Position"). Make sure this is the Connections.csv from your LinkedIn data export.'
+    );
+  }
+
+  const header = rows[headerIndex].map((c) => c.trim().toLowerCase());
+  const col = (name) => header.indexOf(name);
+  const iFirst = col('first name'), iLast = col('last name'), iUrl = col('url');
+  const iCompany = col('company'), iPosition = col('position'), iConnected = col('connected on');
+
+  const connections = [];
+  const seen = new Set();
+  let skipped = 0;
+
+  for (const r of rows.slice(headerIndex + 1)) {
+    const cell = (i) => (i >= 0 && r[i] != null ? String(r[i]).trim() : '');
+    const name = `${cell(iFirst)} ${cell(iLast)}`.trim();
+    if (!name) { skipped++; continue; }
+
+    const company = cell(iCompany);
+    const role = cell(iPosition);
+    const profileUrl = cell(iUrl);
+
+    // /paths and the sidebar read seniority off `headline`, not `role`, so
+    // rebuild the "Role at Company" shape the scraper would have produced.
+    const headline = role && company ? `${role} at ${company}` : role || company || name;
+
+    const id = profileUrl ? hashId(profileUrl) : `csv-row-${connections.length}`;
+    if (seen.has(id)) { skipped++; continue; }
+    seen.add(id);
+
+    let connected_date = null;
+    const raw = cell(iConnected);
+    if (raw) {
+      const d = new Date(raw);
+      if (!isNaN(d.getTime())) connected_date = d.toISOString().split('T')[0];
+    }
+
+    connections.push({
+      id,
+      degree: 1,
+      name,
+      headline,
+      role,
+      company,
+      profile_url: profileUrl || null,
+      profile_image_url: null,   // the official export carries no photos
+      connected_date,
+      source_connection_id: null,
+      is_catalyst: false,
+      catalyst_score: null,
+      circle_power: null,
+      circle_s_count: null,
+      circle_a_count: null,
+      circle_elite_pct: null,
+      outreach_status: null,
+      unlock_status: null,
+      ...scoreRecord(headline, company),
+    });
+  }
+
+  if (!connections.length) {
+    throw new ConnectionsCsvError(
+      'That file parsed, but no connections were found in it. Double-check that it is Connections.csv from your LinkedIn data export.'
+    );
+  }
+
+  connections.sort((a, b) => b.power_score - a.power_score);
+  return { connections, skipped, total: connections.length + skipped };
+}
+
+// ── Session-scoped storage (never the database) ────────────────────────────
+export function saveSessionNetwork({ degree1 = [], degree2 = [], source = 'csv' }) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ degree1, degree2, source, importedAt: Date.now() }));
+    return true;
+  } catch {
+    return false; // quota — very large networks
+  }
+}
+
+export function saveCsvNetwork(connections) {
+  return saveSessionNetwork({ degree1: connections, degree2: [], source: 'csv' });
+}
+
+export function hasCsvNetwork() {
+  try { return !!sessionStorage.getItem(STORAGE_KEY); } catch { return false; }
+}
+
+export function loadCsvNetwork() {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    return { degree1: parsed.degree1 || [], degree2: parsed.degree2 || [], source: parsed.source || 'csv' };
+  } catch { return null; }
+}
+
+export function clearCsvNetwork() {
+  try { sessionStorage.removeItem(STORAGE_KEY); } catch {}
+}
+
+export const CSV_USER = { id: 'csv-local-user', name: 'You' };

package/lib/db-client.js

@@ -0,0 +1,152 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, existsSync, readFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { SCHEMA_SQL } from '../db/schema.js';
+import { APP_VERSION } from './app-version.js';
+
+// The database lives OUTSIDE the app directory so an installed copy never
+// writes into its own package. Override with SIX_DEGREES_HOME.
+export function dataDir() {
+  const dir = process.env.SIX_DEGREES_HOME || path.join(homedir(), '.six-degrees');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// Columns that are stored as JSON text and handed back to callers as objects
+// or arrays, matching what the Postgres jsonb/text[] columns used to return.
+export const JSON_COLUMNS = {
+  users: ['sectors', 'goals', 'company_prestige_config'],
+  user_profile: ['sectors', 'goals', 'company_prestige_config'],
+  linkedin_connections: ['influence_signals'],
+  notifications: ['data'],
+  queue_items: [],
+  user_stats: [],
+};
+
+// Columns SQLite stores as 0/1 but callers expect as true/false.
+export const BOOLEAN_COLUMNS = {
+  linkedin_connections: ['is_catalyst'],
+  notifications: ['seen'],
+  users: [],
+  user_profile: [],
+  queue_items: [],
+  user_stats: [],
+};
+
+let _db = null;
+
+export function getDb() {
+  if (_db) return _db;
+
+  const file = process.env.SIX_DEGREES_DB || path.join(dataDir(), 'six-degrees.sqlite');
+  _db = new DatabaseSync(file);
+
+  // Before this version changes anything: if a different version opened this
+  // data last, keep a copy of it as it was. See backupOnNewVersion().
+  try {
+    const saved = backupOnNewVersion(_db, { dir: path.dirname(file), version: APP_VERSION });
+    if (saved) console.log(`Six Degrees ${APP_VERSION}: backed up your data first → ${saved}`);
+  } catch (err) {
+    console.error(`Six Degrees: could not back up your data before ${APP_VERSION} (will try again next start): ${err.message}`);
+  }
+
+  // Idempotent: every statement is CREATE ... IF NOT EXISTS, so this doubles
+  // as first-run setup and as a no-op on every later boot.
+  _db.exec(SCHEMA_SQL);
+  addMissingColumns(_db);
+
+  return _db;
+}
+
+// CREATE TABLE IF NOT EXISTS never adds a column to a table that already
+// exists, so columns added after first release are added here, once.
+const ADDED_COLUMNS = [
+  ['linkedin_connections', 'score_why', 'TEXT'],
+];
+
+function addMissingColumns(db) {
+  for (const [table, column, type] of ADDED_COLUMNS) {
+    const has = db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+    if (!has) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+  }
+}
+
+// ── a copy of the data before each new version touches it ──────────────────
+// The first time a version opens a database that a different version (or one
+// from before this existed) used last, it copies the database, as it was, into
+// backups/ — before the schema step or anything else writes to it. VACUUM INTO
+// makes one consistent file even mid-WAL. The newest five automatic copies are
+// kept; anything else in backups/ (copies made by hand) is never touched. The
+// marker is written only after the copy succeeds, so a failed copy (a full
+// disk) is retried at the next start.
+
+export const AUTO_BACKUP_PREFIX = 'auto-before-';
+
+export function backupOnNewVersion(db, { dir, version, keep = 5, now = new Date() }) {
+  const marker = path.join(dir, 'app-version');
+  let last = null;
+  try { last = readFileSync(marker, 'utf8').trim(); } catch { /* first run, or older than this */ }
+  if (last === version) return null;
+
+  let saved = null;
+  const hasData = db.prepare(
+    "SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'linkedin_connections'"
+  ).get().n > 0;
+  if (hasData) {
+    const folder = path.join(dir, 'backups');
+    mkdirSync(folder, { recursive: true });
+    const stamp = now.toISOString().replace(/[:.]/g, '-');
+    saved = path.join(folder, `${AUTO_BACKUP_PREFIX}${version}-${stamp}.sqlite`);
+    db.exec(`VACUUM INTO '${saved.replace(/'/g, "''")}'`);
+
+    const autos = readdirSync(folder)
+      .filter((f) => f.startsWith(AUTO_BACKUP_PREFIX) && f.endsWith('.sqlite'))
+      .map((f) => ({ f, at: statSync(path.join(folder, f)).mtimeMs }))
+      .sort((a, b) => b.at - a.at || b.f.localeCompare(a.f));
+    for (const { f } of autos.slice(keep)) rmSync(path.join(folder, f), { force: true });
+  }
+  writeFileSync(marker, `${version}\n`);
+  return saved;
+}
+
+// Exposed for tests, which need a fresh in-memory database per case.
+export function _setDbForTesting(db) {
+  _db = db;
+}
+
+export function newId() {
+  return crypto.randomUUID();
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+// ── row codecs ─────────────────────────────────────────────────────────────
+export function decodeRow(table, row) {
+  if (!row) return row;
+  const out = { ...row };
+  for (const col of JSON_COLUMNS[table] || []) {
+    if (typeof out[col] === 'string') {
+      try { out[col] = JSON.parse(out[col]); } catch { /* leave as-is */ }
+    }
+  }
+  for (const col of BOOLEAN_COLUMNS[table] || []) {
+    if (out[col] === 0 || out[col] === 1) out[col] = Boolean(out[col]);
+  }
+  return out;
+}
+
+export function encodeValue(table, col, value) {
+  if (value === undefined) return null;
+  if ((JSON_COLUMNS[table] || []).includes(col)) {
+    return value === null ? null : JSON.stringify(value);
+  }
+  if ((BOOLEAN_COLUMNS[table] || []).includes(col)) {
+    return value === null ? null : value ? 1 : 0;
+  }
+  if (typeof value === 'boolean') return value ? 1 : 0;
+  if (value !== null && typeof value === 'object') return JSON.stringify(value);
+  return value;
+}