@pxlarified/browser 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@pxlarified/browser",
+  "version": "0.1.0",
+  "description": "Minimal local browser-control CLI for OpenBrowser.",
+  "type": "module",
+  "bin": {
+    "OpenBrowser": "./bin/OpenBrowser.js"
+  },
+  "scripts": {
+    "build": "node scripts/build.js firefox",
+    "build:firefox": "node scripts/build.js firefox",
+    "release:firefox": "node scripts/sign-firefox.js",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "extensions/manifest.json",
+    "extensions/background.js",
+    "extensions/content.js",
+    "dist/extensions/",
+    "scripts/",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "web-ext": "^8.3.0",
+    "yazl": "^3.3.1"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/build.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import yazl from "yazl";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const target = process.argv[2] || "firefox";
+
+if (target !== "firefox") {
+  throw new Error(`Unsupported build target: ${target}`);
+}
+
+const sourceDir = path.join(root, "extensions");
+const buildDir = path.join(root, "build", "firefox-extension");
+const outDir = path.join(root, "dist", "extensions", "firefox");
+const outFile = path.join(outDir, "openbrowser-dev.xpi");
+
+fs.rmSync(buildDir, { recursive: true, force: true });
+fs.mkdirSync(buildDir, { recursive: true });
+fs.mkdirSync(outDir, { recursive: true });
+
+copyFile(path.join(sourceDir, "manifest.json"), path.join(buildDir, "manifest.json"));
+copyFile(path.join(sourceDir, "background.js"), path.join(buildDir, "background.js"));
+copyFile(path.join(sourceDir, "content.js"), path.join(buildDir, "content.js"));
+
+await zipDirectory(buildDir, outFile);
+console.log(`Built ${path.relative(root, outFile)}`);
+
+function copyFile(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.copyFileSync(from, to);
+}
+
+function zipDirectory(directory, destination) {
+  return new Promise((resolve, reject) => {
+    const zip = new yazl.ZipFile();
+    const output = fs.createWriteStream(destination);
+
+    output.on("close", resolve);
+    output.on("error", reject);
+    zip.outputStream.on("error", reject);
+    zip.outputStream.pipe(output);
+
+    for (const file of listFiles(directory)) {
+      zip.addFile(file, path.relative(directory, file).replace(/\\/g, "/"));
+    }
+    zip.end();
+  });
+}
+
+function listFiles(directory) {
+  const result = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...listFiles(full));
+    else result.push(full);
+  }
+  return result;
+}

