election-vibe 0.1.1 → 0.1.3

package/README.md

@@ -27,6 +27,14 @@ On Tuesday, after the polls close:
 
 Without installing, put `npx election-vibe` where `elections` is (`npx election-vibe collect`, `npx election-vibe watch`). The statusline and the plugin need the global install.
 
+### One-step setup with Claude
+
+In Claude Code (the terminal CLI, or its desktop app), you can hand the whole setup to Claude. Paste this prompt and Claude installs the package, starts the collector, asks which races you care about, and follows them:
+
+> Set up election-vibe for election night. If you cannot run commands on my computer, say so and stop. Install it with `npm i -g election-vibe` (it needs Node 22 or later; help me get that first if it is missing). Add its Claude Code plugin: `claude plugin marketplace add "$(npm root -g)/election-vibe"`, then `claude plugin install election-vibe@election-vibe --config store=production`. Start the collector by running `elections collect` in a terminal tab and leave it running. Then ask me which state I vote in and which races I care about (one question at a time, with answer options when you can), look them up with `elections find`, and follow them with `elections follow <id>`. If a race needs a district I do not know, point me to my county registrar's lookup instead of guessing. When everything is set, tell me to run /reload-plugins so the results line and the /elections pane appear. Results are unofficial: never call a race yourself, and present a check mark only as the named source's call.
+
+The collector runs while that terminal tab stays open; every other surface reads its local snapshot. On default permission settings Claude asks you to approve the install steps; that is expected. The prompt sets up the plugin (Option B below); [In Claude Code](#in-claude-code) describes what it shows and the statusline alternative.
+
 ## What you will see
 
 Printed on Sunday, Nov 1, 2026, 9:39 PM PST, from real reads of the sources. Before the polls close, every contest looks like this: no counts yet, and the time its polls close.
@@ -133,6 +141,8 @@ elections list --state CA --level measure  # every California measure, statewide
 
 Two ways, both reading the same local snapshot. Pick one: in a terminal, using both shows the same line twice (once in the statusline, once above the prompt). Both need the global install (`npm i -g election-vibe`); `npx` leaves nothing installed for them to run.
 
+Setup can also be a single pasted prompt: see [One-step setup with Claude](#one-step-setup-with-claude).
+
 ### Option A: the statusline only
 
 `prompt` prints one line for a statusline: your followed contests (or, with none followed, the hot races), one shown and the rest counted (`+N`). A source call or a withdrawn call from the last five minutes is shown first. It reads the local snapshot only: it never fetches, never starts the collector, and never prints an error (with no snapshot it says `no results yet · run: elections collect`). Before any of those contests' polls close it says when the first one does; a snapshot more than 10 minutes old is called out first (`⚠ results 14m old`). Same words as the board: "leading" is never a win, and ✓ marks only a named source's call. `--width N` (default 80), `--color` for color, `--store rehearsal` for the test store.
@@ -302,6 +312,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.

package/dist/cli.js

@@ -216,7 +216,7 @@ var REHEARSAL_SENTENCE = {
 
 // src/http.ts
 import { gunzipSync } from "zlib";
-var USER_AGENT = `ElectionsCompanion/${"0.1.1"} (unofficial results reader; local, no telemetry)`;
+var USER_AGENT = `ElectionsCompanion/${"0.1.3"} (unofficial results reader; local, no telemetry)`;
 function retryAfterMs(header, nowMs) {
   if (!header) return void 0;
   const t = header.trim();
@@ -1943,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) {
@@ -2001,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;
@@ -2139,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) {
@@ -2147,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);
@@ -2239,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;
     }
@@ -2497,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) {
@@ -2508,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}`);
@@ -46285,7 +46335,7 @@ function storeOf(p) {
 }
 async function main(argv, io) {
   if (argv[0] === "--version" || argv[0] === "version") {
-    io.out("0.1.1");
+    io.out("0.1.3");
     return 0;
   }
   const p = parseArgs(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "election-vibe",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",