agentlane 0.0.0 → 0.4.0-rc.2

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.
Files changed (146) hide show
  1. package/CHANGELOG.md +118 -0
  2. package/LICENSE +27 -0
  3. package/README.md +167 -2
  4. package/dist/agents/claude-plugin.js +79 -0
  5. package/dist/agents/cli.js +258 -0
  6. package/dist/agents/detect.js +88 -0
  7. package/dist/agents/init.js +251 -0
  8. package/dist/agents/launcher.js +32 -0
  9. package/dist/agents/package.js +119 -0
  10. package/dist/agents/skills.js +59 -0
  11. package/dist/agents/toml.js +325 -0
  12. package/dist/agents/wiring-check.js +117 -0
  13. package/dist/agents/wiring.js +374 -0
  14. package/dist/bench/host.js +104 -0
  15. package/dist/bench/live.js +511 -0
  16. package/dist/bench/mcp-client.js +91 -0
  17. package/dist/bench/model.js +15 -0
  18. package/dist/bench/report.js +162 -0
  19. package/dist/bench/run.js +121 -0
  20. package/dist/bench/schedule.js +140 -0
  21. package/dist/bench/stats.js +59 -0
  22. package/dist/bench-cli.js +167 -0
  23. package/dist/browser/aria.js +184 -0
  24. package/dist/browser/control.js +203 -0
  25. package/dist/browser/env.js +118 -0
  26. package/dist/browser/evidence.js +44 -0
  27. package/dist/browser/install.js +361 -0
  28. package/dist/browser/kinds.js +10 -0
  29. package/dist/browser/lane-browser.js +224 -0
  30. package/dist/browser/libraries.js +56 -0
  31. package/dist/browser/paths.js +29 -0
  32. package/dist/browser/release.js +121 -0
  33. package/dist/browser/screen.js +19 -0
  34. package/dist/browser/signin.js +154 -0
  35. package/dist/browser/stop.js +163 -0
  36. package/dist/browser/tools.js +25 -0
  37. package/dist/cache/build.js +154 -0
  38. package/dist/cache/config.js +186 -0
  39. package/dist/cache/index.js +4 -0
  40. package/dist/cache/key.js +196 -0
  41. package/dist/cache/store.js +303 -0
  42. package/dist/cli.js +178 -0
  43. package/dist/clock.js +4 -0
  44. package/dist/devices/adb.js +160 -0
  45. package/dist/devices/android.js +214 -0
  46. package/dist/devices/backend.js +7 -0
  47. package/dist/devices/bundler.js +46 -0
  48. package/dist/devices/common.js +51 -0
  49. package/dist/devices/controls.js +65 -0
  50. package/dist/devices/dial.js +56 -0
  51. package/dist/devices/emulator.js +396 -0
  52. package/dist/devices/hygiene.js +202 -0
  53. package/dist/devices/index.js +5 -0
  54. package/dist/devices/launch.js +76 -0
  55. package/dist/devices/simctl.js +119 -0
  56. package/dist/devices/tools.js +1 -0
  57. package/dist/devices/variant.js +99 -0
  58. package/dist/devices/xcrun.js +265 -0
  59. package/dist/driver/absence.js +54 -0
  60. package/dist/driver/caller.js +51 -0
  61. package/dist/driver/client.js +312 -0
  62. package/dist/driver/diff.js +180 -0
  63. package/dist/driver/elements.js +70 -0
  64. package/dist/driver/engine-main.js +13 -0
  65. package/dist/driver/engine.js +499 -0
  66. package/dist/driver/errors.js +11 -0
  67. package/dist/driver/exec.js +66 -0
  68. package/dist/driver/failure.js +156 -0
  69. package/dist/driver/flow.js +94 -0
  70. package/dist/driver/idle.js +100 -0
  71. package/dist/driver/images.js +68 -0
  72. package/dist/driver/install.js +272 -0
  73. package/dist/driver/lock.js +101 -0
  74. package/dist/driver/look.js +223 -0
  75. package/dist/driver/maestro-child.js +194 -0
  76. package/dist/driver/maestro-runs.js +46 -0
  77. package/dist/driver/paths.js +105 -0
  78. package/dist/driver/pixels.js +144 -0
  79. package/dist/driver/plan.js +108 -0
  80. package/dist/driver/release.js +7 -0
  81. package/dist/driver/runner.js +42 -0
  82. package/dist/driver/selector.js +91 -0
  83. package/dist/driver/session.js +474 -0
  84. package/dist/driver/suggest.js +86 -0
  85. package/dist/driver/supervisor.js +251 -0
  86. package/dist/driver/tree.js +426 -0
  87. package/dist/driver-cli.js +865 -0
  88. package/dist/evidence/device.js +177 -0
  89. package/dist/evidence/evidence.js +304 -0
  90. package/dist/evidence/files.js +92 -0
  91. package/dist/hooks/env.js +81 -0
  92. package/dist/hooks/run.js +101 -0
  93. package/dist/mcp/server.js +69 -0
  94. package/dist/mcp/tools.js +246 -0
  95. package/dist/name.js +22 -0
  96. package/dist/plugin/aims.js +465 -0
  97. package/dist/plugin/conventions.js +73 -0
  98. package/dist/plugin/guard.js +163 -0
  99. package/dist/plugin/hook-cli.js +216 -0
  100. package/dist/plugin/session-name.js +28 -0
  101. package/dist/plugin/shell.js +254 -0
  102. package/dist/processes.js +77 -0
  103. package/dist/project/config.js +316 -0
  104. package/dist/project/schema.js +335 -0
  105. package/dist/project/validate.js +224 -0
  106. package/dist/registry/config.js +142 -0
  107. package/dist/registry/format.js +22 -0
  108. package/dist/registry/owner.js +265 -0
  109. package/dist/registry/paths.js +50 -0
  110. package/dist/registry/ports.js +26 -0
  111. package/dist/registry/prune.js +160 -0
  112. package/dist/registry/refusal.js +53 -0
  113. package/dist/registry/registry.js +1027 -0
  114. package/dist/registry/resources.js +117 -0
  115. package/dist/registry/rows.js +115 -0
  116. package/dist/registry/status.js +85 -0
  117. package/dist/registry/store.js +274 -0
  118. package/dist/registry/types.js +1 -0
  119. package/dist/registry-cli.js +544 -0
  120. package/dist/services/services.js +268 -0
  121. package/dist/services/system.js +189 -0
  122. package/dist/up/deps.js +1 -0
  123. package/dist/up/doctor.js +424 -0
  124. package/dist/up/exec.js +133 -0
  125. package/dist/up/lane-files.js +75 -0
  126. package/dist/up/lane-services.js +38 -0
  127. package/dist/up/maestro-env.js +172 -0
  128. package/dist/up/preflight.js +232 -0
  129. package/dist/up/release.js +148 -0
  130. package/dist/up/resources.js +178 -0
  131. package/dist/up/restart.js +87 -0
  132. package/dist/up/setup.js +28 -0
  133. package/dist/up/up.js +610 -0
  134. package/dist/up-cli.js +258 -0
  135. package/dist/usage.js +16 -0
  136. package/package.json +58 -3
  137. package/schema/agentlane.schema.json +675 -0
  138. package/skills/create-verification-skill/LICENSE +21 -0
  139. package/skills/create-verification-skill/SKILL.md +88 -0
  140. package/skills/dev-loop/LICENSE +21 -0
  141. package/skills/dev-loop/SKILL.md +61 -0
  142. package/skills/device/SKILL.md +8 -0
  143. package/skills/drive/SKILL.md +64 -0
  144. package/skills/maintain-verification-skill/LICENSE +21 -0
  145. package/skills/maintain-verification-skill/SKILL.md +42 -0
  146. package/skills/setup/SKILL.md +80 -0
