six-degrees 0.2.0

package/lib/paused.js

@@ -0,0 +1,75 @@
+// Who has a list that was only partly read — the Scan page's Paused list.
+//
+// This must agree with the scanner's own queue (scripts/scrape.py,
+// next_page_to_read and auto_bridge_all), or "Resume all" would read people the
+// list doesn't show and skip people it does. The rules, mirrored:
+//   - someone is mapped once they have a circle saved or a progress note;
+//   - no note means they were mapped before 0.1.6, at 10 pages: carry on at 11;
+//   - "hidden" and "no more pages" are not paused; neither is page 100.
+// tests/paused.test.mjs pins them.
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const LEGACY_PAGES_READ = 10;
+export const LINKEDIN_MAX_PAGES = 100;
+
+/** The scanner's next_page_to_read, in JS. null = nothing left. */
+export function nextPageToRead(entry) {
+  if (!entry) return LEGACY_PAGES_READ + 1;
+  if (entry.hidden || !entry.more) return null;
+  const next = (Number(entry.pages) || 0) + 1;
+  return next <= LINKEDIN_MAX_PAGES ? next : null;
+}
+
+/** This profile's progress notes, keyed by profile URL. */
+export function readProgress(dir, userId) {
+  try {
+    const all = JSON.parse(readFileSync(path.join(dir, 'bridge-progress.json'), 'utf8'));
+    const mine = all?.[String(userId || 'default')];
+    return mine && typeof mine === 'object' ? mine : {};
+  } catch {
+    return {};
+  }
+}
+
+export function readUnclear(dir) {
+  try { return JSON.parse(readFileSync(path.join(dir, 'bridge-unclear.json'), 'utf8')) || {}; } catch { return {}; }
+}
+
+/**
+ * @param {object[]} firstDegree  { id, name, tier, profile_url, connected_date, created_at }
+ * @param {Set<string>} mappedIds ids of 1st-degree people with a saved circle
+ * @param {object} progress       readProgress()
+ * @param {object} unclear        readUnclear()
+ * @returns people newest-connected first, each with pagesRead, nextPage, legacy, at, unclear
+ */
+export function pausedList(firstDegree, mappedIds, progress = {}, unclear = {}) {
+  const out = [];
+  for (const c of firstDegree) {
+    const url = c.profile_url;
+    const entry = url ? progress[url] : undefined;
+    if (!mappedIds.has(c.id) && !entry) continue;         // not mapped yet: not paused
+    const nextPage = nextPageToRead(entry);
+    if (nextPage == null) continue;
+    out.push({
+      id: c.id,
+      name: c.name,
+      tier: c.tier,
+      profileUrl: url,
+      pagesRead: nextPage - 1,
+      nextPage,
+      legacy: !entry,
+      at: entry?.at || null,
+      unclear: Number(unclear?.[url]?.n) || 0,
+      connected: c.connected_date || null,
+      created: c.created_at || null,
+    });
+  }
+  // The scanner's order: dated people newest first, then the undated by when
+  // they were saved; anyone unclear twice goes to the back. So the first people
+  // shown are the first "Resume all" reads.
+  const key = (x) => `${x.connected ? 1 : 0}|${x.connected || x.created || ''}`;
+  out.sort((a, b) => (a.unclear >= 2) - (b.unclear >= 2) || key(b).localeCompare(key(a)));
+  return out;
+}

package/lib/profile.js

