lacspace-leads 1.7.2 → 1.8.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { writeFileSync as writeFileSync3, existsSync as existsSync3, readFileSync as readFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { resolve as resolve2, extname as extname2 } from "path";
 import { createInterface } from "readline/promises";
 import { stdin, stdout, stderr, argv, exit } from "process";
@@ -717,17 +717,6 @@ function rowsToLeads(rows) {
 }
 
 // src/scrape.ts
-async function pool(items, n, fn, signal) {
-  let next = 0;
-  const workers = Array.from({ length: Math.max(1, Math.min(n, items.length)) }, async () => {
-    for (; ; ) {
-      const i = next++;
-      if (i >= items.length || signal?.aborted) return;
-      await fn(items[i], i);
-    }
-  });
-  await Promise.all(workers);
-}
 var LeadsError = class extends Error {
   code;
   cause;
@@ -765,9 +754,14 @@ function parseLatLng(url) {
   if (at) return { latitude: parseFloat(at[1]), longitude: parseFloat(at[2]) };
   return {};
 }
+function placeKey(href) {
+  const id = href.match(/!1s(0x[0-9a-f]+:0x[0-9a-f]+)/i) ?? href.match(/[?&]cid=(\d+)/);
+  if (id) return id[1].toLowerCase();
+  return href.split("?")[0].replace(/\/@[^/]+/, "").toLowerCase();
+}
 async function launchBrowser(headless, proxy) {
   let lastErr;
-  const base = { headless };
+  const base = { headless, handleSIGINT: false };
   if (proxy) base.proxy = { server: proxy };
   for (const channel of ["chrome", "msedge"]) {
     try {
@@ -828,7 +822,7 @@ async function extractDetail(page, fields, fallbackName) {
   const text = async (sel) => {
     const loc = page.locator(sel).first();
     if (await loc.count()) {
-      const t = (await loc.innerText().catch(() => "")).trim();
+      const t = (await loc.innerText({ timeout: 2e3 }).catch(() => "")).trim();
       return t || void 0;
     }
     return void 0;
@@ -836,7 +830,7 @@ async function extractDetail(page, fields, fallbackName) {
   const aria = async (sel) => {
     const loc = page.locator(sel).first();
     if (await loc.count()) {
-      return await loc.getAttribute("aria-label").catch(() => null) ?? void 0;
+      return await loc.getAttribute("aria-label", { timeout: 2e3 }).catch(() => null) ?? void 0;
     }
     return void 0;
   };
@@ -854,14 +848,14 @@ async function extractDetail(page, fields, fallbackName) {
     const box = page.locator("div.F7nice").first();
     if (await box.count()) {
       if (fields.has("rating")) {
-        const rt = await box.locator('span[aria-hidden="true"]').first().innerText().catch(() => "");
+        const rt = await box.locator('span[aria-hidden="true"]').first().innerText({ timeout: 1500 }).catch(() => "");
         lead.rating = parseRating(rt);
       }
       if (fields.has("reviews")) {
-        const rv = await box.locator('span[aria-label*="review"]').first().getAttribute("aria-label").catch(() => null);
+        const rv = await box.locator('span[aria-label*="review"]').first().getAttribute("aria-label", { timeout: 1500 }).catch(() => null);
         let count = parseReviewCount(rv);
         if (count === void 0) {
-          const boxText = await box.innerText().catch(() => "");
+          const boxText = await box.innerText({ timeout: 1500 }).catch(() => "");
           const m = boxText.match(/\(([\d.,\s]+)\)/);
           if (m) count = parseReviewCount(m[1]);
         }
@@ -878,7 +872,7 @@ async function extractDetail(page, fields, fallbackName) {
   if (fields.has("website")) {
     const site = page.locator('a[data-item-id="authority"]').first();
     if (await site.count()) {
-      lead.website = await site.getAttribute("href").catch(() => null) ?? void 0;
+      lead.website = await site.getAttribute("href", { timeout: 2e3 }).catch(() => null) ?? void 0;
     }
   }
   if (fields.has("priceLevel")) {
@@ -934,6 +928,7 @@ async function scrapeLeads(opts) {
   const near = opts.near;
   const collect = new Set(fields);
   if (wantEnrich) collect.add("website");
+  if (opts.filters?.hasWebsite || opts.filters?.noWebsite || opts.filters?.hasContact) collect.add("website");
   if (near) {
     collect.add("latitude");
     collect.add("longitude");
@@ -949,6 +944,7 @@ async function scrapeLeads(opts) {
       locale
     });
     const page = await context.newPage();
+    page.setDefaultTimeout(5e3);
     const urlOpts = { hl: locale };
     if (opts.region) urlOpts.gl = opts.region;
     if (near) urlOpts.center = { lat: near.lat, lng: near.lng, zoom: zoomForRadius(opts.radiusM ?? opts.zoomRadiusM ?? 2e3, near.lat) };
@@ -976,6 +972,19 @@ async function scrapeLeads(opts) {
       onProgress?.("no listings found (Google may have shown a CAPTCHA or an empty result).");
       return [];
     }
+    {
+      const seen = /* @__PURE__ */ new Set();
+      const uniq = cards.filter((card) => {
+        const k = placeKey(card.href);
+        if (seen.has(k)) return false;
+        seen.add(k);
+        return true;
+      });
+      if (uniq.length !== cards.length) {
+        onProgress?.(`${cards.length - uniq.length} listing${cards.length - uniq.length === 1 ? "" : "s"} shown twice in the feed \u2014 opening each place once.`);
+        cards.splice(0, cards.length, ...uniq);
+      }
+    }
     if (opts.skipListing) {
       const all = cards;
       const before = all.length;
@@ -992,9 +1001,87 @@ async function scrapeLeads(opts) {
       }
       if (all.length === 0) return [];
     }
-    let leads = [];
+    const dedupeBy = opts.dedupe ?? "smart";
+    const seenKeys = /* @__PURE__ */ new Set();
+    const accepted = [];
+    const order = /* @__PURE__ */ new Map();
+    const socialFields = ENRICHED_FIELDS.filter((f) => f !== "email");
+    const concurrency = Math.max(1, Math.trunc(opts.concurrency ?? 3));
+    let inflight = 0;
+    let enriched = 0;
+    const waiters = [];
+    const tasks = [];
+    const settleOne = () => new Promise((res) => waiters.push(res));
+    const finish = async (lead) => {
+      if ((opts.cleanUrls ?? true) && lead.website) lead.website = cleanWebsite(lead.website);
+      if (near && typeof lead.latitude === "number" && typeof lead.longitude === "number") {
+        const m = haversineMeters(near, { lat: lead.latitude, lng: lead.longitude });
+        lead.distanceKm = Math.round(m / 1e3 * 100) / 100;
+      }
+      if (near && opts.radiusM !== void 0 && !(lead.distanceKm !== void 0 && lead.distanceKm * 1e3 <= opts.radiusM)) return;
+      const key = dedupeKey(lead, dedupeBy);
+      if (key !== void 0) {
+        if (seenKeys.has(key)) return;
+        seenKeys.add(key);
+      }
+      if (wantEnrich && lead.website && !overBudget() && !signal?.aborted) {
+        onProgress?.(`enriching ${++enriched}: ${lead.name ?? lead.website}\u2026`);
+        try {
+          const c2 = await enrichContacts(lead.website);
+          if (fields.has("email") && c2.email) lead.email = c2.email;
+          for (const f of socialFields) {
+            const v = c2[f];
+            if (fields.has(f) && v) lead[f] = v;
+          }
+        } catch {
+        }
+      }
+      if (wantVerify && lead.email && !signal?.aborted) {
+        try {
+          await verifyEmails([lead], { concurrency: 1 });
+        } catch {
+        }
+      }
+      if (opts.country && fields.has("phone") && lead.phone) lead.phone = normalizePhone(lead.phone, opts.country);
+      if (opts.filters && filterLeads([lead], opts.filters).length === 0) return;
+      if (!fields.has("website")) delete lead.website;
+      if (wantVerify && !fields.has("emailStatus")) delete lead.emailStatus;
+      if (near) {
+        if (!fields.has("latitude")) delete lead.latitude;
+        if (!fields.has("longitude")) delete lead.longitude;
+        if (!fields.has("distanceKm")) delete lead.distanceKm;
+      }
+      accepted.push(lead);
+      try {
+        opts.onResult?.(lead);
+      } catch {
+      }
+    };
+    const schedule = async (lead, index) => {
+      order.set(lead, index);
+      while (inflight >= concurrency) await settleOne();
+      inflight++;
+      tasks.push(finish(lead).catch(() => {
+      }).finally(() => {
+        inflight--;
+        waiters.shift()?.();
+      }));
+    };
+    const wantMore = async () => {
+      if (!opts.remaining) return true;
+      for (; ; ) {
+        const left = opts.remaining();
+        if (left <= 0) return false;
+        if (left - inflight > 0) return true;
+        if (inflight === 0) return true;
+        await settleOne();
+      }
+    };
+    let read = 0;
     if (!wantDetails) {
-      leads = cards.map((c2) => {
+      for (let i = 0; i < cards.length; i++) {
+        if (signal?.aborted || !await wantMore()) break;
+        const c2 = cards[i];
         const lead = {};
         if (collect.has("name")) lead.name = c2.name;
         if (collect.has("mapsUrl")) lead.mapsUrl = c2.href;
@@ -1003,17 +1090,16 @@ async function scrapeLeads(opts) {
           if (collect.has("latitude")) lead.latitude = geo.latitude;
           if (collect.has("longitude")) lead.longitude = geo.longitude;
         }
-        return lead;
-      });
-      for (const lead of leads) {
+        read++;
         try {
           onLead?.(lead);
         } catch {
         }
+        await schedule(lead, i);
       }
     } else {
       for (let i = 0; i < cards.length; i++) {
-        if (signal?.aborted || overBudget()) break;
+        if (signal?.aborted || overBudget() || !await wantMore()) break;
         const card = cards[i];
         onProgress?.(`reading ${i + 1}/${cards.length}: ${card.name ?? "listing"}\u2026`);
         let lead;
@@ -1039,84 +1125,20 @@ async function scrapeLeads(opts) {
           }
         }
         if (lead) {
-          leads.push(lead);
+          read++;
           try {
             onLead?.(lead);
           } catch {
           }
+          await schedule(lead, i);
         }
         if (delayMs) await page.waitForTimeout(pauseMs());
       }
     }
-    onProgress?.(`collected ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
-    if (opts.cleanUrls ?? true) {
-      for (const lead of leads) {
-        if (lead.website) lead.website = cleanWebsite(lead.website);
-      }
-    }
-    if (near) {
-      for (const lead of leads) {
-        if (typeof lead.latitude === "number" && typeof lead.longitude === "number") {
-          const m = haversineMeters(near, { lat: lead.latitude, lng: lead.longitude });
-          lead.distanceKm = Math.round(m / 1e3 * 100) / 100;
-        }
-      }
-      if (opts.radiusM !== void 0) {
-        const r = opts.radiusM;
-        leads = leads.filter((l) => l.distanceKm !== void 0 && l.distanceKm * 1e3 <= r);
-        onProgress?.(`within ${Math.round(r)} m: ${leads.length} listing${leads.length === 1 ? "" : "s"}.`);
-      }
-    }
-    leads = dedupeLeads(leads, opts.dedupe ?? "website");
-    if (wantEnrich) {
-      const socialFields = ENRICHED_FIELDS.filter((f) => f !== "email");
-      let done = 0;
-      await pool(
-        leads,
-        Math.max(1, Math.trunc(opts.concurrency ?? 3)),
-        async (lead) => {
-          if (overBudget()) return;
-          const site = lead.website;
-          if (site) {
-            onProgress?.(`enriching ${++done}/${leads.length}: ${lead.name ?? site}\u2026`);
-            const c2 = await enrichContacts(site);
-            if (fields.has("email") && c2.email) lead.email = c2.email;
-            for (const f of socialFields) {
-              const v = c2[f];
-              if (fields.has(f) && v) lead[f] = v;
-            }
-          }
-          if (!fields.has("website")) delete lead.website;
-        },
-        signal
-      );
-    }
-    if (wantVerify && !signal?.aborted) {
-      onProgress?.("verifying email domains\u2026");
-      const vOpts = {
-        concurrency: Math.max(1, Math.trunc(opts.concurrency ?? 5))
-      };
-      if (onProgress) vOpts.onProgress = (m) => onProgress(m);
-      await verifyEmails(leads, vOpts);
-    }
-    if (opts.country && fields.has("phone")) {
-      for (const lead of leads) {
-        if (lead.phone) lead.phone = normalizePhone(lead.phone, opts.country);
-      }
-    }
-    if (opts.filters) leads = filterLeads(leads, opts.filters);
+    await Promise.all(tasks);
+    onProgress?.(`read ${read} listing${read === 1 ? "" : "s"}.`);
+    let leads = accepted.sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
     if (opts.sort) leads = sortLeads(leads, opts.sort, opts.sortDir);
-    if (wantVerify && !fields.has("emailStatus")) for (const l of leads) delete l.emailStatus;
-    if (near) {
-      const keepLat = fields.has("latitude");
-      const keepLng = fields.has("longitude");
-      const keepDist = fields.has("distanceKm");
-      for (const l of leads) {
-        if (!keepLat) delete l.latitude;
-        if (!keepLng) delete l.longitude;
-        if (!keepDist) delete l.distanceKm;
-      }
-    }
     onProgress?.(`collected ${leads.length} lead${leads.length === 1 ? "" : "s"}.`);
     return leads;
   } finally {
@@ -1146,8 +1168,29 @@ async function searchLeadsBatch(queries, opts = {}) {
   void _q;
   let merged = seedLeads ? [...seedLeads] : [];
   const seenDedupe = shared.dedupe ?? "website";
+  const userOnResult = shared.onResult;
+  const userRemaining = shared.remaining;
+  const liveKeys = /* @__PURE__ */ new Set();
+  for (const l of merged) {
+    const k = dedupeKey(l, seenDedupe);
+    if (k !== void 0) liveKeys.add(k);
+  }
+  let live = merged.length;
+  const onResult = (lead) => {
+    const k = dedupeKey(lead, seenDedupe);
+    if (k !== void 0) {
+      if (liveKeys.has(k)) return;
+      liveKeys.add(k);
+    }
+    live++;
+    try {
+      userOnResult?.(lead);
+    } catch {
+    }
+  };
+  const remaining = () => Math.min(total !== void 0 && total > 0 ? total - live : Infinity, userRemaining ? userRemaining() : Infinity);
   for (let i = 0; i < queries.length; i++) {
-    if (signal?.aborted) break;
+    if (signal?.aborted || remaining() <= 0) break;
     const q = queries[i];
     const label = (() => {
       try {
@@ -1170,6 +1213,8 @@ async function searchLeadsBatch(queries, opts = {}) {
       ...q.area ? { area: q.area } : {}
     };
     delete subOpts.sort;
+    subOpts.onResult = onResult;
+    if (userRemaining || total !== void 0 && total > 0) subOpts.remaining = remaining;
     if (signal) subOpts.signal = signal;
     if (onProgress) subOpts.onProgress = (m) => onProgress(`  ${m}`);
     try {
@@ -1430,6 +1475,151 @@ function formatSummary(s) {
   return lines.join("\n");
 }
 
+// src/live.ts
+import { appendFileSync, closeSync, existsSync as existsSync2, fstatSync, openSync, renameSync as renameSync2, writeFileSync as writeFileSync2, writeSync } from "fs";
+import { stringify as csvStringify3 } from "@lacspace/csv";
+var pick = (lead, fields) => {
+  const o = {};
+  for (const f of fields) if (lead[f] !== void 0) o[f] = lead[f];
+  return o;
+};
+function createLiveWriter(opts) {
+  const { file, format, fields } = opts;
+  const by = opts.dedupe ?? "smart";
+  const toStdout = file === "-" || !!opts.stdout;
+  const out = opts.stdout ?? { write: (c2) => process.stdout.write(c2) };
+  if (toStdout && (format === "json" || format === "xlsx")) throw new Error(`live output to stdout needs csv or ndjson, not ${format}`);
+  const rows = [];
+  const keys = /* @__PURE__ */ new Set();
+  let added = 0;
+  let failed = false;
+  let dirty = false;
+  let jsonFd;
+  const warn = (err) => {
+    if (!failed) opts.onWriteError?.(err);
+    failed = true;
+    dirty = true;
+  };
+  const atomic = (data) => {
+    const tmp = `${file}.tmp`;
+    writeFileSync2(tmp, data);
+    renameSync2(tmp, file);
+  };
+  const csvLine = (lead) => csvStringify3(toRows([lead], fields), { header: false, escapeFormulas: true });
+  const csvHeader = () => csvStringify3([toRows([{}], fields)[0]], { escapeFormulas: true }).split(/\r?\n/)[0] + "\n";
+  const nl = (s) => s.endsWith("\n") ? s : s + "\n";
+  const rewrite = (list) => {
+    const { data, binary } = serialize([...list], format, fields, opts.sheetName ? { sheetName: opts.sheetName } : {});
+    if (format === "csv" && !list.length) atomic(csvHeader());
+    else atomic(binary ? Buffer.from(data) : format === "json" ? data : nl(data));
+  };
+  const jsonAppend = (lead) => {
+    jsonFd ??= openSync(file, "r+");
+    const size = fstatSync(jsonFd).size;
+    const body = JSON.stringify(pick(lead, fields), null, 2).replace(/^/gm, "  ");
+    const chunk = (rows.length === 1 ? "\n" : ",\n") + body + "\n]";
+    writeSync(jsonFd, chunk, Math.max(1, size - (rows.length === 1 ? 1 : 2)));
+  };
+  const start = () => {
+    for (const l of opts.seed ?? []) {
+      const k = dedupeKey(l, by);
+      if (k !== void 0) keys.add(k);
+      rows.push(l);
+    }
+    if (toStdout) {
+      if (format === "csv") out.write(csvHeader());
+      return;
+    }
+    try {
+      if (format === "json" && !rows.length) atomic("[]");
+      else rewrite(rows);
+    } catch (e) {
+      warn(e);
+    }
+  };
+  const write = (lead) => {
+    if (toStdout) {
+      out.write(format === "csv" ? nl(csvLine(lead)) : JSON.stringify(pick(lead, fields)) + "\n");
+      return;
+    }
+    if (dirty) {
+      try {
+        if (jsonFd !== void 0) {
+          closeSync(jsonFd);
+          jsonFd = void 0;
+        }
+        rewrite(rows);
+        dirty = false;
+      } catch (e) {
+        warn(e);
+      }
+      return;
+    }
+    try {
+      if (format === "csv") appendFileSync(file, nl(csvLine(lead)));
+      else if (format === "ndjson") appendFileSync(file, JSON.stringify(pick(lead, fields)) + "\n");
+      else if (format === "json") {
+        if (rows.length > 1 && !existsSync2(file)) throw new Error("output file disappeared");
+        jsonAppend(lead);
+      } else rewrite(rows);
+    } catch (e) {
+      warn(e);
+    }
+  };
+  start();
+  return {
+    add(lead) {
+      const k = dedupeKey(lead, by);
+      if (k !== void 0) {
+        if (keys.has(k)) return false;
+        keys.add(k);
+      }
+      rows.push(lead);
+      added++;
+      write(lead);
+      return true;
+    },
+    get count() {
+      return rows.length;
+    },
+    get added() {
+      return added;
+    },
+    get leads() {
+      return rows;
+    },
+    flush() {
+      if (toStdout || !dirty) return;
+      try {
+        if (jsonFd !== void 0) {
+          closeSync(jsonFd);
+          jsonFd = void 0;
+        }
+        rewrite(rows);
+        dirty = false;
+      } catch (e) {
+        warn(e);
+      }
+    },
+    finish(final) {
+      if (jsonFd !== void 0) {
+        try {
+          closeSync(jsonFd);
+        } catch {
+        }
+        jsonFd = void 0;
+      }
+      if (toStdout) return;
+      try {
+        rewrite(final ?? rows);
+        dirty = false;
+      } catch (e) {
+        warn(e);
+      }
+    }
+  };
+}
+
 // src/pipe.ts
 function leadDomain(website) {
   if (!website) return void 0;
@@ -1531,8 +1721,26 @@ async function sweepLeads(opts) {
     stats.unique = collected.length;
     return collected.length - before;
   };
-  const enough = () => collected.length >= want;
-  const stepLimit = () => Math.min(cap, Math.max(MIN_PER_STEP, (want - collected.length) * 2));
+  const userOnResult = shared.onResult;
+  const userRemaining = shared.remaining;
+  const userSkip = shared.skipListing;
+  const liveKeys = /* @__PURE__ */ new Set();
+  let live = 0;
+  const onResult = (lead) => {
+    const k = dedupeKey(lead, dedupeBy);
+    if (k !== void 0) {
+      if (liveKeys.has(k)) return;
+      liveKeys.add(k);
+    }
+    live++;
+    try {
+      userOnResult?.(lead);
+    } catch {
+    }
+  };
+  const remaining = () => Math.min(want - Math.max(live, collected.length), userRemaining ? userRemaining() : Infinity);
+  const enough = () => remaining() <= 0;
+  const stepLimit = () => Math.min(cap, Math.max(MIN_PER_STEP, Math.max(0, remaining()) * 2));
   let center = near ? { lat: near.lat, lng: near.lng } : void 0;
   const captureCenter = (c2) => {
     center ??= c2;
@@ -1543,7 +1751,9 @@ async function sweepLeads(opts) {
       ...shared,
       ...step,
       limit: stepLimit(),
-      onCenter: captureCenter
+      onCenter: captureCenter,
+      onResult,
+      remaining
     };
     const found = await scrapeLeads(searchOpts);
     stats.searches++;
@@ -1569,7 +1779,9 @@ async function sweepLeads(opts) {
           limit: stepLimit(),
           near: point,
           onCenter: captureCenter,
-          skipListing
+          skipListing: (l) => skipListing(l) || (userSkip?.(l) ?? false),
+          onResult,
+          remaining
         };
         delete tileOpts.area;
         delete tileOpts.city;
@@ -1667,6 +1879,7 @@ function parseArgs(list) {
     jitter: false,
     resume: false,
     summary: false,
+    live: true,
     yes: false,
     help: false
   };
@@ -1723,6 +1936,8 @@ function parseArgs(list) {
     else if (arg === "--business-status") a.businessStatus = next();
     else if (arg === "--name-exclude" || arg === "--exclude-names") a.nameExclude = next();
     else if (arg === "--resume") a.resume = true;
+    else if (arg === "--no-live") a.live = false;
+    else if (arg === "--live") a.live = true;
     else if (arg === "--summary") a.summary = true;
     else if (arg === "--dedupe-across") a.dedupeAcross = next();
     else if (arg === "--enrich-out") a.enrichOut = next();
@@ -1800,8 +2015,8 @@ ${c("bold", "Filters & order")}
       --category <text> Keep only leads whose category/tags contain this text
       --business-status <s>  Keep only this status (operational | closed | temporarily-closed)
       --name-exclude <list>  Drop leads whose name contains any of these terms
-      --dedupe <key>    website | phone | name | smart | none   (default website;
-                        --append uses smart: website\u2192phone\u2192name)
+      --dedupe <key>    website | phone | name | smart | none   (default smart:
+                        same website, else same phone, else same name)
       --dedupe-across <file>  Drop leads already present in an existing master file
       --sort <key>      rating | reviews | name | priceLevel | distance
       --desc / --asc    Sort direction (distance defaults nearest-first)
@@ -1817,7 +2032,13 @@ ${c("bold", "Output")}
       --sheet <name>    Excel sheet name         (default "Leads")
       --summary         Print run stats (rating bands, % with contact, top categories)
       --enrich-out <f>  Also write { name, website, domain } NDJSON for lacspace-enrich
-      --resume          Resume an interrupted city sweep from its checkpoint file
+      --resume          Continue an interrupted run: keeps the rows already in the
+                        output file, skips those listings and fills up to --target
+                        (multi-area sweeps also use their checkpoint file)
+      --no-live         Write the file only at the end. By default every lead is
+                        added to the file the moment it is found (csv/ndjson rows
+                        append, json stays valid, xlsx is rewritten), so stopping
+                        early never loses what was collected
 
 ${c("bold", "Runtime")}
       --delay <ms>      Pause between listings    (default 700)
@@ -1952,7 +2173,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
     return;
   }
   const fields = config.fields ? normalizeFields(config.fields) : ALL_FIELDS.filter((f) => leads.some((l) => l[f] !== void 0));
-  if (args.dedupeAcross && existsSync2(args.dedupeAcross)) {
+  if (args.dedupeAcross && existsSync3(args.dedupeAcross)) {
     try {
       const master = rowsToLeads(await readRows(args.dedupeAcross));
       const before = leads.length;
@@ -1962,7 +2183,7 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
       log(c("yellow", `  ! couldn't read --dedupe-across (${err.message})`));
     }
   }
-  if ((args.append || config.append) && existsSync2(out)) {
+  if ((args.append || config.append) && existsSync3(out)) {
     try {
       const existing = rowsToLeads(await readRows(out));
       const before = existing.length;
@@ -1976,13 +2197,13 @@ ${c("bold", c("magenta", "\u25C6 lacspace-leads config"))} ${c("dim", "\u2014 ru
     const inputs = leadsToEnrichInput(leads);
     const nd = inputs.map((o) => JSON.stringify(o)).join("\n") + (inputs.length ? "\n" : "");
     const enrichPath = resolve2(args.enrichOut);
-    writeFileSync2(enrichPath, nd);
+    writeFileSync3(enrichPath, nd);
     log(`  ${c("cyan", "\u25F7")} ${c("dim", `wrote ${inputs.length} enrich input${inputs.length === 1 ? "" : "s"} \u2192 ${enrichPath}`)}`);
   }
   const serOpts = {};
   if (args.sheet ?? config.sheet) serOpts.sheetName = args.sheet ?? config.sheet;
   const { data, binary } = serialize(leads, format, fields, serOpts);
-  writeFileSync2(out, binary ? Buffer.from(data) : data);
+  writeFileSync3(out, binary ? Buffer.from(data) : data);
   if (cpFile) clearCheckpoint(cpFile);
   const s = computeStats(leads);
   log(`
@@ -2158,9 +2379,83 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   log("");
   const controller = new AbortController();
   const onSig = () => {
+    if (controller.signal.aborted) {
+      writerRef.current?.flush();
+      log(c("yellow", "\n  ! Quit. Rows already written stay in the file; --resume continues from them.\n"));
+      exit(130);
+    }
     controller.abort();
+    log(c("yellow", "\n  ! Stopping \u2014 finishing the leads in hand. Press Ctrl-C again to quit at once (rows already written stay in the file)."));
+  };
+  const writerRef = {};
+  process.on("SIGINT", onSig);
+  let existing = [];
+  if ((args.append || args.resume) && !toStdout && existsSync3(out)) {
+    try {
+      existing = rowsToLeads(await readRows(out));
+    } catch (err) {
+      log(c("yellow", `  ! couldn't read "${out}" (${err.message}); starting it fresh`));
+    }
+  }
+  let master;
+  if (args.dedupeAcross && existsSync3(args.dedupeAcross)) {
+    try {
+      master = rowsToLeads(await readRows(args.dedupeAcross));
+    } catch (err) {
+      log(c("yellow", `  ! couldn't read --dedupe-across "${args.dedupeAcross}" (${err.message}); keeping all`));
+    }
+  }
+  const dedupeBy = args.dedupe ?? "smart";
+  const inMaster = master?.length ? (l) => subtractLeads([l], master, dedupeBy).length === 0 : void 0;
+  const resumeRows = args.resume && !isBatch ? existing : [];
+  if (resumeRows.length) log(`  ${c("cyan", "\u25F7")} ${c("dim", `resuming \u2014 ${resumeRows.length} leads already in ${out}; skipping those listings`)}`);
+  const liveFormat = toStdout ? args.format === "csv" || args.format === "ndjson" : true;
+  let writer;
+  const outExisted = !toStdout && existsSync3(out);
+  const dropEmpty = () => {
+    if (!writer || toStdout) return;
+    if (outExisted) writer.finish([...existing]);
+    else {
+      writer.finish([]);
+      try {
+        unlinkSync2(out);
+      } catch {
+      }
+    }
+  };
+  if (args.live && liveFormat && !(toStdout && args.split)) {
+    try {
+      writer = createLiveWriter({
+        file: out,
+        format: args.format,
+        fields,
+        dedupe: dedupeBy,
+        seed: existing,
+        ...args.sheet ? { sheetName: args.sheet } : {},
+        ...toStdout ? { stdout } : {},
+        onWriteError: (e) => log(c("yellow", `  ! couldn't write ${out} (${e.message}) \u2014 is it open in another app? Rows are kept and written as soon as it's free.`))
+      });
+      writerRef.current = writer;
+      if (!toStdout) log(`  ${c("cyan", "\u25F7")} ${c("dim", `writing live \u2192 ${out}`)}`);
+    } catch (err) {
+      log(c("yellow", `  ! live output off: ${err.message}`));
+    }
+  }
+  const goal = args.target ?? (isBatch ? args.total : void 0) ?? (isBatch ? void 0 : args.limit);
+  const startedAt = Date.now();
+  let fresh0 = 0;
+  const onResult = (lead) => {
+    if (inMaster?.(lead)) return;
+    if (writer && !writer.add(lead)) return;
+    fresh0++;
+    const have = resumeRows.length + fresh0;
+    const mins = (Date.now() - startedAt) / 6e4;
+    const rate = mins > 0.05 ? fresh0 / mins : 0;
+    const left = goal !== void 0 ? Math.max(0, goal - have) : 0;
+    const eta = rate > 0 && left > 0 ? `, ~${Math.ceil(left / rate)} min left` : "";
+    const bits = [lead.phone, lead.website?.replace(/^https?:\/\/(www\.)?/, "").replace(/\/$/, ""), lead.email].filter(Boolean).join(" \xB7 ");
+    log(`  ${c("green", "\u271A")} ${c("bold", goal !== void 0 ? `${have}/${goal}` : String(have))} ${lead.name ?? "(no name)"}${bits ? c("dim", ` \u2014 ${bits}`) : ""}${rate ? c("dim", `  (${rate.toFixed(1)}/min${eta})`) : ""}`);
   };
-  process.once("SIGINT", onSig);
   const opts = {
     type: args.type ?? "",
     query: args.query ?? "",
@@ -2176,10 +2471,17 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     verifyEmails: args.verifyEmails,
     jitter: args.jitter,
     signal: controller.signal,
-    onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`)
+    onProgress: (m) => log(`  ${c("cyan", "\u25F7")} ${c("dim", m)}`),
+    onResult
   };
+  if (resumeRows.length) {
+    const names = new Set(resumeRows.map((l) => l.name?.trim().toLowerCase()).filter(Boolean));
+    const urls = new Set(resumeRows.map((l) => l.mapsUrl).filter(Boolean));
+    opts.skipListing = (l) => urls.has(l.href) || !!l.name && names.has(l.name.trim().toLowerCase());
+  }
+  if (args.target !== void 0 && (resumeRows.length || inMaster)) opts.remaining = () => args.target - resumeRows.length - fresh0;
   if (hasFilters) opts.filters = filters;
-  if (args.dedupe) opts.dedupe = args.dedupe;
+  opts.dedupe = dedupeBy;
   if (nearPoint) opts.near = { lat: nearPoint.lat, lng: nearPoint.lng };
   if (radiusM !== void 0) opts.radiusM = radiusM;
   if (args.sort) opts.sort = args.sort;
@@ -2239,6 +2541,15 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
       leads = await scrapeLeads(opts);
     }
   } catch (err) {
+    if (writer && writer.added) {
+      writer.flush();
+      log(c("yellow", `
+  ! ${err.message}`));
+      log(`  ${c("green", "\u2714")} ${c("bold", String(writer.count))} leads are saved in ${c("cyan", out)}. Run the same command with ${c("bold", "--resume")} to continue.
+`);
+      exit(controller.signal.aborted ? 130 : 1);
+      return;
+    }
     log(c("red", `
 \u2717 ${err.message}`));
     exit(1);
@@ -2246,6 +2557,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   } finally {
     process.removeListener("SIGINT", onSig);
   }
+  const stoppedEarly = controller.signal.aborted;
   if (sweptShort) {
     log(c("yellow", `
   ! The map ran out of new results at ${leads.length} \u2014 that is everything Google lists here.`));
@@ -2256,44 +2568,37 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
     log(c("dim", `    To really get ${args.limit}, ask for a total: --target ${args.limit} \u2014 it sweeps every area you name, then tiles the map.
 `));
   }
-  if (leads.length === 0) {
+  if (leads.length === 0 && !resumeRows.length) {
     log(c("yellow", "\n  No leads collected. Try a broader area, looser filters, or a smaller --limit.\n"));
+    dropEmpty();
     if (cpFile) clearCheckpoint(cpFile);
     return;
   }
-  if (args.dedupeAcross && existsSync2(args.dedupeAcross)) {
-    try {
-      const master = rowsToLeads(await readRows(args.dedupeAcross));
-      const before = leads.length;
-      leads = subtractLeads(leads, master, args.dedupe ?? "smart");
-      log(`  ${c("cyan", "\u25F7")} ${c("dim", `dropped ${before - leads.length} already in ${args.dedupeAcross} \u2192 ${leads.length} new`)}`);
-    } catch (err) {
-      log(c("yellow", `  ! couldn't read --dedupe-across "${args.dedupeAcross}" (${err.message}); keeping all`));
-    }
+  if (master) {
+    const before = leads.length;
+    leads = subtractLeads(leads, master, dedupeBy);
+    log(`  ${c("cyan", "\u25F7")} ${c("dim", `dropped ${before - leads.length} already in ${args.dedupeAcross} \u2192 ${leads.length} new`)}`);
     if (leads.length === 0) {
       log(c("yellow", "\n  Nothing new \u2014 every lead was already in the master file.\n"));
+      dropEmpty();
       if (cpFile) clearCheckpoint(cpFile);
       return;
     }
   }
   let fresh = leads.length;
-  if (args.append && !toStdout && existsSync2(out)) {
-    try {
-      const existing = rowsToLeads(await readRows(out));
-      const before = existing.length;
-      const merged = dedupeLeads([...existing, ...leads], args.dedupe ?? "smart");
-      fresh = merged.length - before;
-      log(`  ${c("cyan", "\u25F7")} ${c("dim", `merged with ${before} existing \u2192 ${merged.length} total (${fresh} new)`)}`);
-      leads = merged;
-    } catch (err) {
-      log(c("yellow", `  ! couldn't read "${out}" to append (${err.message}); overwriting instead`));
-    }
+  if ((args.append || resumeRows.length) && !toStdout && existing.length) {
+    const before = existing.length;
+    const merged = dedupeLeads([...existing, ...leads], dedupeBy);
+    fresh = merged.length - before;
+    log(`  ${c("cyan", "\u25F7")} ${c("dim", `merged with ${before} existing \u2192 ${merged.length} total (${fresh} new)`)}`);
+    leads = merged;
+    if (args.target !== void 0 && resumeRows.length) leads = leads.slice(0, Math.max(args.target, before));
   }
   if (args.enrichOut) {
     const inputs = leadsToEnrichInput(leads);
     const nd = inputs.map((o) => JSON.stringify(o)).join("\n") + (inputs.length ? "\n" : "");
     const enrichPath = resolve2(args.enrichOut);
-    writeFileSync2(enrichPath, nd);
+    writeFileSync3(enrichPath, nd);
     log(`  ${c("cyan", "\u25F7")} ${c("dim", `wrote ${inputs.length} enrich input${inputs.length === 1 ? "" : "s"} \u2192 ${enrichPath} (feed to lacspace-enrich)`)}`);
   }
   const printSummary = () => {
@@ -2307,8 +2612,10 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   if (args.sheet) serOpts.sheetName = args.sheet;
   const { data, binary } = serialize(leads, args.format, fields, serOpts);
   if (toStdout) {
-    stdout.write(binary ? Buffer.from(data) : data);
-    if (!binary) stdout.write("\n");
+    if (!writer) {
+      stdout.write(binary ? Buffer.from(data) : data);
+      if (!binary) stdout.write("\n");
+    }
     log(`
   ${c("green", "\u2714")} ${c("bold", String(leads.length))} leads written to stdout ${c("dim", `(${args.format})`)}
 `);
@@ -2328,13 +2635,14 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
       for (const [group, rows] of groups) {
         const file = `${stem}-${groupSlug(group)}${ext}`;
         const part = serialize(rows, args.format, fields, serOpts);
-        writeFileSync2(file, part.binary ? Buffer.from(part.data) : part.data);
+        writeFileSync3(file, part.binary ? Buffer.from(part.data) : part.data);
         log(`  ${c("green", "\u2714")} ${c("bold", String(rows.length))} leads \u2192 ${c("cyan", file)}`);
       }
     }
   }
-  writeFileSync2(out, binary ? Buffer.from(data) : data);
-  if (cpFile) clearCheckpoint(cpFile);
+  if (writer) writer.finish(leads);
+  else writeFileSync3(out, binary ? Buffer.from(data) : data);
+  if (cpFile && !stoppedEarly) clearCheckpoint(cpFile);
   const s = computeStats(leads);
   log(`
   ${c("green", "\u2714")} Saved ${c("bold", String(leads.length))} leads \u2192 ${c("cyan", out)}${args.append && fresh !== leads.length ? c("dim", ` (${fresh} new)`) : ""}`);
@@ -2344,6 +2652,7 @@ ${c("yellow", "!")} This opens a browser and searches Google Maps. Continue? ${c
   if (args.socials) parts.push(`${s.withSocial} with a social link`);
   if (s.avgRating !== void 0) parts.push(`avg \u2605 ${s.avgRating}`);
   log(`    ${c("dim", parts.join(" \xB7 "))}`);
+  if (stoppedEarly) log(c("yellow", `  ! Stopped early. Run the same command with --resume to carry on from these ${leads.length}.`));
   printSummary();
   log("");
 }