@pa1nd/horse-browser 0.4.0

package/install.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# One-time setup for horse-browser. Safe to re-run.
+#
+#   1. Fetches Chrome for Testing (a dedicated, automation-purposed browser that
+#      coexists with your daily browser) via @puppeteer/browsers — you install
+#      nothing by hand. Override with HORSE_BROWSER_BIN=/path/to/chromium to use
+#      your own Chromium instead.
+#   2. Writes config + symlinks the `horse-browser` launcher onto your PATH.
+#   3. Launches the browser for the first time (sign into your apps — logins
+#      persist), then smoke-tests the whole chain via browser-harness if present.
+#
+# Env overrides: HORSE_BROWSER_BIN, HORSE_BROWSER_PORT (9223),
+# HORSE_BROWSER_PROFILE (~/.config/horse-browser/profile).
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PORT="${HORSE_BROWSER_PORT:-9223}"
+PROFILE="${HORSE_BROWSER_PROFILE:-$HOME/.config/horse-browser/profile}"
+CONFIG_DIR="$HOME/.config/horse-browser"
+CONFIG="$CONFIG_DIR/config"
+CACHE="$HOME/.cache/horse-browser"
+BINDIR="$HOME/.local/bin"
+EXT="$HERE/extension"
+
+mkdir -p "$CONFIG_DIR" "$BINDIR" "$CACHE"
+
+# 1. browser ──────────────────────────────────────────────────────────────────
+BIN="${HORSE_BROWSER_BIN:-}"
+if [ -n "$BIN" ]; then
+  echo "Using your nominated browser: $BIN"
+else
+  if ! command -v npx >/dev/null 2>&1; then
+    echo "ERROR: npx (Node) not found — needed to fetch Chrome for Testing." >&2
+    echo "  Install Node, or set HORSE_BROWSER_BIN to a Chromium binary, then re-run." >&2
+    exit 1
+  fi
+  echo "Fetching Chrome for Testing via @puppeteer/browsers (one-time, ~170MB)…"
+  out="$(npx -y @puppeteer/browsers install chrome@stable --path "$CACHE")"
+  # output line: "chrome@<version> <path-to-executable>"  (path may contain spaces)
+  BIN="$(printf '%s\n' "$out" | grep '^chrome@' | tail -1 | sed 's/^[^ ]* //')"
+fi
+if [ ! -x "$BIN" ]; then
+  echo "ERROR: browser binary not found / not executable: $BIN" >&2
+  exit 1
+fi
+echo "✓ browser: $BIN"
+
+# 2. config + launcher on PATH ─────────────────────────────────────────────────
+cat > "$CONFIG" <<EOF
+# horse-browser config — written by install.sh
+BROWSER_BIN="$BIN"
+EXTENSION_DIR="$EXT"
+PORT="$PORT"
+PROFILE="$PROFILE"
+EOF
+# When installed via npm (`npm i -g @pa1nd/horse-browser`), npm owns the launcher
+# symlink (package.json "bin") — don't lay down a second, competing one in ~/.local/bin.
+if [ -n "${HORSE_FROM_NPM:-}" ]; then
+  echo "✓ launcher: managed by npm (bin: horse-browser)  (config: $CONFIG)"
+else
+  ln -sf "$HERE/bin/horse-browser" "$BINDIR/horse-browser"
+  echo "✓ launcher: $BINDIR/horse-browser  (config: $CONFIG)"
+  case ":$PATH:" in *":$BINDIR:"*) ;; *) echo "  note: $BINDIR isn't on your PATH — add it so 'horse-browser' resolves";; esac
+fi
+
+# 3. bh_open helpers into browser-harness ───────────────────────────────────────
+# browser-harness auto-loads <workspace>/agent_helpers.py on every call; we append our
+# bh_open/bh_list/bh_switch_tab helpers there so they exist on the first run — no agent
+# installs the recipe by hand. The workspace location varies by version/install (≤0.1.0:
+# <repo>/agent-workspace; 0.1.1+: ~/.config/browser-harness/agent-workspace; or whatever
+# BH_AGENT_WORKSPACE points at) — so instead of guessing, we ASK browser-harness itself
+# where it loads from via its own python (helpers.AGENT_WORKSPACE). Append-once.
+if ! command -v browser-harness >/dev/null 2>&1; then
+  # browser-harness is a separate (Python) prerequisite. In a hand/curl install it's
+  # required up front. Under npm it's a *declared* prereq the user may not have yet — so
+  # warn and finish cleanly (config + Chrome are already in place; re-run setup once
+  # browser-harness is installed to get the bh_open helpers) rather than failing the install.
+  echo "! browser-harness not found on PATH — skipping the bh_open helper sync." >&2
+  echo "  Install it (e.g. 'uv tool install browser-harness'), then re-run setup." >&2
+  [ -n "${HORSE_FROM_NPM:-}" ] && exit 0
+  echo "  (https://github.com/browser-use/browser-harness)" >&2
+  exit 1
+fi
+HELPERS_SRC="$HERE/agent-helpers.py"
+HELPERS_MARKER="# ── horse-browser helpers (installed by horse-browser/install.sh) ──"
+install_helpers_into() {  # $1 = workspace dir; (re)syncs our helpers block — idempotent, so
+  local dst="$1/agent_helpers.py"  # re-running install.sh deploys helper UPDATES, not just the first time.
+  mkdir -p "$1" 2>/dev/null || return 0
+  # drop any previously-installed block (marker → EOF), trim trailing blanks, then re-append
+  if [ -f "$dst" ] && grep -qF "$HELPERS_MARKER" "$dst"; then
+    awk -v m="$HELPERS_MARKER" 'index($0,m){exit} {print}' "$dst" \
+      | awk 'NF{last=NR} {b[NR]=$0} END{for(i=1;i<=last;i++)print b[i]}' > "$dst.tmp" && mv "$dst.tmp" "$dst"
+  fi
+  { [ -s "$dst" ] && printf '\n\n'; printf '%s\n' "$HELPERS_MARKER"; cat "$HELPERS_SRC"; } >> "$dst"
+  echo "✓ synced bh_open helpers → $dst"
+}
+# (a) the workspace browser-harness ACTUALLY loads from — ask it via its own python
+# (the CLI's shebang points at it); helpers.AGENT_WORKSPACE honours BH_AGENT_WORKSPACE and
+# resolves the right default on every version. Fall back to known defaults if the query fails.
+WS_NEW=""
+BHPY="$(head -1 "$(command -v browser-harness)" 2>/dev/null | sed 's/^#!//;s/ .*//')"
+[ -n "$BHPY" ] && [ -x "$BHPY" ] && WS_NEW="$("$BHPY" -c 'from browser_harness.helpers import AGENT_WORKSPACE; print(AGENT_WORKSPACE)' 2>/dev/null)"
+[ -z "$WS_NEW" ] && WS_NEW="${BH_AGENT_WORKSPACE:-$HOME/.config/browser-harness/agent-workspace}"
+install_helpers_into "$WS_NEW"
+# (b) a source checkout's agent-workspace, if present (editable/dev installs)
+BH_DIR="${BROWSER_HARNESS_DIR:-}"
+if [ -z "$BH_DIR" ]; then
+  for c in "$HOME/Developer/browser-harness" "$HOME/browser-harness"; do
+    [ -f "$c/agent-workspace/agent_helpers.py" ] && { BH_DIR="$c"; break; }
+  done
+fi
+[ -n "$BH_DIR" ] && [ "$BH_DIR/agent-workspace" != "$WS_NEW" ] && install_helpers_into "$BH_DIR/agent-workspace"
+
+# Keep the stable symlink that ~/.claude/CLAUDE.md's @-import points at aimed at the current
+# (Python-version-specific) packaged SKILL, so the import never rots across reinstalls. We
+# only refresh the symlink — registering the block in CLAUDE.md is opt-in (./claude-md.sh apply).
+# Under npm we don't reach into ~/.claude from a silent postinstall — the next-steps
+# note tells the user how to wire SKILL.md into their CLAUDE.md themselves.
+if [ -z "${HORSE_FROM_NPM:-}" ]; then
+  "$HERE/claude-md.sh" symlink || echo "  (skipped CLAUDE.md SKILL symlink — see ./claude-md.sh)" >&2
+fi
+
+# 4. first launch + smoke test ─────────────────────────────────────────────────
+# HORSE_SKIP_LAUNCH=1 skips this whole step — used by the "update" path (re-running
+# install for a fresh pull) where relaunching the browser + a 40s smoke test would
+# be noise. Steps 1–3 (browser fetch, config, launcher, helpers) still run.
+if [ -n "${HORSE_SKIP_LAUNCH:-}" ]; then
+  echo "✓ setup refreshed (skipped launch/smoke-test: HORSE_SKIP_LAUNCH set)"
+  echo "  Restart to pick up changes:  horse-browser"
+  exit 0
+fi
+
+echo "Launching for the first time…"
+"$BINDIR/horse-browser" || true
+
+if command -v browser-harness >/dev/null 2>&1; then
+  export BU_CDP_URL="http://127.0.0.1:$PORT"
+  read -r -d '' check <<'PY' || true
+import browser_harness.helpers as _h
+from browser_harness.helpers import cdp
+# our helpers must have loaded AND overridden cdp (so auto-home is active), not just added bh_open
+if not hasattr(_h, "bh_open") or getattr(_h.cdp, "__module__", "") != "browser_harness_agent_helpers":
+    print("NOHELPERS"); raise SystemExit(0)
+sw = next((t["targetId"] for t in cdp("Target.getTargets")["targetInfos"]
+           if t.get("type") == "service_worker"
+           and t.get("url", "").startswith("chrome-extension://")), None)
+if not sw:
+    print("PENDING"); raise SystemExit(0)
+s = cdp("Target.attachToTarget", targetId=sw, flatten=True)["sessionId"]
+r = cdp("Runtime.evaluate", session_id=s,
+        expression="self.listTabs ? self.listTabs('__install_check__') : 'NOFN'",
+        awaitPromise=True, returnByValue=True)
+cdp("Target.detachFromTarget", sessionId=s)
+print("READY" if isinstance(r.get("result", {}).get("value"), list) else "PENDING")
+PY
+  echo "Verifying through browser-harness…"
+  verified=""; result=""
+  for _ in $(seq 1 20); do   # ~40s — must clear the SW's first 30s keepalive tick
+    result="$(printf '%s' "$check" | browser-harness 2>/dev/null | tail -1)"
+    [ "$result" = "READY" ] && { verified=1; break; }
+    [ "$result" = "NOHELPERS" ] && break   # helpers not loading — no point retrying
+    sleep 2
+  done
+  if [ -n "$verified" ]; then
+    echo "✓ verified — bh_open loaded + listTabs() answered over CDP; the extension is live"
+  elif [ "$result" = "NOHELPERS" ]; then
+    echo "! bh_open did NOT load — browser-harness isn't reading the workspace we appended to." >&2
+    echo "  Set BH_AGENT_WORKSPACE to its agent-workspace dir and re-run ./install.sh." >&2
+  else
+    echo "! couldn't confirm the extension within ~40s — check the browser window."
+  fi
+fi
+
+echo
+echo "Next:"
+echo "  • Sign into the apps you want your agents to use — logins persist in $PROFILE"
+echo "  • Point CDP clients at it:  export BU_CDP_URL=http://127.0.0.1:$PORT"
+echo "  • (Re)launch anytime — agents too — with:  horse-browser"

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@pa1nd/horse-browser",
+  "version": "0.4.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "A dedicated, focus-safe browser for AI agents: per-session colored tab groups, a live monitor wall, and a browser-harness drop-in launcher. Log in once — every agent inherits the session, and none of them steals your focus.",
+  "bin": {
+    "horse-browser": "bin/horse-browser"
+  },
+  "files": [
+    "bin",
+    "extension",
+    "agent-helpers.py",
+    "scripts",
+    "install.sh",
+    "claude-md.sh",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "postinstall": "bash scripts/postinstall.sh"
+  },
+  "dependencies": {
+    "@puppeteer/browsers": "^3.0.6"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "license": "MIT",
+  "author": "pA1nD",
+  "homepage": "https://github.com/pA1nD/horse-browser#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pA1nD/horse-browser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pA1nD/horse-browser/issues"
+  },
+  "keywords": [
+    "browser",
+    "cdp",
+    "chrome-devtools",
+    "ai-agents",
+    "browser-automation",
+    "browser-harness",
+    "puppeteer",
+    "tab-groups",
+    "macos"
+  ]
+}

