browserctrl 0.4.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeRaowl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# browserctrl
+
+> AI agents drive your real Chrome via MCP — the `kubectl` for your logged-in browser.
+
+`npm i -g browserctrl` installs the [BrowserCtrl](https://github.com/DeRaowl/browserctrl) CLI on macOS and Linux. This package is a thin launcher; the native binary ships in a platform-specific sub-package that npm picks automatically based on your host.
+
+## Install
+
+```sh
+npm i -g browserctrl
+```
+
+You'll need:
+
+- **Node.js ≥ 20.10** (you have it; you're running npm)
+- **Chrome ≥ 120** with the BrowserCtrl extension loaded
+- **macOS (Apple Silicon)** or **Linux x64 / arm64**
+
+## Quick start
+
+```sh
+browserctrl init      # one-shot wizard: state dir + manifests + MCP host config + pair code
+browserctrl diagnose  # if something looks off
+```
+
+The wizard auto-detects Claude Desktop, Cursor, Windsurf, Zed, and Claude Code and offers to register `browserctrl` as an MCP server in each.
+
+## How it works
+
+`browserctrl` declares 3 optional dependencies — one per supported platform:
+
+```json
+"optionalDependencies": {
+  "browserctrl-darwin-arm64": "0.4.0-alpha.1",
+  "browserctrl-linux-x64":    "0.4.0-alpha.1",
+  "browserctrl-linux-arm64":  "0.4.0-alpha.1"
+}
+```
+
+Each sub-package declares its own `os` + `cpu` in its manifest, so npm only installs the one matching your host — the others are skipped silently. The meta package's `bin/browserctrl.js` then resolves whichever sub-package landed on disk and spawns its native binary.
+
+Same pattern as esbuild, swc, biome, and prisma.
+
+## Troubleshooting
+
+**`unsupported platform <os>-<arch>`** — `npm i -g browserctrl` supports darwin-arm64 (Apple Silicon), linux-x64, and linux-arm64. Intel Mac and Windows users should install from source: `git clone` + `make build`.
+
+**`platform package ... is not installed`** — your install ran with `--no-optional` or `--ignore-scripts`, or hit an offline cache without the platform pkg. Retry: `npm rebuild browserctrl` or `npm install -g browserctrl --include=optional`.
+
+## Links
+
+- **Repository:** https://github.com/DeRaowl/browserctrl
+- **Issues:** https://github.com/DeRaowl/browserctrl/issues
+- **License:** MIT OR Apache-2.0

package/bin/browserctrl.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Tiny launcher: resolve the platform-specific sub-package npm installed
+// and spawn the native binary it carries.
+//
+// npm picks the right sub-package via `optionalDependencies` + `os` /
+// `cpu` specifiers — only the one matching the host installs cleanly;
+// the others are skipped silently. At runtime we walk the candidate
+// list, find the one that actually resolves, and exec its binary.
+//
+// spawnSync (not spawn) so the Node process stays around as the child's
+// parent — that way Ctrl-C in the user's terminal reliably signals the
+// native binary, and the exit code propagates cleanly. The extra Node
+// frame is ~5 ms.
+
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const { resolveBinary } = require("../lib/resolve.js");
+
+let binaryPath;
+try {
+  binaryPath = resolveBinary(process.platform, process.arch);
+} catch (err) {
+  process.stderr.write(`browserctrl: ${err.message}\n`);
+  process.exit(127);
+}
+
+const result = spawnSync(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  // Pass through the current env so BROWSERCTRL_* / NODE_ENV / etc.
+  // reach the native binary unchanged.
+});
+
+if (result.error) {
+  process.stderr.write(`browserctrl: failed to spawn binary: ${result.error.message}\n`);
+  process.exit(1);
+}
+
+// `result.status` is null when the child was killed by a signal; exit
+// with the conventional 128 + signo so callers see a normal SIGINT-ish
+// exit when the user hit Ctrl-C.
+if (result.status === null && result.signal) {
+  const signoMap = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1, SIGQUIT: 3 };
+  process.exit(128 + (signoMap[result.signal] || 0));
+}
+
+process.exit(result.status ?? 1);