@@ -0,0 +1,55 @@
+import { getDb, newId, decodeRow } from './db-client.js';
+
+// Which profile is "you" on this machine.
+//
+// This is a one-person app with one database file. It used to ask for a name on
+// any browser it had not seen before, and every answer that did not exactly
+// match an existing name made a new, empty profile. The next browser then found
+// several profiles, could not tell which was real, and asked again — while the
+// whole network sat under the first one. The scraper hit the same ambiguity and
+// refused to run, with a reason nobody saw.
+//
+// So the answer is decided here, once, from the data: the profile that owns the
+// most connections, the oldest on a tie. Empty duplicates can never win against
+// a real network. On a machine with no profile at all, one is made, because a
+// first run should open on a welcome screen, not a form.
+
+export const DEFAULT_NAME = 'You';
+
+/** Every profile, busiest first, with its connection count attached. */
+export function listProfiles() {
+  const rows = getDb().prepare(`
+    SELECT u.*,
+           (SELECT COUNT(*) FROM linkedin_connections c WHERE c.user_id = u.id) AS connections
+    FROM users u
+    ORDER BY connections DESC, u.created_at ASC, u.rowid ASC
+  `).all();
+  return rows.map((r) => decodeRow('users', r));
+}
+
+/**
+ * A profile's network by degree: the people you know (first), the people found
+ * through them (second), and people found by scanning a company (third). Kept
+ * apart because one total reads as "connections" and is not.
+ */
+export function networkCounts(userId) {
+  const rows = getDb().prepare(
+    'SELECT degree, COUNT(*) AS n FROM linkedin_connections WHERE user_id = ? GROUP BY degree',
+  ).all(userId);
+  const by = Object.fromEntries(rows.map((r) => [r.degree, r.n]));
+  return { first: by[1] || 0, second: by[2] || 0, third: by[3] || 0 };
+}
+
+/**
+ * The profile this machine uses. Creates one when there is none, unless
+ * `create` is false, in which case it returns null.
+ */
+export function resolveProfile({ create = true } = {}) {
+  const [top] = listProfiles();
+  if (top) return top;
+  if (!create) return null;
+
+  const id = newId();
+  getDb().prepare('INSERT INTO users (id, name) VALUES (?, ?)').run(id, DEFAULT_NAME);
+  return { ...decodeRow('users', getDb().prepare('SELECT * FROM users WHERE id = ?').get(id)), connections: 0 };
+}

package/lib/promote.js

