poltertab 1.1.0 → 1.2.0

package/README.md

@@ -229,6 +229,41 @@ poltertab/
 └── README.md
 ```
 
+## Staying up to date
+
+```bash
+poltertab doctor
+```
+
+Reports the installed version, whether npm has a newer one, and — the part that
+matters — whether the two halves agree:
+
+```
+  server      1.1.0
+  extension   1.0.0  SKEW      last seen 3m ago
+  bridge      listening on port 7822
+  state       ~/.poltertab
+  npm         1.2.0 available
+```
+
+The npm package updates when you run `npm update -g poltertab`. The extension,
+loaded unpacked, **never updates on its own** — Chrome only auto-updates what came
+from the Web Store. So the interesting failure is not a missing update, it is
+skew: a newer server sending a command an older extension does not implement,
+which surfaces as an element mysteriously not being found.
+
+Both halves ship as one version, so a mismatch is unambiguous. The extension
+reports its version when it connects; the server compares, logs it, and shows it
+in the extension popup. If either half is behind, the first tool response of a
+session says so once, so you hear about it without having to think to check.
+
+Update checks hit `registry.npmjs.org` at most once a day, cached in
+`~/.poltertab/update-check.json`, and never block anything. Set
+`POLTERTAB_NO_UPDATE_CHECK=1` to turn them off — skew detection is local and
+keeps working either way.
+
+`poltertab doctor` exits non-zero on skew, so CI or a shell prompt can act on it.
+
 ## Where your data lives
 
 Nothing the server accumulates is stored inside the package:

package/bin/doctor.js

@@ -0,0 +1,174 @@
+// `poltertab doctor` — what is installed, what is available, and whether the
+// two halves agree.
+//
+// Deliberately works with no server running and no network. Someone runs this
+// because something is already broken, which is the worst time to demand that
+// more things be working.
+
+const fs = require("fs");
+const net = require("net");
+const os = require("os");
+const path = require("path");
+
+const PKG = path.join(__dirname, "..");
+const updates = require(path.join(PKG, "mcp-server", "update-check.js"));
+
+const c = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+
+const home = () =>
+  process.env.POLTERTAB_HOME || path.join(os.homedir(), ".poltertab");
+
+function port() {
+  const i = process.argv.indexOf("--port");
+  if (i !== -1 && process.argv[i + 1]) return Number(process.argv[i + 1]);
+  return Number(process.env.MCP_BROWSER_WS_PORT) || 7822;
+}
+
+// A listening port means a server holds the bridge. Cheaper and more reliable
+// than speaking the protocol just to answer "is anything running".
+function probePort(p, timeout = 700) {
+  return new Promise((resolve) => {
+    const s = net.connect({ port: p, host: "127.0.0.1" });
+    const done = (v) => {
+      s.destroy();
+      resolve(v);
+    };
+    s.setTimeout(timeout);
+    s.once("connect", () => done(true));
+    s.once("timeout", () => done(false));
+    s.once("error", () => done(false));
+  });
+}
+
+const ago = (ts) => {
+  const s = Math.max(0, Math.round((Date.now() - ts) / 1000));
+  if (s < 90) return `${s}s ago`;
+  const m = Math.round(s / 60);
+  if (m < 90) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`;
+};
+
+async function run(argv = []) {
+  const H = home();
+  const own = require(path.join(PKG, "package.json")).version;
+  const row = (k, v) => console.log(`  ${k.padEnd(12)}${v}`);
+
+  console.log(`\n  ${c.bold("PolterTab")} ${c.dim("doctor")}\n`);
+
+  // Start the registry lookup before printing anything, then report everything
+  // local while it is in flight. A cold lookup costs seconds, and blocking the
+  // whole report on it makes doctor look hung exactly when someone is already
+  // suspicious that something is broken.
+  const checking = updates
+    .checkForUpdate({ current: own, home: H, force: argv.includes("--force") })
+    .catch(() => ({ latest: null, updateAvailable: false }));
+
+  // --- versions
+  const seen = updates.readExtensionState(H);
+  const ext = seen && seen.extensionVersion;
+  const sk = updates.skew(own, ext);
+
+  row("server", own);
+
+  if (!ext) {
+    row("extension", c.dim("never seen — has it connected to a server yet?"));
+  } else {
+    row(
+      "extension",
+      `${ext}  ${sk ? c.red("SKEW") : c.green("matches server")}` +
+        c.dim(`  last seen ${ago(seen.seenAt || 0)}`),
+    );
+  }
+
+  const listening = await probePort(port());
+  row(
+    "bridge",
+    listening
+      ? `${c.green("listening")} ${c.dim(`on port ${port()}`)}`
+      : `${c.dim(`nothing on port ${port()}`)}`,
+  );
+
+  row("state", c.dim(H));
+
+  // Now collect the answer we started with.
+  const check = await checking;
+  if (updates.disabled() && !check.latest) {
+    row("npm", c.dim("update check disabled by POLTERTAB_NO_UPDATE_CHECK"));
+  } else if (check.latest) {
+    row(
+      "npm",
+      check.updateAvailable
+        ? `${c.yellow(check.latest)} ${c.dim("available")}`
+        : `${c.green("up to date")} ${c.dim(`(latest is ${check.latest})`)}`,
+    );
+  } else {
+    row("npm", c.dim("could not reach the registry"));
+  }
+
+  // --- what to do about it
+  const todo = [];
+  if (sk && sk.kind === "extension-behind") {
+    todo.push(
+      `${c.red("The extension is older than the server.")} Browser commands can fail\n` +
+        `    in ways that look like a missing element. Download and reload it:\n` +
+        `    ${c.cyan(updates.EXTENSION_URL)}`,
+    );
+  } else if (sk && sk.kind === "server-behind") {
+    todo.push(
+      `${c.yellow("The extension is newer than the server.")} Update the package:\n` +
+        `    ${c.cyan("npm update -g poltertab")}`,
+    );
+  }
+  if (check.updateAvailable) {
+    todo.push(
+      `PolterTab ${c.bold(check.latest)} is available:\n` +
+        `    ${c.cyan("npm update -g poltertab")}\n` +
+        `    ${c.dim("then reload the extension from")} ${c.cyan(updates.EXTENSION_URL)}`,
+    );
+  }
+  if (!listening) {
+    todo.push(
+      `No bridge on port ${port()}. That is expected unless an MCP client has\n` +
+        `    PolterTab running — the server starts when the client starts it.`,
+    );
+  }
+
+  if (todo.length) {
+    console.log(`\n  ${c.bold("To do")}\n`);
+    for (const t of todo) console.log(`  • ${t}`);
+  } else if (!ext) {
+    // Claiming "both halves agree" having never seen one of them is the kind of
+    // all-clear that sends someone looking for the fault somewhere else.
+    console.log(
+      `\n  ${c.yellow("Nothing wrong found, but the extension has never checked in.")}\n` +
+        `  ${c.dim("Install it, open a page, and run doctor again to compare versions:")}\n` +
+        `  ${c.cyan(updates.EXTENSION_URL)}`,
+    );
+  } else {
+    console.log(`\n  ${c.green("Nothing to do — both halves agree and are current.")}`);
+  }
+  console.log("");
+
+  // Non-zero on skew only: an available update is information, but two halves
+  // that disagree is a real fault, and a script may want to act on it.
+  return sk ? 1 : 0;
+}
+
+module.exports = { run, probePort, ago };
+
+if (require.main === module) {
+  run(process.argv.slice(3))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(`\n  doctor failed: ${err.message}\n`);
+      process.exit(1);
+    });
+}