package/lib/resolve.js

@@ -0,0 +1,59 @@
+// Platform-binary resolution for the `browserctrl` meta package.
+//
+// npm installs one of `browserctrl-darwin-arm64`, `browserctrl-linux-x64`,
+// or `browserctrl-linux-arm64` based on the host's `process.platform` +
+// `process.arch` (the platform packages declare `os` and `cpu` in their
+// manifests, and the meta lists them as `optionalDependencies` so the
+// non-matching ones skip cleanly). At runtime we resolve whichever one
+// landed on disk and point at its bundled binary.
+
+const path = require("node:path");
+
+const PLATFORM_MAP = {
+  "darwin-arm64": "browserctrl-darwin-arm64",
+  "linux-x64": "browserctrl-linux-x64",
+  "linux-arm64": "browserctrl-linux-arm64",
+};
+
+/**
+ * Returns the absolute path to the native `browserctrl` binary the
+ * matching platform package shipped. Throws with a readable message if
+ * (a) the host's platform isn't shipped, or (b) the matching sub-package
+ * isn't installed (e.g., `--no-optional` or an offline install that
+ * skipped optionalDependencies).
+ */
+function resolveBinary(platform, arch) {
+  const key = `${platform}-${arch}`;
+  const pkg = PLATFORM_MAP[key];
+
+  if (!pkg) {
+    throw new Error(
+      `unsupported platform ${key}. Shipped: darwin-arm64 (Apple Silicon), linux-x64, linux-arm64. ` +
+        "Intel Mac and Windows users should install from source: " +
+        "https://github.com/DeRaowl/browserctrl#install",
+    );
+  }
+
+  // `require.resolve` walks the same module-resolution algorithm npm
+  // used when picking which optional dep to install. If the package
+  // isn't on disk this throws MODULE_NOT_FOUND — we catch that and
+  // remap to a friendlier error.
+  let pkgJsonPath;
+  try {
+    pkgJsonPath = require.resolve(`${pkg}/package.json`);
+  } catch (err) {
+    if (err && err.code === "MODULE_NOT_FOUND") {
+      throw new Error(
+        `platform package ${pkg} is not installed. ` +
+          "If you installed with `--no-optional` or `--ignore-scripts`, retry with the defaults. " +
+          "Otherwise: npm rebuild browserctrl",
+      );
+    }
+    throw err;
+  }
+
+  const binName = platform === "win32" ? "browserctrl.exe" : "browserctrl";
+  return path.join(path.dirname(pkgJsonPath), binName);
+}
+
+module.exports = { resolveBinary, PLATFORM_MAP };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "browserctrl",
+  "version": "0.4.0-alpha.1",
+  "description": "AI agents drive your real Chrome via MCP — the kubectl for your logged-in browser.",
+  "keywords": [
+    "browser",
+    "chrome",
+    "automation",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "claude",
+    "cursor",
+    "playwright",
+    "extension"
+  ],
+  "homepage": "https://github.com/DeRaowl/browserctrl#readme",
+  "bugs": {
+    "url": "https://github.com/DeRaowl/browserctrl/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DeRaowl/browserctrl.git",
+    "directory": "npm/meta"
+  },
+  "license": "MIT OR Apache-2.0",
+  "bin": {
+    "browserctrl": "bin/browserctrl.js"
+  },
+  "scripts": {
+    "prepublishOnly": "cp ../../LICENSE LICENSE",
+    "test": "node --test test/"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "optionalDependencies": {
+    "browserctrl-darwin-arm64": "0.4.0-alpha.1",
+    "browserctrl-linux-x64": "0.4.0-alpha.1",
+    "browserctrl-linux-arm64": "0.4.0-alpha.1"
+  }
+}