@@ -0,0 +1,139 @@
+// Turning a 2nd-degree contact into a 1st-degree one, without losing the path.
+//
+// The whole point of this tool is that someone was reachable *through* a
+// particular person. When you finally connect with them, that fact should not
+// evaporate — you should still be able to see that Jane is why you know them.
+//
+// Two things get conflated easily and must not be:
+//
+//   source_connection_id     whose circle they currently sit in. A direct
+//                            connection sits in nobody's circle, so this is
+//                            cleared on promotion.
+//   unlocked_from_bridge_id  who introduced them. Permanent. Survives
+//                            promotion, re-scrapes, and their own later
+//                            promotion to a bridge with a circle of their own.
+//
+// Before this existed, a 2nd-degree person who became a connection was dropped
+// on the floor: the ingest route counted "any row with this profile_url" as
+// already handled, then updated rows matching `degree = 1` — of which there
+// were none. They stayed 2nd-degree forever and the path was never marked.
+
+/**
+ * Promote one person to 1st degree, keeping their origin.
+ * Safe to call repeatedly; a person already at 1st degree keeps their origin.
+ */
+export async function promoteToFirstDegree(db, { profileUrl, userId, fields = {} }) {
+  if (!profileUrl) return { promoted: false, reason: 'no profile url' };
+  // Without the profile, rows of every profile in the app would be folded
+  // together — and deleted. Nothing is safe to do.
+  if (!userId) return { promoted: false, reason: 'no profile' };
+
+  let q = db.from('linkedin_connections').select('*').eq('profile_url', profileUrl);
+  if (userId) q = q.eq('user_id', userId);
+  const { data } = await q;
+  const rows = data || [];
+  if (rows.length === 0) return { promoted: false, reason: 'not on file' };
+
+  // Already a direct connection: keep the row they have, and add no origin.
+  //
+  // This used to prefer the 2nd-degree copy (the "deepest" row) and delete the
+  // rest — including the person's own 1st-degree row. Other rows point at that
+  // row's id: above all, everyone in their own mapped circle. On 2026-09-24 a
+  // full scan did this to 13 people whose circles had been mapped, and 1,072
+  // people in those circles were left pointing at rows that no longer existed.
+  // It also gave 150 long-standing connections a "you met them through" origin
+  // they never had: they were connections before they turned up in anyone's
+  // circle. TRAPS §36.
+  const direct = rows.filter((r) => r.degree === 1);
+  if (direct.length > 0) {
+    const keep = await mostReferenced(db, direct);
+    // Only this person's copies in the same profile; never another profile's rows.
+    const fold = rows.filter((r) => r.id !== keep.id && r.user_id === keep.user_id);
+    for (const row of fold) {
+      // Only delete a row once nothing points at it any more.
+      if (await repoint(db, row.id, keep.id)) {
+        await db.from('linkedin_connections').delete().eq('id', row.id);
+      }
+    }
+    if (Object.keys(fields).length) {
+      await db.from('linkedin_connections').update({ ...fields, updated_at: new Date().toISOString() }).eq('id', keep.id);
+    }
+    return { promoted: false, reason: 'already a direct connection', id: keep.id, folded: fold.length };
+  }
+
+  // Prefer a row that already carries an origin, then the deepest one — that is
+  // where the provenance lives.
+  const source = rows.find((r) => r.unlocked_from_bridge_id)
+    || rows.slice().sort((a, b) => (b.degree || 0) - (a.degree || 0))[0];
+
+  const originId = source.unlocked_from_bridge_id || source.source_connection_id || null;
+  let originName = source.unlocked_from_name || null;
+
+  if (originId && !originName) {
+    const { data: bridge } = await db
+      .from('linkedin_connections').select('name').eq('id', originId).limit(1);
+    originName = bridge?.[0]?.name || null;
+  }
+
+  const updates = {
+    degree: 1,
+    source_connection_id: null,        // a direct connection is in nobody's circle
+    unlock_status: originId ? 'unlocked' : source.unlock_status,
+    unlocked_from_bridge_id: originId,
+    unlocked_from_name: originName,
+    updated_at: new Date().toISOString(),
+    ...fields,
+  };
+
+  // If the same person somehow exists more than once, keep the one carrying the
+  // origin and fold the rest away rather than leaving duplicates behind —
+  // pointing anything that referred to a folded row at the one kept.
+  const fold = rows.filter((r) => r.id !== source.id);
+  for (const row of fold) {
+    if (await repoint(db, row.id, source.id)) {
+      await db.from('linkedin_connections').delete().eq('id', row.id);
+    }
+  }
+
+  await db.from('linkedin_connections').update(updates).eq('id', source.id);
+  return { promoted: true, id: source.id, originId, originName };
+}
+
+/** Of several rows for one person, the one other rows point at most. */
+async function mostReferenced(db, rows) {
+  if (rows.length === 1) return rows[0];
+  let best = rows[0];
+  let bestCount = -1;
+  for (const row of rows) {
+    const { data } = await db.from('linkedin_connections').select('id').eq('source_connection_id', row.id);
+    const n = (data || []).length;
+    if (n > bestCount) { best = row; bestCount = n; }
+  }
+  return best;
+}
+
+/**
+ * Point everything that referred to row `fromId` at `toId`. True only if all
+ * of it moved — the caller deletes `fromId` only then, so a failure can never
+ * leave rows pointing at nothing (TRAPS §36).
+ *
+ * Someone can sit in both circles; the index allows them once per bridge, so
+ * a copy already under `toId` is the one kept and the other is dropped.
+ */
+async function repoint(db, fromId, toId) {
+  const { data: members, error: readErr } = await db
+    .from('linkedin_connections').select('id, profile_url, user_id').eq('source_connection_id', fromId);
+  if (readErr) return false;
+  for (const m of members || []) {
+    const { data: twin } = await db.from('linkedin_connections').select('id')
+      .eq('source_connection_id', toId).eq('profile_url', m.profile_url).eq('user_id', m.user_id);
+    const { error } = (twin || []).length
+      ? await db.from('linkedin_connections').delete().eq('id', m.id)
+      : await db.from('linkedin_connections').update({ source_connection_id: toId }).eq('id', m.id);
+    if (error) return false;
+  }
+  const { error } = await db.from('linkedin_connections')
+    .update({ unlocked_from_bridge_id: toId }).eq('unlocked_from_bridge_id', fromId);
+  return !error;
+}
+

