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/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 { pyRepr, pyStr, pyTruthy } from "./py.js";
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: ${pyRepr(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: ${pyRepr(service)}`);
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 ${pyRepr(key[0])} has unknown default ${pyRepr(fallback)}`);
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 (!pyTruthy(layer))
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", "sources"].filter((key) => !pyTruthy(data[key]));
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: pyTruthy(get(login, "required")), url: get(login, "url", null) },
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(pyStr),
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 ${pyRepr(pair)}`);
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", "sources", "steps"];
239
- const missing = required.filter((key) => !pyTruthy(data[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 ${pyRepr(data.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 ${pyRepr(unknown)}`);
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 ${pyRepr(param)} has no value. Pass --param ${param}=VALUE`);
271
+ throw new RunbookError(`${file}: parameter ${quote(param)} has no value. Pass --param ${param}=VALUE`);
257
272
  }
258
- return pyStr(value);
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 ${pyRepr(actor)}`);
265
- if (!pyTruthy(step.instruction))
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: pyTruthy(step.done_when) ? fill(step.done_when) : null,
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 { tmpdir } from "node:os";
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 { pyRepr, sleep } from "./py.js";
19
+ import { quote, sleep } from "./format.js";
18
20
  import * as workspace from "./workspace.js";
19
- const STARTUP_MS = 15_000;
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 join(home(), "session.json");
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 = join(home(), "session.tmp");
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 ${pyRepr(spec)}`);
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 ${pyRepr(choice)}`);
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: ${pyRepr(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
- "--window-size=1120,867", // The browser UI takes 87px; the page viewport is 1120x780.
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 (chrome === "windows") {
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 = { pid, profile: folder, saved_profile: profile, chrome, headed };
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 ${pyRepr(profile)} open in another Chrome window?`);
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
- if (!state.saved_profile)
292
- rmSync(state.profile, { recursive: true, force: true });
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.2.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
- "smoke": "node src/run.ts",
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": "^24.19.2",
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",