package/scripts/sign-firefox.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+loadDotEnv(path.join(root, ".env"));
+
+const sourceDir = path.join(root, "extensions");
+const artifactsDir = path.join(root, "dist", "extensions", "firefox", "signed");
+const bundledArtifact = path.join(root, "dist", "extensions", "firefox", "openbrowser.xpi");
+
+if (!process.env.AMO_JWT_ISSUER || !process.env.AMO_JWT_SECRET) {
+  throw new Error("Firefox signing requires AMO_JWT_ISSUER and AMO_JWT_SECRET.");
+}
+
+if (!fs.existsSync(path.join(sourceDir, "manifest.json"))) {
+  throw new Error("Missing Firefox extension source manifest at ./extensions/manifest.json.");
+}
+
+await run(process.execPath, [path.join(root, "scripts", "build.js"), "firefox"]);
+
+fs.rmSync(artifactsDir, { recursive: true, force: true });
+fs.mkdirSync(artifactsDir, { recursive: true });
+
+await run("npx", [
+  "web-ext",
+  "sign",
+  "--source-dir", sourceDir,
+  "--channel", "unlisted",
+  "--api-key", process.env.AMO_JWT_ISSUER,
+  "--api-secret", process.env.AMO_JWT_SECRET,
+  "--artifacts-dir", artifactsDir,
+], { stdio: "inherit" });
+
+const signed = fs.readdirSync(artifactsDir)
+  .filter((file) => file.endsWith(".xpi"))
+  .map((file) => path.join(artifactsDir, file))
+  .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0];
+
+if (!signed) throw new Error("web-ext did not produce a signed .xpi artifact.");
+fs.copyFileSync(signed, bundledArtifact);
+console.log(`Bundled signed Firefox artifact at ${path.relative(root, bundledArtifact)}`);
+
+function loadDotEnv(file) {
+  if (!fs.existsSync(file)) return;
+
+  const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const separator = trimmed.indexOf("=");
+    if (separator === -1) continue;
+
+    const key = trimmed.slice(0, separator).trim();
+    let value = trimmed.slice(separator + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (!process.env[key]) process.env[key] = value;
+  }
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: root, stdio: options.stdio || "inherit", shell: process.platform === "win32" });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${command} ${args.join(" ")} exited with ${code}`));
+    });
+  });
+}

package/src/bridge/client.js

@@ -0,0 +1,87 @@
+import net from "node:net";
+import { bridgeSocketPath } from "../util/paths.js";
+
+export class BridgeUnavailableError extends Error {
+  constructor(browser, cause) {
+    super(
+      `OpenBrowser bridge for ${browser} is not available. Start ${browser}, make sure the OpenBrowser extension is installed, then retry.`,
+    );
+    this.name = "BridgeUnavailableError";
+    this.cause = cause;
+  }
+}
+
+export function sendBridgeCommand(browser, command, args = {}, options = {}) {
+  const socketPath = bridgeSocketPath(browser);
+  const timeoutMs = options.timeoutMs ?? 30_000;
+
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let settled = false;
+    let buffer = "";
+
+    const timer = setTimeout(() => {
+      finish(new Error(`Timed out waiting for ${browser} to complete ${command}.`));
+      socket.destroy();
+    }, timeoutMs);
+
+    function finish(error, value) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(value);
+    }
+
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify({ command, args })}\n`);
+    });
+
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf("\n");
+      if (newline === -1) return;
+      const line = buffer.slice(0, newline);
+      socket.end();
+
+      try {
+        const response = JSON.parse(line);
+        if (!response.ok) {
+          const error = new Error(response.error?.message || "OpenBrowser command failed.");
+          error.code = response.error?.code;
+          finish(error);
+          return;
+        }
+        finish(null, response.result);
+      } catch (error) {
+        finish(error);
+      }
+    });
+
+    socket.on("error", (error) => {
+      if (error.code === "ENOENT" || error.code === "ECONNREFUSED") {
+        finish(new BridgeUnavailableError(browser, error));
+        return;
+      }
+      finish(error);
+    });
+  });
+}
+
+export async function sendBridgeCommandWithRetry(browser, command, args = {}, options = {}) {
+  const attempts = options.attempts ?? 1;
+  const delayMs = options.delayMs ?? 500;
+  let lastError;
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await sendBridgeCommand(browser, command, args, options);
+    } catch (error) {
+      lastError = error;
+      if (!(error instanceof BridgeUnavailableError) || attempt === attempts - 1) break;
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastError;
+}

package/src/browsers/firefox-family.js

