@phnx-labs/browser-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+First standalone release of `@phnx-labs/browser-cli`, extracted from the
+`agents browser` subsystem of agents-cli.
+
+- Drive Chromium-family browsers (Chrome, Brave, Edge, Chromium, Comet) over the
+  Chrome DevTools Protocol, Firefox over WebDriver BiDi, and Arc over Apple
+  Events on macOS.
+- Manage browser processes, tasks, tabs and network capture through a local IPC
+  service; keep a local action ledger and `browser sessions` history.
+- Machine-local profiles with `cdp://`, `bidi=firefox-bidi://` and `ssh://`
+  endpoints; bind a task to a remote device with `--device` on `start`.
+- No runtime dependency on agents-cli. The inherited context descriptor, event
+  stream and shared on-disk paths are the only seams (see docs/integration.md).
+- Ship per-platform binaries (macOS arm64/x64, Linux arm64/x64, Windows x64) as
+  optional dependencies behind a small Node launcher. The build minifies,
+  obfuscates and bytecode-compiles the bundle; the npm tarball carries no
+  TypeScript sources or source maps. `scripts/verify-compiled.mjs` gates each
+  binary in CI.

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Phoenix Horizon, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,144 @@
+# browser-cli
+
+`browser` drives real browsers from the command line — the same Chrome, Brave,
+Edge, Chromium, Comet, Firefox or Arc you use by hand, with their profiles and
+cookies. It manages the browser process, tabs and network capture through a
+local IPC service, so a sequence of commands (`start`, `navigate`, `screenshot`,
+`done`) acts on one persistent session instead of a fresh headless launch each
+time. It talks to Chromium-family browsers over the Chrome DevTools Protocol,
+Firefox over WebDriver BiDi, and Arc over Apple Events, and it can drive a
+browser on another machine over SSH.
+
+## Install
+
+```sh
+npm install -g @phnx-labs/browser-cli
+browser --version
+```
+
+npm installs a small Node launcher plus one compiled binary for your platform
+(macOS arm64/x64, Linux arm64/x64, or Windows x64). No TypeScript sources or
+source maps ship in the package.
+
+## First run
+
+```sh
+browser profiles create work --browser chromium
+browser start --profile work
+browser navigate https://example.com --profile work
+browser screenshot -o shot.png
+browser done --profile work
+```
+
+`start` launches (or attaches to) the browser for a profile and opens a **task** —
+a named browsing context with its own tabs and capture ledger. Page verbs like
+`navigate` and `screenshot` attach to that task: they resolve the caller's live
+task, or take `--task <id>` to pick one explicitly. `done` closes the task's
+tabs; `browser stop` stops the whole service.
+
+Run `browser --help` for the full verb list and `browser <verb> --help` for its
+options.
+
+## Profiles and endpoints
+
+A **profile** names a browser, where it runs, and how to reach it. Profiles are
+machine-local and stored under `~/.agents/devices/<machine>/agents.yaml`.
+
+```sh
+browser profiles create work --browser chrome            # local Chrome, auto-assigned CDP port
+browser profiles create hl --browser chromium --headless # headless Chromium
+browser profiles list
+```
+
+Each profile resolves to an endpoint:
+
+- `cdp://127.0.0.1:9222` — a Chromium-family browser over the DevTools Protocol.
+- `bidi=firefox-bidi://127.0.0.1:9674` — Firefox over WebDriver BiDi.
+- `ssh://user@box?port=9222` — a browser on a remote host reached over SSH.
+
+## Remote browsers
+
+Bind a task to a browser on another machine with `--device` on `start`:
+
+```sh
+browser start --device box --profile work
+browser navigate https://example.com
+browser screenshot -o shot.png
+```
+
+`--device <alias>` resolves against `~/.ssh/config`, and against an inherited
+context descriptor when the CLI runs under agents-cli. browser-cli itself does
+not read a fleet registry. Use `--device local` to force the task onto this
+machine. The device is bound once at `start`; page verbs run against the task's
+bound device, so `--device` is only valid there.
+
+## Using it through agents-cli
+
+Agents CLI ships `agents browser` as a thin consumer of this binary. It forwards
+every verb unchanged and adds the concerns it owns: fleet device discovery
+(`--device` becomes an SSH target), agent-session identity, remote-control
+consent, and cross-machine session history. The seam between the two — the
+inherited context descriptor, the event stream, and the shared on-disk paths —
+is documented in [docs/integration.md](docs/integration.md). The command
+reference is [docs/browser.md](docs/browser.md).
+
+## Platform support
+
+| Platform | Architectures |
+| --- | --- |
+| macOS | arm64, x64 |
+| Linux | arm64, x64 |
+| Windows | x64 |
+
+Chromium CDP, Firefox BiDi and SSH endpoints work on all three. Native Arc
+control is macOS-only. Safari is not supported.
+
+## Troubleshooting
+
+- **Headless on Linux.** A headless Chromium or Brave needs the usual shared
+  libraries (fonts, `libnss3`, `libatk`, `libgbm`, and friends). Install your
+  distribution's chromium package to pull them in; a missing library shows up as
+  the browser process exiting immediately after `start`.
+- **Port already in use.** Each profile binds a debugging port. If `start`
+  reports a squatted port, another browser or a stale process holds it — stop it,
+  or create the profile with a different `--endpoint`.
+- **Comet and Arc.** Comet is driven as a Chromium-family browser over CDP and
+  works best as an attach-only profile against a browser you already launched.
+  Arc is always attach-only and reuses an open tab or Space rather than creating
+  one; it is macOS-only.
+- **Service state.** `browser status` shows whether the IPC service is running
+  and lists active tasks. `browser stop` shuts the service down.
+
+## Development
+
+```sh
+bash scripts/install.sh   # install dependencies
+bash scripts/test.sh      # typecheck + tests
+bash scripts/build.sh     # compile this platform's binary into dist/
+```
+
+`scripts/build.sh` bundles and minifies `src/`, obfuscates the bundle, then
+compiles a bytecode binary per target. `scripts/verify-compiled.mjs` asserts the
+shipped artifact behaves correctly and that source string literals do not survive
+in plaintext. Run `dist/<platform>-<arch>/browser` directly during development.
+
+Release with the repository's own script:
+
+```sh
+bash scripts/release.sh                 # print the release plan (dry run)
+secrets exec npmjs.com -- bash scripts/release.sh --confirm
+```
+
+Release requires a clean linked worktree at the reviewed `origin/main` commit. It
+builds every platform, verifies packed file lists and immutable package
+integrity, publishes the launcher and per-platform packages, and checks a
+registry install.
+
+Minification, obfuscation and bytecode compilation raise the bar for casual
+inspection; they are not a guarantee against reverse engineering. Keep
+credentials out of the binary.
+
+## License
+
+Functional Source License 1.1 with an Apache 2.0 future grant
+([FSL-1.1-Apache-2.0](LICENSE)).