@@ -0,0 +1,361 @@
1
+ import crypto from 'node:crypto';
2
+ import fs from 'node:fs';
3
+ import http from 'node:http';
4
+ import https from 'node:https';
5
+ import path from 'node:path';
6
+ import { pipeline } from 'node:stream/promises';
7
+ import { DriverError, messageOf } from "../driver/errors.js";
8
+ import { runCommand, tail } from "../driver/exec.js";
9
+ import { dataDir, sha256Of } from "../driver/install.js";
10
+ import { tryLock, unlock } from "../driver/lock.js";
11
+ import { CLI, envName, TOOL } from "../name.js";
12
+ import { identityOf, systemProcesses } from "../processes.js";
13
+ import { AGENT_BROWSER_RELEASE, hostKey, PLAYWRIGHT_RELEASE, } from "./release.js";
14
+ /** A Playwright browsers folder to use instead of the pinned builds, for a host they aren't pinned for. */
15
+ export const BROWSERS_OVERRIDE_ENV = envName('PLAYWRIGHT_BROWSERS');
16
+ export const INSTALL_FIX = `${CLI} browser install`;
17
+ const MARKER = '.agentlane-installed';
18
+ const LOCK_WAIT_MS = 15 * 60_000;
19
+ export function browsersPath(env) {
20
+ return env[BROWSERS_OVERRIDE_ENV] ?? path.join(dataDir(env), 'playwright', 'browsers');
21
+ }
22
+ function playwrightHome(env, release) {
23
+ return path.join(dataDir(env), 'playwright', release.version);
24
+ }
25
+ function agentBrowserHome(env, release) {
26
+ return path.join(dataDir(env), 'agent-browser', release.version);
27
+ }
28
+ export function browserFolder(build) {
29
+ return `${build.name.replaceAll('-', '_')}-${build.revision}`;
30
+ }
31
+ function readMarker(dir) {
32
+ try {
33
+ return JSON.parse(fs.readFileSync(path.join(dir, MARKER), 'utf8'));
34
+ }
35
+ catch {
36
+ return undefined;
37
+ }
38
+ }
39
+ function writeMarker(dir, marker) {
40
+ fs.writeFileSync(path.join(dir, MARKER), `${JSON.stringify(marker)}\n`);
41
+ }
42
+ function isFile(file) {
43
+ try {
44
+ return fs.statSync(file).isFile();
45
+ }
46
+ catch {
47
+ return false;
48
+ }
49
+ }
50
+ function sha512Base64(file) {
51
+ const hash = crypto.createHash('sha512');
52
+ return pipeline(fs.createReadStream(file), hash).then(() => hash.digest('base64'));
53
+ }
54
+ function archiveOf(build, host) {
55
+ return build.archives[host];
56
+ }
57
+ function unpinned(host, what) {
58
+ return new DriverError(`${TOOL} pins no ${what} build for ${host}`, `install Playwright's browsers for this host yourself (PLAYWRIGHT_BROWSERS_PATH=<folder> npx playwright@${PLAYWRIGHT_RELEASE.version} install chromium ffmpeg) and set ${BROWSERS_OVERRIDE_ENV}=<folder>`);
59
+ }
60
+ /** The state of one pinned browser build: installed and checked, absent, or there without the toolkit's check. */
61
+ function buildState(base, build, host) {
62
+ const archive = archiveOf(build, host);
63
+ const dir = path.join(base, browserFolder(build));
64
+ if (!archive)
65
+ return { kind: 'missing', what: `${build.name} ${build.revision} (no pinned build for ${host})` };
66
+ const marker = readMarker(dir);
67
+ if (!fs.existsSync(dir))
68
+ return { kind: 'missing', what: `${build.name} ${build.revision} in ${base}` };
69
+ if (marker?.hash !== archive.sha256) {
70
+ return {
71
+ kind: 'mismatch',
72
+ what: `${dir} was not installed from the pinned ${path.basename(archive.url)} (sha256 ${archive.sha256.slice(0, 12)}…)`,
73
+ };
74
+ }
75
+ if (!isFile(path.join(dir, ...archive.executable))) {
76
+ return { kind: 'mismatch', what: `${dir} lacks ${archive.executable.join('/')}` };
77
+ }
78
+ return null;
79
+ }
80
+ function packageState(home, pin, entry) {
81
+ const marker = readMarker(home);
82
+ if (!fs.existsSync(home))
83
+ return { kind: 'missing', what: `${pin.name} ${pin.version} in ${home}` };
84
+ if (marker?.hash !== pin.sha512 || marker.version !== pin.version) {
85
+ return { kind: 'mismatch', what: `${home} is not the pinned ${pin.name} ${pin.version}` };
86
+ }
87
+ if (!isFile(path.join(home, 'package', entry)))
88
+ return { kind: 'mismatch', what: `${home} lacks package/${entry}` };
89
+ return null;
90
+ }
91
+ const PLAYWRIGHT_CLI_ENTRY = path.join('lib', 'tools', 'cli-client', 'cli.js');
92
+ function executableOf(base, build, host) {
93
+ const archive = build && archiveOf(build, host);
94
+ return build && archive ? path.join(base, browserFolder(build), ...archive.executable) : '';
95
+ }
96
+ /** Whether the driver and its browsers are installed as pinned: what `doctor` reports and what a lane runs. */
97
+ export function installState(env, driver, options = {}) {
98
+ const playwright = options.playwright ?? PLAYWRIGHT_RELEASE;
99
+ const agentBrowser = options.agentBrowser ?? AGENT_BROWSER_RELEASE;
100
+ const host = options.host ?? hostKey();
101
+ const base = browsersPath(env);
102
+ const overridden = env[BROWSERS_OVERRIDE_ENV] !== undefined;
103
+ const core = playwrightHome(env, playwright);
104
+ const coreProblem = packageState(core, playwright.core, PLAYWRIGHT_CLI_ENTRY);
105
+ if (coreProblem)
106
+ return coreProblem;
107
+ if (!overridden) {
108
+ for (const build of playwright.browsers) {
109
+ const problem = buildState(base, build, host);
110
+ if (problem)
111
+ return problem;
112
+ }
113
+ }
114
+ const chromium = playwright.browsers.find(b => b.name === 'chromium');
115
+ const headlessShell = playwright.browsers.find(b => b.name === 'chromium-headless-shell');
116
+ const ffmpeg = playwright.browsers.find(b => b.name === 'ffmpeg');
117
+ const installed = {
118
+ driver,
119
+ version: playwright.version,
120
+ cli: [process.execPath, path.join(core, 'package', PLAYWRIGHT_CLI_ENTRY)],
121
+ playwrightCore: path.join(core, 'package'),
122
+ browsersPath: base,
123
+ chrome: executableOf(base, chromium, host),
124
+ headlessShell: executableOf(base, headlessShell, host),
125
+ ffmpeg: executableOf(base, ffmpeg, host),
126
+ overridden,
127
+ };
128
+ if (driver === 'playwright')
129
+ return { kind: 'installed', driver: installed };
130
+ const home = agentBrowserHome(env, agentBrowser);
131
+ const binary = agentBrowser.binaries[host];
132
+ if (binary === undefined)
133
+ return { kind: 'missing', what: `agent-browser ${agentBrowser.version} has no binary for ${host}` };
134
+ const problem = packageState(home, agentBrowser.package, binary);
135
+ if (problem)
136
+ return problem;
137
+ return {
138
+ kind: 'installed',
139
+ driver: { ...installed, version: agentBrowser.version, cli: [path.join(home, 'package', binary)] },
140
+ };
141
+ }
142
+ export function describeInstallState(driver, state) {
143
+ switch (state.kind) {
144
+ case 'installed': {
145
+ const d = state.driver;
146
+ const browsers = d.overridden
147
+ ? `the browsers in ${d.browsersPath} (${BROWSERS_OVERRIDE_ENV}, NOT the pinned builds)`
148
+ : `Chrome for Testing in ${d.browsersPath}`;
149
+ return `${driver} ${d.version}, pinned, with ${browsers}`;
150
+ }
151
+ case 'missing':
152
+ return `${driver} is not installed: ${state.what}`;
153
+ case 'mismatch':
154
+ return `${driver} does not match its pin: ${state.what}`;
155
+ }
156
+ }
157
+ /** How long a download may wait for a connection or for its next bytes; the CDN is slow from some networks. */
158
+ export const DOWNLOAD_IDLE_MS = 600_000;
159
+ const MAX_REDIRECTS = 5;
160
+ function download(url, file, redirects) {
161
+ return new Promise((resolve, reject) => {
162
+ const have = isFile(file) ? fs.statSync(file).size : 0;
163
+ const client = url.startsWith('http:') ? http : https;
164
+ const request = client.get(url, { headers: have > 0 ? { range: `bytes=${String(have)}-` } : {}, timeout: DOWNLOAD_IDLE_MS }, response => {
165
+ const status = response.statusCode ?? 0;
166
+ const location = response.headers.location;
167
+ if (status >= 300 && status < 400 && location !== undefined) {
168
+ response.resume();
169
+ if (redirects >= MAX_REDIRECTS)
170
+ reject(new DriverError(`${url} redirected more than ${String(MAX_REDIRECTS)} times`, `retry ${INSTALL_FIX}`));
171
+ else
172
+ resolve(download(new URL(location, url).toString(), file, redirects + 1));
173
+ return;
174
+ }
175
+ if (status === 416 && have > 0) {
176
+ response.resume();
177
+ fs.rmSync(file, { force: true });
178
+ resolve(download(url, file, redirects));
179
+ return;
180
+ }
181
+ if (status !== 200 && status !== 206) {
182
+ response.resume();
183
+ reject(new DriverError(`downloading ${url} failed: HTTP ${String(status)}`, `retry ${INSTALL_FIX}`));
184
+ return;
185
+ }
186
+ pipeline(response, fs.createWriteStream(file, { flags: status === 206 && have > 0 ? 'a' : 'w' })).then(resolve, reject);
187
+ });
188
+ request.on('timeout', () => {
189
+ request.destroy(new Error(`${new URL(url).host} sent nothing for ${String(DOWNLOAD_IDLE_MS / 1000)} s`));
190
+ });
191
+ request.on('error', reject);
192
+ });
193
+ }
194
+ /** Fetches a URL over HTTPS into a file, resuming what an earlier attempt left, and waiting long on a slow network. */
195
+ export const httpsFetch = (url, file) => download(url, file, 0);
196
+ async function fetchWithRetries(fetcher, url, file, size, log) {
197
+ let last;
198
+ for (let attempt = 1; attempt <= 4; attempt++) {
199
+ if (attempt > 1) {
200
+ const got = fs.statSync(file, { throwIfNoEntry: false })?.size ?? 0;
201
+ log(`${path.basename(file)}: ${messageOf(last)}; resuming at ${String(Math.round(got / 1_048_576))} MB (attempt ${String(attempt)} of 4)`);
202
+ }
203
+ try {
204
+ await fetcher(url, file);
205
+ if (size === null || fs.statSync(file).size === size)
206
+ return;
207
+ if (fs.statSync(file).size > size)
208
+ fs.rmSync(file, { force: true });
209
+ last = new Error(`${path.basename(file)} is ${String(fs.statSync(file, { throwIfNoEntry: false })?.size ?? 0)} bytes of ${String(size)}`);
210
+ }
211
+ catch (error) {
212
+ last = error;
213
+ }
214
+ }
215
+ throw new DriverError(`downloading ${url} failed after 4 attempts: ${messageOf(last)}`, `retry ${INSTALL_FIX}; a download resumes where it stopped`);
216
+ }
217
+ function refuse(what, problem) {
218
+ return new DriverError(`${problem}; refusing to install ${what}`, `retry ${INSTALL_FIX}, since a download can arrive damaged. If the same hash comes back, the published file no longer matches what this ${TOOL} pins, so upgrade ${TOOL}`);
219
+ }
220
+ class Installer {
221
+ options;
222
+ log;
223
+ work;
224
+ constructor(options, work) {
225
+ this.options = options;
226
+ this.log = options.log ?? (() => undefined);
227
+ this.work = work;
228
+ }
229
+ async obtain(url, size, what) {
230
+ const name = path.basename(new URL(url).pathname);
231
+ if (this.options.from !== undefined) {
232
+ const file = path.join(this.options.from, name);
233
+ if (!isFile(file))
234
+ throw new DriverError(`${file} is missing`, `put ${name} in ${this.options.from}, or install without --from`);
235
+ return file;
236
+ }
237
+ const file = path.join(this.work, name);
238
+ this.log(`downloading ${what}${size === null ? '' : ` (${String(Math.round(size / 1_048_576))} MB)`} from ${url}`);
239
+ await fetchWithRetries(this.options.fetch ?? httpsFetch, url, file, size, this.log);
240
+ return file;
241
+ }
242
+ async unpackPackage(pin, home) {
243
+ const what = `${pin.name} ${pin.version}`;
244
+ const file = await this.obtain(pin.tarball, null, what);
245
+ const actual = await sha512Base64(file);
246
+ if (actual !== pin.sha512)
247
+ throw refuse(what, `${path.basename(file)} hashes to sha512 ${actual}, but ${TOOL} pins ${pin.sha512}`);
248
+ const into = fs.mkdtempSync(path.join(this.work, 'package-'));
249
+ const ran = await runCommand('tar', ['-xzf', file, '-C', into], { timeoutMs: 10 * 60_000 });
250
+ if (ran.code !== 0)
251
+ throw new DriverError(`tar could not unpack ${path.basename(file)}: ${tail(ran.stderr, 5)}`, `retry ${INSTALL_FIX}`);
252
+ writeMarker(into, { version: pin.version, hash: pin.sha512, installedAt: new Date().toISOString() });
253
+ replace(home, into, this.work);
254
+ this.log(`installed ${what} in ${home}`);
255
+ }
256
+ async unpackBrowser(base, build, archive) {
257
+ const what = `${build.name} ${build.revision}`;
258
+ const file = await this.obtain(archive.url, archive.size, what);
259
+ const size = fs.statSync(file).size;
260
+ if (size !== archive.size)
261
+ throw refuse(what, `${path.basename(file)} is ${String(size)} bytes, but the pinned build is ${String(archive.size)}`);
262
+ const actual = await sha256Of(file);
263
+ if (actual !== archive.sha256)
264
+ throw refuse(what, `${path.basename(file)} hashes to sha256 ${actual}, but ${TOOL} pins ${archive.sha256}`);
265
+ const into = fs.mkdtempSync(path.join(this.work, 'browser-'));
266
+ const ran = await runCommand('unzip', ['-q', file, '-d', into], { timeoutMs: 10 * 60_000 });
267
+ if (ran.code !== 0)
268
+ throw new DriverError(`unzip of ${path.basename(file)} failed: ${tail(ran.stderr, 5)}`, `install unzip, then retry ${INSTALL_FIX}`);
269
+ const executable = path.join(into, ...archive.executable);
270
+ if (!isFile(executable))
271
+ throw refuse(what, `${path.basename(file)} has no ${archive.executable.join('/')}`);
272
+ fs.chmodSync(executable, 0o755);
273
+ fs.writeFileSync(path.join(into, 'INSTALLATION_COMPLETE'), '');
274
+ writeMarker(into, { version: build.revision, hash: archive.sha256, installedAt: new Date().toISOString() });
275
+ replace(path.join(base, browserFolder(build)), into, this.work);
276
+ this.log(`installed ${what} in ${path.join(base, browserFolder(build))}`);
277
+ }
278
+ }
279
+ function replace(target, fresh, work) {
280
+ fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
281
+ if (fs.existsSync(target))
282
+ fs.renameSync(target, path.join(work, `previous-${path.basename(target)}-${String(Date.now())}`));
283
+ fs.renameSync(fresh, target);
284
+ }
285
+ /** Links our playwright-core into the browsers folder the way Playwright's own install does, so its cleanup keeps them. */
286
+ function linkPlaywright(base, core) {
287
+ const links = path.join(base, '.links');
288
+ fs.mkdirSync(links, { recursive: true });
289
+ fs.writeFileSync(path.join(links, crypto.createHash('sha1').update(core).digest('hex')), core);
290
+ }
291
+ /** Installs what the driver needs that is missing or does not match its pin, under a lock held across processes. */
292
+ export async function ensureBrowserDriver(driver, options) {
293
+ const releases = {
294
+ playwright: options.playwright ?? PLAYWRIGHT_RELEASE,
295
+ agentBrowser: options.agentBrowser ?? AGENT_BROWSER_RELEASE,
296
+ host: options.host ?? hostKey(),
297
+ };
298
+ const before = installState(options.env, driver, releases);
299
+ if (before.kind === 'installed')
300
+ return before.driver;
301
+ const root = dataDir(options.env);
302
+ fs.mkdirSync(root, { recursive: true, mode: 0o700 });
303
+ const processes = options.processes ?? systemProcesses;
304
+ const me = identityOf(processes, process.pid);
305
+ if (!me)
306
+ throw new Error(`ps could not read this process's start time (pid ${String(process.pid)})`);
307
+ const lock = path.join(root, '.browsers.lock');
308
+ const deadline = Date.now() + (options.lockWaitMs ?? LOCK_WAIT_MS);
309
+ let announced = false;
310
+ for (;;) {
311
+ const attempt = tryLock(lock, me, processes);
312
+ if (attempt.acquired)
313
+ break;
314
+ if (Date.now() > deadline) {
315
+ throw new DriverError(`another process (pid ${String(attempt.holder?.pid ?? '?')}) has been installing the browser drivers for too long`, `wait for it, or remove ${lock} if that process is gone`);
316
+ }
317
+ if (!announced)
318
+ options.log?.(`waiting for pid ${String(attempt.holder?.pid ?? '?')}, which is installing the browser drivers`);
319
+ announced = true;
320
+ await new Promise(resolve => setTimeout(resolve, 500));
321
+ }
322
+ const work = fs.mkdtempSync(path.join(root, '.browsers-install-'));
323
+ try {
324
+ const installer = new Installer(options, work);
325
+ const { playwright, agentBrowser, host } = releases;
326
+ const core = playwrightHome(options.env, playwright);
327
+ if (packageState(core, playwright.core, PLAYWRIGHT_CLI_ENTRY))
328
+ await installer.unpackPackage(playwright.core, core);
329
+ if (options.env[BROWSERS_OVERRIDE_ENV] === undefined) {
330
+ const base = browsersPath(options.env);
331
+ fs.mkdirSync(base, { recursive: true, mode: 0o700 });
332
+ linkPlaywright(base, path.join(core, 'package'));
333
+ for (const build of playwright.browsers) {
334
+ if (!buildState(base, build, host))
335
+ continue;
336
+ const archive = archiveOf(build, host);
337
+ if (!archive)
338
+ throw unpinned(host, build.name);
339
+ await installer.unpackBrowser(base, build, archive);
340
+ }
341
+ }
342
+ if (driver === 'agent-browser') {
343
+ const binary = agentBrowser.binaries[host];
344
+ if (binary === undefined)
345
+ throw unpinned(host, 'agent-browser');
346
+ const home = agentBrowserHome(options.env, agentBrowser);
347
+ if (packageState(home, agentBrowser.package, binary)) {
348
+ await installer.unpackPackage(agentBrowser.package, home);
349
+ fs.chmodSync(path.join(home, 'package', binary), 0o755);
350
+ }
351
+ }
352
+ const after = installState(options.env, driver, releases);
353
+ if (after.kind !== 'installed')
354
+ throw new DriverError(describeInstallState(driver, after), `retry ${INSTALL_FIX}`);
355
+ return after.driver;
356
+ }
357
+ finally {
358
+ fs.rmSync(work, { recursive: true, force: true });
359
+ unlock(lock, me);
360
+ }
361
+ }
@@ -0,0 +1,10 @@
1
+ export const BROWSER_DRIVERS = ['playwright', 'agent-browser'];
2
+ export const DEFAULT_BROWSER_DRIVER = 'playwright';
3
+ /** The ports table rows a lane's browser holds, beside its services' rows. */
4
+ export const BROWSER_DEBUG_SERVICE = 'browser';
5
+ export const BROWSER_STREAM_SERVICE = 'browser-stream';
6
+ export const BROWSER_PORT_TYPE = 'browser';
7
+ export const BROWSER_SERVICES = [BROWSER_DEBUG_SERVICE, BROWSER_STREAM_SERVICE];
8
+ export function isBrowserDriver(value) {
9
+ return typeof value === 'string' && BROWSER_DRIVERS.includes(value);
10
+ }
@@ -0,0 +1,224 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { DriverError, messageOf } from "../driver/errors.js";
4
+ import { CLI } from "../name.js";
5
+ import { laneEnvironment, webUrl } from "../hooks/env.js";
6
+ import { loadLaneConfig } from "../project/config.js";
7
+ import { laneDir, readUpRecord } from "../up/lane-files.js";
8
+ import { browserVariables, cdpUrl, writeDriverFiles } from "./env.js";
9
+ import { INSTALL_FIX, describeInstallState } from "./install.js";
10
+ import { browserPaths } from "./paths.js";
11
+ import { acceptSavedLogin, describeSavedLogin } from "./signin.js";
12
+ import { describeProcesses, onProfile, stopBrowserProcesses } from "./stop.js";
13
+ const SHIM = { playwright: 'playwright-cli', 'agent-browser': 'agent-browser' };
14
+ export function hasBrowser(lane) {
15
+ return lane.browser !== null;
16
+ }
17
+ export function pathsOf(stateDir, lane) {
18
+ return browserPaths(stateDir, lane.id, lane.browser.session);
19
+ }
20
+ function marksOf(stateDir, lane, session) {
21
+ return { session, paths: browserPaths(stateDir, lane, session) };
22
+ }
23
+ /** Installs the lane's driver if it must, writes its wrapper and settings, and returns its variables and control. */
24
+ export async function laneBrowser(ctx, install) {
25
+ const { browser } = ctx.lane;
26
+ const installed = install ?? (await ctx.tools.install(browser.driver, ctx.env, ctx.log));
27
+ const setting = {
28
+ browser,
29
+ paths: pathsOf(ctx.stateDir, ctx.lane),
30
+ install: installed,
31
+ headed: ctx.config?.web?.browser.headed ?? false,
32
+ url: ctx.url,
33
+ };
34
+ writeDriverFiles(setting, ctx.lane.id);
35
+ const vars = browserVariables(setting, ctx.laneEnv.PATH ?? ctx.env.PATH ?? '/usr/bin:/bin');
36
+ const control = ctx.tools.control(browser.driver, path.join(setting.paths.bin, SHIM[browser.driver]), { ...ctx.laneEnv, ...vars }, ctx.cwd);
37
+ return { setting, vars, control };
38
+ }
39
+ /**
40
+ * The lane's browser for a command outside `up` (look, screenshot, evidence, release): with the config `up` last ran
41
+ * for it when that config still loads, so the web app's URL and the headed setting carry over.
42
+ */
43
+ export async function browserOfLane(tools, stateDir, lane, env, install) {
44
+ const dir = laneDir(stateDir, lane.id);
45
+ const record = readUpRecord(dir);
46
+ const config = (() => {
47
+ try {
48
+ return record ? loadLaneConfig(record.config, record.platform) : null;
49
+ }
50
+ catch {
51
+ return null;
52
+ }
53
+ })();
54
+ return laneBrowser({
55
+ tools,
56
+ stateDir,
57
+ lane,
58
+ config,
59
+ url: webUrl(config, lane),
60
+ env,
61
+ laneEnv: laneEnvironment(env, lane, config, dir),
62
+ cwd: config?.dir ?? lane.worktree,
63
+ log: () => undefined,
64
+ }, install);
65
+ }
66
+ /** Stops whatever of the lane's browser runs under the driver it no longer uses, after its driver changed. */
67
+ async function stopOtherDriver(ctx, clock) {
68
+ const stopped = await stopBrowserProcesses(ctx.tools.processes, marksOf(ctx.stateDir, ctx.lane.id, ctx.lane.browser.session), clock);
69
+ return stopped.stopped.length > 0 ? `stopped ${describeProcesses(stopped.stopped)} left from before` : null;
70
+ }
71
+ /** Opens the web app in the lane's browser: started with the lane's profile, on its debugging port. */
72
+ export async function openWebApp(ctx, clock, driverChanged) {
73
+ if (ctx.url === null)
74
+ throw new Error(`lane ${ctx.lane.id} has no port for the web app's service`);
75
+ const notes = [];
76
+ if (driverChanged) {
77
+ const left = await stopOtherDriver(ctx, clock);
78
+ if (left)
79
+ notes.push(left);
80
+ }
81
+ const browser = await laneBrowser(ctx);
82
+ const libraries = await librariesCheck(ctx.tools, browser.setting.install);
83
+ if (libraries && !libraries.ok)
84
+ throw new DriverError(libraries.detail, libraries.fix);
85
+ await browser.control.open(ctx.url);
86
+ const where = `${browser.control.driver} session ${ctx.lane.browser.session}, debugging port ${String(ctx.lane.browser.debugPort)}${ctx.lane.browser.streamPort === null ? '' : `, stream port ${String(ctx.lane.browser.streamPort)}`}`;
87
+ return { browser, detail: [`opened ${ctx.url} (${where})`, ...notes].join('; ') };
88
+ }
89
+ /** Starts the lane's browser on the saved login the signin hook wrote, and opens the web app again with it. */
90
+ export async function signInBrowser(ctx, browser) {
91
+ const login = acceptSavedLogin(browser.setting.paths.storageState, ctx.url);
92
+ await browser.control.loadState(login.file);
93
+ if (ctx.url !== null)
94
+ await browser.control.open(ctx.url);
95
+ return login;
96
+ }
97
+ export { describeSavedLogin };
98
+ /** Keeps a trace of the driver's actions running, so a failed command run under `exec` can leave it behind. */
99
+ export async function startFailureTrace(browser) {
100
+ if (!browser.control.tracesActions)
101
+ return false;
102
+ await browser.control.traceStart();
103
+ return true;
104
+ }
105
+ /** Removes what the lane's browser kept that holds its login: the profile and the saved login. Evidence stays. */
106
+ function forgetLogin(paths) {
107
+ for (const target of [paths.profile, paths.storageState, paths.playwrightSessions, paths.output, paths.agentBrowserSockets]) {
108
+ fs.rmSync(target, { recursive: true, force: true });
109
+ }
110
+ }
111
+ /** Stops a lane's browser: the driver's own close first, then every process of it the process table still shows. */
112
+ export async function stopLaneBrowser(tools, stateDir, lane, session, clock, control) {
113
+ const result = { notes: [], problems: [] };
114
+ if (control) {
115
+ try {
116
+ if (await control.isOpen()) {
117
+ await control.close();
118
+ result.notes.push(`closed the ${control.driver} session ${session}`);
119
+ }
120
+ }
121
+ catch (error) {
122
+ result.notes.push(`the driver could not close its session (${messageOf(error).split('\n')[0] ?? ''}); stopping its processes`);
123
+ }
124
+ }
125
+ const marks = marksOf(stateDir, lane, session);
126
+ const stopped = await stopBrowserProcesses(tools.processes, marks, clock);
127
+ if (stopped.stopped.length > 0)
128
+ result.notes.push(`stopped the browser's processes: ${describeProcesses(stopped.stopped)}`);
129
+ if (stopped.left === undefined)
130
+ result.problems.push(`the process table could not be read, so the browser of lane ${lane} may still run`);
131
+ else if (stopped.left.length > 0)
132
+ result.problems.push(`the browser of lane ${lane} survived SIGKILL: ${describeProcesses(stopped.left)}`);
133
+ else
134
+ forgetLogin(marks.paths);
135
+ return result;
136
+ }
137
+ /** Stops the browsers of lanes that have ended, however they ended, and forgets each once nothing of it runs. */
138
+ export async function stopEndedBrowsers(tools, registry, stateDir, clock) {
139
+ const results = [];
140
+ for (const ended of registry.endedBrowsers()) {
141
+ const done = await stopLaneBrowser(tools, stateDir, ended.lane, ended.session, clock, null);
142
+ if (done.problems.length === 0)
143
+ registry.forgetBrowser(ended.lane);
144
+ if (done.notes.length > 0 || done.problems.length > 0)
145
+ results.push({ lane: ended.lane, ...done });
146
+ }
147
+ return results;
148
+ }
149
+ const UP = `${CLI} up`;
150
+ /** Playwright's own command that installs, through apt, the system libraries its Chromium builds need. */
151
+ export function installDepsCommand(installed, root = process.getuid?.() === 0) {
152
+ return `${root ? '' : 'sudo '}${process.execPath} ${path.join(installed.playwrightCore, 'cli.js')} install-deps chromium`;
153
+ }
154
+ /** Whether the machine has the system libraries the lane's browsers link; null where that isn't checked. */
155
+ async function librariesCheck(tools, installed) {
156
+ const missing = await tools.missingLibraries(installed);
157
+ if (missing === null)
158
+ return null;
159
+ const ok = missing.length === 0;
160
+ return {
161
+ name: 'browser libraries',
162
+ ok,
163
+ detail: ok
164
+ ? 'Chrome for Testing finds every system library it links'
165
+ : `Chrome for Testing can't start without system libraries this machine lacks: ${missing.join(', ')}`,
166
+ fix: ok
167
+ ? ''
168
+ : `${installDepsCommand(installed)} (apt packages, for Ubuntu and Debian; elsewhere install the packages that provide these libraries)`,
169
+ };
170
+ }
171
+ /** Whether the lane's browser runs, and is this lane's: its debugging port answers, from a browser on the lane's profile. */
172
+ export async function browserChecks(tools, stateDir, lane, env) {
173
+ const { browser } = lane;
174
+ const state = tools.state(browser.driver, env);
175
+ const checks = [
176
+ {
177
+ name: 'browser driver',
178
+ ok: state.kind === 'installed',
179
+ detail: describeInstallState(browser.driver, state),
180
+ fix: state.kind === 'installed' ? '' : `${INSTALL_FIX}${browser.driver === 'agent-browser' ? ' --driver agent-browser' : ''}`,
181
+ },
182
+ ];
183
+ if (state.kind === 'installed') {
184
+ const libraries = await librariesCheck(tools, state.driver);
185
+ if (libraries)
186
+ checks.push(libraries);
187
+ }
188
+ const paths = pathsOf(stateDir, lane);
189
+ const answer = await tools.probe(`${cdpUrl(browser)}/json/version`);
190
+ const table = tools.processes.list();
191
+ const running = table?.filter(e => onProfile(e.args, paths.profile)) ?? [];
192
+ if (answer?.status !== 200) {
193
+ checks.push({
194
+ name: 'browser',
195
+ ok: false,
196
+ detail: running.length > 0
197
+ ? `a browser runs on the lane's profile (${describeProcesses(running.slice(0, 1))}), but nothing answers on its debugging port ${String(browser.debugPort)}`
198
+ : `the lane's browser is not running: nothing answers on its debugging port ${String(browser.debugPort)}`,
199
+ fix: `${UP} (it opens the web app in the lane's browser)`,
200
+ });
201
+ return checks;
202
+ }
203
+ const version = (() => {
204
+ try {
205
+ return JSON.parse(answer.body).Browser ?? 'a browser';
206
+ }
207
+ catch {
208
+ return 'something that is not a browser';
209
+ }
210
+ })();
211
+ const listening = tools.listeners(browser.debugPort);
212
+ const ours = listening === undefined ? running.length > 0 : listening.some(pid => running.some(e => e.pid === pid));
213
+ checks.push({
214
+ name: 'browser',
215
+ ok: ours,
216
+ detail: ours
217
+ ? `${version} on debugging port ${String(browser.debugPort)}, with this lane's profile ${paths.profile}, ${browser.driver} session ${browser.session}`
218
+ : `${version} answers on debugging port ${String(browser.debugPort)}, but no browser runs on this lane's profile ${paths.profile}: that port is another browser's`,
219
+ fix: ours
220
+ ? ''
221
+ : `stop what listens on ${String(browser.debugPort)} (lsof -nP -iTCP:${String(browser.debugPort)} -sTCP:LISTEN), then ${UP}`,
222
+ });
223
+ return checks;
224
+ }
@@ -0,0 +1,56 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { runCommand } from "../driver/exec.js";
4
+ /** The libraries `ldd` lists as `<name> => not found`. */
5
+ export function notFound(lddOutput) {
6
+ return lddOutput
7
+ .split('\n')
8
+ .map(line => line.trim())
9
+ .filter(line => line.endsWith('not found') && line.includes('=>'))
10
+ .map(line => line.split('=>')[0]?.trim() ?? '')
11
+ .filter(name => name !== '');
12
+ }
13
+ function sharedLibrariesBeside(executable) {
14
+ const folder = path.dirname(executable);
15
+ try {
16
+ return fs
17
+ .readdirSync(folder)
18
+ .filter(name => /\.so(\.|$)/.test(name))
19
+ .map(name => path.join(folder, name))
20
+ .filter(file => fs.statSync(file).isFile());
21
+ }
22
+ catch {
23
+ return [];
24
+ }
25
+ }
26
+ /**
27
+ * The system libraries the executables, and the shared libraries shipped beside them, need and the machine lacks,
28
+ * sorted; null when ldd can't run or none of them exists. Each executable's own folder is on the library path, as the
29
+ * browser loads from it.
30
+ */
31
+ export async function missingLibraries(executables, ldd) {
32
+ const present = executables.filter(e => e !== '' && fs.statSync(e, { throwIfNoEntry: false })?.isFile());
33
+ if (present.length === 0)
34
+ return null;
35
+ const missing = new Set();
36
+ for (const executable of present) {
37
+ for (const file of [executable, ...sharedLibrariesBeside(executable)]) {
38
+ const output = await ldd(file, [path.dirname(executable)]);
39
+ if (output === null)
40
+ return null;
41
+ for (const name of notFound(output))
42
+ missing.add(name);
43
+ }
44
+ }
45
+ return [...missing].sort();
46
+ }
47
+ export const systemLdd = async (file, libraryPath) => {
48
+ const inherited = process.env.LD_LIBRARY_PATH;
49
+ const ran = await runCommand('ldd', [file], {
50
+ env: { ...process.env, LD_LIBRARY_PATH: [...(inherited ? [inherited] : []), ...libraryPath].join(':') },
51
+ timeoutMs: 30_000,
52
+ });
53
+ if (ran.error !== undefined)
54
+ return null;
55
+ return ran.stdout;
56
+ };