package/lib/quest.js

@@ -0,0 +1,119 @@
+// Outlink as a game: every mapped connection's circle is a cluster to work
+// through, a few people at a time.
+//
+// A long ranked list of strangers is daunting, and nothing in it says you're
+// getting anywhere. Here each cluster offers its best few people (a "stage");
+// send invites to them and the ring fills, the stage clears, and the next few
+// appear. Someone who accepts becomes your connection — and their circle is the
+// next degree to map. Points come only from real events (invites you marked
+// sent, people who actually joined your network), never from browsing.
+// Plain functions; tests/quest.test.mjs.
+
+export const STAGE_SIZE = 5;
+export const XP_SEND = { S: 25, A: 15, B: 10, C: 5, D: 2 };
+export const XP_ADDED = { S: 100, A: 60, B: 35, C: 15, D: 5 };
+
+/** Level from points: each level needs a little more than the last. */
+export function levelFor(points) {
+  const level = Math.floor(Math.sqrt(Math.max(0, points) / 40)) + 1;
+  const floor = (level - 1) ** 2 * 40;
+  const next = level ** 2 * 40;
+  return { level, floor, next, progress: (points - floor) / (next - floor) };
+}
+
+/**
+ * @param recs    2nd-degree people worth adding: { id, profile_url, tier, priority, bridge }
+ * @param sentIds ids marked "invite sent"
+ * @param added   1st-degree people who came through a cluster (unlocked_from_bridge_id set)
+ * @param mappedIds ids of 1st-degree people whose own circle is mapped
+ */
+export function buildQuest({ recs = [], sentIds = new Set(), added = [], mappedIds = new Set() }) {
+  const byBridge = new Map();
+  const seen = new Set();
+  for (const r of [...recs].sort((a, b) => (b.priority || 0) - (a.priority || 0))) {
+    if (!r.bridge) continue;
+    const k = `${r.bridge.id}|${r.profile_url || r.id}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    let c = byBridge.get(r.bridge.id);
+    if (!c) { c = { bridge: r.bridge, people: [] }; byBridge.set(r.bridge.id, c); }
+    c.people.push(r);
+  }
+  const addedBy = new Map();
+  for (const a of added) {
+    const id = a.unlocked_from_bridge_id;
+    if (!id) continue;
+    addedBy.set(id, [...(addedBy.get(id) || []), a]);
+  }
+
+  const clusters = [];
+  let points = 0;
+  let sentTotal = 0;
+  for (const { bridge, people } of byBridge.values()) {
+    const sent = people.filter((p) => sentIds.has(p.id));
+    const addedHere = addedBy.get(bridge.id) || [];
+    sentTotal += sent.length;
+    points += sent.reduce((s, p) => s + (XP_SEND[p.tier] || 2), 0);
+    points += addedHere.reduce((s, p) => s + (XP_ADDED[p.tier] || 5), 0);
+
+    // Stages are the cluster's people in priority order, STAGE_SIZE at a time.
+    // The current stage is the first one not fully sent.
+    const stages = Math.ceil(people.length / STAGE_SIZE) || 1;
+    let stage = 0;
+    while (stage < stages - 1 && people.slice(stage * STAGE_SIZE, (stage + 1) * STAGE_SIZE).every((p) => sentIds.has(p.id))) stage++;
+    const targets = people.slice(stage * STAGE_SIZE, (stage + 1) * STAGE_SIZE);
+    const done = targets.filter((p) => sentIds.has(p.id)).length;
+    const complete = done === targets.length && stage === stages - 1;
+    clusters.push({
+      bridge,
+      people,
+      stage: stage + 1,
+      stages,
+      targets,
+      done,
+      progress: targets.length ? done / targets.length : 1,
+      complete,
+      sent: sent.length,
+      added: addedHere,
+      value: targets.filter((p) => !sentIds.has(p.id)).reduce((s, p) => s + (p.priority || 0), 0),
+      open: { S: targets.filter((p) => p.tier === 'S' && !sentIds.has(p.id)).length, A: targets.filter((p) => p.tier === 'A' && !sentIds.has(p.id)).length },
+    });
+  }
+
+  // In progress first (closest to clearing), then untouched by value; finished last.
+  clusters.sort((a, b) =>
+    (a.complete - b.complete)
+    || ((b.progress > 0 && b.progress < 1) - (a.progress > 0 && a.progress < 1))
+    || (b.progress - a.progress)
+    || (b.value - a.value));
+
+  // The next best moves: the most valuable open people, nudged towards clusters
+  // you've started, so finishing a stage is always within reach.
+  const moves = clusters.filter((c) => !c.complete).flatMap((c) =>
+    c.targets.filter((p) => !sentIds.has(p.id)).map((p) => ({
+      person: p, cluster: c, score: (p.priority || 0) * (1 + 0.6 * c.progress),
+    })))
+    .sort((a, b) => b.score - a.score);
+  const seenPeople = new Set();
+  const nextMoves = [];
+  for (const m of moves) {
+    const k = m.person.profile_url || m.person.id;
+    if (seenPeople.has(k)) continue;
+    seenPeople.add(k);
+    nextMoves.push(m);
+    if (nextMoves.length === 3) break;
+  }
+
+  const addedTotal = added.filter((a) => a.unlocked_from_bridge_id).length;
+  return {
+    clusters,
+    nextMoves,
+    points,
+    level: levelFor(points),
+    sentTotal,
+    addedTotal,
+    // People you've added whose own circle isn't mapped yet: the next degree.
+    newDoors: added.filter((a) => a.unlocked_from_bridge_id && !mappedIds.has(a.id)),
+    clearedStages: clusters.reduce((s, c) => s + (c.stage - 1) + (c.complete ? 1 : 0), 0),
+  };
+}

package/lib/release.js

@@ -0,0 +1,50 @@
+// Facts about the installed copy, for the Updates panel.
+//
+// A git checkout updates with `git pull` (app/api/update/route.js). Everything
+// else was installed — the Mac app (install.sh or the .dmg) or the npm package
+// (`npx six-degrees@latest`) — and updates by installing the newer release over
+// the top. This works out which one this is, and how to tell the two versions
+// apart.
+
+/** "git+https://github.com/owner/repo.git" → "owner/repo". */
+export function repoSlug(repository) {
+  const url = typeof repository === 'string' ? repository : repository?.url || '';
+  const m = url.match(/github\.com[/:]([^/]+)\/([^/.#?]+)/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** Numeric compare of dotted versions. "v0.10.0" > "0.9.3". Pre-release tags are ignored. */
+export function compareVersions(a, b) {
+  const parts = (v) => String(v || '').replace(/^v/i, '').split(/[-+]/)[0]
+    .split('.').map((n) => Number.parseInt(n, 10) || 0);
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * 'mac-app', 'source' (a git checkout run with `npm run start:packaged`) or
+ * 'npm'. The launchers say which (SIX_DEGREES_INSTALL); an older Mac app that
+ * predates that is recognised by where it is running from.
+ */
+export function installKind(env = process.env, root = '') {
+  if (['mac-app', 'source', 'npm'].includes(env.SIX_DEGREES_INSTALL)) {
+    return env.SIX_DEGREES_INSTALL;
+  }
+  return /\.app\/Contents\/Resources/.test(root || '') ? 'mac-app' : 'npm';
+}
+
+/** What to run to update, for each way of installing. */
+export function updateCommand(kind, slug) {
+  if (kind === 'mac-app') {
+    return `curl -fsSL https://raw.githubusercontent.com/${slug}/main/install.sh | bash`;
+  }
+  if (kind === 'source') {
+    return 'git pull && npm ci && npm run build && npm run start:packaged';
+  }
+  return 'npx six-degrees@latest';
+}

