diggylab 0.1.34 → 0.1.36

package/README.md

@@ -6,9 +6,9 @@ headless Chromium — the Electron app is not involved.
 
 ## Requirements
 
-- Node.js 22+
-- Linux packages: `xvfb`, `x11vnc`, `websockify`, `novnc` (Debian/Ubuntu: `apt install xvfb x11vnc websockify novnc`). The Docker image below bundles them.
-- Chromium for Playwright: run `diggylab install-browser` once after installing the CLI.
+- Node.js 20+
+- Linux packages: `xvfb`, `x11vnc`, `websockify`, `novnc` — run `diggylab install-display` (Debian/Ubuntu) or install them yourself. The Docker image below bundles them.
+- Chromium for Playwright: downloaded automatically during `npm install`; rerun `diggylab install-browser` if that download failed.
 
 ## Install
 
@@ -61,7 +61,8 @@ npm publish apps/desktop-agent/dist-npm --access public
 | `login` | Opens the Facebook login page on a virtual screen and prints a noVNC link + QR code. Log in from your phone; the session is stored encrypted on the server. |
 | `run` | Connects the WebSocket worker, receives assigned scans, scans headlessly, uploads results. |
 | `status` | Shows the config directory, API origin, paired device, and Facebook session state. |
-| `install-browser` | Downloads the Chromium build Playwright needs (one time, ~150 MB). Run it once after installing the CLI. |
+| `install-browser` | Downloads the Chromium build Playwright needs (~150 MB). It also runs during `npm install`, so you only need it if that download failed. |
+| `install-display` | On Debian/Ubuntu, installs `xvfb`, `x11vnc`, `websockify`, and `novnc` for the shared login screen. |
 | `unpair` | Removes device credentials, the Facebook session, and pending scans. |
 
 Useful options: `--api <origin>` (default `https://api.diggylab.com`), `--port` / `--bind` /
@@ -80,6 +81,15 @@ The noVNC URL carries a one-time token, the port is only open while `login` runs
 torn down when the login finishes or times out (10 minutes). If you prefer not to expose a port,
 pass `--bind 127.0.0.1` and forward it over SSH (`ssh -L 6080:127.0.0.1:6080 <server>`).
 
+### Which address the link uses
+
+The link points at the machine's default-route address, so a multi-homed server advertises the
+network it actually reaches the internet through. When that address is private, the agent also looks
+up the public IP and prints a second link for phones on another network — forward the port first.
+
+Pin it explicitly with `--public-host <ip or domain>` or `DIGGYLAB_PUBLIC_HOST`, for example when a
+domain points at the server.
+
 ## Security notes
 
 - `~/.diggylab/key` (mode `600`) encrypts device credentials, the Facebook session, and the

package/cli.js

