election-vibe 0.1.0 → 0.1.2

package/README.md

@@ -9,7 +9,7 @@ Unofficial results for the US general election of November 3, 2026, in your term
 You need Node 22 or later.
 
 ```bash
-npm i -g election-vibe     # installs the `elections` command
+npm i -g election-vibe     # installs the `elections` command (also as `election-vibe`)
 elections collect          # the collector: leave it running in its own terminal
 ```
 
@@ -302,6 +302,8 @@ To remove it all, in this order (the plugin lives inside the package's folder, s
 
 **Does collection stop on November 4?** No: the collector runs until you stop it. November 4 is how long the tool is supported; see [Operating window](#operating-window).
 
+**Why does `collect --once` take so long?** It is not stuck. `--once` reads everything that is due, once, then exits. On a fresh install that is every contest the collector reads from civicAPI (471, plus one for each followed California contest that civicAPI also carries), one request at a time at about one per second, so the single pass takes about 10 minutes and prints its one log line at the end. Plain `elections collect` paces itself (at most 9 civicAPI requests per pass, then a 10-second wait before the next pass) and is the normal way to run it. For a quick connectivity check, `elections collect --once --civic-limit 2` bounds the pass to two civicAPI requests and exits in seconds.
+
 **Does this run on Windows?** Not tested. This release was built and tested on macOS. The CLI uses only Node, but the plugin assumes a macOS or Linux shell path, and nothing here has been tried on Windows or Linux.
 
 **Does `race` treat the comma as part of the query?** Yes. `race` takes its words as one phrase, punctuation included, and looks for it in titles and ids: `"palo alto, transactions"` matches Palo Alto's Measure J because its title contains that phrase. `find` is the one that matches word by word.
@@ -310,6 +312,8 @@ To remove it all, in this order (the plugin lives inside the package's folder, s
 
 **Which Claude Code version?** The plugin was tested with Claude Code 2.1.316. To update: update the package, restart the collector, then `/reload-plugins`. To remove: the plugin before the package (see above).
 
+**Does it work behind a corporate proxy?** It connects to the sources directly and does not use a proxy (`HTTPS_PROXY` is not read). On a network that inspects HTTPS or blocks direct connections, the reads fail, and `elections sources` says why for each source (for example "the connection's certificate is not trusted").
+
 **How do I pick the display time zone?** `--tz <IANA zone>` on any command, or `ELECTIONS_TZ`. The default is your computer's zone.
 
 **How much disk does it use?** A few megabytes for the snapshots, plus one log line per collector cycle.

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { appendFileSync } from "fs";
+import { appendFileSync, realpathSync } from "fs";
+import { fileURLToPath } from "url";
 
 // src/store.ts
 import { randomBytes } from "crypto";
@@ -215,7 +216,7 @@ var REHEARSAL_SENTENCE = {
 
 // src/http.ts
 import { gunzipSync } from "zlib";
-var USER_AGENT = `ElectionsCompanion/${"0.1.0"} (unofficial results reader; local, no telemetry)`;
+var USER_AGENT = `ElectionsCompanion/${"0.1.2"} (unofficial results reader; local, no telemetry)`;
 function retryAfterMs(header, nowMs) {
   if (!header) return void 0;
   const t = header.trim();
@@ -295,6 +296,9 @@ async function fetchDocument(url, opts) {
       }
     }
     if (res.status === 401 || res.status === 403) return { kind: "denied", status: res.status, fetchedAt: stamp() };
+    if (res.status === 407) {
+      return { kind: "client-error", status: 407, fetchedAt: stamp(), detail: "HTTP 407: a proxy asks for credentials; this tool connects directly and does not use a proxy" };
+    }
     if (res.status >= 500) return { kind: "server-error", status: res.status, fetchedAt: stamp() };
     if (res.status !== 200) return { kind: "client-error", status: res.status, fetchedAt: stamp() };
     let body = opts.method === "HEAD" ? Buffer.alloc(0) : await readBounded2(res, maxBytes);
@@ -319,11 +323,23 @@ async function fetchDocument(url, opts) {
   } catch (err) {
     if (err instanceof BodyTooLargeError) return { kind: "too-large", status: err.status, fetchedAt: stamp(), detail: "captured body over bound" };
     const aborted = err.name === "AbortError";
-    return { kind: aborted ? "timeout" : "network", fetchedAt: stamp(), detail: aborted ? void 0 : String(err.message ?? err).slice(0, 120) };
+    return { kind: aborted ? "timeout" : "network", fetchedAt: stamp(), detail: aborted ? void 0 : networkWords(err) };
   } finally {
     clearTimeout(timer);
   }
 }
+function networkWords(err) {
+  const raw = err?.cause?.code;
+  const code = typeof raw === "string" && /^[A-Z][A-Z0-9_]{1,39}$/.test(raw) ? raw : "";
+  if (/^(SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_(GET_ISSUER_CERT(_LOCALLY)?|VERIFY_LEAF_SIGNATURE)|CERT_[A-Z_]+|ERR_TLS_[A-Z_]+)$/.test(code)) {
+    return `the connection's certificate is not trusted (${code}): a network that inspects HTTPS, such as a corporate proxy, causes this; this tool connects directly`;
+  }
+  if (/^(ECONNREFUSED|ECONNRESET|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|UND_ERR_CONNECT_TIMEOUT|UND_ERR_SOCKET)$/.test(code)) {
+    return `the connection was refused or cut off (${code}): no network, or a firewall or proxy that blocks direct connections`;
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return `the source's name could not be resolved (${code}): no network, or a network that blocks the name`;
+  return code ? `the connection failed (${code})` : "the connection failed";
+}
 function jsonOf(body) {
   try {
     return JSON.parse(body.toString("utf8"));
@@ -1927,6 +1943,8 @@ var CIVIC_BLANKET_FLOOR_SEC = 900;
 var THROTTLE_FLOOR_MS = 5 * 6e4;
 var BACKOFF_MAX_MS = 30 * 6e4;
 var MAX_EVENTS = 2e3;
+var CLOSE_SPREAD_MS = 6e4;
+var READ_JITTER_SHARE = 0.1;
 var CLARITY_RECHECK_MS = 30 * 6e4;
 var LockLost = class extends Error {
   constructor(report) {
@@ -1985,10 +2003,40 @@ function newerRecord(a, b) {
 function blocked(s, nowMs) {
   return !!s.deniedAt || !!s.cooldownUntil && Date.parse(s.cooldownUntil) > nowMs;
 }
-function sourceCadenceMs(src, contests, nowMs, rehearsal = false) {
+var closeOffsets = /* @__PURE__ */ new WeakMap();
+function closeOffsetMs(deps, id) {
+  let run = closeOffsets.get(deps);
+  if (!run) {
+    run = /* @__PURE__ */ new Map();
+    closeOffsets.set(deps, run);
+  }
+  let o = run.get(id);
+  if (o === void 0) {
+    const r = deps.random();
+    o = r >= 0 && r < 1 ? Math.floor(r * CLOSE_SPREAD_MS) : 0;
+    run.set(id, o);
+  }
+  return o;
+}
+var readJitters = /* @__PURE__ */ new WeakMap();
+function readJitterMs(deps, id, after, cadenceMs) {
+  let run = readJitters.get(deps);
+  if (!run) {
+    run = /* @__PURE__ */ new Map();
+    readJitters.set(deps, run);
+  }
+  let held = run.get(id);
+  if (!held || held.after !== after) {
+    const r = deps.random();
+    held = { after, share: r >= 0 && r < 1 ? r : 0 };
+    run.set(id, held);
+  }
+  return Math.floor(held.share * READ_JITTER_SHARE * cadenceMs);
+}
+function sourceCadenceMs(src, contests, nowMs, rehearsal, offsetMs, jitterMs) {
   if (rehearsal) return src.cadenceSec * 1e3;
-  const anyClosed = contests.some((c) => c.sources.some((m2) => m2.source === src.id) && Date.parse(c.pollsClose) <= nowMs);
-  return (anyClosed ? src.cadenceSec : src.preCloseCadenceSec) * 1e3;
+  const anyClosed = contests.some((c) => c.sources.some((m2) => m2.source === src.id) && Date.parse(c.pollsClose) + offsetMs <= nowMs);
+  return anyClosed ? src.cadenceSec * 1e3 + jitterMs() : src.preCloseCadenceSec * 1e3;
 }
 function due(s, cadenceMs, nowMs) {
   if (blocked(s, nowMs)) return false;
@@ -2123,7 +2171,7 @@ function sealSources(raw) {
   }
   return out;
 }
-function civicQueue(registry, src, config, last, nowMs) {
+function civicQueue(registry, src, config, last, nowMs, closeOffsetMs2 = 0, jitterMs = () => 0) {
   const blanketSec = Math.max(CIVIC_BLANKET_FLOOR_SEC, config.blanketSec ?? Number(src.config.blanketSec ?? 1800));
   const out = [];
   for (const def of registry) {
@@ -2131,10 +2179,10 @@ function civicQueue(registry, src, config, last, nowMs) {
     if (!m2) continue;
     const watch = config.follow.includes(def.id) || (def.presets ?? []).includes("hot");
     if (m2.role !== "primary" && !watch) continue;
-    const preClose = nowMs < Date.parse(def.pollsClose);
+    const preClose = nowMs < Date.parse(def.pollsClose) + closeOffsetMs2;
     const cadence = (preClose ? src.preCloseCadenceSec : watch ? src.cadenceSec : blanketSec) * 1e3;
     const prev = last[m2.key];
-    if (prev !== void 0 && nowMs - prev < cadence) continue;
+    if (prev !== void 0 && nowMs - prev < cadence + (preClose ? 0 : jitterMs(m2.key, prev, cadence))) continue;
     out.push({ def, key: m2.key, tier: watch ? "watch" : "blanket", age: prev === void 0 ? Number.POSITIVE_INFINITY : nowMs - prev });
   }
   out.sort((a, b) => a.tier === b.tier ? b.age - a.age : a.tier === "watch" ? -1 : 1);
@@ -2223,7 +2271,15 @@ async function cycle(deps, opts) {
     if (src.kind === "civicapi") continue;
     const approval = approvals[src.id];
     const approvedSinceAttempt = !!approval && !!s.lastAttemptAt && Date.parse(approval.approvedAt) > Date.parse(s.lastAttemptAt);
-    if (!(approvedSinceAttempt && !blocked(s, t0)) && !due(s, sourceCadenceMs(src, deps.registry, t0, opts.admissionDisabled === true), t0)) {
+    const cadenceMs = sourceCadenceMs(
+      src,
+      deps.registry,
+      t0,
+      opts.admissionDisabled === true,
+      closeOffsetMs(deps, src.id),
+      () => readJitterMs(deps, src.id, s.lastAttemptAt, src.cadenceSec * 1e3)
+    );
+    if (!(approvedSinceAttempt && !blocked(s, t0)) && !due(s, cadenceMs, t0)) {
       report.outcomes[src.id] = "skipped";
       continue;
     }
@@ -2481,7 +2537,15 @@ async function cycle(deps, opts) {
   const civic = deps.sources.find((s) => s.kind === "civicapi");
   if (civic && !config.disabledSources.includes(civic.id)) {
     const minInterval = Number(civic.config.minIntervalMs ?? 1100);
-    const queue = civicQueue(deps.registry, civic, config, cstate.civicLast, deps.now());
+    const queue = civicQueue(
+      deps.registry,
+      civic,
+      config,
+      cstate.civicLast,
+      deps.now(),
+      opts.admissionDisabled === true ? 0 : closeOffsetMs(deps, civic.id),
+      opts.admissionDisabled === true ? void 0 : (key, prev, cadenceMs) => readJitterMs(deps, `civic:${key}`, prev, cadenceMs)
+    );
     const limit = opts.civicLimit ?? queue.length;
     let n = 0;
     for (const item of queue) {
@@ -2492,7 +2556,9 @@ async function cycle(deps, opts) {
         log("civicapi: hourly ceiling reached; the rest waits");
         break;
       }
-      if (n > 0) await deps.sleep(minInterval + Math.round(deps.random() * 250));
+      const draw = deps.random();
+      const spread = draw >= 0 && draw < 1 ? Math.round(draw * 250) : 0;
+      await deps.sleep(n > 0 ? minInterval + spread : spread);
       n++;
       cstate.civicLast[item.key] = deps.now();
       const r = await get(civic, `${civic.config.base}/race/${item.key}`);
@@ -46269,7 +46335,7 @@ function storeOf(p) {
 }
 async function main(argv, io) {
   if (argv[0] === "--version" || argv[0] === "version") {
-    io.out("0.1.0");
+    io.out("0.1.2");
     return 0;
   }
   const p = parseArgs(argv);
@@ -46476,6 +46542,8 @@ ${renderRace(v, { nowMs, zone, width, color, partisan, pollsClose })}`);
             disabled: cfg.disabledSources.includes(s.id),
             approved: approvals[s.id] ?? null,
             lastOutcome: st?.lastOutcome ?? null,
+            // Why the last read failed, in words (a blocked network names what blocks it); null after a success.
+            lastOutcomeDetail: st?.lastOutcome && st.lastOutcome !== "ok" && st.lastOutcome !== "not-modified" && st.lastOutcomeDetail ? humanLabel(st.lastOutcomeDetail, 300) : null,
             lastSuccessAt: st?.lastSuccessAt ?? null,
             cooldownUntil: st?.cooldownUntil ?? null,
             deniedAt: st?.deniedAt ?? null,
@@ -46492,7 +46560,7 @@ ${renderRace(v, { nowMs, zone, width, color, partisan, pollsClose })}`);
           const lines = rows.map(
             (r) => [
               `${r.name} (${r.id}) \xB7 ledger ${r.ledger} \xB7 admission ${r.admission}${r.disabled ? " \xB7 DISABLED locally" : ""}`,
-              `  last: ${r.lastOutcome ?? "never read"}${r.lastSuccessAt ? ` \xB7 last success ${formatAge(r.lastSuccessAt, nowMs)} ago` : ""}${r.cooldownUntil && Date.parse(r.cooldownUntil) > nowMs ? ` \xB7 cooling down until ${formatInstant(r.cooldownUntil, zone)}` : ""}${r.deniedAt ? " \xB7 ACCESS DENIED: stopped pending diagnosis" : ""}`,
+              `  last: ${r.lastOutcome ?? "never read"}${r.lastOutcomeDetail ? `: ${r.lastOutcomeDetail}` : ""}${r.lastSuccessAt ? ` \xB7 last success ${formatAge(r.lastSuccessAt, nowMs)} ago` : ""}${r.cooldownUntil && Date.parse(r.cooldownUntil) > nowMs ? ` \xB7 cooling down until ${formatInstant(r.cooldownUntil, zone)}` : ""}${r.deniedAt ? " \xB7 ACCESS DENIED: stopped pending diagnosis" : ""}`,
               `  revision: ${r.lastRevision ? `${localizeTimes(r.lastRevision.label, zone)} (hash ${r.lastRevision.hash})` : "none"} \xB7 production: ${r.approved ? `approved from ${approvalPoint(r.id, r.approved.revisionOrder, zone)}, at ${formatInstant(r.approved.approvedAt, zone)}` : r.admission === "operator" ? "awaiting production approval" : "admitted by source tag after poll close"}`,
               `  requests this hour: ${r.requestsThisHour} \xB7 ${r.officialLink ? `official results: ${r.officialLink}` : `not an official source (aggregator): ${r.site}`}`
             ].join("\n")
@@ -46720,8 +46788,15 @@ function approvalPoint(sourceId, order, zone) {
   const src = sourceById(sourceId);
   return src && orderIsTime(src) ? `the report of ${formatInstant(new Date(order).toISOString(), zone)}` : `revision ${order}`;
 }
-var isEntry = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/elections") || process.argv[1]?.endsWith("cli.js");
-if (isEntry) {
+function isEntryPath(launched, moduleUrl) {
+  if (!launched) return false;
+  try {
+    return realpathSync(launched) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+if (isEntryPath(process.argv[1], import.meta.url)) {
   main(process.argv.slice(2), {
     out: (s) => process.stdout.write(`${s}
 `),
@@ -46751,6 +46826,7 @@ function exitWhenFlushed(code) {
   process.stderr.write("", done);
 }
 export {
+  isEntryPath,
   main,
   parseArgs
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "election-vibe",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "US election night, Nov 3, 2026, in your terminal and in Claude Code: unofficial results from official free sources and civicAPI, kept on your machine. Never calls a race. Unofficial results. Not an election authority. Not affiliated with any government, campaign, or party.",
   "keywords": [
     "election",
@@ -19,7 +19,8 @@
     "node": ">=22"
   },
   "bin": {
-    "elections": "./dist/cli.js"
+    "elections": "./dist/cli.js",
+    "election-vibe": "./dist/cli.js"
   },
   "files": [
     "dist",