package/bin/poltertab.js

@@ -15,6 +15,14 @@ if (arg === "setup") {
     console.error(`\n  setup failed: ${err.message}\n`);
     process.exit(1);
   });
+} else if (arg === "doctor") {
+  require("./doctor.js")
+    .run(process.argv.slice(3))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(`\n  doctor failed: ${err.message}\n`);
+      process.exit(1);
+    });
 } else if (arg === "--version" || arg === "-v") {
   console.log(require("../package.json").version);
 } else if (arg === "--help" || arg === "-h") {
@@ -23,9 +31,14 @@ if (arg === "setup") {
 
     poltertab           start the MCP server (stdio)
     poltertab setup     install skill, CLAUDE.md section, and MCP registration
+    poltertab doctor    versions, update check, and extension/server skew
     poltertab --version
 
-  setup flags: --global | --project  (skips the prompt)
+  setup flags:   --global | --project  (skips the prompt)
+  doctor flags:  --force (ignore the cached update check), --port <n>
+
+  POLTERTAB_HOME             where memory and downloads live
+  POLTERTAB_NO_UPDATE_CHECK  set to disable the npm version check
 `);
 } else {
   require("../mcp-server/index.js");

package/mcp-server/index.js

@@ -30,6 +30,26 @@ const DOWNLOADS_DIR = path.join(POLTERTAB_HOME, "downloads");
 
 fs.mkdirSync(MEMORY_DIR, { recursive: true });
 
+const updates = require("./update-check.js");
+const OWN_VERSION = require("./../package.json").version;
+
+// Populated when the extension connects; stays null until then, which is itself
+// worth reporting — a skew warning must not fire on "no extension yet".
+let extensionVersion = null;
+let updateState = { latest: null, updateAvailable: false };
+let noticeDelivered = false;
+
+// Fire and forget at startup so the answer is ready by the first tool call.
+// A rejected promise here must never reach the top level.
+if (!updates.disabled()) {
+  updates
+    .checkForUpdate({ current: OWN_VERSION, home: POLTERTAB_HOME })
+    .then((r) => {
+      updateState = r;
+    })
+    .catch(() => {});
+}
+
 // Installs predating the move kept memory beside the code. Copy it forward once
 // so an upgrade does not look like the agent forgot everything it learned.
 // Never overwrite: if both sides have a note for a domain, the one already in
@@ -370,6 +390,27 @@ function setupPrimaryWss(wss) {
               extensionSocket = ws;
               console.error("[PolterTab MCP] Chrome extension connected.");
             }
+            // The extension has always sent its version here and we always
+            // dropped it, so the one mismatch that actually breaks commands was
+            // invisible to both halves.
+            if (msg.version && msg.version !== extensionVersion) {
+              extensionVersion = msg.version;
+              updates.recordExtension(POLTERTAB_HOME, msg.version);
+              const sk = updates.skew(OWN_VERSION, msg.version);
+              console.error(
+                `[PolterTab MCP] Extension v${msg.version} (server v${OWN_VERSION})` +
+                  (sk ? ` — VERSION SKEW: ${sk.kind}` : ""),
+              );
+              // Let the extension show the mismatch in its popup; it cannot
+              // know the server's version otherwise.
+              try {
+                ws.send(
+                  JSON.stringify({ type: "server_version", version: OWN_VERSION }),
+                );
+              } catch (_) {
+                // A socket that died mid-handshake reconnects on its own.
+              }
+            }
           }
           return;
         }
@@ -554,7 +595,9 @@ async function sendCommand(action, params) {
 const server = new Server(
   {
     name: "poltertab-browser-mcp",
-    version: "1.0.0",
+    // Read, not hardcoded: this said "1.0.0" through every release, so the
+    // version the client reported had nothing to do with what was installed.
+    version: OWN_VERSION,
   },
   {
     capabilities: {
@@ -867,7 +910,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   };
 });
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+const handleToolCall = async (request) => {
   const { name, arguments: args } = request.params;
 
   if (!name.startsWith("browser_")) {
@@ -1064,6 +1107,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       ],
     };
   }
+};
+
+// Update and skew notices ride out on the first tool response and never again.
+// Doctor and the extension popup both require the user to already suspect
+// something is wrong; the agent's reply is the one place they are certainly
+// looking. Appended as its own content block so it cannot corrupt a payload
+// something downstream is parsing.
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const result = await handleToolCall(request);
+  if (noticeDelivered) return result;
+
+  const text = updates.notice({
+    current: OWN_VERSION,
+    latest: updateState.latest,
+    updateAvailable: updateState.updateAvailable,
+    skew: updates.skew(OWN_VERSION, extensionVersion),
+  });
+  if (!text) return result;
+
+  noticeDelivered = true;
+  if (!result || !Array.isArray(result.content)) return result;
+  return { ...result, content: [...result.content, { type: "text", text }] };
 });
 
 // Start the server

package/mcp-server/update-check.js

@@ -0,0 +1,242 @@
+// Update and version-skew checking.
+//
+// Two halves ship as one version but update on completely different schedules.
+// The npm package updates when someone remembers to run `npm update -g`; the
+// extension, loaded unpacked, never updates at all — Chrome only auto-updates
+// what came from the Web Store. So the interesting failure is not "an update
+// exists", it is skew: a 1.2 server sending a command a 1.0 extension does not
+// implement. That surfaces as an element mysteriously not being found, which is
+// indistinguishable from the page genuinely not having it.
+//
+// Nothing here may block startup or throw into a caller. A failed update check
+// is a non-event; the browser tools have to keep working with no network.
+
+const fs = require("fs");
+const path = require("path");
+
+const CACHE_FILE = "update-check.json";
+const STATE_FILE = "state.json";
+const OK_TTL_MS = 24 * 60 * 60 * 1000; // a day between successful checks
+const FAIL_TTL_MS = 60 * 60 * 1000; // retry sooner after a failure
+
+// Measured, not guessed: a cold connection to registry.npmjs.org costs ~4s here
+// (DNS + TLS; the body itself arrives in ~5ms). Every check is cold, because it
+// runs once at startup in a fresh process. An earlier 3s value aborted 100% of
+// real lookups while every unit test passed, since those inject a fake fetch —
+// so keep a wide margin over the observed cost. Nothing waits on this: the
+// server fires it and forgets, and doctor prints local state first.
+const FETCH_TIMEOUT_MS = 15000;
+
+// --- semver ----------------------------------------------------------------
+
+function parse(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(
+    String(version || "").trim().replace(/^v/, ""),
+  );
+  if (!m) return null;
+  return {
+    nums: [Number(m[1]), Number(m[2]), Number(m[3])],
+    pre: m[4] ? m[4].split(".") : [],
+  };
+}
+
+// Full semver precedence, because the shortcuts are all wrong in ways that
+// matter here: string compare puts "1.10.0" below "1.9.0", and ignoring the
+// prerelease tail would tell someone on 1.2.0-beta.1 to "update" to 1.1.0.
+function compareVersions(a, b) {
+  const A = parse(a);
+  const B = parse(b);
+  if (!A || !B) return 0;
+
+  for (let i = 0; i < 3; i++) {
+    if (A.nums[i] !== B.nums[i]) return A.nums[i] < B.nums[i] ? -1 : 1;
+  }
+
+  // 1.2.0 outranks every 1.2.0-anything.
+  if (!A.pre.length && B.pre.length) return 1;
+  if (A.pre.length && !B.pre.length) return -1;
+
+  for (let i = 0; i < Math.max(A.pre.length, B.pre.length); i++) {
+    const x = A.pre[i];
+    const y = B.pre[i];
+    if (x === undefined) return -1; // a shorter prerelease ranks lower
+    if (y === undefined) return 1;
+    const xNum = /^\d+$/.test(x);
+    const yNum = /^\d+$/.test(y);
+    if (xNum && yNum) {
+      if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
+    } else if (xNum !== yNum) {
+      return xNum ? -1 : 1; // numeric identifiers rank below alphanumeric
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+const isNewer = (candidate, current) => compareVersions(candidate, current) > 0;
+
+// --- on-disk state ---------------------------------------------------------
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (_) {
+    return null; // absent, unreadable, or truncated — all mean "no state"
+  }
+}
+
+function writeJson(file, data) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    return true;
+  } catch (_) {
+    return false; // a read-only home is not worth failing a browser command
+  }
+}
+
+// The extension only ever talks to a running server, so `poltertab doctor` has
+// no way to ask it directly. Recording the version here means doctor can report
+// it — honestly labelled as last-seen — without any new protocol, and even when
+// no server is running.
+const readExtensionState = (home) => readJson(path.join(home, STATE_FILE));
+
+function recordExtension(home, version, now = Date.now()) {
+  if (!version) return false;
+  return writeJson(path.join(home, STATE_FILE), {
+    extensionVersion: version,
+    seenAt: now,
+  });
+}
+
+// --- registry --------------------------------------------------------------
+
+function disabled() {
+  const v = process.env.POLTERTAB_NO_UPDATE_CHECK;
+  return v !== undefined && v !== "" && v !== "0" && v !== "false";
+}
+
+// Resolves to a version string, or null for any failure at all — offline,
+// 404 (the package is not published yet), timeout, garbage response.
+async function fetchLatest(pkg = "poltertab", fetchImpl = globalThis.fetch) {
+  if (typeof fetchImpl !== "function") return null;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(
+      `https://registry.npmjs.org/${encodeURIComponent(pkg)}/latest`,
+      { signal: ac.signal, headers: { accept: "application/json" } },
+    );
+    if (!res || !res.ok) return null;
+    const body = await res.json();
+    return parse(body && body.version) ? body.version : null;
+  } catch (_) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Cached so a per-session server start does not mean a per-session request.
+// Returns the cached answer without touching the network when it is fresh.
+async function checkForUpdate({
+  current,
+  home,
+  pkg = "poltertab",
+  now = Date.now(),
+  fetchImpl = globalThis.fetch,
+  force = false,
+} = {}) {
+  const cacheFile = path.join(home, CACHE_FILE);
+  const cached = readJson(cacheFile);
+
+  if (!force && cached && typeof cached.checkedAt === "number") {
+    const ttl = cached.latest ? OK_TTL_MS : FAIL_TTL_MS;
+    if (now - cached.checkedAt < ttl) {
+      return {
+        latest: cached.latest || null,
+        updateAvailable: !!cached.latest && isNewer(cached.latest, current),
+        fromCache: true,
+      };
+    }
+  }
+
+  if (!force && disabled()) {
+    return { latest: null, updateAvailable: false, disabled: true };
+  }
+
+  const latest = await fetchLatest(pkg, fetchImpl);
+  writeJson(cacheFile, { checkedAt: now, latest });
+  return {
+    latest,
+    updateAvailable: !!latest && isNewer(latest, current),
+    fromCache: false,
+  };
+}
+
+// --- skew ------------------------------------------------------------------
+
+// Compares only major.minor. A patch-level difference between the two halves is
+// normal — someone updates the package and reloads the extension a minute later
+// — and warning about it would train people to ignore the warning.
+function skew(serverVersion, extensionVersion) {
+  if (!extensionVersion) return null;
+  const s = parse(serverVersion);
+  const e = parse(extensionVersion);
+  if (!s || !e) return null;
+  if (s.nums[0] === e.nums[0] && s.nums[1] === e.nums[1]) return null;
+  const behind = compareVersions(extensionVersion, serverVersion) < 0;
+  return {
+    kind: behind ? "extension-behind" : "server-behind",
+    server: serverVersion,
+    extension: extensionVersion,
+  };
+}
+
+// --- the one-line notice ---------------------------------------------------
+
+const EXTENSION_URL = "https://github.com/abhinav162/poltertab/releases/latest";
+
+// Surfaced once per server process on a tool response, because it is the only
+// channel the user reliably reads: doctor and the popup both require them to
+// already suspect something is wrong.
+function notice({ current, latest, updateAvailable, skew: sk }) {
+  const parts = [];
+  if (sk && sk.kind === "extension-behind") {
+    parts.push(
+      `The Chrome extension (${sk.extension}) is older than this server (${sk.server}) — ` +
+        `browser commands may fail in ways that look like missing elements. ` +
+        `Reload it from ${EXTENSION_URL}`,
+    );
+  } else if (sk && sk.kind === "server-behind") {
+    parts.push(
+      `The Chrome extension (${sk.extension}) is newer than this server (${sk.server}). ` +
+        `Update with: npm update -g poltertab`,
+    );
+  }
+  if (updateAvailable && latest) {
+    parts.push(
+      `PolterTab ${latest} is available (running ${current}). ` +
+        `Update with: npm update -g poltertab && poltertab setup`,
+    );
+  }
+  if (!parts.length) return null;
+  return `[PolterTab] ${parts.join(" ")} (Mention this to the user once, then carry on.)`;
+}
+
+module.exports = {
+  compareVersions,
+  isNewer,
+  parse,
+  readExtensionState,
+  recordExtension,
+  fetchLatest,
+  checkForUpdate,
+  skew,
+  notice,
+  disabled,
+  EXTENSION_URL,
+  CACHE_FILE,
+  STATE_FILE,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poltertab",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Let any AI assistant drive and scrape your existing Chrome profile — no headless browser, no complex setup.",
   "bin": {
     "poltertab": "./bin/poltertab.js"