@generativereality/browser-automation 0.4.19 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/dist/index.js +23 -12
- package/package.json +1 -1
- package/scripts/release.sh +40 -7
- package/scripts/sync-plugin.sh +53 -32
- package/skills/browser/SKILL.md +62 -12
- package/skills/browser/references/input-and-forms.md +5 -4
- package/skills/browser/references/page-recipes.md +125 -0
- package/skills/browser/references/windows.md +60 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "browser-automation",
|
|
3
3
|
"description": "Daemonless, per-tab-isolated browser automation for Claude Code via the `browser-automation` CLI. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.5.1",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "generativereality"
|
|
7
7
|
},
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { execFileSync, spawn, spawnSync } from "node:child_process";
|
|
|
9
9
|
import { fileURLToPath } from "node:url";
|
|
10
10
|
//#region package.json
|
|
11
11
|
var name = "@generativereality/browser-automation";
|
|
12
|
-
var version = "0.
|
|
12
|
+
var version = "0.5.1";
|
|
13
13
|
var description = "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.";
|
|
14
14
|
var package_default = {
|
|
15
15
|
name,
|
|
@@ -345,8 +345,7 @@ async function withPage(targetId, fn) {
|
|
|
345
345
|
* CDP `Input.*` events (and the user-activation they grant) are dropped by the
|
|
346
346
|
* renderer when the tab's `visibilityState` is `hidden` — which it is whenever
|
|
347
347
|
* the automation Chrome window isn't the frontmost OS window (the normal case:
|
|
348
|
-
* the user is in their terminal). `
|
|
349
|
-
* the tab still reports `hidden`. `Emulation.setFocusEmulationEnabled` forces
|
|
348
|
+
* the user is in their terminal). `Emulation.setFocusEmulationEnabled` forces
|
|
350
349
|
* the renderer to treat itself as focused+visible regardless of the real window
|
|
351
350
|
* state (this is how Playwright drives backgrounded/headless pages), and
|
|
352
351
|
* `Page.setWebLifecycleState: active` un-throttles a frozen tab. Together they
|
|
@@ -354,9 +353,20 @@ async function withPage(targetId, fn) {
|
|
|
354
353
|
* drag actually lands and grants user activation — which activation-gated flows
|
|
355
354
|
* (e.g. drop-zone uploaders that only start work inside a user gesture) require.
|
|
356
355
|
*
|
|
357
|
-
*
|
|
356
|
+
* Both are best-effort: older Chrome builds may not expose every command.
|
|
357
|
+
*
|
|
358
|
+
* ⛔ **No `Page.bringToFront` here, and do not add it back.** It used to be the
|
|
359
|
+
* first call, and it makes this tab the SELECTED tab of its Chrome window: the
|
|
360
|
+
* tab the person had showing goes `hidden`, and the next time they bring Chrome
|
|
361
|
+
* forward and type, the keys land in the automated tab. That happened for real
|
|
362
|
+
* (issue #28, 2026-10-14): an agent's quiet `focus` left its Outlook calendar
|
|
363
|
+
* selected, and the person's typing created events named "A", "d", "w", "a",
|
|
364
|
+
* "cti" in their real calendar. It bought nothing: measured the same day on
|
|
365
|
+
* Chrome 155 / macOS 27, a background tab with ONLY the two commands below
|
|
366
|
+
* reports `visible` + `hasFocus()`, takes a CDP mouse click as
|
|
367
|
+
* `isTrusted: true` and a CDP key, and the person's tab stays the visible one
|
|
368
|
+
* throughout and after the probe tab is closed. */
|
|
358
369
|
async function forceForeground(s) {
|
|
359
|
-
await s.send("Page.bringToFront").catch(() => {});
|
|
360
370
|
await s.send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => {});
|
|
361
371
|
await s.send("Page.setWebLifecycleState", { state: "active" }).catch(() => {});
|
|
362
372
|
}
|
|
@@ -1701,7 +1711,7 @@ const clickCommand = define({
|
|
|
1701
1711
|
},
|
|
1702
1712
|
trusted: {
|
|
1703
1713
|
type: "boolean",
|
|
1704
|
-
description: "Dispatch a real, genuinely-trusted CDP mouse click (Input.dispatchMouseEvent) at the element instead of the default JS-dispatched el.click().
|
|
1714
|
+
description: "Dispatch a real, genuinely-trusted CDP mouse click (Input.dispatchMouseEvent) at the element instead of the default JS-dispatched el.click(). Makes the renderer treat the tab as focused+visible and WAITS until it reports so (CDP input no-ops on a backgrounded tab) — without selecting the tab in its window, so the person's own tab keeps their typing, then waits for the element to be actionable (stable position + unoccluded hit-test) before pressing — mirroring Playwright. Use for widgets that demand isTrusted events AND animate in: artdeco dropdown menu items (LinkedIn More→Connect), Radix dropdown/popover triggers, cmdk comboboxes — which a default click, or an immediate trusted click on stale coordinates, only highlights without firing."
|
|
1705
1715
|
}
|
|
1706
1716
|
},
|
|
1707
1717
|
async run(ctx) {
|
|
@@ -1929,8 +1939,9 @@ const sleep$2 = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
|
1929
1939
|
* # The two ways, and why the quiet one is the default
|
|
1930
1940
|
*
|
|
1931
1941
|
* `Emulation.setFocusEmulationEnabled` makes the renderer treat itself as
|
|
1932
|
-
* focused and visible whatever the real window is doing — no window moves,
|
|
1933
|
-
*
|
|
1942
|
+
* focused and visible whatever the real window is doing — no window moves, the
|
|
1943
|
+
* operator's frontmost app is undisturbed, and the tab their window SHOWS stays
|
|
1944
|
+
* the one it showed (it did not until issue #28: see forceForeground). That is what this does by
|
|
1934
1945
|
* default, and it is how Playwright drives backgrounded pages.
|
|
1935
1946
|
*
|
|
1936
1947
|
* `--raise` additionally calls `Target.activateTarget`, which genuinely brings
|
|
@@ -1941,14 +1952,14 @@ const sleep$2 = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
|
1941
1952
|
*
|
|
1942
1953
|
* # It reports the outcome, not the acceptance
|
|
1943
1954
|
*
|
|
1944
|
-
*
|
|
1955
|
+
* Both CDP commands are best-effort — an older Chrome may not expose one —
|
|
1945
1956
|
* so "sent" says nothing. This reads `document.hasFocus()` and
|
|
1946
1957
|
* `visibilityState` back afterwards and prints what it actually achieved,
|
|
1947
1958
|
* naming what it could not confirm rather than printing a tick over it.
|
|
1948
1959
|
*/
|
|
1949
1960
|
const focusCommand = define({
|
|
1950
1961
|
name: "focus",
|
|
1951
|
-
description: "Make a tab report itself focused + visible, so pages that defer work while hidden (rendering, polling, charts, video) behave as if watched. Quiet by default — no window moves
|
|
1962
|
+
description: "Make a tab report itself focused + visible, so pages that defer work while hidden (rendering, polling, charts, video) behave as if watched. Quiet by default — no window moves, the operator keeps their frontmost app, and their window keeps showing its own tab. Add --raise to genuinely bring the tab to the front, which DOES take the screen.",
|
|
1952
1963
|
args: {
|
|
1953
1964
|
...targetArgs,
|
|
1954
1965
|
raise: {
|
|
@@ -2381,7 +2392,7 @@ function guessMime(p) {
|
|
|
2381
2392
|
}
|
|
2382
2393
|
const dropCommand = define({
|
|
2383
2394
|
name: "drop",
|
|
2384
|
-
description: "Drop local file(s) onto a drop-zone element by ref — for uploaders wired to drag-and-drop (a `drop` listener reading `e.dataTransfer.files`) rather than an <input type=file>. Default fires a genuinely-trusted CDP drag sequence (Input.dispatchDragEvent) carrying the real files from disk:
|
|
2395
|
+
description: "Drop local file(s) onto a drop-zone element by ref — for uploaders wired to drag-and-drop (a `drop` listener reading `e.dataTransfer.files`) rather than an <input type=file>. Default fires a genuinely-trusted CDP drag sequence (Input.dispatchDragEvent) carrying the real files from disk: makes the renderer treat the tab as focused+visible (without selecting it in its window), waits for that, waits for the target to be actionable (stable + unoccluded), then dragEnter→dragOver→drop — mirroring `click --trusted`. Use --js for a synthetic (isTrusted=false) DataTransfer drop that does NOT steal focus, for zones that accept synthetic events. For a static <input type=file> use `setfiles`; for a button that opens a file chooser use `upload`.",
|
|
2385
2396
|
args: {
|
|
2386
2397
|
...targetArgs,
|
|
2387
2398
|
on: {
|
|
@@ -2394,7 +2405,7 @@ const dropCommand = define({
|
|
|
2394
2405
|
},
|
|
2395
2406
|
js: {
|
|
2396
2407
|
type: "boolean",
|
|
2397
|
-
description: "Dispatch a synthetic (isTrusted=false) DataTransfer drop instead of the trusted CDP path.
|
|
2408
|
+
description: "Dispatch a synthetic (isTrusted=false) DataTransfer drop instead of the trusted CDP path. Needs no focus emulation. Injects each file's bytes into the page to build the File objects. Use for drop zones that accept synthetic events; falls short on zones that gate on isTrusted."
|
|
2398
2409
|
}
|
|
2399
2410
|
},
|
|
2400
2411
|
async run(ctx) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@generativereality/browser-automation",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/scripts/release.sh
CHANGED
|
@@ -31,6 +31,9 @@ PKG=@generativereality/browser-automation
|
|
|
31
31
|
die() { echo "Error: $*" >&2; exit 1; }
|
|
32
32
|
say() { printf '\n== %s\n' "$*"; }
|
|
33
33
|
|
|
34
|
+
# HTTP status of one version on the registry: 200 published, 404 not.
|
|
35
|
+
registry_code() { curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/${PKG/\//%2F}/$1"; }
|
|
36
|
+
|
|
34
37
|
last_tag() { git -C "$ROOT" describe --tags --abbrev=0 "$BASE" 2>/dev/null || true; }
|
|
35
38
|
|
|
36
39
|
plan() {
|
|
@@ -78,7 +81,13 @@ cut() {
|
|
|
78
81
|
[0-9]*.[0-9]*.[0-9]*) next="$want" ;;
|
|
79
82
|
*) die "unknown version '$want'" ;;
|
|
80
83
|
esac
|
|
84
|
+
# A tag is never moved or re-pushed, and a version is never re-used: on
|
|
85
|
+
# 2026-09-23 v0.4.15 was re-created on another commit after it had published,
|
|
86
|
+
# so npm's 0.4.15 and the git tag still name different commits. Ask the remote
|
|
87
|
+
# and the registry, not just this clone's tags.
|
|
81
88
|
git rev-parse -q --verify "refs/tags/v$next" >/dev/null && die "v$next already exists"
|
|
89
|
+
[ -z "$(git ls-remote origin "refs/tags/v$next")" ] || die "v$next already exists on origin"
|
|
90
|
+
[ "$(registry_code "$next")" = 404 ] || die "$next is already on npm (or the registry did not answer 404) — pick another version"
|
|
82
91
|
[ -z "$(git log --format=%h "$(last_tag)..HEAD")" ] && die "nothing unreleased since $(last_tag)"
|
|
83
92
|
|
|
84
93
|
say "Releasing $cur -> $next"
|
|
@@ -134,8 +143,19 @@ TXT
|
|
|
134
143
|
finish() {
|
|
135
144
|
git fetch -q origin --tags
|
|
136
145
|
local tag; tag="$(last_tag)"; local v="${tag#v}"
|
|
137
|
-
|
|
138
|
-
|
|
146
|
+
# GitHub's run LISTING lags the run: at 0.4.18 `gh run list --branch <tag>`
|
|
147
|
+
# answered nothing for minutes while `gh run view <id>` said success — so
|
|
148
|
+
# finish died "no release run" twice on a release that had shipped. Retry.
|
|
149
|
+
# The run for the tag's CURRENT commit: a tag that was ever re-pushed has a
|
|
150
|
+
# run per push (v0.4.15 had two), and the newest is not necessarily it.
|
|
151
|
+
local sha; sha="$(git rev-parse "$tag^{commit}")"
|
|
152
|
+
local run=""
|
|
153
|
+
for _ in $(seq 1 18); do
|
|
154
|
+
run="$(gh run list --repo "$REPO" --workflow release.yml --branch "$tag" --limit 10 --json databaseId,headSha --jq "[.[] | select(.headSha == \"$sha\")][0].databaseId // empty")"
|
|
155
|
+
[ -n "$run" ] && break
|
|
156
|
+
sleep 10
|
|
157
|
+
done
|
|
158
|
+
[ -n "$run" ] || die "no release run for $tag after 3 minutes"
|
|
139
159
|
|
|
140
160
|
say "Waiting for the release run of $tag"
|
|
141
161
|
local s
|
|
@@ -153,13 +173,17 @@ finish() {
|
|
|
153
173
|
# The registry, not `npm view`: publishing reports success minutes before
|
|
154
174
|
# the version is served (3.5 min for 0.4.13), and `npm view` also caches.
|
|
155
175
|
say "Waiting for $v on the registry"
|
|
156
|
-
local name="${PKG/\//%2F}"
|
|
157
176
|
for _ in $(seq 1 60); do
|
|
158
|
-
[ "$(
|
|
177
|
+
[ "$(registry_code "$v")" = 200 ] && break
|
|
159
178
|
sleep 10
|
|
160
179
|
done
|
|
161
|
-
[ "$(
|
|
162
|
-
|
|
180
|
+
[ "$(registry_code "$v")" = 200 ] || die "$v not on the registry after 10 minutes"
|
|
181
|
+
# And it is the tag's commit: npm records the commit it packed as gitHead.
|
|
182
|
+
# This is how 0.4.15's mismatch was found, two weeks late.
|
|
183
|
+
local head
|
|
184
|
+
head="$(curl -s "https://registry.npmjs.org/${PKG/\//%2F}/$v" | node -pe 'JSON.parse(require("fs").readFileSync(0)).gitHead')"
|
|
185
|
+
[ "$head" = "$sha" ] || die "npm's $v was packed from $head, but $tag is $sha — stop and tell the maintainer"
|
|
186
|
+
echo " $PKG@$v is live, packed from $tag ($(git rev-parse --short "$sha"))"
|
|
163
187
|
|
|
164
188
|
say "Plugin marketplace"
|
|
165
189
|
# Sync from the released tag, not from whatever this checkout has.
|
|
@@ -170,7 +194,16 @@ finish() {
|
|
|
170
194
|
BA_PLUGIN_SOURCE="$RELEASE_WT" bash "$ROOT/scripts/sync-plugin.sh"
|
|
171
195
|
|
|
172
196
|
say "This machine"
|
|
173
|
-
|
|
197
|
+
# --prefer-online: npm caches the package's metadata, so right after a
|
|
198
|
+
# publish `npm install -g pkg@<new>` answers ETARGET "No matching version"
|
|
199
|
+
# for a version the registry is already serving (0.4.17: the version
|
|
200
|
+
# endpoint said 200, install said notarget). And say when it fails — this
|
|
201
|
+
# line used to swallow that and print nothing.
|
|
202
|
+
if npm install -g --prefer-online "$PKG@$v" >/dev/null 2>&1; then
|
|
203
|
+
echo " installed $(browser-automation --version)"
|
|
204
|
+
else
|
|
205
|
+
echo " ⚠ could not install $PKG@$v globally — run: npm install -g --prefer-online $PKG@$v" >&2
|
|
206
|
+
fi
|
|
174
207
|
|
|
175
208
|
say "Downstream — not done by this script"
|
|
176
209
|
cat <<TXT
|
package/scripts/sync-plugin.sh
CHANGED
|
@@ -13,7 +13,11 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
|
|
13
13
|
# finish` points it at the released tag, so what ships is what was tagged —
|
|
14
14
|
# while still running THIS copy of the script (an old tag's copy lacks fixes).
|
|
15
15
|
REPO_ROOT="${BA_PLUGIN_SOURCE:-$(dirname "$SCRIPT_DIR")}"
|
|
16
|
-
|
|
16
|
+
# Beside the MAIN checkout, not beside this script: a release run from a linked
|
|
17
|
+
# worktree (scratch dirs, .claude/worktrees/…) has no ../plugins next to it —
|
|
18
|
+
# 0.5.0's finish died there. --git-common-dir is the main checkout's .git.
|
|
19
|
+
MAIN_CHECKOUT="$(dirname "$(git -C "$SCRIPT_DIR" rev-parse --path-format=absolute --git-common-dir)")"
|
|
20
|
+
PLUGINS_DIR="${BA_PLUGINS_DIR:-$MAIN_CHECKOUT/../plugins}" # override for tests
|
|
17
21
|
CHECK_ONLY=false
|
|
18
22
|
[ "${1:-}" = "--check" ] && CHECK_ONLY=true
|
|
19
23
|
|
|
@@ -55,46 +59,63 @@ if [ "$CHECK_ONLY" = true ]; then
|
|
|
55
59
|
exit 0
|
|
56
60
|
fi
|
|
57
61
|
|
|
58
|
-
#
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
62
|
+
# **Start from the latest marketplace, then copy on top.** Never commit first and
|
|
63
|
+
# rebase after: the payload is generated from a release, so the only thing a
|
|
64
|
+
# rebase can conflict with is an OLDER sync of this same plugin made from another
|
|
65
|
+
# checkout — which is exactly what happened at 0.4.16 (0.4.15 had been synced
|
|
66
|
+
# elsewhere). Copying onto an up-to-date tree has nothing to conflict with.
|
|
67
|
+
cd "$PLUGINS_DIR"
|
|
68
|
+
BRANCH="$(git rev-parse --abbrev-ref HEAD)"
|
|
69
|
+
[ "$BRANCH" = "main" ] || { echo "Error: plugins repo is on '$BRANCH', not main. Not syncing into a branch." >&2; exit 1; }
|
|
70
|
+
# Other plugins sync from here too. Their uncommitted or unpushed work is not
|
|
71
|
+
# ours to carry, drop or rebase — stop and say so.
|
|
72
|
+
if [ -n "$(git status --porcelain)" ]; then
|
|
73
|
+
echo "Error: $PLUGINS_DIR has uncommitted changes; not syncing on top of someone's work:" >&2
|
|
74
|
+
git status --short >&2; exit 1
|
|
75
|
+
fi
|
|
76
|
+
git fetch -q origin main
|
|
77
|
+
if [ -n "$(git rev-list origin/main..HEAD)" ]; then
|
|
78
|
+
echo "Error: $PLUGINS_DIR has commits not on origin/main — push or drop them first:" >&2
|
|
79
|
+
git log --oneline origin/main..HEAD >&2; exit 1
|
|
80
|
+
fi
|
|
63
81
|
|
|
64
|
-
|
|
65
|
-
|
|
82
|
+
SRC_VERSION="$(node -p "require('$REPO_ROOT/.claude-plugin/plugin.json').version")"
|
|
83
|
+
sync_on_top() {
|
|
84
|
+
git merge -q --ff-only origin/main
|
|
85
|
+
# Never replace a newer published plugin with an older one.
|
|
86
|
+
local have
|
|
87
|
+
have="$(node -p "try{require('./plugins/browser-automation/.claude-plugin/plugin.json').version}catch{''}" 2>/dev/null)"
|
|
88
|
+
if [ -n "$have" ] && [ "$(printf '%s\n%s\n' "$have" "$SRC_VERSION" | sort -V | tail -1)" != "$SRC_VERSION" ]; then
|
|
89
|
+
echo "Error: the marketplace already has browser-automation $have, newer than $SRC_VERSION. Not downgrading." >&2
|
|
90
|
+
exit 1
|
|
91
|
+
fi
|
|
92
|
+
for rel in "${PAYLOAD_FILES[@]}"; do
|
|
93
|
+
mkdir -p "$(dirname "plugins/browser-automation/$rel")"
|
|
94
|
+
cp -p "$REPO_ROOT/$rel" "plugins/browser-automation/$rel"
|
|
95
|
+
done
|
|
96
|
+
# Remove .mcp.json if it lingers from an older sync (no MCP server any more).
|
|
97
|
+
rm -f "plugins/browser-automation/.mcp.json"
|
|
98
|
+
}
|
|
66
99
|
|
|
67
|
-
|
|
100
|
+
sync_on_top
|
|
68
101
|
if git diff --quiet -- plugins/browser-automation && [ -z "$(git ls-files --others --exclude-standard -- plugins/browser-automation)" ]; then
|
|
69
102
|
echo "Plugins repo already up to date"
|
|
70
103
|
exit 0
|
|
71
104
|
fi
|
|
72
|
-
|
|
73
|
-
# **Other plugins publish to this repo too.** The 0.4.14 sync was rejected
|
|
74
|
-
# because a cctabs sync had landed on origin/main in between — the marketplace
|
|
75
|
-
# is shared, so "behind origin" is the normal state, not an error. Commit ONLY
|
|
76
|
-
# our directory, then replay it on top of whatever arrived and push; our
|
|
77
|
-
# commit touches nothing outside plugins/browser-automation, so the rebase
|
|
78
|
-
# cannot conflict with another plugin's sync. It can conflict with a sync of
|
|
79
|
-
# THIS plugin from another checkout — then stop rather than guess.
|
|
80
|
-
BRANCH="$(git rev-parse --abbrev-ref HEAD)"
|
|
81
|
-
if [ "$BRANCH" != "main" ]; then
|
|
82
|
-
echo "Error: plugins repo is on '$BRANCH', not main. Not syncing into a branch." >&2
|
|
83
|
-
exit 1
|
|
84
|
-
fi
|
|
85
|
-
VERSION="$(node -p "require('$REPO_ROOT/package.json').version" 2>/dev/null || echo '?')"
|
|
86
105
|
git add plugins/browser-automation
|
|
87
|
-
git commit -q -m "chore: sync browser-automation plugin to $
|
|
106
|
+
git commit -q -m "chore: sync browser-automation plugin to $SRC_VERSION"
|
|
107
|
+
|
|
108
|
+
# Someone may push between our fetch and our push. Then drop OUR commit (we
|
|
109
|
+
# verified above that nothing else was local), take theirs, and copy again.
|
|
88
110
|
for attempt in 1 2 3; do
|
|
89
|
-
git fetch -q origin main
|
|
90
|
-
if ! git rebase -q origin/main; then
|
|
91
|
-
git rebase --abort
|
|
92
|
-
echo "Error: rebasing the sync onto origin/main conflicted — something else changed" >&2
|
|
93
|
-
echo " plugins/browser-automation. Resolve in $PLUGINS_DIR, then push." >&2
|
|
94
|
-
exit 1
|
|
95
|
-
fi
|
|
96
111
|
git push -q origin main && break
|
|
97
112
|
[ "$attempt" = 3 ] && { echo "Error: push kept being rejected; see $PLUGINS_DIR." >&2; exit 1; }
|
|
113
|
+
git fetch -q origin main
|
|
114
|
+
git reset -q --hard origin/main
|
|
115
|
+
sync_on_top
|
|
116
|
+
git diff --quiet -- plugins/browser-automation && { echo "Plugins repo already up to date"; exit 0; }
|
|
117
|
+
git add plugins/browser-automation
|
|
118
|
+
git commit -q -m "chore: sync browser-automation plugin to $SRC_VERSION"
|
|
98
119
|
done
|
|
99
120
|
|
|
100
|
-
echo "Synced browser-automation to plugins repo"
|
|
121
|
+
echo "Synced browser-automation $SRC_VERSION to plugins repo"
|
package/skills/browser/SKILL.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: browser
|
|
3
3
|
description: Drive a real browser from the shell via the `browser-automation` CLI — open pages, click, type, fill forms, read text, capture snapshots, all against one shared headed Chrome with a persistent profile (cookies + extensions survive). Daemonless and per-tab isolated, so many parallel Claude Code sessions can each drive their own tab without interfering. Use whenever you need to interact with a web page (especially behind a login) and there's no CLI or API that already covers the task.
|
|
4
|
-
allowed-tools: Bash(browser-automation:*) Bash(
|
|
4
|
+
allowed-tools: Bash(browser-automation list:*) Bash(browser-automation snapshot:*) Bash(browser-automation read:*) Bash(browser-automation screenshot:*) Bash(browser-automation doctor:*) Bash(browser-automation port:*)
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Browser automation via `browser-automation`
|
|
@@ -40,12 +40,23 @@ file under `~/.browser-automation/sessions/`.
|
|
|
40
40
|
background, and nothing fronts a tab as a side effect of ordinary driving:
|
|
41
41
|
`goto`, `read`, `snapshot`, `fill`, `eval`, `screenshot` all leave your
|
|
42
42
|
frontmost app alone. Three things deliberately do more, and only these:
|
|
43
|
-
`focus`
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
`focus` unless a person needs to see
|
|
43
|
+
`focus`, `click --trusted` and `drop` make the RENDERER believe the tab is
|
|
44
|
+
focused and visible (focus emulation; CDP input grants no user activation to
|
|
45
|
+
a renderer that considers itself hidden) — **no window moves, and the tab the
|
|
46
|
+
person's window shows stays the one it showed**. `focus --raise` calls
|
|
47
|
+
`Target.activateTarget` and **genuinely takes the operator's screen**; it is
|
|
48
|
+
the only one that does. Reach for plain `focus` unless a person needs to see
|
|
49
|
+
the tab.
|
|
50
|
+
- ⛔ **Selecting a tab moves where the person's typing goes.** Whatever tab a
|
|
51
|
+
Chrome window shows is where their keystrokes land the next time they bring
|
|
52
|
+
Chrome forward. Before CLI 0.5.1 a plain `focus` (and `click --trusted`,
|
|
53
|
+
`drop`) also selected the session's tab in its window; an agent's quiet
|
|
54
|
+
`focus` left an Outlook calendar selected, and the person's typing created
|
|
55
|
+
events named "A", "d", "w", "a", "cti" in their real calendar (issue #28,
|
|
56
|
+
2026-10-14). So: `--show` and `focus --raise` are the only commands that
|
|
57
|
+
select a tab on purpose — use them when a person is meant to look, and on an
|
|
58
|
+
older CLI avoid `focus` on a tab where stray keys do damage (calendars, chat,
|
|
59
|
+
editors).
|
|
49
60
|
- **Show the work: `--show` / `BAC_SHOW_TAB=1`.** A person watching the Chrome
|
|
50
61
|
window sees whichever tab is SELECTED, and the tabs you work in are background
|
|
51
62
|
tabs — so by default they watch one stale page while titles change elsewhere
|
|
@@ -216,9 +227,9 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
216
227
|
those refs for one action → re-snapshot. "ref not found" means re-snapshot.
|
|
217
228
|
- **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched by
|
|
218
229
|
default, so widgets that demand trusted events ignore them. **For clicks, pass
|
|
219
|
-
`--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`,
|
|
220
|
-
|
|
221
|
-
|
|
230
|
+
`--trusted`** — it dispatches a real CDP `Input.dispatchMouseEvent`, makes the
|
|
231
|
+
renderer treat the tab as focused+visible (CDP input no-ops on a backgrounded
|
|
232
|
+
tab; the person's window keeps showing its own tab) and waits for the element to be actionable (stable position +
|
|
222
233
|
unoccluded hit-test) before pressing. For fills, pass `--native` to drive
|
|
223
234
|
character insertion through CDP `Input.insertText`, which fires real
|
|
224
235
|
`beforeinput`/`input` events.
|
|
@@ -260,8 +271,8 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
260
271
|
underlying export URL/endpoint and use `--url`, or the site's API.
|
|
261
272
|
- **File upload — three paths:** `setfiles [ref] [path…]` for a static `<input type=file>`;
|
|
262
273
|
`upload --click [ref] [path…]` for a button that opens a native file chooser; `drop [ref]
|
|
263
|
-
[path…]` for a drag-and-drop zone with no file input (`--js` for a synthetic drop that
|
|
264
|
-
|
|
274
|
+
[path…]` for a drag-and-drop zone with no file input (`--js` for a synthetic drop that needs
|
|
275
|
+
no focus emulation). ⛔ **Upload once, verify by `snapshot`/`screenshot`, and don't blindly
|
|
265
276
|
retry** — each successful run adds another attachment, and apps reset `files` to 0 after
|
|
266
277
|
consuming it. How each path works and when to pick it:
|
|
267
278
|
[`references/input-and-forms.md`](references/input-and-forms.md).
|
|
@@ -295,6 +306,38 @@ There's no `state-save`/`state-load` to manage — the profile *is* the auth sto
|
|
|
295
306
|
Chrome by hand on Windows any more; that was the workaround for CLIs older than
|
|
296
307
|
0.4.18, which refused with `unsupported OS MINGW64_NT`. A cold start brings
|
|
297
308
|
Chrome to the front once, on every platform.
|
|
309
|
+
→ **Read [`references/windows.md`](references/windows.md)** before driving from
|
|
310
|
+
Git Bash or PowerShell: the CLI is often not on `PATH` there, `list` cannot tell
|
|
311
|
+
you whether a browser is up, and `|` in an `eval` breaks through the `.cmd` shim.
|
|
312
|
+
- ⛔ **Every `eval` on a session shares ONE JavaScript context**, so a `const` from
|
|
313
|
+
an earlier call is still declared, and reusing the name fails with
|
|
314
|
+
`SyntaxError: Identifier 'b' has already been declared`, which reads as a
|
|
315
|
+
quoting problem in the expression you just wrote. ⇒ Wrap every `eval` body in
|
|
316
|
+
an IIFE: `(() => { const t = …; return …; })()`.
|
|
317
|
+
- ⛔ **`read` is not a byte-exact transport.** It returns *rendered* text, so
|
|
318
|
+
soft-wrap points leak into long unbroken strings: the same JSON endpoint read
|
|
319
|
+
twice gave `696febae99cb770065879511` and `696 febae99cb770065879511`. Nothing
|
|
320
|
+
errors and it still parses. ⇒ When the bytes matter (JSON you will commit or
|
|
321
|
+
diff, anything hashed), use `download --url [endpoint]`, which was byte-identical
|
|
322
|
+
across repeated reads.
|
|
323
|
+
- ⛔ **A background tab's cross-origin iframes screenshot as blank space** (payment
|
|
324
|
+
forms, embedded PDF viewers, widgets) while everything around them renders, so
|
|
325
|
+
it reads as a broken page. The renderer is simply not painting them: run `focus`
|
|
326
|
+
on the tab first, and capture the **viewport**, not `--full` (with
|
|
327
|
+
`captureBeyondViewport` they composite at their pre-capture width, narrow and
|
|
328
|
+
clipped). A blank region on a page with no cross-origin iframes is a real finding.
|
|
329
|
+
- **Controls that ignore `click`** (Radix menus, `click` vs `--trusted`), hidden
|
|
330
|
+
dialogs, stalled infinite scroll, React composers and GitHub image attachments:
|
|
331
|
+
**[`references/page-recipes.md`](references/page-recipes.md)**.
|
|
332
|
+
- **This needs the operator's machine, awake.** The shared headed Chrome and its
|
|
333
|
+
logins live there, so a cloud run (a scheduled remote agent) cannot use it, and a
|
|
334
|
+
closed lid sleeps the machine (`caffeinate` prevents idle sleep, not lid-close
|
|
335
|
+
sleep). Split the work: browser- and login-bound steps locally; research and
|
|
336
|
+
repo work wherever.
|
|
337
|
+
- **`screencapture` / `osascript` are not a fallback without macOS grants.**
|
|
338
|
+
Ungranted, they fail with `could not create image from display` and AppleEvent
|
|
339
|
+
`-1712`: Screen Recording and Automation permissions, not missing capability.
|
|
340
|
+
Probe with one line before relying on them.
|
|
298
341
|
|
|
299
342
|
## Network insights — find the API behind a page
|
|
300
343
|
|
|
@@ -365,6 +408,13 @@ code lives, how to validate with `node dist/index.js`, and the PR steps:
|
|
|
365
408
|
and exact: *open Terminal and run `browser-automation profile --migrate`; if macOS
|
|
366
409
|
asks whether Terminal may access data from other apps, allow it.*
|
|
367
410
|
- **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
|
|
411
|
+
- **The Chrome on the port is on a profile you did not expect** → someone worked
|
|
412
|
+
around a launch failure by hand (`BROWSER_AUTOMATION_PROFILE`, a typed
|
|
413
|
+
`--user-data-dir`), and that instance has few or no logins. Read the live
|
|
414
|
+
browser's profile before trusting a drive:
|
|
415
|
+
`ps -p $(lsof -ti:9223) -o command= | tr ' ' '\n' | grep user-data-dir`. The
|
|
416
|
+
shared profile is `~/.browser-automation/chrome-profile`. ⚠️ Do not just kill it;
|
|
417
|
+
it may be the operator's live browser. Ask, then `launch`.
|
|
368
418
|
- **Chrome was restarted** → nothing to do; the next `goto` recreates the
|
|
369
419
|
session's tab automatically (sessions self-heal; `list` shows `stale`).
|
|
370
420
|
- **A login wall on a repeat run** → the profile lost cookies (rare) or the site
|
|
@@ -118,11 +118,12 @@ under Gotchas; this is the detail and the worked cases behind them.
|
|
|
118
118
|
all — a `drop` listener reading `e.dataTransfer.files` (vocalremover-style audio
|
|
119
119
|
tools, many image/video drop zones). Neither `setfiles` nor `upload` applies;
|
|
120
120
|
use `drop <ref> <path…>`. By default it fires a genuinely-**trusted** CDP drag
|
|
121
|
-
(`Input.dispatchDragEvent`) carrying the real files from disk: it
|
|
122
|
-
the
|
|
123
|
-
focused+visible even when the Chrome window isn't the frontmost OS
|
|
121
|
+
(`Input.dispatchDragEvent`) carrying the real files from disk: it forces the
|
|
122
|
+
tab foreground for the renderer (focus emulation + active lifecycle — so the
|
|
123
|
+
tab reports focused+visible even when the Chrome window isn't the frontmost OS
|
|
124
|
+
window, without selecting it in that window; see issue #28),
|
|
124
125
|
waits for the zone to be actionable, then dragEnter→dragOver→drop. The
|
|
125
|
-
|
|
126
|
+
forced foreground matters: drop-zone uploaders commonly do their work only inside a
|
|
126
127
|
**user activation**, and CDP input grants no activation on a tab the renderer
|
|
127
128
|
considers `hidden` — which it is whenever the window is occluded (the usual
|
|
128
129
|
case while you work in the terminal). vocalremover.org is the canonical example:
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Page recipes — controls that need more than `click`
|
|
2
|
+
|
|
3
|
+
Each of these looks like "the site is broken" or "the ref went stale" the first time, and
|
|
4
|
+
each cost a real session at least one wrong diagnosis.
|
|
5
|
+
|
|
6
|
+
## Clicks: synthetic and trusted are BOTH needed, on different controls
|
|
7
|
+
|
|
8
|
+
Never generalise from one control. On the same site, a dropdown menu ignored untrusted
|
|
9
|
+
clicks and needed `click --trusted`, while a link-styled **Withdraw** anchor was the
|
|
10
|
+
reverse: `Input.dispatchMouseEvent` at its centre silently did nothing, and `el.click()`
|
|
11
|
+
opened the confirm dialog every time. Try both before concluding a control is broken.
|
|
12
|
+
|
|
13
|
+
## Radix menus open on `pointerdown`
|
|
14
|
+
|
|
15
|
+
A Radix `DropdownMenu` or a row "⋯" trigger will not open from `click`, nor from a bare
|
|
16
|
+
`element.click()`. Radix listens on `pointerdown`, so you get a snapshot with no
|
|
17
|
+
`[role=menuitem]` in it. Send pointer events **plus** a real click, and return the items
|
|
18
|
+
in the same call so you see at once whether it opened:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
browser-automation eval -s app '(() => {
|
|
22
|
+
const b = [...document.querySelectorAll("button")].find(x => /Open menu/.test(x.getAttribute("aria-label") || x.textContent));
|
|
23
|
+
const o = { bubbles: true, cancelable: true, pointerId: 1, isPrimary: true, button: 0 };
|
|
24
|
+
b.dispatchEvent(new PointerEvent("pointerdown", o));
|
|
25
|
+
b.dispatchEvent(new PointerEvent("pointerup", o));
|
|
26
|
+
b.click();
|
|
27
|
+
return [...document.querySelectorAll("[role=menuitem]")].map(x => x.textContent.trim()).join(" | ");
|
|
28
|
+
})()'
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
⚠️ **Do not fire `click` and then this sequence.** Two activations toggle the menu open
|
|
32
|
+
and shut again, which looks identical to it never opening. Once it is open, the menu
|
|
33
|
+
items and dialog buttons take an ordinary `click [ref]` after a re-snapshot; only the
|
|
34
|
+
trigger needs pointer events.
|
|
35
|
+
|
|
36
|
+
## Dialogs: filter by visibility, not by role
|
|
37
|
+
|
|
38
|
+
A page can hold several hidden `[role=dialog]` nodes (search overlays, ad-option panels).
|
|
39
|
+
`querySelector('[role=dialog]')` returns an empty one, and your automation reports "no
|
|
40
|
+
button" after an action that actually worked. Match `offsetParent !== null` (or `.open`)
|
|
41
|
+
**plus** the text you expect.
|
|
42
|
+
|
|
43
|
+
## Infinite scroll stalls in a background tab
|
|
44
|
+
|
|
45
|
+
Chrome throttles timers and IntersectionObservers in unfocused tabs, so a lazy-loading
|
|
46
|
+
list stops after a page or two however you scroll it, and it fails by **stalling
|
|
47
|
+
silently**, which reads as "the list is capped". Measured on a 144-row list: window
|
|
48
|
+
scroll, container `scrollTop`, synthetic `wheel` events and a 12000px emulated viewport
|
|
49
|
+
all stalled at 30 rows; bringing the tab to the front walked the same loop to 144,
|
|
50
|
+
matching the count in the page's own header.
|
|
51
|
+
|
|
52
|
+
So when a list "won't paginate", **make the tab render before concluding anything about
|
|
53
|
+
the site**: `focus -s [session]` first, and if the count still stalls, `focus --raise`,
|
|
54
|
+
which really fronts the tab. ⚠️ `--raise` takes the operator's screen, so keep it to a
|
|
55
|
+
bounded step and tell them. Then scroll until the row count stops rising, and check it
|
|
56
|
+
against whatever count the page displays.
|
|
57
|
+
|
|
58
|
+
⛔ **`Emulation.clearDeviceMetricsOverride` does not reliably restore the real
|
|
59
|
+
viewport.** If you override device metrics, set them back to the real size explicitly.
|
|
60
|
+
Otherwise `getBoundingClientRect` coordinates are computed in a viewport the window does
|
|
61
|
+
not have, and every coordinate-based click lands nowhere and reports success.
|
|
62
|
+
|
|
63
|
+
## Rich composers accept `fill` and still submit nothing
|
|
64
|
+
|
|
65
|
+
`contenteditable` composers wired to React show your text in the DOM while React's state
|
|
66
|
+
stays empty, so the **Send** button never enables, and re-reading the element confirms
|
|
67
|
+
your text, which makes it look like a UI bug. Use `fill --native` on such a composer from
|
|
68
|
+
the start. ⛔ Clearing it with `el.innerHTML = ""` makes it worse: it can collapse the
|
|
69
|
+
whole action row until a reload.
|
|
70
|
+
|
|
71
|
+
## Log out, then navigate, as separate calls
|
|
72
|
+
|
|
73
|
+
A logout `fetch` and a `goto` in one chain race: the logout returns `{"success":true}`
|
|
74
|
+
and you still land on the signed-in page, because the navigation resolves against a
|
|
75
|
+
session the request has not finished clearing. The tell is a login URL that renders
|
|
76
|
+
signed-in content. Issue the request, confirm it returned, then `goto` in a **separate**
|
|
77
|
+
invocation and assert `location.pathname`.
|
|
78
|
+
|
|
79
|
+
## Attach an image to a GitHub PR or issue
|
|
80
|
+
|
|
81
|
+
A committed image cannot be shown in a PR body on a **private** repo: GitHub's image
|
|
82
|
+
proxy fetches without the viewer's credentials, so `…/blob/[sha]/x.png?raw=true` renders
|
|
83
|
+
broken (`naturalWidth: 0`). Only a **user-attachment** renders, and that exists only
|
|
84
|
+
because a browser uploaded it.
|
|
85
|
+
|
|
86
|
+
⭐ **Stamp the ref yourself.** The comment form's file input is `display:none`, so
|
|
87
|
+
`snapshot` never gives it an `eN` ref, and `setfiles` needs one. Setting the attribute
|
|
88
|
+
by hand is enough:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
browser-automation goto -s pr "https://github.com/[org]/[repo]/pull/[n]"
|
|
92
|
+
# 1. The comment form is lazy-rendered; wait until it exists.
|
|
93
|
+
browser-automation eval -s pr 'document.querySelector("input#fc-new_comment_field") ? "ready" : "waiting"'
|
|
94
|
+
# 2. Stamp a ref on the input, then setfiles.
|
|
95
|
+
browser-automation eval -s pr '(() => { document.querySelector("input#fc-new_comment_field").setAttribute("data-ba-ref", "e998"); return "ok"; })()'
|
|
96
|
+
browser-automation setfiles -s pr e998 /abs/one.png /abs/two.png
|
|
97
|
+
# 3. Poll the textarea until every upload has landed, then read the URLs out.
|
|
98
|
+
browser-automation eval -s pr '(() => String((document.querySelector("textarea#new_comment_field").value.match(/user-attachments\/assets\/[0-9a-f-]+/g) || []).length))()'
|
|
99
|
+
browser-automation eval -s pr 'document.querySelector("textarea#new_comment_field").value'
|
|
100
|
+
# 4. Clear the draft with the native value setter. Do NOT submit the comment.
|
|
101
|
+
browser-automation eval -s pr '(() => { const t = document.querySelector("textarea#new_comment_field"); Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value").set.call(t, ""); t.dispatchEvent(new Event("input", { bubbles: true })); return t.value === ""; })()'
|
|
102
|
+
# 5. Put the harvested <img> tags into the body: gh pr edit --body-file …
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The uploaded URLs are plain text from then on, so **harvest them, don't re-upload**, and
|
|
106
|
+
place them anywhere, including the PR description via `gh pr edit`. If ref-stamping ever
|
|
107
|
+
stops working, raw per-tab CDP `DOM.setFileInputFiles` on `input[type="file"]` is what
|
|
108
|
+
`setfiles` does internally, and it fires the trusted `input`/`change` GitHub listens for.
|
|
109
|
+
|
|
110
|
+
Traps:
|
|
111
|
+
|
|
112
|
+
- ⛔ **`upload --click` on "Paste, drop, or click to add files" reports success and
|
|
113
|
+
stages nothing.** *"delivered N file(s) to the page's file handler via chooser"* means
|
|
114
|
+
delivery to *a* handler, not GitHub accepting the files; the textarea stays empty.
|
|
115
|
+
- `snapshot` caps at about 200 elements, so on a long PR the attach control never gets a
|
|
116
|
+
ref. A hand-stamped ref must be shaped `e[number]`; anything else is rejected.
|
|
117
|
+
- The description editor itself is not reachable this way (its menu renders lazily).
|
|
118
|
+
Use `gh pr edit` for the body and the browser only for the upload.
|
|
119
|
+
- **Verify the images render, not that the markup is there.** Attachments go through a
|
|
120
|
+
proxy, so filter on `alt` rather than `src`, force lazy images to load
|
|
121
|
+
(`img.loading = "eager"`), and assert `naturalWidth > 0`. An image below the fold
|
|
122
|
+
reports 0 only because it has not loaded.
|
|
123
|
+
- A mid-session "Single sign-on to [org]" wall is normal on an enterprise org; its
|
|
124
|
+
**Continue** resumes an already-valid IdP session. If it asks for credentials or MFA,
|
|
125
|
+
stop and hand back to the operator.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Driving the CLI on Windows
|
|
2
|
+
|
|
3
|
+
`launch` runs on Windows since 0.4.18 (see Troubleshooting in `SKILL.md`). These are the
|
|
4
|
+
traps after that, all measured driving a real site from Git Bash and PowerShell.
|
|
5
|
+
|
|
6
|
+
## The CLI is installed but `command not found`
|
|
7
|
+
|
|
8
|
+
The npm global dir holds three shims — `browser-automation`, `.cmd` and `.ps1` — and on a
|
|
9
|
+
stock setup the bare name resolves in neither Git Bash nor PowerShell. `command not found`
|
|
10
|
+
then reads as "not installed" when it is. The same goes for `pnpm`. Invoke the `.cmd`
|
|
11
|
+
through PowerShell:
|
|
12
|
+
|
|
13
|
+
```powershell
|
|
14
|
+
& "$env:APPDATA\npm\browser-automation.cmd" --version
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## `list` cannot tell you whether a browser is running
|
|
18
|
+
|
|
19
|
+
With **zero open tabs**, `list` prints the full saved-session list — every row flagged
|
|
20
|
+
`[stale]` — and exits 255. That looks exactly like the no-browser case, because `[stale]`
|
|
21
|
+
describes a saved session whose tab is gone, not the browser's health. The tell is the
|
|
22
|
+
`# open tabs (0)` line at the **end** of the output, easy to miss under a long listing.
|
|
23
|
+
|
|
24
|
+
⭐ **Ask the CDP endpoint instead.** It answers in one call and names the browser:
|
|
25
|
+
|
|
26
|
+
```powershell
|
|
27
|
+
Invoke-RestMethod -Uri "http://127.0.0.1:9223/json/version" -TimeoutSec 5 # Browser : Chrome/…
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
A stale session list plus a live `/json/version` means **open a tab**
|
|
31
|
+
(`new -s [name] [url]`), not relaunch the browser. It also tells you *which* browser is
|
|
32
|
+
on the port: a Chrome started by hand, or an Edge standing in for Chrome, answers the same
|
|
33
|
+
way.
|
|
34
|
+
|
|
35
|
+
## `|`, `&` and parentheses break through the `.cmd` shim
|
|
36
|
+
|
|
37
|
+
`cmd.exe` reads `|` as a pipe, and it appears in ordinary **regex alternation**:
|
|
38
|
+
`eval "…match(/(connections|followers)/)…"` dies with `'followers)' is not recognized as an
|
|
39
|
+
internal or external command`, which reads as a broken CLI rather than quoting. `&` does
|
|
40
|
+
the same, and parentheses or nested quotes in an `eval` expression fail with
|
|
41
|
+
`Positional argument 'expr' is required`.
|
|
42
|
+
|
|
43
|
+
⭐ **The robust pattern is `read` plus host-side parsing**, so no JS crosses the shim:
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
$t = & "$env:APPDATA\npm\browser-automation.cmd" read -s [session] | Out-String
|
|
47
|
+
[regex]::Matches($t,'[\d,\.]+K?\s*(?:connections|followers)') | ForEach-Object { $_.Value }
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
When you genuinely need `eval`, write **quote-free JS**: regex literals instead of string
|
|
51
|
+
literals, `.join()` with no argument instead of `join("\n")`. `eval` has no `--file`
|
|
52
|
+
option, so there is no other escape hatch.
|
|
53
|
+
|
|
54
|
+
## A global install fails behind a TLS-intercepting proxy
|
|
55
|
+
|
|
56
|
+
`npm install -g` can fail with `SELF_SIGNED_CERT_IN_CHAIN` or
|
|
57
|
+
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY` behind a corporate proxy. That is npm's certificate
|
|
58
|
+
configuration (`npm config set cafile …`), not this tool. Note that `npm install -g` reads
|
|
59
|
+
the **user** `~/.npmrc`, not a project's `.npmrc`, so a registry or CA set only in the
|
|
60
|
+
project does not apply to it.
|