webhand 0.2.0 → 0.4.0
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/README.ja.md +104 -0
- package/README.md +70 -219
- package/assets/recorder.js +4 -0
- package/assets/snapshot.js +224 -4
- package/dist/agent.js +154 -13
- package/dist/auth.js +62 -0
- package/dist/bin.js +0 -0
- package/dist/browser.js +702 -23
- package/dist/cli.js +684 -86
- package/dist/collect.js +70 -0
- package/dist/compare.js +173 -0
- package/dist/daemon.js +125 -0
- package/dist/format.js +44 -0
- package/dist/knowledge.js +206 -0
- package/dist/learn.js +11 -5
- package/dist/metrics.js +64 -4
- package/dist/more.js +58 -0
- package/dist/policies/base.js +110 -14
- package/dist/policies/jev.js +245 -18
- package/dist/policies/scripted.js +2 -2
- package/dist/remote.js +165 -0
- package/dist/runbook.js +34 -19
- package/dist/session.js +261 -17
- package/dist/types.js +12 -0
- package/package.json +9 -6
- package/dist/py.js +0 -141
- package/dist/run.js +0 -80
- package/dist/tasks.js +0 -37
package/dist/runbook.js
CHANGED
|
@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
|
|
|
9
9
|
import { dirname, join, resolve } from "node:path";
|
|
10
10
|
import { pathToFileURL } from "node:url";
|
|
11
11
|
import { parse } from "smol-toml";
|
|
12
|
-
import {
|
|
12
|
+
import { quote, show } from "./format.js";
|
|
13
13
|
import { roots, scopeRoot } from "./workspace.js";
|
|
14
14
|
const WORD = "[\\p{L}\\p{N}_-]+";
|
|
15
15
|
const NAME = new RegExp(`^${WORD}(/${WORD})?$`, "u");
|
|
@@ -19,6 +19,8 @@ const ACTORS = new Set(["jev", "human"]);
|
|
|
19
19
|
const STATUSES = new Set(["draft", "approved"]);
|
|
20
20
|
const DEFAULTS = new Set(["focus", "skip"]); // A region's default in service.toml. Without one, it is observed as usual.
|
|
21
21
|
const SERVICE_FILE = "service"; // runbooks/<service>/service.toml holds the service information.
|
|
22
|
+
/** Kinds the read layer can hold, by page structure. `none` clears an earlier choice. */
|
|
23
|
+
export const READ_KINDS = ["outline", "text", "table", "list", "link", "control", "media"];
|
|
22
24
|
/** The runbook folder of a scope, whether or not it exists. */
|
|
23
25
|
export function root(scope = "project") {
|
|
24
26
|
return join(scopeRoot(scope), "runbooks");
|
|
@@ -34,13 +36,13 @@ export class RunbookError extends Error {
|
|
|
34
36
|
/** Checks a runbook name such as hotel/filter. */
|
|
35
37
|
function checkName(name) {
|
|
36
38
|
if (!NAME.test(name) || name.split("/").at(-1) === SERVICE_FILE) {
|
|
37
|
-
throw new RunbookError(`Invalid runbook name: ${
|
|
39
|
+
throw new RunbookError(`Invalid runbook name: ${quote(name)}`);
|
|
38
40
|
}
|
|
39
41
|
return name;
|
|
40
42
|
}
|
|
41
43
|
function checkService(service) {
|
|
42
44
|
if (!SERVICE_NAME.test(service))
|
|
43
|
-
throw new RunbookError(`Invalid service name: ${
|
|
45
|
+
throw new RunbookError(`Invalid service name: ${quote(service)}`);
|
|
44
46
|
return service;
|
|
45
47
|
}
|
|
46
48
|
/** Where a runbook of a scope is written. */
|
|
@@ -83,6 +85,16 @@ function readToml(file) {
|
|
|
83
85
|
throw new RunbookError(`${file}: ${error instanceof Error ? error.message : String(error)}`);
|
|
84
86
|
}
|
|
85
87
|
}
|
|
88
|
+
/** Missing, false, zero, or an empty string, list, or table. */
|
|
89
|
+
function blank(value) {
|
|
90
|
+
if (value === null || value === undefined || value === false || value === 0 || value === "")
|
|
91
|
+
return true;
|
|
92
|
+
if (Array.isArray(value))
|
|
93
|
+
return value.length === 0;
|
|
94
|
+
if (typeof value === "object")
|
|
95
|
+
return Object.keys(value).length === 0;
|
|
96
|
+
return false;
|
|
97
|
+
}
|
|
86
98
|
const get = (doc, key, fallback = undefined) => (key in doc ? doc[key] : fallback);
|
|
87
99
|
/** Region patterns, such as "main/form:宿泊予約" or "footer". Anything else is an error. */
|
|
88
100
|
function patterns(file, where, value) {
|
|
@@ -102,7 +114,7 @@ function regions(file, page) {
|
|
|
102
114
|
throw new RunbookError(`${file}: a region on ${get(page, "url", "?")} has no key`);
|
|
103
115
|
const fallback = get(region, "default", null);
|
|
104
116
|
if (fallback !== null && !DEFAULTS.has(fallback)) {
|
|
105
|
-
throw new RunbookError(`${file}: region ${
|
|
117
|
+
throw new RunbookError(`${file}: region ${quote(key[0])} has unknown default ${quote(fallback)}`);
|
|
106
118
|
}
|
|
107
119
|
found.push({ key: key[0], purpose: get(region, "purpose", ""), default: fallback });
|
|
108
120
|
}
|
|
@@ -115,8 +127,11 @@ function regions(file, page) {
|
|
|
115
127
|
export function view(...layers) {
|
|
116
128
|
let focus = [];
|
|
117
129
|
let skip = [];
|
|
130
|
+
let read;
|
|
118
131
|
for (const layer of layers) {
|
|
119
|
-
if (
|
|
132
|
+
if (layer?.read?.length)
|
|
133
|
+
read = layer.read.includes("none") ? undefined : [...layer.read]; // The later choice wins.
|
|
134
|
+
if (blank(layer))
|
|
120
135
|
continue;
|
|
121
136
|
const newFocus = [...(layer?.focus ?? [])];
|
|
122
137
|
const newSkip = [...(layer?.skip ?? [])];
|
|
@@ -124,7 +139,7 @@ export function view(...layers) {
|
|
|
124
139
|
focus = [...newFocus, ...focus.filter(kept)];
|
|
125
140
|
skip = [...skip.filter(kept), ...newSkip];
|
|
126
141
|
}
|
|
127
|
-
return { focus, skip };
|
|
142
|
+
return read ? { focus, skip, read } : { focus, skip };
|
|
128
143
|
}
|
|
129
144
|
/** What the service information says to focus on or skip on every page. */
|
|
130
145
|
export function serviceView(info) {
|
|
@@ -141,7 +156,7 @@ export function loadService(service) {
|
|
|
141
156
|
return null;
|
|
142
157
|
const { file, scope } = found;
|
|
143
158
|
const { data } = readToml(file);
|
|
144
|
-
const missing = ["service", "description", "base_url"
|
|
159
|
+
const missing = ["service", "description", "base_url"].filter((key) => blank(data[key]));
|
|
145
160
|
if (missing.length)
|
|
146
161
|
throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
|
|
147
162
|
const login = get(data, "login", {});
|
|
@@ -149,13 +164,13 @@ export function loadService(service) {
|
|
|
149
164
|
service: data.service,
|
|
150
165
|
description: String(data.description).trim(),
|
|
151
166
|
base_url: data.base_url,
|
|
152
|
-
login: { required:
|
|
167
|
+
login: { required: !blank(get(login, "required")), url: get(login, "url", null) },
|
|
153
168
|
pages: get(data, "pages", []).map((p) => ({
|
|
154
169
|
url: get(p, "url", ""),
|
|
155
170
|
purpose: get(p, "purpose", ""),
|
|
156
171
|
regions: regions(file, p),
|
|
157
172
|
})),
|
|
158
|
-
facts: get(data, "facts", []).map(
|
|
173
|
+
facts: get(data, "facts", []).map(show),
|
|
159
174
|
scope,
|
|
160
175
|
};
|
|
161
176
|
}
|
|
@@ -207,7 +222,7 @@ export function parseValues(pairs) {
|
|
|
207
222
|
for (const pair of pairs) {
|
|
208
223
|
const at = pair.indexOf("=");
|
|
209
224
|
if (at <= 0)
|
|
210
|
-
throw new RunbookError(`Expected KEY=VALUE, got ${
|
|
225
|
+
throw new RunbookError(`Expected KEY=VALUE, got ${quote(pair)}`);
|
|
211
226
|
values[pair.slice(0, at)] = pair.slice(at + 1);
|
|
212
227
|
}
|
|
213
228
|
return values;
|
|
@@ -235,40 +250,40 @@ export function load(name, values = {}) {
|
|
|
235
250
|
}
|
|
236
251
|
export function loadFile(file, name, scope, values = {}, base = process.cwd()) {
|
|
237
252
|
const { raw, data } = readToml(file);
|
|
238
|
-
const required = ["service", "name", "goal", "start_url", "status", "
|
|
239
|
-
const missing = required.filter((key) =>
|
|
253
|
+
const required = ["service", "name", "goal", "start_url", "status", "steps"];
|
|
254
|
+
const missing = required.filter((key) => blank(data[key]));
|
|
240
255
|
if (missing.length)
|
|
241
256
|
throw new RunbookError(`${file}: missing ${missing.join(", ")}`);
|
|
242
257
|
if (!STATUSES.has(data.status))
|
|
243
|
-
throw new RunbookError(`${file}: unknown status ${
|
|
258
|
+
throw new RunbookError(`${file}: unknown status ${quote(data.status)}`);
|
|
244
259
|
const declared = get(data, "params", {});
|
|
245
260
|
const unknown = Object.keys(values)
|
|
246
261
|
.filter((key) => !(key in declared))
|
|
247
262
|
.sort();
|
|
248
263
|
if (unknown.length)
|
|
249
|
-
throw new RunbookError(`${file}: unknown parameters ${
|
|
264
|
+
throw new RunbookError(`${file}: unknown parameters ${quote(unknown)}`);
|
|
250
265
|
const filled = {};
|
|
251
266
|
for (const [key, spec] of Object.entries(declared))
|
|
252
267
|
filled[key] = key in values ? values[key] : get(spec, "default");
|
|
253
268
|
const fill = (text) => String(text).replace(PARAM, (_match, param) => {
|
|
254
269
|
const value = filled[param];
|
|
255
270
|
if (value === null || value === undefined) {
|
|
256
|
-
throw new RunbookError(`${file}: parameter ${
|
|
271
|
+
throw new RunbookError(`${file}: parameter ${quote(param)} has no value. Pass --param ${param}=VALUE`);
|
|
257
272
|
}
|
|
258
|
-
return
|
|
273
|
+
return show(value);
|
|
259
274
|
});
|
|
260
275
|
const steps = data.steps.map((step, i) => {
|
|
261
276
|
const number = i + 1;
|
|
262
277
|
const actor = get(step, "actor", "jev");
|
|
263
278
|
if (!ACTORS.has(actor))
|
|
264
|
-
throw new RunbookError(`${file}: step ${number} has unknown actor ${
|
|
265
|
-
if (
|
|
279
|
+
throw new RunbookError(`${file}: step ${number} has unknown actor ${quote(actor)}`);
|
|
280
|
+
if (blank(step.instruction))
|
|
266
281
|
throw new RunbookError(`${file}: step ${number} has no instruction`);
|
|
267
282
|
return {
|
|
268
283
|
actor,
|
|
269
284
|
instruction: fill(step.instruction),
|
|
270
285
|
hints: get(step, "hints", []).map(fill),
|
|
271
|
-
done_when:
|
|
286
|
+
done_when: blank(step.done_when) ? null : fill(step.done_when),
|
|
272
287
|
};
|
|
273
288
|
});
|
|
274
289
|
return {
|
package/dist/session.js
CHANGED
|
@@ -11,14 +11,31 @@
|
|
|
11
11
|
*/
|
|
12
12
|
import { execFileSync, spawn } from "node:child_process";
|
|
13
13
|
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
14
|
-
import {
|
|
14
|
+
import { connect, createServer } from "node:net";
|
|
15
|
+
import { homedir, tmpdir } from "node:os";
|
|
15
16
|
import { delimiter, join } from "node:path";
|
|
17
|
+
import { fileURLToPath } from "node:url";
|
|
16
18
|
import { chromium } from "playwright-core";
|
|
17
|
-
import {
|
|
19
|
+
import { quote, sleep } from "./format.js";
|
|
18
20
|
import * as workspace from "./workspace.js";
|
|
19
|
-
|
|
21
|
+
/** How long a browser may take to start. Tests set WEBHAND_STARTUP_MS higher: several suites at once load the machine. */
|
|
22
|
+
const STARTUP_MS = Number(process.env.WEBHAND_STARTUP_MS) || 15_000;
|
|
20
23
|
const PROFILE_NAME = /^[\p{L}\p{N}_-]+$/u;
|
|
24
|
+
/** Where Chrome runs (--chrome). */
|
|
21
25
|
export const CHROMES = ["auto", "linux", "windows"];
|
|
26
|
+
/** Engines that run as `serve` behind a daemon: no window, no saved profile, and pages that end with a CDP connection. */
|
|
27
|
+
const ENGINES = ["lightpanda", "obscura"];
|
|
28
|
+
/** What runs the browser (--engine). auto is the default: see chooseEngine. */
|
|
29
|
+
export const ENGINE_CHOICES = ["auto", "chrome", "headless-shell", ...ENGINES];
|
|
30
|
+
const ENGINE_NAMES = {
|
|
31
|
+
"headless-shell": "Chrome headless shell",
|
|
32
|
+
lightpanda: "Lightpanda",
|
|
33
|
+
obscura: "Obscura",
|
|
34
|
+
};
|
|
35
|
+
/** How a session's browser reads in output: "Lightpanda", or "linux Chrome". */
|
|
36
|
+
export function hostName(engine, chrome) {
|
|
37
|
+
return ENGINE_NAMES[engine] ?? `${chrome} Chrome`;
|
|
38
|
+
}
|
|
22
39
|
const WINDOWS_CHROME = [
|
|
23
40
|
"/mnt/c/Program Files/Google/Chrome/Application/chrome.exe",
|
|
24
41
|
"/mnt/c/Program Files (x86)/Google/Chrome/Application/chrome.exe",
|
|
@@ -30,20 +47,92 @@ export class SessionError extends Error {
|
|
|
30
47
|
export function home() {
|
|
31
48
|
return join(workspace.home(), "state");
|
|
32
49
|
}
|
|
50
|
+
export const DEFAULT_ID = "default";
|
|
51
|
+
const ID_PATTERN = /^[A-Za-z0-9_-]{1,40}$/;
|
|
52
|
+
let currentId = DEFAULT_ID;
|
|
53
|
+
/** Which session the commands that follow work on. Several can run at once, each with its own Chrome and state. */
|
|
54
|
+
export function use(id = DEFAULT_ID) {
|
|
55
|
+
if (!ID_PATTERN.test(id))
|
|
56
|
+
throw new SessionError(`Expected --id of letters, digits, - or _ (up to 40), got ${quote(id)}`);
|
|
57
|
+
currentId = id;
|
|
58
|
+
}
|
|
59
|
+
export function id() {
|
|
60
|
+
return currentId;
|
|
61
|
+
}
|
|
62
|
+
/** The value of --id (or --id=ID) in the arguments, for callers that look at the session before main() does. */
|
|
63
|
+
export function idFrom(argv) {
|
|
64
|
+
for (let i = 0; i < argv.length; i++) {
|
|
65
|
+
if (argv[i] === "--id")
|
|
66
|
+
return argv[i + 1] ?? "";
|
|
67
|
+
if (argv[i].startsWith("--id="))
|
|
68
|
+
return argv[i].slice("--id=".length);
|
|
69
|
+
}
|
|
70
|
+
return DEFAULT_ID;
|
|
71
|
+
}
|
|
72
|
+
/** The default session keeps the file names it always had. */
|
|
73
|
+
function file(stem, extension = "") {
|
|
74
|
+
return join(home(), currentId === DEFAULT_ID ? `${stem}${extension}` : `${stem}-${currentId}${extension}`);
|
|
75
|
+
}
|
|
33
76
|
function path() {
|
|
34
|
-
return
|
|
77
|
+
return file("session", ".json");
|
|
78
|
+
}
|
|
79
|
+
/** Where the tab the run is on is kept between commands. */
|
|
80
|
+
export function tabPath() {
|
|
81
|
+
return file("tab");
|
|
35
82
|
}
|
|
36
83
|
export function load() {
|
|
37
84
|
return existsSync(path()) ? JSON.parse(readFileSync(path(), "utf8")) : null;
|
|
38
85
|
}
|
|
86
|
+
/** Every session that is open, by id. */
|
|
87
|
+
export function active() {
|
|
88
|
+
if (!existsSync(home()))
|
|
89
|
+
return [];
|
|
90
|
+
const found = [];
|
|
91
|
+
for (const name of readdirSync(home())) {
|
|
92
|
+
const match = /^session(?:-([A-Za-z0-9_-]+))?\.json$/.exec(name);
|
|
93
|
+
if (!match)
|
|
94
|
+
continue;
|
|
95
|
+
try {
|
|
96
|
+
found.push([match[1] ?? DEFAULT_ID, JSON.parse(readFileSync(join(home(), name), "utf8"))]);
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
// A file being replaced; the next listing sees it.
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
return found;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* One command at a time per session: two `run`s on the same Chrome would act twice. The lock holds the pid of the
|
|
106
|
+
* command, so one left by a command that died is taken over. Returns the release function.
|
|
107
|
+
*/
|
|
108
|
+
export function lock() {
|
|
109
|
+
mkdirSync(home(), { recursive: true });
|
|
110
|
+
const target = file("session", ".lock");
|
|
111
|
+
for (let attempt = 0;; attempt++) {
|
|
112
|
+
try {
|
|
113
|
+
writeFileSync(target, String(process.pid), { flag: "wx", mode: 0o600 });
|
|
114
|
+
return () => rmSync(target, { force: true });
|
|
115
|
+
}
|
|
116
|
+
catch (error) {
|
|
117
|
+
if (error.code !== "EEXIST")
|
|
118
|
+
throw error;
|
|
119
|
+
const holder = Number.parseInt(readFileSync(target, "utf8"), 10);
|
|
120
|
+
if (attempt > 0 || (Number.isInteger(holder) && holder !== process.pid && alive(holder))) {
|
|
121
|
+
throw new SessionError(`Session ${quote(currentId)} is busy: another webhand command is using it (pid ${holder}). Wait for it, or use another --id`);
|
|
122
|
+
}
|
|
123
|
+
rmSync(target, { force: true });
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
}
|
|
39
127
|
export function save(state) {
|
|
40
128
|
mkdirSync(home(), { recursive: true });
|
|
41
|
-
const temporary =
|
|
129
|
+
const temporary = file("session", ".tmp");
|
|
42
130
|
writeFileSync(temporary, JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
|
|
43
131
|
renameSync(temporary, path());
|
|
44
132
|
}
|
|
45
133
|
export function clear() {
|
|
46
134
|
rmSync(path(), { force: true });
|
|
135
|
+
rmSync(tabPath(), { force: true });
|
|
47
136
|
}
|
|
48
137
|
/** 'new' gives null; 'profile:NAME' gives NAME. */
|
|
49
138
|
export function parseSession(spec) {
|
|
@@ -53,7 +142,7 @@ export function parseSession(spec) {
|
|
|
53
142
|
const kind = at < 0 ? spec : spec.slice(0, at);
|
|
54
143
|
const name = at < 0 ? "" : spec.slice(at + 1);
|
|
55
144
|
if (kind !== "profile" || !PROFILE_NAME.test(name)) {
|
|
56
|
-
throw new SessionError(`Expected --session new or profile:NAME, got ${
|
|
145
|
+
throw new SessionError(`Expected --session new or profile:NAME, got ${quote(spec)}`);
|
|
57
146
|
}
|
|
58
147
|
return name;
|
|
59
148
|
}
|
|
@@ -79,6 +168,9 @@ export const probes = {
|
|
|
79
168
|
windowsChrome() {
|
|
80
169
|
return WINDOWS_CHROME.find(isFile) ?? null;
|
|
81
170
|
},
|
|
171
|
+
headlessShell() {
|
|
172
|
+
return shellBinary();
|
|
173
|
+
},
|
|
82
174
|
networkingMode() {
|
|
83
175
|
try {
|
|
84
176
|
return run("wslinfo", ["--networking-mode"], { timeout: 5000 }) || null;
|
|
@@ -91,6 +183,20 @@ export const probes = {
|
|
|
91
183
|
return run("wslpath", ["-w", path]);
|
|
92
184
|
},
|
|
93
185
|
};
|
|
186
|
+
/**
|
|
187
|
+
* What auto means. A run that needs no window and no saved profile uses the headless shell when one is installed:
|
|
188
|
+
* half the memory, the same results (see docs/research-plan.md). A window or a profile keeps Chrome, and so does
|
|
189
|
+
* asking for the Windows Chrome (--chrome windows; --chrome auto only says "use it if you can", and a headless run
|
|
190
|
+
* gains nothing from it). A missing shell falls back to Chrome quietly: that is what the run used before. A named
|
|
191
|
+
* engine is taken as asked. `chrome` is what --chrome asked for, not where it resolved to.
|
|
192
|
+
*/
|
|
193
|
+
export function chooseEngine(engine, options) {
|
|
194
|
+
if (engine !== "auto")
|
|
195
|
+
return engine;
|
|
196
|
+
if (options.headed || options.profile || options.chrome === "windows")
|
|
197
|
+
return "chrome";
|
|
198
|
+
return probes.headlessShell() ? "headless-shell" : "chrome";
|
|
199
|
+
}
|
|
94
200
|
function windowsLocalAppData() {
|
|
95
201
|
let folder = "";
|
|
96
202
|
try {
|
|
@@ -106,7 +212,7 @@ function windowsLocalAppData() {
|
|
|
106
212
|
/** Returns ['linux' or 'windows', a note for the person when auto fell back]. */
|
|
107
213
|
export function chooseChrome(choice) {
|
|
108
214
|
if (!CHROMES.includes(choice))
|
|
109
|
-
throw new SessionError(`Unknown --chrome ${
|
|
215
|
+
throw new SessionError(`Unknown --chrome ${quote(choice)}`);
|
|
110
216
|
if (choice === "linux")
|
|
111
217
|
return ["linux", null];
|
|
112
218
|
let reason = null;
|
|
@@ -132,7 +238,7 @@ function profilesRoot(chrome) {
|
|
|
132
238
|
}
|
|
133
239
|
export function profileDir(chrome, name) {
|
|
134
240
|
if (!PROFILE_NAME.test(name))
|
|
135
|
-
throw new SessionError(`Invalid profile name: ${
|
|
241
|
+
throw new SessionError(`Invalid profile name: ${quote(name)}`);
|
|
136
242
|
return join(profilesRoot(chrome), name);
|
|
137
243
|
}
|
|
138
244
|
export function listProfiles(chrome) {
|
|
@@ -164,10 +270,12 @@ export function chromeArgs(executable, userDataDir, options) {
|
|
|
164
270
|
"--no-first-run",
|
|
165
271
|
"--no-default-browser-check",
|
|
166
272
|
"--hide-crash-restore-bubble",
|
|
167
|
-
|
|
273
|
+
// Chrome's window includes 87px of browser UI, so 1120x867 shows a 1120x780 page. The headless shell has no UI:
|
|
274
|
+
// its window is the page, so it takes the page size. The same viewport, or the two read different elements.
|
|
275
|
+
options.shell ? "--window-size=1120,780" : "--window-size=1120,867",
|
|
168
276
|
"about:blank",
|
|
169
277
|
];
|
|
170
|
-
if (!options.headed)
|
|
278
|
+
if (!options.headed && !options.shell)
|
|
171
279
|
args.splice(1, 0, "--headless=new");
|
|
172
280
|
return args;
|
|
173
281
|
}
|
|
@@ -181,6 +289,33 @@ async function reachable(port) {
|
|
|
181
289
|
return false;
|
|
182
290
|
}
|
|
183
291
|
}
|
|
292
|
+
/** chrome-headless-shell: WEBHAND_HEADLESS_SHELL, PATH, or the newest one in Playwright's browser cache. */
|
|
293
|
+
function shellBinary() {
|
|
294
|
+
const given = process.env.WEBHAND_HEADLESS_SHELL;
|
|
295
|
+
if (given && isFile(given))
|
|
296
|
+
return given;
|
|
297
|
+
const onPath = which("chrome-headless-shell");
|
|
298
|
+
if (onPath)
|
|
299
|
+
return onPath;
|
|
300
|
+
const cache = process.env.PLAYWRIGHT_BROWSERS_PATH ?? join(homedir(), ".cache", "ms-playwright");
|
|
301
|
+
let builds = [];
|
|
302
|
+
try {
|
|
303
|
+
builds = readdirSync(cache).filter((name) => name.startsWith("chromium_headless_shell-"));
|
|
304
|
+
}
|
|
305
|
+
catch {
|
|
306
|
+
return null;
|
|
307
|
+
}
|
|
308
|
+
builds.sort((a, b) => Number.parseInt(b.split("-")[1], 10) - Number.parseInt(a.split("-")[1], 10));
|
|
309
|
+
for (const build of builds) {
|
|
310
|
+
const folder = join(cache, build);
|
|
311
|
+
for (const inner of readdirSync(folder).filter((name) => name.startsWith("chrome-headless-shell"))) {
|
|
312
|
+
const binary = join(folder, inner, "chrome-headless-shell");
|
|
313
|
+
if (isFile(binary))
|
|
314
|
+
return binary;
|
|
315
|
+
}
|
|
316
|
+
}
|
|
317
|
+
return null;
|
|
318
|
+
}
|
|
184
319
|
function which(command) {
|
|
185
320
|
for (const dir of (process.env.PATH ?? "").split(delimiter)) {
|
|
186
321
|
const file = join(dir, command);
|
|
@@ -197,13 +332,98 @@ function childExited(pid) {
|
|
|
197
332
|
return null;
|
|
198
333
|
return child.exitCode !== null || child.signalCode !== null;
|
|
199
334
|
}
|
|
335
|
+
async function freePort() {
|
|
336
|
+
return await new Promise((resolve, reject) => {
|
|
337
|
+
const server = createServer();
|
|
338
|
+
server.once("error", reject);
|
|
339
|
+
server.listen(0, "127.0.0.1", () => {
|
|
340
|
+
const { port } = server.address();
|
|
341
|
+
server.close(() => resolve(port));
|
|
342
|
+
});
|
|
343
|
+
});
|
|
344
|
+
}
|
|
345
|
+
/** Whether something accepts connections on this unix socket. */
|
|
346
|
+
async function listening(path) {
|
|
347
|
+
return await new Promise((resolve) => {
|
|
348
|
+
const probe = connect(path);
|
|
349
|
+
probe.once("connect", () => {
|
|
350
|
+
probe.destroy();
|
|
351
|
+
resolve(true);
|
|
352
|
+
});
|
|
353
|
+
probe.once("error", () => resolve(false));
|
|
354
|
+
});
|
|
355
|
+
}
|
|
356
|
+
/** daemon.ts, or daemon.js once built. */
|
|
357
|
+
function daemonScript() {
|
|
358
|
+
const ts = import.meta.url.endsWith(".ts");
|
|
359
|
+
return fileURLToPath(new URL(ts ? "./daemon.ts" : "./daemon.js", import.meta.url));
|
|
360
|
+
}
|
|
361
|
+
/** Where an engine's binary is: PATH, or WEBHAND_OBSCURA for Obscura (its release archive is not installed anywhere). */
|
|
362
|
+
function engineBinary(engine) {
|
|
363
|
+
const given = engine === "obscura" ? process.env.WEBHAND_OBSCURA : undefined;
|
|
364
|
+
return given && isFile(given) ? given : which(engine);
|
|
365
|
+
}
|
|
366
|
+
/**
|
|
367
|
+
* An engine (Lightpanda, Obscura) has no window and no profile, and drops its pages when a CDP connection ends. A
|
|
368
|
+
* daemon runs it and holds the connection for the session; commands reach the page through state.socket (see
|
|
369
|
+
* daemon.ts, remote.ts). Asks for a saved profile or a window fail here rather than being quietly dropped.
|
|
370
|
+
*/
|
|
371
|
+
async function startEngine(engine, options) {
|
|
372
|
+
const name = hostName(engine, "linux");
|
|
373
|
+
if (options.profile)
|
|
374
|
+
throw new SessionError(`${name} has no saved profile. Use --session new`);
|
|
375
|
+
if (options.headed)
|
|
376
|
+
throw new SessionError(`${name} has no window, so --headed is not available`);
|
|
377
|
+
const executable = engineBinary(engine);
|
|
378
|
+
if (!executable)
|
|
379
|
+
throw new SessionError(`${engine} was not found on PATH`);
|
|
380
|
+
const port = await freePort();
|
|
381
|
+
const folder = mkdtempSync(join(tmpdir(), "webhand-")); // Holds the socket; removed when the session stops.
|
|
382
|
+
const socket = join(folder, "rpc.sock");
|
|
383
|
+
const child = spawn(process.execPath, [daemonScript(), socket, engine, executable, String(port)], {
|
|
384
|
+
detached: true, // its own process group, so it outlives this CLI call and stops as a group with the engine
|
|
385
|
+
stdio: "ignore",
|
|
386
|
+
});
|
|
387
|
+
child.on("error", () => { });
|
|
388
|
+
child.unref();
|
|
389
|
+
const pid = child.pid;
|
|
390
|
+
children.set(pid, child);
|
|
391
|
+
const state = { pid, profile: folder, saved_profile: null, chrome: "linux", engine, headed: false, socket };
|
|
392
|
+
const deadline = performance.now() + STARTUP_MS;
|
|
393
|
+
while (performance.now() < deadline) {
|
|
394
|
+
if (childExited(pid))
|
|
395
|
+
break;
|
|
396
|
+
if (await listening(socket))
|
|
397
|
+
return state;
|
|
398
|
+
await sleep(50);
|
|
399
|
+
}
|
|
400
|
+
await stopChrome(state);
|
|
401
|
+
throw new SessionError(`${name} did not start`);
|
|
402
|
+
}
|
|
200
403
|
/** profile=null makes a new temporary folder. A saved profile is kept when the run ends. */
|
|
201
404
|
export async function startChrome(options = {}) {
|
|
202
405
|
const headed = options.headed ?? false;
|
|
203
406
|
const profile = options.profile ?? null;
|
|
204
407
|
const chrome = options.chrome ?? "linux";
|
|
408
|
+
if (options.engine && ENGINES.includes(options.engine))
|
|
409
|
+
return startEngine(options.engine, { headed, profile });
|
|
410
|
+
const shell = options.engine === "headless-shell";
|
|
411
|
+
if (shell) {
|
|
412
|
+
// No window to sign in in, and a profile made by Chrome may be newer than this build.
|
|
413
|
+
if (headed)
|
|
414
|
+
throw new SessionError("The headless shell has no window, so --headed is not available");
|
|
415
|
+
if (profile)
|
|
416
|
+
throw new SessionError("The headless shell has no saved profile. Use --session new");
|
|
417
|
+
if (chrome === "windows")
|
|
418
|
+
throw new SessionError("The headless shell runs on Linux only");
|
|
419
|
+
}
|
|
205
420
|
let executable;
|
|
206
|
-
if (
|
|
421
|
+
if (shell) {
|
|
422
|
+
executable = shellBinary();
|
|
423
|
+
if (!executable)
|
|
424
|
+
throw new SessionError("chrome-headless-shell was not found (set WEBHAND_HEADLESS_SHELL)");
|
|
425
|
+
}
|
|
426
|
+
else if (chrome === "windows") {
|
|
207
427
|
executable = probes.windowsChrome();
|
|
208
428
|
if (!executable)
|
|
209
429
|
throw new SessionError("chrome.exe was not found on Windows");
|
|
@@ -228,7 +448,7 @@ export async function startChrome(options = {}) {
|
|
|
228
448
|
folder = mkdtempSync(join(tmpdir(), "webhand-"));
|
|
229
449
|
}
|
|
230
450
|
const userDataDir = chrome === "windows" ? probes.toWindows(folder) : folder;
|
|
231
|
-
const [command, ...args] = chromeArgs(executable, userDataDir, { headed });
|
|
451
|
+
const [command, ...args] = chromeArgs(executable, userDataDir, { headed, shell });
|
|
232
452
|
const child = spawn(command, args, {
|
|
233
453
|
detached: true, // its own process group, so it outlives this CLI call and stops as a group
|
|
234
454
|
stdio: "ignore",
|
|
@@ -238,7 +458,14 @@ export async function startChrome(options = {}) {
|
|
|
238
458
|
child.unref();
|
|
239
459
|
const pid = child.pid;
|
|
240
460
|
children.set(pid, child);
|
|
241
|
-
const state = {
|
|
461
|
+
const state = {
|
|
462
|
+
pid,
|
|
463
|
+
profile: folder,
|
|
464
|
+
saved_profile: profile,
|
|
465
|
+
chrome,
|
|
466
|
+
headed,
|
|
467
|
+
...(shell ? { engine: "headless-shell" } : {}),
|
|
468
|
+
};
|
|
242
469
|
const portFile = join(folder, "DevToolsActivePort");
|
|
243
470
|
const deadline = performance.now() + STARTUP_MS;
|
|
244
471
|
while (performance.now() < deadline) {
|
|
@@ -254,7 +481,7 @@ export async function startChrome(options = {}) {
|
|
|
254
481
|
}
|
|
255
482
|
await stopChrome(state);
|
|
256
483
|
if (profile && childExited(pid)) {
|
|
257
|
-
throw new SessionError(`Chrome exited at once. Is profile ${
|
|
484
|
+
throw new SessionError(`Chrome exited at once. Is profile ${quote(profile)} open in another Chrome window?`);
|
|
258
485
|
}
|
|
259
486
|
throw new SessionError("Chrome did not open a reachable debugging port");
|
|
260
487
|
}
|
|
@@ -287,9 +514,26 @@ export async function stopChrome(state) {
|
|
|
287
514
|
catch {
|
|
288
515
|
// Already gone.
|
|
289
516
|
}
|
|
290
|
-
await exited(state.pid, state.chrome === "windows" ? 5000 : 2000)
|
|
291
|
-
|
|
292
|
-
|
|
517
|
+
if (!(await exited(state.pid, state.chrome === "windows" ? 5000 : 2000))) {
|
|
518
|
+
// A browser slow to exit (a loaded machine) is still writing into its folder: end it, or the folder cannot go.
|
|
519
|
+
try {
|
|
520
|
+
process.kill(-state.pid, "SIGKILL");
|
|
521
|
+
}
|
|
522
|
+
catch {
|
|
523
|
+
// Already gone.
|
|
524
|
+
}
|
|
525
|
+
await exited(state.pid, 2000);
|
|
526
|
+
}
|
|
527
|
+
if (!state.saved_profile) {
|
|
528
|
+
// A temporary folder is only tidying: it may not fail the call, which has done what it was asked to
|
|
529
|
+
// (round of full test runs at once: ENOTEMPTY turned "the browser did not start" into a crash).
|
|
530
|
+
try {
|
|
531
|
+
rmSync(state.profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
|
|
532
|
+
}
|
|
533
|
+
catch {
|
|
534
|
+
// Left behind in the temporary folder.
|
|
535
|
+
}
|
|
536
|
+
}
|
|
293
537
|
}
|
|
294
538
|
function alive(pid) {
|
|
295
539
|
const own = childExited(pid);
|
package/dist/types.js
CHANGED
|
@@ -2,10 +2,22 @@
|
|
|
2
2
|
/** The model gave no usable decision. Nothing was executed. */
|
|
3
3
|
export class PolicyError extends Error {
|
|
4
4
|
name = "PolicyError";
|
|
5
|
+
/** Why the model refused, for the run log only (such as Jev's HTTP status, request size and error body). */
|
|
6
|
+
diagnostic;
|
|
7
|
+
constructor(message, diagnostic = null) {
|
|
8
|
+
super(message);
|
|
9
|
+
this.diagnostic = diagnostic;
|
|
10
|
+
}
|
|
5
11
|
}
|
|
6
12
|
/** A decision no longer refers to the observed page. Nothing was executed. */
|
|
7
13
|
export class StalePage extends Error {
|
|
8
14
|
name = "StalePage";
|
|
15
|
+
/** What differed from the observation, for the run log only (such as url, scroll, scope_text). */
|
|
16
|
+
changed;
|
|
17
|
+
constructor(message, changed = []) {
|
|
18
|
+
super(message);
|
|
19
|
+
this.changed = changed;
|
|
20
|
+
}
|
|
9
21
|
}
|
|
10
22
|
/** A browser mutation may have happened. It must never be retried. */
|
|
11
23
|
export class MutationUncertain extends Error {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "webhand",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Claude plans, asks, checks, and replans; Jev operates the browser toward the goal.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "sakamoto66",
|
|
@@ -25,22 +25,25 @@
|
|
|
25
25
|
"assets",
|
|
26
26
|
"LICENSE",
|
|
27
27
|
"THIRD_PARTY_LICENSE_jev-ultrafast.txt",
|
|
28
|
-
"README.md"
|
|
28
|
+
"README.md",
|
|
29
|
+
"README.ja.md"
|
|
29
30
|
],
|
|
30
31
|
"engines": {
|
|
31
32
|
"node": ">=22"
|
|
32
33
|
},
|
|
33
34
|
"scripts": {
|
|
34
|
-
"build": "tsc -p tsconfig.build.json",
|
|
35
|
+
"build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
|
|
35
36
|
"lint": "biome check .",
|
|
36
37
|
"typecheck": "tsc --noEmit",
|
|
37
38
|
"knip": "knip",
|
|
38
39
|
"check": "npm run lint && npm run typecheck && npm run knip",
|
|
40
|
+
"check:package": "node scripts/check-package.ts",
|
|
39
41
|
"test": "vitest run",
|
|
40
42
|
"test:coverage": "vitest run --coverage",
|
|
41
|
-
"
|
|
43
|
+
"test:golden:update": "UPDATE_GOLDEN=1 vitest run tests/golden.test.ts",
|
|
44
|
+
"smoke": "node research/smoke.ts",
|
|
42
45
|
"prepare": "husky",
|
|
43
|
-
"prepublishOnly": "npm run check && npm run build"
|
|
46
|
+
"prepublishOnly": "npm run check && npm run build && npm run check:package"
|
|
44
47
|
},
|
|
45
48
|
"dependencies": {
|
|
46
49
|
"playwright-core": "~1.64.1",
|
|
@@ -49,7 +52,7 @@
|
|
|
49
52
|
},
|
|
50
53
|
"devDependencies": {
|
|
51
54
|
"@biomejs/biome": "^2.6.4",
|
|
52
|
-
"@types/node": "^
|
|
55
|
+
"@types/node": "^26.6.6",
|
|
53
56
|
"@vitest/coverage-v8": "^5.1.0",
|
|
54
57
|
"husky": "^9.1.7",
|
|
55
58
|
"knip": "^6.44.1",
|