package/lib/rpc.js

@@ -0,0 +1,80 @@
+import { getDb, nowIso } from './db-client.js';
+
+// Replacements for the stored procedures the hosted database used to provide.
+// Scoring lives in lib/scoring.js; this file only reads rows and writes the
+// results back. (scripts/*.sql are the retired hosted-era model.)
+
+import { scoreNetwork, explainScore, SCORING_VERSION } from './scoring.js';
+import { industryOf } from './companies.js';
+
+export function companyOverrides(db = getDb()) {
+  return new Map(db.prepare('SELECT name, score FROM company_scores').all().map((r) => [r.name, r.score]));
+}
+
+/**
+ * Rescore everyone. The score depends on the whole network (how many of your
+ * people work at a company, how strong a bridge's circle is), so after any
+ * ingest or company-score change every row is recomputed — ~0.1s for 4,000.
+ */
+export function rescoreAll() {
+  const db = getDb();
+  const rows = db.prepare('SELECT id, degree, headline, role, company, scanned_company, profile_url, source_connection_id FROM linkedin_connections').all();
+  const { scores } = scoreNetwork(rows, { overrides: companyOverrides(db), industryOf: (c, h) => industryOf(c, h).key });
+  const update = db.prepare(`UPDATE linkedin_connections SET seniority_score = ?, company_prestige_score = ?, power_score = ?, tier = ?,
+    score_why = ?, circle_power = ?, circle_s_count = ?, circle_a_count = ?, circle_elite_pct = ?, is_catalyst = ?, catalyst_score = ?, updated_at = ?
+    WHERE id = ?`);
+  const now = nowIso();
+  db.exec('BEGIN');
+  try {
+    for (const r of rows) {
+      const s = scores.get(r.id);
+      const c = s.circle;
+      update.run(s.title.points, s.companyScore, s.power, s.tier, explainScore(s, s.boost),
+        c ? Math.round(c.circlePower * 100) / 100 : 0, c?.sCount || 0, c?.aCount || 0, c ? Math.round(c.elitePct * 100) / 100 : 0,
+        c?.isCatalyst ? 1 : 0, c?.isCatalyst ? c.sCount + c.aCount : 0, now, r.id);
+    }
+    db.prepare('INSERT INTO app_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run('scoring_version', String(SCORING_VERSION));
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+  return { scored: rows.length };
+}
+
+/** Rescore once if the stored scores came from an older scoring model. */
+export function rescoreIfStale() {
+  const db = getDb();
+  const v = db.prepare("SELECT value FROM app_meta WHERE key = 'scoring_version'").get()?.value;
+  return v === String(SCORING_VERSION) ? { scored: 0 } : rescoreAll();
+}
+
+function incrementXp({ amount = 0 } = {}) {
+  const db = getDb();
+  const stats = db.prepare('SELECT id, xp FROM user_stats LIMIT 1').get();
+  if (!stats) {
+    const id = crypto.randomUUID();
+    db.prepare('INSERT INTO user_stats (id, xp) VALUES (?, ?)').run(id, amount);
+    return { xp: amount };
+  }
+  const xp = (stats.xp || 0) + amount;
+  db.prepare('UPDATE user_stats SET xp = ?, last_active_at = ? WHERE id = ?').run(xp, nowIso(), stats.id);
+  return { xp };
+}
+
+export async function runRpc(name, args = {}) {
+  try {
+    // The name is the hosted-era one; it now rescores everyone (see rescoreAll).
+    if (name === 'score_new_connections' || name === 'rescore_all') return { data: rescoreAll(), error: null };
+    if (name === 'rescore_if_stale') return { data: rescoreIfStale(), error: null };
+    if (name === 'increment_xp') return { data: incrementXp(args), error: null };
+    if (name === 'exec_sql') {
+      // Intentionally unsupported. The hosted build exposed arbitrary DDL over
+      // an unauthenticated HTTP route; there is no local equivalent worth having.
+      return { data: null, error: { message: 'exec_sql is not supported in the local build' } };
+    }
+    return { data: null, error: { message: `Unknown function: ${name}` } };
+  } catch (err) {
+    return { data: null, error: { message: err.message } };
+  }
+}

package/lib/scan-progress.js

@@ -0,0 +1,63 @@
+// How far a running scan has got, read from the lines it prints, so the Scan
+// page can draw a bar instead of asking someone to read a log.
+//
+// Both formats come from scripts/scrape.py — keep these patterns in step with it.
+// If its wording changes, this returns null and the bar simply disappears; it
+// never shows a wrong number.
+//
+//   1st degree:  "  LinkedIn reports 817 connections"
+//                "  350 / 817 collected"            (every fifty people)
+//                "  Collected all 817 connections."  (the end)
+//   2nd degree:  "[3/10] Some Name (A-tier, score 6.2)"  (as each person starts)
+
+const REPORTED = /LinkedIn reports (\d+) connections/;
+const COLLECTED = /(\d+)\s*\/\s*(\d+)\s+collected/;
+const COLLECTED_ALL = /Collected all (\d+) connections/;
+const BRIDGE_STEP = /\[(\d+)\/(\d+)\]/;
+// After the walk: saving to the app and fetching photos, which can take a minute
+// or two for a whole network. Without this the bar sat at 99% and looked stuck.
+const SAVING = /^(Collected \d+ connections|Pushing \d+ connections|\s*Sent \d+ →|\s*Updating \d+ profile images|\s*\[image_store\]|\s*Images \d+-\d+)/;
+
+/**
+ * @param {string[]} log    the scan's output lines, oldest first
+ * @param {string} action   the Scan page action that is running
+ * @returns {{done?: number, total?: number, current?: number, kind: 'walk'|'batch'|'saving'} | null}
+ */
+export function scanProgress(log, action) {
+  if (!Array.isArray(log) || log.length === 0) return null;
+
+  if (action === 'full' || action === 'refresh') {
+    for (let i = log.length - 1; i >= 0; i--) {
+      const line = String(log[i]);
+      if (SAVING.test(line)) return { kind: 'saving' };
+      const all = line.match(COLLECTED_ALL);
+      if (all) return walk(Number(all[1]), Number(all[1]));
+      const m = line.match(COLLECTED);
+      if (m) return walk(Number(m[1]), Number(m[2]));
+      const r = line.match(REPORTED);
+      if (r) return walk(0, Number(r[1]));
+    }
+    return null;
+  }
+
+  if (action && (action.startsWith('auto-bridge') || action === 'resume-all')) {
+    for (let i = log.length - 1; i >= 0; i--) {
+      const m = String(log[i]).match(BRIDGE_STEP);
+      if (m) {
+        const current = Number(m[1]);
+        const total = Number(m[2]);
+        if (!total) return null;
+        // "[3/10]" is printed as the third person STARTS, so two are finished.
+        return { done: Math.min(current - 1, total), total, current, kind: 'batch' };
+      }
+    }
+    return null;
+  }
+
+  return null;
+}
+
+function walk(done, total) {
+  if (!total) return null;
+  return { done: Math.min(done, total), total, kind: 'walk' };
+}