poltertab 1.9.0 → 1.10.0-beta.2

package/bin/pair-flow.js

@@ -0,0 +1,320 @@
+"use strict";
+
+// Shared pairing-flow primitives used by both `poltertab setup` and
+// `poltertab uploads pair`. These handle the code-exchange protocol but
+// never print command-specific headers — callers print those.
+
+const { addTrustedExtensionId } = require("../mcp-server/uploads-config.js");
+
+// ── port resolution ────────────────────────────────────────────────────────
+
+function resolveWsPort() {
+  try {
+    return require("../mcp-server/config.js").resolvePort();
+  } catch (_) {
+    return 7822;
+  }
+}
+
+// ── server connection ──────────────────────────────────────────────────────
+
+// Resolves with the open socket; rejects with err.code === "ECONNREFUSED"
+// if nothing is listening, or err.code === "ETIMEDOUT" on timeout.
+function tryConnectToServer(port, timeoutMs = 3000) {
+  return new Promise((resolve, reject) => {
+    let WebSocket;
+    try { WebSocket = require("ws"); } catch (_) {
+      reject(new Error("ws module not available")); return;
+    }
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const timer = setTimeout(() => {
+      ws.terminate();
+      reject(Object.assign(new Error("connection timed out"), { code: "ETIMEDOUT" }));
+    }, timeoutMs);
+    ws.on("open", () => { clearTimeout(timer); resolve(ws); });
+    ws.on("error", (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
+// ── pair via running Primary server ────────────────────────────────────────
+
+// Uses the running server as the pair host. The server manages codes and
+// sends uploads_pair_result when the user submits a code.
+//
+// rl — an already-open readline.Interface (shared with the wizard).
+//
+// Returns:
+//   { ok: true, extensionId }              — success
+//   { ok: false, reason: 'skipped' }       — user pressed Enter with no code
+//   { ok: false, reason: 'locked' }        — 5-attempt lockout triggered
+//   { ok: false, reason: 'error'|... }     — connection or server error
+function pairViaRunningServer(serverWs, rl) {
+  return new Promise((resolve) => {
+    let done = false;
+
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      try { serverWs.close(); } catch (_) {}
+      resolve(result);
+    };
+
+    const sigintHandler = () => { finish({ ok: false, reason: "skipped" }); process.exit(0); };
+    process.once("SIGINT", sigintHandler);
+
+    serverWs.on("error", (err) => finish({ ok: false, reason: "error", error: err }));
+    serverWs.on("close", () => {
+      if (!done) finish({ ok: false, reason: "server_disconnected" });
+    });
+
+    serverWs.on("message", (raw) => {
+      let msg;
+      try { msg = JSON.parse(raw); } catch (_) { return; }
+      if (msg.type !== "uploads_pair_result") return;
+
+      if (msg.ok) {
+        finish({ ok: true, extensionId: msg.extensionId });
+      } else if (msg.reason === "locked_out") {
+        const mins = msg.secsLeft ? Math.ceil(msg.secsLeft / 60) : 15;
+        process.stderr.write(
+          `\n  Too many wrong codes. Pairing is locked for ${mins} minutes.\n` +
+          "  (You can still pair during the lockout with: poltertab uploads pair --id <extension-id>)\n",
+        );
+        finish({ ok: false, reason: "locked" });
+      } else if (msg.reason === "expired") {
+        process.stderr.write(
+          "  That code expired — the popup is showing a fresh one. Try again.\n",
+        );
+        askCode();
+      } else if (msg.reason === "config_write_failed") {
+        process.stderr.write(
+          "  Pairing failed — could not save the extension ID to config.json.\n" +
+          "  Check that the file is writable, then try again.\n",
+        );
+        finish({ ok: false, reason: "config_write_failed" });
+      } else {
+        const triesLeft =
+          msg.triesLeft !== undefined ? ` ${msg.triesLeft} tries left.` : "";
+        process.stderr.write(`  That code didn’t match.${triesLeft}\n`);
+        askCode();
+      }
+    });
+
+    function askCode() {
+      rl.question("  Code (Enter to skip): ", (ans) => {
+        const code = (ans || "").trim().toUpperCase().replace(/\s+/g, "");
+        if (!code) { finish({ ok: false, reason: "skipped" }); return; }
+        serverWs.send(JSON.stringify({ type: "uploads_pair_submit", code }));
+      });
+    }
+
+    askCode();
+  });
+}
+
+// ── pair via temporary listener (no Primary running) ──────────────────────
+
+const TEMP_IDLE_MS = 5 * 60 * 1000; // 5-minute idle timeout
+
+// Binds a pairing-only WebSocket server on port. Waits for a
+// chrome-extension:// socket, generates a code for it, then prompts the
+// user to type the code.
+//
+// opts.onStatus(msg) — called when the extension connects; callers use it
+//   to print the "extension connected" status line.
+//
+// Returns { ok: true, extensionId } | { ok: false, reason }.
+async function pairViaTempListener(port, rl, { onStatus } = {}) {
+  const WebSocket = require("ws");
+  const { PairHost } = require("../mcp-server/pair-host.js");
+
+  const pairHost = new PairHost();
+  let idleTimer = null;
+  let server = null;
+  let resolved = false;
+
+  const cleanup = () => {
+    clearTimeout(idleTimer);
+    if (server) {
+      try { server.clients.forEach((c) => c.terminate()); } catch (_) {}
+      try { server.close(); } catch (_) {}
+    }
+  };
+
+  server = new WebSocket.WebSocketServer({ host: "127.0.0.1", port });
+
+  // Wait for the server to start listening before returning.
+  await new Promise((resolve, reject) => {
+    server.on("listening", resolve);
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        reject(Object.assign(new Error(`Port ${port} is in use`), { code: "EADDRINUSE" }));
+      } else {
+        reject(err);
+      }
+    });
+  });
+
+  return new Promise((outerResolve) => {
+    const finish = (result) => {
+      if (resolved) return;
+      resolved = true;
+      cleanup();
+      outerResolve(result);
+    };
+
+    const resetIdle = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => finish({ ok: false, reason: "skipped" }), TEMP_IDLE_MS);
+    };
+
+    const sigintHandler = () => { finish({ ok: false, reason: "skipped" }); process.exit(0); };
+    process.once("SIGINT", sigintHandler);
+
+    resetIdle();
+
+    server.on("connection", (ws, req) => {
+      const origin = (req.headers && req.headers.origin) || null;
+      resetIdle();
+
+      // Only accept chrome-extension:// sockets; silently close everything else.
+      if (!origin || !origin.startsWith("chrome-extension://")) {
+        ws.close(4000, "pairing-only listener");
+        return;
+      }
+
+      ws.on("message", (raw) => {
+        resetIdle();
+        let msg;
+        try { msg = JSON.parse(raw); } catch (_) { return; }
+
+        if (msg.type === "extension_ready") {
+          // Generate a code only on first contact; subsequent pings must not regenerate.
+          if (!pairHost._socketCodes.has(ws)) {
+            pairHost.generateForSocket(ws, origin);
+            if (onStatus) onStatus("extension connected — the code is in its popup");
+            askCode();
+          }
+          return;
+        }
+
+        if (msg.type === "ping") {
+          // Keep-alive — just reset the idle timer (already done above); do NOT regenerate.
+          return;
+        }
+
+        if (msg.type === "pair_code_request") {
+          pairHost.handleCodeRequest(ws, origin);
+          return;
+        }
+
+        // Popup/options asking whether this extension is paired yet.
+        // Reply with uploads_not_paired so the UI can show the pair code.
+        if (msg.type === "uploads_get_config") {
+          try {
+            if (ws.readyState === 1 /* OPEN */) {
+              const reply = { type: "uploads_not_paired", pairCode: pairHost._socketCodes.get(ws) || null };
+              if (msg._replyId !== undefined) reply._replyId = msg._replyId;
+              ws.send(JSON.stringify(reply));
+            }
+          } catch (_) {}
+          return;
+        }
+
+        // Non-pairing message from a Secondary or AI tool dialing in during setup.
+        try {
+          if (ws.readyState === 1 /* OPEN */) {
+            ws.send(JSON.stringify({
+              type: "error",
+              error: "pairing mode — restart your AI tool for browser control",
+            }));
+          }
+        } catch (_) {}
+      });
+
+      ws.on("close", () => pairHost.onSocketClose(ws));
+      ws.on("error", () => pairHost.onSocketClose(ws));
+
+      function askCode() {
+        rl.question("  Code (Enter to skip): ", (ans) => {
+          const code = (ans || "").trim().toUpperCase().replace(/\s+/g, "");
+          if (!code) { finish({ ok: false, reason: "skipped" }); return; }
+
+          const result = pairHost.submitCode(code);
+          if (result.ok) {
+            const bareId = result.extensionId
+              .replace(/^chrome-extension:\/\//, "")
+              .replace(/\/$/, "");
+            let writeErr = null;
+            try { addTrustedExtensionId(bareId); } catch (e) { writeErr = e; }
+            if (writeErr) {
+              // Re-push to the specific extension that matched, not the enclosing socket.
+              if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+                pairHost.generateForSocket(result.extWs, result.extensionId);
+              }
+              process.stderr.write(
+                "  Pairing failed — could not save the extension ID to config.json.\n" +
+                "  Check that the file is writable, then try again.\n",
+              );
+              finish({ ok: false, reason: "config_write_failed" });
+              return;
+            }
+            try {
+              if (result.extWs && result.extWs.readyState === WebSocket.OPEN) {
+                result.extWs.send(JSON.stringify({ type: "uploads_paired" }));
+              }
+            } catch (_) {}
+            finish({ ok: true, extensionId: bareId });
+          } else if (result.reason === "locked_out") {
+            const mins = result.secsLeft ? Math.ceil(result.secsLeft / 60) : 15;
+            process.stderr.write(
+              `\n  Too many wrong codes. Pairing is locked for ${mins} minutes.\n` +
+              "  (You can still pair during the lockout with: poltertab uploads pair --id <extension-id>)\n",
+            );
+            finish({ ok: false, reason: "locked" });
+          } else if (result.reason === "expired") {
+            process.stderr.write(
+              "  That code expired — the popup is showing a fresh one. Try again.\n",
+            );
+            askCode();
+          } else {
+            const triesLeft =
+              result.triesLeft !== undefined ? ` ${result.triesLeft} tries left.` : "";
+            process.stderr.write(`  That code didn’t match.${triesLeft}\n`);
+            askCode();
+          }
+        });
+      }
+    });
+  });
+}
+
+// ── poltertab server probe ─────────────────────────────────────────────────
+
+// Returns true when the server at port is a poltertab Primary.
+// Prevents treating an unrelated WebSocket server as the pair host.
+async function probeIsPoltertab(port) {
+  const http = require("http");
+  return new Promise((resolve) => {
+    const req = http.get({ host: "127.0.0.1", port, path: "/status", timeout: 2000 }, (res) => {
+      let data = "";
+      res.on("data", (c) => { data += c; });
+      res.on("end", () => {
+        try {
+          const body = JSON.parse(data);
+          resolve(body.role === "primary");
+        } catch (_) { resolve(false); }
+      });
+    });
+    req.on("error", () => resolve(false));
+    req.on("timeout", () => { req.destroy(); resolve(false); });
+  });
+}
+
+module.exports = {
+  resolveWsPort,
+  tryConnectToServer,
+  probeIsPoltertab,
+  pairViaRunningServer,
+  pairViaTempListener,
+};