@@ -0,0 +1,204 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { EXTENSION_ID, FIREFOX_DEV_ARTIFACT, FIREFOX_SIGNED_ARTIFACT, NATIVE_HOST_NAME } from "../constants.js";
+import { openBrowserHome, packageRoot } from "../util/paths.js";
+
+export class FirefoxFamilyAdapter {
+  constructor(options) {
+    this.name = options.name;
+    this.displayName = options.displayName;
+    this.profileRoots = options.profileRoots;
+    this.launchCommands = options.launchCommands;
+    this.nativeManifestRoots = options.nativeManifestRoots;
+  }
+
+  artifactPath() {
+    const root = packageRoot();
+    const signed = path.join(root, FIREFOX_SIGNED_ARTIFACT);
+    if (fs.existsSync(signed)) return signed;
+    return path.join(root, FIREFOX_DEV_ARTIFACT);
+  }
+
+  async install() {
+    const artifact = this.artifactPath();
+    if (!fs.existsSync(artifact)) {
+      throw new Error(`Missing Firefox extension artifact: ${artifact}. Run npm run build:firefox first.`);
+    }
+
+    const nativeHost = installNativeHost(this.name);
+    const manifests = installNativeMessagingManifests(this.nativeManifestRoots, nativeHost);
+    const profiles = this.findProfiles();
+    if (profiles.length === 0) {
+      throw new Error(`No ${this.displayName} profile was found. Open ${this.displayName} once, then run install again.`);
+    }
+
+    const installedExtensions = [];
+    for (const profile of profiles) {
+      const extensionsDir = path.join(profile, "extensions");
+      fs.mkdirSync(extensionsDir, { recursive: true });
+      const destination = path.join(extensionsDir, `${EXTENSION_ID}.xpi`);
+      fs.copyFileSync(artifact, destination);
+      installedExtensions.push(destination);
+    }
+
+    return {
+      browser: this.name,
+      artifact,
+      signed: path.basename(artifact) === "openbrowser.xpi",
+      profiles,
+      installedExtensions,
+      nativeHost,
+      nativeManifests: manifests,
+      note: "Extension install/update is staged in the profile. Restart the browser if it does not load immediately.",
+    };
+  }
+
+  async launch() {
+    for (const command of this.launchCommands) {
+      try {
+        const child = spawn(command.command, command.args, {
+          detached: true,
+          stdio: "ignore",
+        });
+        child.unref();
+        return true;
+      } catch {
+        // Try the next known command.
+      }
+    }
+    return false;
+  }
+
+  findProfiles() {
+    const roots = this.profileRoots.map((root) => expandHome(root));
+    const profiles = [];
+
+    for (const root of roots) {
+      const profilesIni = path.join(root, "profiles.ini");
+      if (!fs.existsSync(profilesIni)) continue;
+      profiles.push(...readProfilesIni(profilesIni, root));
+    }
+
+    return uniqueExistingDirectories(profiles);
+  }
+}
+
+function installNativeHost(browser) {
+  const source = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../native-host.cjs");
+  const dir = path.join(openBrowserHome(), "native-host");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const hostScript = path.join(dir, "openbrowser-native-host.cjs");
+  fs.copyFileSync(source, hostScript);
+  if (process.platform !== "win32") fs.chmodSync(hostScript, 0o755);
+
+  if (process.platform === "win32") {
+    const cmd = path.join(dir, `openbrowser-native-host-${browser}.cmd`);
+    fs.writeFileSync(cmd, `@echo off\r\nset OPENBROWSER_BROWSER=${browser}\r\n"${process.execPath}" "${hostScript}"\r\n`, "utf8");
+    return cmd;
+  }
+
+  const launcher = path.join(dir, `openbrowser-native-host-${browser}`);
+  fs.writeFileSync(launcher, `#!/bin/sh\nOPENBROWSER_BROWSER=${shellQuote(browser)} exec ${shellQuote(process.execPath)} ${shellQuote(hostScript)}\n`, "utf8");
+  fs.chmodSync(launcher, 0o755);
+  return launcher;
+}
+
+function installNativeMessagingManifests(roots, hostPath) {
+  const manifest = {
+    name: NATIVE_HOST_NAME,
+    description: "OpenBrowser local user-scoped native bridge",
+    path: hostPath,
+    type: "stdio",
+    allowed_extensions: [EXTENSION_ID],
+  };
+
+  const written = [];
+  const manifestDirectoryName = process.platform === "linux" ? "native-messaging-hosts" : "NativeMessagingHosts";
+  for (const root of roots.map((entry) => expandHome(entry))) {
+    const dir = path.join(root, manifestDirectoryName);
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+      const target = path.join(dir, `${NATIVE_HOST_NAME}.json`);
+      fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+      written.push(target);
+    } catch {
+      // Some candidate vendor directories may not be writable or useful on this platform.
+    }
+  }
+
+  if (process.platform === "win32") {
+    const manifestDir = path.join(openBrowserHome(), "native-messaging-hosts");
+    fs.mkdirSync(manifestDir, { recursive: true });
+    const manifestPath = path.join(manifestDir, `${NATIVE_HOST_NAME}.json`);
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    written.push(manifestPath);
+    try {
+      spawn("reg", [
+        "add",
+        `HKCU\\Software\\Mozilla\\NativeMessagingHosts\\${NATIVE_HOST_NAME}`,
+        "/ve",
+        "/t",
+        "REG_SZ",
+        "/d",
+        manifestPath,
+        "/f",
+      ], { stdio: "ignore" });
+    } catch {}
+  }
+
+  return written;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function expandHome(value) {
+  if (!value.startsWith("~")) return value;
+  return path.join(os.homedir(), value.slice(2));
+}
+
+function readProfilesIni(file, root) {
+  const text = fs.readFileSync(file, "utf8");
+  const sections = [];
+  let current = null;
+
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith(";") || line.startsWith("#")) continue;
+    const section = line.match(/^\[(.+)]$/);
+    if (section) {
+      current = { name: section[1] };
+      sections.push(current);
+      continue;
+    }
+    const separator = line.indexOf("=");
+    if (separator === -1 || !current) continue;
+    current[line.slice(0, separator)] = line.slice(separator + 1);
+  }
+
+  const profileSections = sections.filter((section) => section.name.startsWith("Profile") && section.Path);
+  profileSections.sort((a, b) => Number(b.Default || 0) - Number(a.Default || 0));
+
+  return profileSections.map((section) => {
+    if (section.IsRelative === "1") return path.join(root, section.Path);
+    return section.Path;
+  });
+}
+
+function uniqueExistingDirectories(paths) {
+  const seen = new Set();
+  const result = [];
+  for (const candidate of paths) {
+    const resolved = path.resolve(candidate);
+    if (seen.has(resolved)) continue;
+    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) continue;
+    seen.add(resolved);
+    result.push(resolved);
+  }
+  return result;
+}