package/bin/browser.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+'use strict';
+const { spawn } = require('node:child_process');
+const name = '@phnx-labs/browser-cli-' + process.platform + '-' + process.arch;
+let executable;
+try {
+  executable = require.resolve(name + '/' + (process.platform === 'win32' ? 'browser.exe' : 'browser'));
+} catch {
+  console.error('browser: missing ' + name + '. Reinstall @phnx-labs/browser-cli with optional dependencies enabled.');
+  process.exit(1);
+}
+const stdio = ['inherit', 'inherit', 'inherit'];
+for (const key of ['BROWSER_CONTEXT_FD', 'BROWSER_EVENTS_FD']) {
+  if (process.env[key] === undefined) continue;
+  const fd = Number(process.env[key]);
+  if (!Number.isInteger(fd) || fd < 3 || fd > 16) {
+    console.error('browser: invalid ' + key);
+    process.exit(1);
+  }
+  while (stdio.length <= fd) stdio.push('ignore');
+  stdio[fd] = fd;
+}
+const child = spawn(executable, process.argv.slice(2), { stdio, windowsHide: true });
+child.on('error', error => { console.error('browser: ' + error.message); process.exitCode = 1; });
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => child.kill(signal));
+}
+child.on('exit', (code, signal) => {
+  if (signal && process.platform !== 'win32') {
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code === null ? 1 : code;
+  }
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@phnx-labs/browser-cli",
+  "version": "0.1.0",
+  "description": "Drive real browsers over CDP, WebDriver BiDi and native Arc",
+  "type": "module",
+  "bin": {
+    "browser": "bin/browser.cjs"
+  },
+  "files": [
+    "bin/browser.cjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phnx-labs/browser-cli.git"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "test": "bash scripts/test.sh"
+  },
+  "optionalDependencies": {
+    "@phnx-labs/browser-cli-darwin-arm64": "0.1.0",
+    "@phnx-labs/browser-cli-darwin-x64": "0.1.0",
+    "@phnx-labs/browser-cli-linux-arm64": "0.1.0",
+    "@phnx-labs/browser-cli-linux-x64": "0.1.0",
+    "@phnx-labs/browser-cli-win32-x64": "0.1.0"
+  },
+  "devDependencies": {
+    "@inquirer/prompts": "8.5.2",
+    "@types/bun": "1.3.10",
+    "@types/node": "26.1.0",
+    "@types/ws": "8.18.1",
+    "bun": "1.4.1",
+    "chalk": "5.6.2",
+    "commander": "15.0.0",
+    "javascript-obfuscator": "5.7.0",
+    "proper-lockfile": "4.1.2",
+    "typescript": "6.0.3",
+    "ws": "8.21.0",
+    "yaml": "2.9.0"
+  }
+}