@@ -3,7 +3,7 @@
 // src/cli/cli.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3, realpathSync } from "node:fs";
 import { hostname, homedir } from "node:os";
 import { dirname as dirname3, join as join4 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -2351,6 +2351,12 @@ function parseCliArgs(argv) {
   return { command, options };
 }
 
+// src/cli/browser-install.ts
+function browserInstallCommands(platform) {
+  const install = ["install", "chromium"];
+  return platform === "linux" ? [["install", "--with-deps", "chromium"], install] : [install];
+}
+
 // src/cli/file-crypto.ts
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -2411,11 +2417,13 @@ function terminalQr(value) {
 // src/cli/virtual-display.ts
 import { spawn } from "node:child_process";
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { mkdirSync as mkdirSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { createConnection } from "node:net";
 import { networkInterfaces } from "node:os";
 import { join as join3 } from "node:path";
 var START_TIMEOUT_MS = 15e3;
+var PUBLIC_IP_TIMEOUT_MS = 3e3;
+var PUBLIC_IP_ENDPOINT = "https://api.ipify.org";
 function waitForPort(host, port, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   return new Promise((resolve, reject) => {
@@ -2437,13 +2445,36 @@ function waitForPort(host, port, timeoutMs) {
     attempt();
   });
 }
-function localAddress() {
-  for (const addresses of Object.values(networkInterfaces())) {
-    for (const address of addresses ?? []) {
-      if (address.family === "IPv4" && !address.internal) return address.address;
+function isPrivateAddress(address) {
+  const [first, second] = address.split(".").map(Number);
+  return first === 10 || first === 127 || first === 169 && second === 254 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 100 && second >= 64 && second <= 127;
+}
+function defaultRouteInterface() {
+  if (process.platform !== "linux") return null;
+  try {
+    for (const line of readFileSync2("/proc/net/route", "utf8").split("\n").slice(1)) {
+      const [iface, destination, , , , , flags] = line.trim().split(/\s+/);
+      if (destination === "00000000" && Number.parseInt(flags ?? "0", 16) & 2) return iface;
     }
+  } catch {
+  }
+  return null;
+}
+function localAddress() {
+  const interfaces = networkInterfaces();
+  const addressOf = (addresses) => addresses?.find((entry) => entry.family === "IPv4" && !entry.internal)?.address ?? null;
+  const preferred = defaultRouteInterface();
+  return (preferred ? addressOf(interfaces[preferred]) : null) ?? Object.values(interfaces).map(addressOf).find((address) => address !== null) ?? "127.0.0.1";
+}
+async function detectPublicIp(fetcher = fetch) {
+  try {
+    const response = await fetcher(PUBLIC_IP_ENDPOINT, { signal: AbortSignal.timeout(PUBLIC_IP_TIMEOUT_MS) });
+    if (!response.ok) return null;
+    const value = (await response.text()).trim();
+    return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(value) ? value : null;
+  } catch {
+    return null;
   }
-  return "127.0.0.1";
 }
 function start(command, args, env, deps) {
   const child = deps.spawnProcess(command, args, env);
@@ -2454,7 +2485,13 @@ function start(command, args, env, deps) {
   return { child, failure };
 }
 async function startVirtualDisplay(options, overrides = {}) {
-  const deps = { spawnProcess: spawn, waitForPort, ...overrides };
+  const deps = {
+    detectPublicIp: () => detectPublicIp(),
+    localAddress,
+    spawnProcess: spawn,
+    waitForPort,
+    ...overrides
+  };
   const bind = options.bind ?? "0.0.0.0";
   const displayNumber = options.displayNumber ?? 99;
   const height = options.height ?? 900;
@@ -2488,10 +2525,13 @@ async function startVirtualDisplay(options, overrides = {}) {
     await stop();
     throw error;
   }
-  const publicHost = options.publicHost ?? localAddress();
+  const publicHost = options.publicHost ?? deps.localAddress();
+  const link = (host) => `http://${host}:${port}/vnc.html?autoconnect=1&token=${encodeURIComponent(token)}`;
+  const publicIp = options.publicHost || !isPrivateAddress(publicHost) ? null : await deps.detectPublicIp();
   return {
+    alternateUrl: publicIp && publicIp !== publicHost ? link(publicIp) : null,
     stop,
-    url: `http://${publicHost}:${port}/vnc.html?autoconnect=1&token=${encodeURIComponent(token)}`
+    url: link(publicHost)
   };
 }
 
@@ -2506,19 +2546,21 @@ Usage:
   diggylab run
   diggylab status
   diggylab install-browser
+  diggylab install-display
   diggylab unpair
 
 Global options:
   --config <directory>   Agent state directory (default ~/.diggylab)
   --api <origin>         API origin (default $DIGGYLAB_API_URL or https://api.diggylab.com)`;
 var MISSING_BROWSER_HINT = "Chromium for Playwright is not installed yet. Run `diggylab install-browser` once.";
+var MISSING_DISPLAY_HINT = "The shared login screen needs Xvfb, x11vnc, websockify, and noVNC. Run `diggylab install-display` (Debian/Ubuntu) or use the Docker image.";
 function agentVersion() {
   let directory = fileURLToPath(new URL(".", import.meta.url));
   for (let depth = 0; depth < 4; depth += 1) {
     const manifest = join4(directory, "package.json");
     if (existsSync2(manifest)) {
       try {
-        const version = JSON.parse(readFileSync2(manifest, "utf8")).version;
+        const version = JSON.parse(readFileSync3(manifest, "utf8")).version;
         if (typeof version === "string" && version) return version;
       } catch {
       }
@@ -2640,18 +2682,23 @@ async function commandLogin(runtime, options, io) {
     if (!needsVirtualDisplay) {
       io.log(process.env.DISPLAY ? `Opening the Facebook login page on display ${process.env.DISPLAY}.` : "Opening the Facebook login page in a browser window.");
     } else {
+      const configuredHost = options.publicHost ?? process.env.DIGGYLAB_PUBLIC_HOST?.trim();
       display = await startVirtualDisplay({
         bind: options.bind,
         displayNumber: options.display,
         novncWeb: options.novncWeb,
         port: options.port,
-        publicHost: options.publicHost,
+        publicHost: configuredHost || void 0,
         tokenDirectory: join4(runtime.directory, "novnc")
       });
       process.env.DISPLAY = `:${options.display ?? 99}`;
       io.log(terminalQr(display.url));
       io.log(`Open this link on your phone, or scan the QR above:
 ${display.url}`);
+      if (display.alternateUrl) {
+        io.log(`Phone on another network? Forward port ${options.port ?? 6080} and use:
+${display.alternateUrl}`);
+      }
       io.log("Log into Facebook on that screen; the agent saves the session automatically.");
     }
     await waitForFacebookLogin(login, LOGIN_TIMEOUT_MS + 6e4);
@@ -2659,6 +2706,10 @@ ${display.url}`);
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (/spawn (?:Xvfb|x11vnc|websockify) ENOENT/.test(message)) {
+      io.error(MISSING_DISPLAY_HINT);
+      return 1;
+    }
     if (/Executable doesn't exist|playwright install/i.test(message)) {
       io.error(MISSING_BROWSER_HINT);
       return 1;
@@ -2677,24 +2728,56 @@ function playwrightCliPath() {
   }
 }
 async function commandInstallBrowser(io) {
+  const soft = process.env.npm_lifecycle_event === "postinstall";
   const cli = playwrightCliPath();
   if (!cli) {
     io.error("Could not locate the bundled Playwright. Reinstall with `npm install -g diggylab@latest`.");
-    return 1;
+    return soft ? 0 : 1;
   }
   io.log("Downloading Chromium for Playwright...");
-  const code = await new Promise((resolve, reject) => {
-    const child = spawn2(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
+  const run = (args) => new Promise((resolve, reject) => {
+    const child = spawn2(process.execPath, [cli, ...args], { stdio: "inherit" });
     child.once("error", reject);
     child.once("exit", (value) => resolve(value ?? 1));
   });
+  let code = 1;
+  for (const [index, args] of browserInstallCommands(process.platform).entries()) {
+    if (index > 0) io.log("Installing the system libraries failed; downloading the browser only...");
+    code = await run(args);
+    if (code === 0) break;
+  }
   if (code !== 0) {
-    io.error("Chromium download failed. Check the network and try again.");
-    return code;
+    io.error(soft ? "Chromium download failed. Run `diggylab install-browser` later." : "Chromium download failed. Check the network and try again.");
+    return soft ? 0 : code;
   }
   io.log("Chromium installed.");
   return 0;
 }
+async function commandInstallDisplay(io) {
+  if (process.platform !== "linux") {
+    io.log("The shared login screen is only needed on a Linux server; desktops open a browser window.");
+    return 0;
+  }
+  if (!existsSync2("/usr/bin/apt-get")) {
+    io.error("Automatic installation supports Debian/Ubuntu. Install xvfb, x11vnc, websockify, and noVNC with your package manager.");
+    return 1;
+  }
+  const sudo = typeof process.getuid === "function" && process.getuid() !== 0 ? ["sudo"] : [];
+  const run = (args) => new Promise((resolve, reject) => {
+    const child = spawn2(args[0], args.slice(1), { stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (value) => resolve(value ?? 1));
+  });
+  io.log("Installing xvfb, x11vnc, websockify, and noVNC...");
+  await run([...sudo, "apt-get", "update"]).catch(() => 1);
+  const code = await run([...sudo, "apt-get", "install", "-y", "xvfb", "x11vnc", "websockify", "novnc"]);
+  if (code !== 0) {
+    io.error("Installation failed. Run the same command with apt manually.");
+    return code;
+  }
+  io.log("Login screen packages installed.");
+  return 0;
+}
 async function commandRun(runtime, io) {
   const stored = await runtime.manager.load();
   if (!stored) {
@@ -2817,12 +2900,13 @@ async function main(argv, io = console) {
     io.log(USAGE);
     return 0;
   }
-  if (!["install-browser", "login", "pair", "run", "status", "unpair"].includes(command)) {
+  if (!["install-browser", "install-display", "login", "pair", "run", "status", "unpair"].includes(command)) {
     io.error(`Unknown command "${command}".`);
     io.error(USAGE);
     return 2;
   }
   if (command === "install-browser") return commandInstallBrowser(io);
+  if (command === "install-display") return commandInstallDisplay(io);
   const runtime = createRuntime(parsed.options);
   switch (command) {
     case "pair":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diggylab",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "DiggyLab Desktop Agent collects posts and information from Facebook Groups on a paired computer. (headless CLI)",
   "type": "module",
   "bin": {
@@ -11,13 +11,16 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=20"
   },
   "dependencies": {
     "playwright": "^1.62.0",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.21.3"
   },
+  "scripts": {
+    "postinstall": "node cli.js install-browser"
+  },
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"