package/src/browsers/registry.js

@@ -0,0 +1,19 @@
+import { ZenBrowserAdapter } from "./zen.js";
+import { DEFAULT_BROWSER } from "../constants.js";
+
+const adapters = new Map([
+  ["zen", new ZenBrowserAdapter()],
+]);
+
+export function supportedBrowsers() {
+  return [...adapters.keys()];
+}
+
+export function resolveBrowser(browser) {
+  const name = (browser || DEFAULT_BROWSER).toLowerCase();
+  const adapter = adapters.get(name);
+  if (!adapter) {
+    throw new Error(`Unsupported browser: ${browser}. Supported browsers: ${supportedBrowsers().join(", ")}.`);
+  }
+  return adapter;
+}

package/src/browsers/zen.js

@@ -0,0 +1,70 @@
+import os from "node:os";
+import path from "node:path";
+import { FirefoxFamilyAdapter } from "./firefox-family.js";
+
+function platformProfileRoots() {
+  if (process.platform === "darwin") {
+    return [
+      "~/Library/Application Support/zen",
+      "~/Library/Application Support/Zen",
+      "~/Library/Application Support/Zen Browser",
+    ];
+  }
+
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return [path.join(appData, "zen"), path.join(appData, "Zen"), path.join(appData, "Zen Browser")];
+  }
+
+  return ["~/.zen", "~/.zen-browser", "~/.mozilla/zen"];
+}
+
+function platformNativeManifestRoots() {
+  if (process.platform === "darwin") {
+    return [
+      "~/Library/Application Support/Mozilla",
+      "~/Library/Application Support/zen",
+      "~/Library/Application Support/Zen",
+      "~/Library/Application Support/Zen Browser",
+    ];
+  }
+
+  if (process.platform === "win32") {
+    return [];
+  }
+
+  return ["~/.mozilla", "~/.zen", "~/.zen-browser"];
+}
+
+function platformLaunchCommands() {
+  if (process.platform === "darwin") {
+    return [
+      { command: "open", args: ["-a", "Zen Browser"] },
+      { command: "open", args: ["-a", "Zen"] },
+    ];
+  }
+
+  if (process.platform === "win32") {
+    return [
+      { command: "cmd", args: ["/c", "start", "", "zen"] },
+      { command: "cmd", args: ["/c", "start", "", "zen-browser"] },
+    ];
+  }
+
+  return [
+    { command: "zen-browser", args: [] },
+    { command: "zen", args: [] },
+  ];
+}
+
+export class ZenBrowserAdapter extends FirefoxFamilyAdapter {
+  constructor() {
+    super({
+      name: "zen",
+      displayName: "Zen",
+      profileRoots: platformProfileRoots(),
+      nativeManifestRoots: platformNativeManifestRoots(),
+      launchCommands: platformLaunchCommands(),
+    });
+  }
+}