package/bin/poltertab.js

@@ -25,6 +25,11 @@ if (arg === "setup") {
     });
 } else if (arg === "--version" || arg === "-v") {
   console.log(require("../package.json").version);
+} else if (arg === "uploads") {
+  require("./uploads.js").run(process.argv.slice(3)).catch((err) => {
+    console.error(`\n  uploads failed: ${err.message}\n`);
+    process.exit(1);
+  });
 } else if (arg === "--help" || arg === "-h") {
   console.log(`
   poltertab — browser control for AI agents
@@ -32,10 +37,16 @@ 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 uploads   manage upload-allowed folders and view the activity log
     poltertab --version
 
   setup flags:   --global | --project  (skips the prompt)
   doctor flags:  --force (ignore the cached update check), --port <n>
+  uploads:
+    poltertab uploads list             show allowed folders, always-blocked, and status
+    poltertab uploads allow <dir>      add a directory to the allowlist
+    poltertab uploads revoke <dir>     remove a directory from the allowlist
+    poltertab uploads log [-n N]       tail the upload activity log (default: 20 lines)
 
   POLTERTAB_HOME             where memory and downloads live
   POLTERTAB_NO_UPDATE_CHECK  set to disable the npm version check

package/bin/setup.js

@@ -30,6 +30,8 @@ const SNIPPET_SRC = path.join(PKG, "assets", "claude-md-snippet.md");
 // link would get the previous stable extension, because GitHub's
 // /releases/latest skips prereleases — a fresh, correctly-followed setup that
 // lands in version skew.
+const { addAllowlistEntry } = require("../mcp-server/uploads-config.js");
+const { validateAllowlistEntry } = require("../mcp-server/upload-paths.js");
 const updates = require("../mcp-server/update-check.js");
 const EXTENSION_URL = updates.extensionUrl(
   require("../package.json").version,
@@ -39,6 +41,10 @@ const EXTENSION_URL = updates.extensionUrl(
 // "already installed" — this is the whole idempotency check for step 2.
 const MARKER = "<!-- poltertab -->";
 
+// Default folder offered in the uploads prompt. Must never be inside
+// buildAlwaysBlocked — a unit test (H7) pins this.
+const DEFAULT_UPLOAD_FOLDER = "~/Downloads";
+
 const c = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
   bold: (s) => `\x1b[1m${s}\x1b[0m`,
@@ -150,13 +156,163 @@ async function chooseScope(rl) {
   }
 }
 
-async function run(argv = []) {
+// --- Section 1: folder prompt -----------------------------------------------
+
+// Shows the uploads-folder prompt and updates the allowlist.
+// Uses the wizard's existing readline interface (rl); never opens a second one.
+// Caller guarantees stdin is a TTY before calling.
+//
+// Exported for direct unit testing.
+async function runFolderPrompt(rl, {
+  homeDir = os.homedir(),
+  addFn = addAllowlistEntry,
+  validateFn = validateAllowlistEntry,
+} = {}) {
+  console.log(`\n  Let agents upload files from a folder?  [${DEFAULT_UPLOAD_FOLDER}]`);
+  console.log("  Enter = allow ~/Downloads · type another folder · n = skip");
+
+  const MAX_RETRIES = 2;
+  let retries = 0;
+
+  for (;;) {
+    const raw = (await ask(rl, "  > ")).trim();
+
+    if (raw === "n" || raw === "N") {
+      console.log("  – uploads skipped      enable later: poltertab uploads allow <dir>");
+      return;
+    }
+
+    const folderPath = raw === "" ? DEFAULT_UPLOAD_FOLDER : raw;
+
+    const v = validateFn(folderPath, homeDir);
+    if (!v.ok) {
+      console.log(`  ${c.yellow("!")} ${v.errorText}`);
+      retries++;
+      if (retries >= MAX_RETRIES) {
+        console.log("  – uploads skipped (poltertab uploads allow <dir> any time)");
+        return;
+      }
+      // re-ask; the loop continues
+      continue;
+    }
+
+    const added = addFn(folderPath);
+    if (added) {
+      console.log(`  ${c.green("✓")} uploads folder       ${c.dim(folderPath)}`);
+    } else {
+      console.log(`  ${c.green("✓")} uploads folder       ${c.dim(folderPath)} (already set)`);
+    }
+    return;
+  }
+}
+
+// --- Section 3: setup pairing step ------------------------------------------
+
+// Shows the extension instructions and runs the pairing code loop.
+// Uses the wizard's existing readline interface (rl).
+// Caller guarantees stdin is a TTY before calling.
+//
+// opts.pairFlow — injectable pair function for unit tests. Signature:
+//   async (rl) => { ok, extensionId? } | { ok: false, reason }
+// When not injected, the real server/temp-listener flow is used.
+//
+// Exported for direct unit testing.
+async function runSetupPairingStep(rl, { pairFlow } = {}) {
+  const {
+    resolveWsPort,
+    tryConnectToServer,
+    probeIsPoltertab,
+    pairViaRunningServer,
+    pairViaTempListener,
+  } = require("./pair-flow.js");
+
+  console.log(`\n  ${c.bold("Last step — connect the extension:")}`);
+  console.log(`  1. Download and unzip:  ${c.cyan(EXTENSION_URL)}`);
+  console.log("  2. chrome://extensions → turn on Developer mode → Load unpacked → pick the folder");
+  console.log("  3. Click the PolterTab icon in Chrome and type the 4-letter code it shows.");
+  console.log("");
+
+  // Use the injected flow (tests) or the real connection flow.
+  if (!pairFlow) {
+    const port = resolveWsPort();
+    let serverWs = null;
+    try {
+      serverWs = await tryConnectToServer(port);
+      // Verify the server is actually poltertab before treating it as the pair host.
+      if (!(await probeIsPoltertab(port))) {
+        serverWs.terminate();
+        serverWs = null;
+        console.log(
+          `  Port ${port} is in use by something that isn’t poltertab.` +
+          " Close it or set a different port in ~/.poltertab/config.json, then retry.",
+        );
+        return;
+      }
+    } catch (err) {
+      if (err.code !== "ECONNREFUSED" && err.code !== "ENOENT" && err.code !== "ETIMEDOUT") {
+        console.log(`  Could not reach port ${port}: ${err.message}`);
+        return;
+      }
+      // Nothing listening — use temp listener below.
+    }
+
+    if (serverWs) {
+      process.stdout.write("  waiting for the extension to connect…\n");
+      pairFlow = (r) => pairViaRunningServer(serverWs, r);
+    } else {
+      process.stdout.write("  waiting for the extension to connect…\n");
+      pairFlow = async (r) => {
+        try {
+          return await pairViaTempListener(port, r, {
+            onStatus: (msg) => process.stdout.write(`  ${msg}\n`),
+          });
+        } catch (e) {
+          if (e.code === "EADDRINUSE") {
+            console.log(
+              `  Port ${port} is in use by something that isn’t poltertab.` +
+              " Close it or set a different port in ~/.poltertab/config.json, then retry.",
+            );
+            return { ok: false, reason: "skipped" };
+          }
+          throw e;
+        }
+      };
+    }
+  }
+
+  const result = await pairFlow(rl);
+
+  if (result.ok) {
+    const shortId = result.extensionId.slice(0, 8);
+    console.log(
+      `  ${c.green("✓")} paired               extension ${shortId}…` +
+      " · uploads panel is live in the extension",
+    );
+    console.log(c.dim(`      undo: poltertab uploads unpair ${result.extensionId}`));
+  } else if (result.reason === "skipped") {
+    console.log(
+      "  – pairing skipped      run poltertab uploads pair once the extension is loaded",
+    );
+  } else if (result.reason === "locked") {
+    console.log("  Too many wrong codes. Pairing is locked for 15 minutes.");
+  }
+  // Other reasons (error, server_disconnected): silent skip, don't abort setup.
+}
+
+// --- wizard ----------------------------------------------------------------
+
+async function run(argv = [], {
+  home = os.homedir(),
+  cwd = process.cwd(),
+  isTTY = process.stdin.isTTY,
+  rl: injectedRl = null,
+} = {}) {
   console.log(`\n  ${c.bold("PolterTab")} — browser control for AI agents\n`);
 
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  // Open one readline interface for all prompts. If tests inject one, use it.
+  const rl = injectedRl || (isTTY
+    ? readline.createInterface({ input: process.stdin, output: process.stdout })
+    : null);
 
   let scope;
   try {
@@ -164,12 +320,15 @@ async function run(argv = []) {
       ? "global"
       : argv.includes("--project")
         ? "project"
-        : await chooseScope(rl);
-  } finally {
-    rl.close();
+        : rl
+          ? await chooseScope(rl)
+          : (() => { throw new Error("Choose --global or --project when stdin is not a TTY"); })();
+  } catch (err) {
+    if (rl && !injectedRl) rl.close();
+    throw err;
   }
 
-  const paths = resolvePaths(scope);
+  const paths = resolvePaths(scope, { home, cwd });
   console.log("");
 
   // Each step reports what it actually did. A step that fails is reported with
@@ -199,10 +358,31 @@ async function run(argv = []) {
     console.log(c.dim(`      run: claude mcp add --scope ${paths.mcpScope} poltertab poltertab`));
   }
 
-  console.log(`\n  ${c.bold("One step left — install the Chrome extension:")}`);
-  console.log(`  ${c.cyan(EXTENSION_URL)}`);
-  console.log(c.dim("      unzip it, then chrome://extensions → Developer mode → Load unpacked\n"));
-  console.log(`  ${c.dim("Restart Claude Code to pick up the new tools.")}\n`);
+  // Section 1: optional uploads folder prompt (TTY only).
+  if (isTTY && rl) {
+    try {
+      await runFolderPrompt(rl, { homeDir: home });
+    } catch (err) {
+      console.log(`  ${c.yellow("!")} uploads folder skipped — ${err.message}`);
+    }
+  }
+
+  // Section 3: optional pairing step (TTY only).
+  if (isTTY && rl) {
+    try {
+      await runSetupPairingStep(rl);
+    } catch (err) {
+      console.log(`  ${c.yellow("!")} pairing step failed — ${err.message}`);
+    }
+  } else {
+    // Non-TTY: show extension instructions so the output is still useful.
+    console.log(`\n  ${c.bold("One step left — install the Chrome extension:")}`);
+    console.log(`  ${c.cyan(EXTENSION_URL)}`);
+    console.log(c.dim("      unzip it, then chrome://extensions → Developer mode → Load unpacked\n"));
+    console.log(`  ${c.dim("Restart Claude Code to pick up the new tools.")}\n`);
+  }
+
+  if (rl && !injectedRl) rl.close();
 }
 
 module.exports = {
@@ -211,8 +391,11 @@ module.exports = {
   installSkill,
   updateClaudeMd,
   registerServer,
+  runFolderPrompt,
+  runSetupPairingStep,
   MARKER,
   EXTENSION_URL,
+  DEFAULT_UPLOAD_FOLDER,
 };
 
 // Guard so the test suite can require this file without triggering a wizard