package/scripts/postinstall.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# npm postinstall for @pa1nd/horse-browser.
+#
+# Runs the package's own install.sh in "npm mode" (HORSE_FROM_NPM) so all the
+# battle-tested setup — fetch Chrome for Testing, write ~/.config/horse-browser/config
+# pointing at THIS install's extension/, sync the bh_open helpers if browser-harness is
+# present — lives in exactly one place. npm mode differs only in what npm already owns
+# or what a silent install shouldn't touch: it skips the ~/.local/bin launcher symlink
+# (npm's "bin" field handles it), skips the ~/.claude SKILL symlink, and doesn't launch
+# the browser / smoke-test on install (HORSE_SKIP_LAUNCH).
+#
+# This must NEVER fail `npm install`: a missing browser-harness, an offline Chrome fetch,
+# or any hiccup degrades to a printed next-step, not a broken install. `horse-browser
+# update` re-fetches Chrome later; re-running setup syncs helpers once browser-harness is in.
+set -u
+
+PKG="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PKG" || exit 0   # cwd = package root so `npx @puppeteer/browsers` resolves the bundled fetcher
+
+echo "horse-browser · setting up (Chrome for Testing + config)…"
+HORSE_FROM_NPM=1 HORSE_SKIP_LAUNCH=1 bash "$PKG/install.sh" || \
+  echo "horse-browser · setup didn't fully complete — run 'horse-browser update' to fetch Chrome." >&2
+
+cat <<EOF
+
+horse-browser installed. Next:
+  • Start it (launches the browser, no focus steal):   horse-browser
+  • Sign into your apps once — logins persist for every agent.
+  • Prereq for driving it: browser-harness (a Python tool) —
+      uv tool install browser-harness      # or: pipx install browser-harness
+  • Teach agents the bh_open discipline — add this to your ~/.claude/CLAUDE.md:
+      @$PKG/SKILL.md
+EOF
+exit 0