turno-browser 0.4.0 → 0.6.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.
Files changed (72) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +92 -149
  3. package/dist/act-model.js +4 -3
  4. package/dist/act.js +2 -1
  5. package/dist/api.d.ts +63 -2
  6. package/dist/api.js +14 -4
  7. package/dist/background-state.d.ts +54 -0
  8. package/dist/background-state.js +97 -0
  9. package/dist/background.d.ts +69 -0
  10. package/dist/background.js +458 -0
  11. package/dist/bin/mcp.js +48 -8
  12. package/dist/captcha.js +3 -2
  13. package/dist/cli/background.d.ts +11 -0
  14. package/dist/cli/background.js +132 -0
  15. package/dist/cli/commands.d.ts +16 -0
  16. package/dist/cli/commands.js +515 -0
  17. package/dist/cli/completion.d.ts +11 -0
  18. package/dist/cli/completion.js +107 -0
  19. package/dist/cli/context.d.ts +75 -0
  20. package/dist/cli/context.js +44 -0
  21. package/dist/cli/do-background.d.ts +27 -0
  22. package/dist/cli/do-background.js +212 -0
  23. package/dist/cli/do.d.ts +85 -0
  24. package/dist/cli/do.js +558 -0
  25. package/dist/cli/flows.d.ts +28 -0
  26. package/dist/cli/flows.js +303 -0
  27. package/dist/cli/identity.d.ts +37 -0
  28. package/dist/cli/identity.js +906 -0
  29. package/dist/cli/live.d.ts +7 -0
  30. package/dist/cli/live.js +99 -0
  31. package/dist/cli/main.d.ts +16 -0
  32. package/dist/cli/main.js +194 -0
  33. package/dist/cli/secret.d.ts +4 -0
  34. package/dist/cli/secret.js +151 -0
  35. package/dist/cli/session.d.ts +6 -0
  36. package/dist/cli/session.js +106 -0
  37. package/dist/cli/setup.d.ts +13 -0
  38. package/dist/cli/setup.js +180 -0
  39. package/dist/cli/vault.d.ts +5 -0
  40. package/dist/cli/vault.js +192 -0
  41. package/dist/client.d.ts +82 -0
  42. package/dist/client.js +303 -0
  43. package/dist/doctor.js +34 -1
  44. package/dist/engine-camoufox.js +5 -4
  45. package/dist/engine-lightpanda.js +3 -2
  46. package/dist/engine.js +2 -1
  47. package/dist/health.js +2 -1
  48. package/dist/host.d.ts +21 -0
  49. package/dist/host.js +75 -15
  50. package/dist/human-input.js +7 -2
  51. package/dist/identities.js +2 -1
  52. package/dist/index.d.ts +5 -1
  53. package/dist/index.js +2 -0
  54. package/dist/lifecycle.d.ts +2 -0
  55. package/dist/lifecycle.js +2 -1
  56. package/dist/live-client.js +8 -6
  57. package/dist/live-page.d.ts +0 -7
  58. package/dist/live-page.js +3 -2
  59. package/dist/live-server.js +6 -3
  60. package/dist/live.js +2 -1
  61. package/dist/login-tool.js +3 -2
  62. package/dist/login.js +2 -1
  63. package/dist/names.d.ts +28 -0
  64. package/dist/names.js +25 -0
  65. package/dist/network.d.ts +1 -1
  66. package/dist/network.js +4 -3
  67. package/dist/opt-in-settings.js +3 -2
  68. package/dist/replay.js +4 -3
  69. package/dist/runtime-lock.js +3 -2
  70. package/dist/vault.js +5 -4
  71. package/npm-shrinkwrap.json +6 -5
  72. package/package.json +13 -7
@@ -0,0 +1,515 @@
1
+ import { DRY_RUN, JSON_FLAG, bool, fail, group, jsonOutput, emit, needsAnswer, paint, parseFlags, str, } from "turno-core/cli";
2
+ import { tildify } from "turno-core/paths";
3
+ import { useNames } from "../names.js";
4
+ import { context } from "./context.js";
5
+ import { ACTION_NAMES, DO_JSON, browserDo, doDetails, doFlagNames, doSynopsis } from "./do.js";
6
+ import * as flowCmd from "./flows.js";
7
+ import * as ident from "./identity.js";
8
+ import * as liveCmd from "./live.js";
9
+ import * as session from "./session.js";
10
+ import { vaultCommand } from "./vault.js";
11
+ import { BACKGROUND_JSON, backgroundCommand } from "./background.js";
12
+ import { secretCommand } from "./secret.js";
13
+ import { SETUP_DETAILS, SETUP_JSON, setup } from "./setup.js";
14
+ /**
15
+ * The identity commands of turno-browser: `turno-browser <cmd>` on its own, `turno browser <cmd>`
16
+ * inside turno-cli. Each command reads its names from the host, so help, hints and errors name
17
+ * the program the person typed.
18
+ */
19
+ /** `bench --json`: turno-browser's report. */
20
+ const BENCH_JSON = jsonOutput(["version", "startedAt", "finishedAt", "engines", "results", "file"]);
21
+ /** `identities --json` (and `list --json`): one element per identity. */
22
+ const IDENTITIES_JSON = jsonOutput(["id", "inUse", "dir"]);
23
+ function checkId(c, id, sub) {
24
+ if (!id)
25
+ return fail(`${c.names.subject}${sub} needs an identity id (for example: ${c.names.browser} ${sub} school)`);
26
+ try {
27
+ c.api.assertIdentityId(id);
28
+ }
29
+ catch (err) {
30
+ return fail(err.message);
31
+ }
32
+ return id;
33
+ }
34
+ const BENCH_FLAGS = {
35
+ engine: { type: "string", multiple: true },
36
+ url: { type: "string", multiple: true },
37
+ "only-urls": { type: "boolean" },
38
+ // Older name of --only-urls, kept so scripts keep working.
39
+ "no-detectors": { type: "boolean" },
40
+ yes: { type: "boolean", short: "y" },
41
+ ...JSON_FLAG,
42
+ };
43
+ const BENCH_PROMPT = "This opens Chrome and visits third-party test pages. Continue? [y/N] ";
44
+ const URLS_PROMPT = "This opens Chrome and visits the URLs you gave. Continue? [y/N] ";
45
+ async function bench(c, args, io) {
46
+ const mod = c.api;
47
+ const p = parseFlags(args, BENCH_FLAGS, 0);
48
+ const list = (name) => (p.values[name] ?? [])
49
+ .flatMap((v) => v.split(","))
50
+ .map((v) => v.trim())
51
+ .filter(Boolean);
52
+ const given = list("engine");
53
+ const urls = p.values.url ?? [];
54
+ const onlyUrls = bool(p, "only-urls") || bool(p, "no-detectors");
55
+ const engines = [];
56
+ for (const e of given) {
57
+ const id = mod.engineId(e);
58
+ if (!id)
59
+ return fail(`unknown engine "${e}" (known: ${mod.ENGINES.join(", ")})`);
60
+ engines.push(id);
61
+ }
62
+ for (const u of urls) {
63
+ if (!/^https?:\/\//.test(u))
64
+ return fail(`--url must start with http:// or https://: ${u}`);
65
+ }
66
+ if (onlyUrls && urls.length === 0)
67
+ return fail("--only-urls needs at least one --url");
68
+ // Opening a browser on outside pages needs a yes from a person: --json is not consent.
69
+ if (!bool(p, "yes")) {
70
+ if (!c.deps.interactive(io)) {
71
+ io.err(`${c.names.subject}bench opens Chrome and visits third-party test pages.`);
72
+ return needsAnswer(`${c.names.subject}bench`);
73
+ }
74
+ if (!(await c.deps.confirm(onlyUrls ? URLS_PROMPT : BENCH_PROMPT, io))) {
75
+ io.err("Cancelled; nothing was opened.");
76
+ return 1;
77
+ }
78
+ }
79
+ const report = await mod.runBench({
80
+ engines,
81
+ urls,
82
+ detectors: !onlyUrls,
83
+ env: io.env,
84
+ onProgress: (m) => io.err(paint(io, m, "2")),
85
+ });
86
+ if (bool(p, "json")) {
87
+ emit(io, p, BENCH_JSON, report);
88
+ }
89
+ else {
90
+ io.out(mod.formatBenchTable(report));
91
+ if (report.file)
92
+ io.out(`\nreport: ${tildify(report.file, io.env)}`);
93
+ }
94
+ return 0;
95
+ }
96
+ function identities(c, args, io) {
97
+ const p = parseFlags(args, JSON_FLAG, 0);
98
+ const list = c.api.listIdentities(io.env);
99
+ if (bool(p, "json")) {
100
+ emit(io, p, IDENTITIES_JSON, list.map((i) => ({ id: i.id, inUse: i.inUse, dir: tildify(i.dir, io.env) })));
101
+ return 0;
102
+ }
103
+ if (!list.length) {
104
+ io.out(`No browser identities yet. Create one with \`${c.names.identity("add", "<id>")}\`.`);
105
+ return 0;
106
+ }
107
+ const width = Math.max(...list.map((i) => i.id.length));
108
+ for (const i of list) {
109
+ const state = i.inUse ? paint(io, "in use", "33") : paint(io, "free ", "32");
110
+ io.out(`${i.id.padEnd(width)} ${state} ${tildify(i.dir, io.env)}`);
111
+ }
112
+ return 0;
113
+ }
114
+ function add(c, args, io) {
115
+ const p = parseFlags(args, { ...DRY_RUN, ...ident.SETTINGS_FLAGS }, 1);
116
+ const id = checkId(c, p.positionals[0], "add");
117
+ const settings = ident.settingsPatch(p);
118
+ if (bool(p, "dry-run")) {
119
+ io.out(`(dry run) would create browser identity "${id}"`);
120
+ return 0;
121
+ }
122
+ const info = ident.hasSettings(settings) ? c.api.addIdentity(id, io.env, settings) : c.api.addIdentity(id, io.env);
123
+ io.out(`identity "${id}" ready at ${tildify(info.dir, io.env)}`);
124
+ io.out(`settings (time zone, languages, health check) in ${tildify(c.api.identitySettingsPath(id, io.env), io.env)}`);
125
+ c.host.connect(id, settings, io);
126
+ return 0;
127
+ }
128
+ async function remove(c, args, io) {
129
+ const mod = c.api;
130
+ const p = parseFlags(args, DRY_RUN, 1);
131
+ const id = checkId(c, p.positionals[0], "remove");
132
+ if (bool(p, "dry-run")) {
133
+ io.out(`(dry run) would delete browser identity "${id}", its saved logins and its vault credentials`);
134
+ return 0;
135
+ }
136
+ if (mod.isInUse(id, io.env))
137
+ return fail(`identity "${id}" is in use by a running Chrome; close it first`);
138
+ // The vault's secret store items first: removeIdentity refuses while they exist.
139
+ const cleared = await mod.vaultClear(id, { env: io.env });
140
+ if (cleared)
141
+ io.out(`deleted ${cleared} vault credential${cleared === 1 ? "" : "s"} of "${id}" from the secret store`);
142
+ mod.removeIdentity(id, io.env);
143
+ io.out(`removed identity "${id}" and its saved browser data`);
144
+ c.host.removed?.(id, io);
145
+ return 0;
146
+ }
147
+ async function login(c, args, io) {
148
+ const mod = c.api;
149
+ const p = parseFlags(args, { url: { type: "string" } }, 1);
150
+ const id = checkId(c, p.positionals[0], "login");
151
+ const url = str(p, "url");
152
+ if (url !== undefined && !/^https?:\/\//.test(url))
153
+ return fail(`--url must start with http:// or https://: ${url}`);
154
+ const holder = mod.inUseBy(id, io.env);
155
+ if (holder)
156
+ return fail(holder);
157
+ if (mod.isInUse(id, io.env)) {
158
+ return fail(`identity "${id}" is in use by a running Chrome (${c.host.busy?.holder ?? "probably an agent's MCP session"}). Close that session or wait for ${c.host.busy?.end ?? "it to end"}, then retry.`);
159
+ }
160
+ io.out(`Opening Chrome for identity "${id}". Sign in to your sites, then close the window to save the session.`);
161
+ const options = { env: io.env };
162
+ if (url)
163
+ options.url = url;
164
+ await mod.loginIdentity(id, options);
165
+ io.out(`saved. Sessions using browser-${id} now start signed in.`);
166
+ return 0;
167
+ }
168
+ /** The first argument that is not a flag, without parsing the flags. */
169
+ function firstId(args) {
170
+ return args.find((a) => !a.startsWith("-"));
171
+ }
172
+ /** Run one subcommand. turno's `identity` command uses it for browser:<id>. */
173
+ async function dispatch(c, sub, rest, io) {
174
+ try {
175
+ switch (sub) {
176
+ case "identities":
177
+ case "list":
178
+ return identities(c, rest, io);
179
+ case "add":
180
+ return add(c, rest, io);
181
+ case "remove":
182
+ case "rm":
183
+ return await remove(c, rest, io);
184
+ case "login":
185
+ return await login(c, rest, io);
186
+ case "bench":
187
+ return await bench(c, rest, io);
188
+ case "export":
189
+ return await session.exportSession(c, rest, io);
190
+ case "import":
191
+ return await session.importSession(c, rest, io);
192
+ case "show":
193
+ return ident.show(c, checkId(c, firstId(rest), "show"), rest, io);
194
+ case "set":
195
+ return ident.set(c, checkId(c, firstId(rest), "set"), rest, io);
196
+ case "doctor":
197
+ return await ident.doctor(c, rest, io);
198
+ case "reputation":
199
+ return ident.reputation(c, rest, io, (id) => checkId(c, id, "reputation"));
200
+ case "flows":
201
+ return flowCmd.flows(c, rest, io);
202
+ case "replay":
203
+ return await flowCmd.replay(c, rest, io);
204
+ case "traces":
205
+ return await flowCmd.traces(c, rest, io);
206
+ case "record":
207
+ return flowCmd.record(c, rest, io);
208
+ case "live":
209
+ return await liveCmd.live(c, rest, io);
210
+ case "pause":
211
+ return await liveCmd.pause(c, rest, io);
212
+ case "resume":
213
+ return await liveCmd.resume(c, rest, io);
214
+ case "setup":
215
+ return setup(c, rest, io);
216
+ default:
217
+ return fail(`unknown ${c.names.subject}command "${sub}"`);
218
+ }
219
+ }
220
+ catch (err) {
221
+ const name = err.name;
222
+ if (["IdentityError", "VaultError", "SealError", "FlowError", "LiveError"].includes(name))
223
+ return fail(err.message);
224
+ throw err;
225
+ }
226
+ }
227
+ /**
228
+ * `<browser> <id> <action>`, the short form of `<browser> do <id> <action>`: taken when the first
229
+ * word is not a subcommand and the second is an action. An identity named like a subcommand
230
+ * (`show`, `flows`) needs the long form, and the docs use the long form so a later subcommand can
231
+ * never change what a written command does.
232
+ */
233
+ function shortDo(args, subs) {
234
+ const [first, second] = args;
235
+ return (first !== undefined &&
236
+ second !== undefined &&
237
+ !(first in subs) &&
238
+ /^[a-z0-9][a-z0-9_-]*$/.test(first) &&
239
+ ACTION_NAMES.includes(second));
240
+ }
241
+ /** The examples of the group's help, typed the way the host names the commands. */
242
+ function examples(c) {
243
+ const b = c.names.browser;
244
+ return [
245
+ `${b} identities`,
246
+ `${b} add school --languages es-MX,es,en`,
247
+ `${b} show school`,
248
+ `${b} set school --health-url https://mail.example.com/ --health-text Inbox`,
249
+ `${b} set school --tabs-max 5 --tabs-popups keep --settle 250ms`,
250
+ `${b} set school --block-trackers true --cache --json`,
251
+ `${b} set school --humanize light`,
252
+ `${b} set school --sharing tabs`,
253
+ `${b} login school --url https://example.com`,
254
+ `${b} doctor --fix`,
255
+ `${b} reputation school --json`,
256
+ `${b} vault add school mail --url https://mail.example.com --username alice`,
257
+ `${b} record school --flows --traces`,
258
+ `${b} flows school`,
259
+ `${b} replay school submit-timesheet --param password=keychain:school-password`,
260
+ `${b} traces school --open`,
261
+ `${b} set school --live true`,
262
+ `${b} live school`,
263
+ `${b} pause school`,
264
+ `${b} resume school`,
265
+ `${b} export school --out school.session --expires 2d`,
266
+ `${b} import school.session --as school-laptop`,
267
+ `${b} remove school --dry-run`,
268
+ `${b} bench --only-urls --url https://example.com --yes`,
269
+ `${b} do school open https://example.com`,
270
+ `${b} do school snapshot`,
271
+ `${b} do school click e12`,
272
+ `${b} do school end`,
273
+ ];
274
+ }
275
+ /** The subcommands, each with its help and completion data. */
276
+ function subcommands(c) {
277
+ const b = c.names.browser;
278
+ const alone = c.names.subject === "";
279
+ const run = (sub) => (args, io) => dispatch(c, sub, args, io);
280
+ // What only turno-browser on its own has: inside turno, `turno mcp sync` writes the agents'
281
+ // configs, `turno secret` stores secrets and `do` goes through mcpd, not a background server.
282
+ const own = alone
283
+ ? {
284
+ setup: {
285
+ summary: "print the MCP config that gives an agent an identity (Claude Code, Codex, Cursor...)",
286
+ synopsis: "<claude-code|codex|cursor|copilot|gemini|json> [--identity <id>] [--json]",
287
+ details: SETUP_DETAILS,
288
+ flags: ["--identity", "--json"],
289
+ json: SETUP_JSON,
290
+ run: run("setup"),
291
+ },
292
+ background: {
293
+ summary: "the background server do starts per identity: status, start, stop",
294
+ synopsis: "status|start|stop [<id>]",
295
+ ownHelp: true,
296
+ json: BACKGROUND_JSON,
297
+ run: (args, io) => backgroundCommand(c).run(args, io),
298
+ },
299
+ secret: {
300
+ summary: "store the secrets identity.json names as keychain:<item> (never printed)",
301
+ synopsis: "set|has|list|remove <item>",
302
+ ownHelp: true,
303
+ run: (args, io) => secretCommand(c).run(args, io),
304
+ },
305
+ }
306
+ : {};
307
+ return {
308
+ ...own,
309
+ // On its own the program says `list`, like `turno identity list`; turno browser keeps `identities`.
310
+ identities: {
311
+ summary: alone ? "same as list" : "list browser identities and whether they are in use",
312
+ hidden: alone,
313
+ synopsis: "[--json]",
314
+ flags: ["--json"],
315
+ json: IDENTITIES_JSON,
316
+ run: run("identities"),
317
+ },
318
+ list: {
319
+ summary: alone ? "list browser identities and whether they are in use" : "same as identities",
320
+ hidden: !alone,
321
+ synopsis: "[--json]",
322
+ flags: ["--json"],
323
+ json: IDENTITIES_JSON,
324
+ run: run("identities"),
325
+ },
326
+ add: {
327
+ summary: c.host.addSummary,
328
+ synopsis: "<id> [--timezone <zone>] [--locale <tag>] [--languages <tag,...>] [--region <CC>] [--health-url <url> --health-text <text>] [--dry-run]",
329
+ flags: ["--dry-run", ...ident.SETTINGS_FLAG_NAMES],
330
+ run: run("add"),
331
+ },
332
+ show: {
333
+ summary: "an identity's settings, session health and who holds it",
334
+ synopsis: "<id> [--json]",
335
+ flags: ["--json"],
336
+ json: ident.SHOW_JSON,
337
+ run: run("show"),
338
+ },
339
+ set: {
340
+ summary: "change an identity's identity.json (an empty value removes a setting)",
341
+ synopsis: `<id> ${ident.SET_SYNOPSIS}`,
342
+ details: ident.setDetails(c.names),
343
+ flags: ident.SET_FLAG_NAMES,
344
+ json: ident.SET_JSON,
345
+ run: run("set"),
346
+ },
347
+ doctor: {
348
+ summary: "check Chrome, a test launch and every identity (settings, lock, sign-in), with fixes",
349
+ synopsis: "[--fix] [--no-launch] [--json]",
350
+ flags: ["--fix", "--no-launch", "--json"],
351
+ json: ident.DOCTOR_JSON,
352
+ run: run("doctor"),
353
+ },
354
+ reputation: {
355
+ summary: "challenges each identity met per site (captcha, verify it's you, block) and their trend",
356
+ synopsis: "[<id>] [--json]",
357
+ flags: ["--json"],
358
+ json: ident.REPUTATION_JSON,
359
+ run: run("reputation"),
360
+ },
361
+ vault: {
362
+ summary: "credentials browser_login fills without showing them to the agent",
363
+ synopsis: "add|list|remove|submit <id> ...",
364
+ ownHelp: true,
365
+ run: (args, io) => vaultCommand(c).run(args, io),
366
+ },
367
+ record: {
368
+ summary: "what an identity records (flows, traces, screenshots); turn it on or off",
369
+ synopsis: "<id> [--flows] [--traces] [--screenshots] [--max-size <size>] [--off] [--dry-run] [--json]",
370
+ details: `With no flag, shows what the identity records and where. --flows, --traces and --screenshots
371
+ turn those on (the next Chrome start uses them), --off turns everything off; turn one off with
372
+ ${b} set <id> --record-traces false. All are off by default.
373
+
374
+ flows every session's actions saved as a flow (auto-<time>, newest 20 kept)
375
+ traces a Playwright trace of each browser session (${b} traces)
376
+ screenshots a screenshot after each action
377
+
378
+ Vault sign-ins never reach a flow, a trace or a screenshot: the trace stops before a fill and
379
+ starts again after the page navigates, and a password or one-time code is never saved.`,
380
+ flags: ["--flows", "--traces", "--screenshots", "--max-size", "--off", "--dry-run", "--json"],
381
+ json: flowCmd.RECORD_JSON,
382
+ run: run("record"),
383
+ },
384
+ flows: {
385
+ summary: "an identity's saved flows; name one to see its steps, --remove to delete it",
386
+ synopsis: "<id> [<flow>] [--remove] [--dry-run] [--json]",
387
+ flags: ["--remove", "--dry-run", "--json"],
388
+ json: flowCmd.FLOWS_JSON,
389
+ run: run("flows"),
390
+ },
391
+ replay: {
392
+ summary: "run a saved flow on the identity's Chrome, without an agent",
393
+ synopsis: "<id> <flow> [--param <name=value>]... [--from <step>] [--headless] [--json]",
394
+ details: `Runs the flow through turno-browser-mcp, the same way an agent's browser_replay does. A
395
+ sensitive parameter is never a value on the command line: pass --param <name>=keychain:<item>
396
+ (store it once with ${c.names.secretSet("<item>")}), or type it at the hidden prompt. When a step fails,
397
+ the report says which locators it tried; --from continues at a later step.`,
398
+ flags: ["--param", "--from", "--headless", "--json"],
399
+ json: flowCmd.REPLAY_JSON,
400
+ run: run("replay"),
401
+ },
402
+ traces: {
403
+ summary: "an identity's recordings (traces, screenshots); --open shows a trace in the viewer",
404
+ synopsis: "<id> [<recording>] [--open] [--segment <n>] [--json]",
405
+ details: `--open serves the trace on 127.0.0.1 with the trace viewer patchright-core ships and opens it
406
+ in your default browser; Ctrl-C stops it. A recording has one trace per stretch of activity (a
407
+ vault sign-in or the idle limit ends one): --segment picks one, the last by default.`,
408
+ flags: ["--open", "--segment", "--json"],
409
+ json: flowCmd.TRACES_JSON,
410
+ run: run("traces"),
411
+ },
412
+ live: {
413
+ summary: "watch the agent in an identity's browser and take the controls (opens the live view)",
414
+ synopsis: "<id> [--no-open] [--json]",
415
+ details: `Shows what the agent is doing (paused or not, its tabs) and opens the live view in your
416
+ default browser: the agent's tab as a picture, Pause and Resume buttons, and while the agent is
417
+ paused, your clicks, keys and scrolls go to the page. The view is served on 127.0.0.1 only; the
418
+ link it opens works once. Off by default: turn it on with ${b} set <id> --live true
419
+ (it starts with the next turno-browser-mcp for the identity).
420
+
421
+ Read mode (Lightpanda) has no pixels, attach mode is your own Chrome, which you already see, and
422
+ Camoufox (Firefox) has no Chrome screencast: there the view is off, and pause and resume still work. A page that holds a vault or password
423
+ value is never shown until it navigates.`,
424
+ flags: ["--no-open", "--json"],
425
+ json: liveCmd.LIVE_JSON,
426
+ run: run("live"),
427
+ },
428
+ pause: {
429
+ summary: "pause the agent in an identity's browser: its next call waits until you resume",
430
+ synopsis: "<id> [--json]",
431
+ details: `A call that is running finishes; the next one waits up to the identity's live wait (2m by
432
+ default), then fails and tells the agent you still have the browser. A batch or replay stops at its
433
+ next step. In a headed Chrome the agent's tab comes to the front. Needs the live view on.`,
434
+ flags: ["--json"],
435
+ json: liveCmd.LIVE_JSON,
436
+ run: run("pause"),
437
+ },
438
+ resume: {
439
+ summary: "give the browser back to the agent; each waiting call is told what changed",
440
+ synopsis: "<id> [--json]",
441
+ details: `The waiting calls go on. Each starts with a note: how long the pause lasted and what changed
442
+ (the current tab's URL and title, tabs opened and closed, your input in the view). When something
443
+ changed, a call that does more than read does not run, and the agent gets a fresh snapshot instead.`,
444
+ flags: ["--json"],
445
+ json: liveCmd.LIVE_JSON,
446
+ run: run("resume"),
447
+ },
448
+ export: {
449
+ summary: "write an identity's cookies and site storage to a file encrypted with a passphrase",
450
+ synopsis: "<id> --out <file> [--expires 7d] [--force]",
451
+ flags: ["--out", "--expires", "--force"],
452
+ run: run("export"),
453
+ },
454
+ import: {
455
+ summary: "replace an identity's session with an export (asks first), or create it",
456
+ synopsis: "<file> [--as <id>] [--yes] [--dry-run]",
457
+ flags: ["--as", "--yes", "--dry-run"],
458
+ run: run("import"),
459
+ },
460
+ remove: {
461
+ summary: "delete an identity, its saved logins and its vault",
462
+ synopsis: "<id> [--dry-run]",
463
+ flags: ["--dry-run"],
464
+ run: run("remove"),
465
+ },
466
+ rm: { summary: "same as remove", hidden: true, run: run("remove") },
467
+ login: {
468
+ summary: "open the identity's Chrome to sign in by hand once",
469
+ synopsis: "<id> [--url <url>]",
470
+ flags: ["--url"],
471
+ run: run("login"),
472
+ },
473
+ do: {
474
+ summary: "one action on an identity's browser from the shell: open, snapshot, click, type, read...",
475
+ synopsis: doSynopsis(c),
476
+ details: doDetails(c),
477
+ ownHelp: true,
478
+ json: DO_JSON,
479
+ flags: doFlagNames(c),
480
+ run: (args, io) => browserDo(c, args, io),
481
+ },
482
+ bench: {
483
+ summary: "check how each browser engine loads reference test pages and your URLs (asks first)",
484
+ synopsis: "[--engine <name>]... [--url <url>]... [--only-urls] [--yes] [--json]",
485
+ flags: ["--engine", "--url", "--only-urls", "--yes", "--json"],
486
+ json: BENCH_JSON,
487
+ run: run("bench"),
488
+ },
489
+ };
490
+ }
491
+ /**
492
+ * The identity commands, named and wired by `host`. turno-cli calls it through the typed api
493
+ * (`api.cli`) with its own host; the `turno-browser` program with `standaloneHost()`.
494
+ */
495
+ export function browserCli(host, deps) {
496
+ // Messages from the library (doctor fixes, errors) name the commands the way this host does.
497
+ useNames(host.names);
498
+ const c = context(host, deps);
499
+ const subs = subcommands(c);
500
+ const name = c.names.subject.trim() || c.names.program;
501
+ const command = group(name, `browser identities: ${c.names.browser} <command>`, subs, {
502
+ footer: host.footer,
503
+ examples: examples(c),
504
+ prefix: c.names.browser,
505
+ });
506
+ return {
507
+ command: {
508
+ ...command,
509
+ run: (args, io) => (shortDo(args, subs) ? browserDo(c, args, io) : command.run(args, io)),
510
+ },
511
+ subs,
512
+ run: (sub, args, io) => dispatch(c, sub, args, io),
513
+ };
514
+ }
515
+ //# sourceMappingURL=commands.js.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Shell completion for the turno-browser program: `turno-browser completion <shell>` prints the
3
+ * script, and the script calls `turno-browser __complete -- <words...>` for candidates. It only
4
+ * reads identity folders: completing never starts Chrome or reads the secret store.
5
+ */
6
+ import { type Sub } from "turno-core/cli";
7
+ /** Candidates for the last word, given the words before it (both after `turno-browser`). */
8
+ export declare function complete(words: readonly string[], subs: Record<string, Sub>, env: NodeJS.ProcessEnv): string[];
9
+ /** `turno-browser completion <shell>`: the script, or undefined for an unknown shell. */
10
+ export declare function completionScript(program: string, shell: string | undefined): string | undefined;
11
+ export declare const COMPLETION_USAGE: (program: string) => string;
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Shell completion for the turno-browser program: `turno-browser completion <shell>` prints the
3
+ * script, and the script calls `turno-browser __complete -- <words...>` for candidates. It only
4
+ * reads identity folders: completing never starts Chrome or reads the secret store.
5
+ */
6
+ import { SHELLS, completionScripts } from "turno-core/cli";
7
+ import { listIdentities } from "../identities.js";
8
+ import { ACTION_NAMES } from "./do.js";
9
+ import { SETUP_AGENTS } from "./setup.js";
10
+ /** Commands whose first argument is an identity. */
11
+ const IDENTITY_FIRST = new Set([
12
+ "show",
13
+ "set",
14
+ "login",
15
+ "remove",
16
+ "export",
17
+ "record",
18
+ "flows",
19
+ "replay",
20
+ "traces",
21
+ "live",
22
+ "pause",
23
+ "resume",
24
+ "do",
25
+ "reputation",
26
+ ]);
27
+ /** Commands with their own subcommands, and whether an identity follows the subcommand. */
28
+ const NESTED = {
29
+ background: { subs: ["status", "start", "stop"], identity: true },
30
+ vault: { subs: ["add", "list", "remove", "submit"], identity: true },
31
+ secret: { subs: ["set", "has", "list", "remove"], identity: false },
32
+ };
33
+ /** Flags whose value can be completed: a list, or the identities, or a path. */
34
+ const FLAG_VALUES = {
35
+ "--identity": "identity",
36
+ "--engine": ["chrome", "lightpanda", "camoufox"],
37
+ "--out": "file",
38
+ "--color": ["auto", "always", "never"],
39
+ };
40
+ const GLOBAL_FLAGS = ["--help", "--version", "--no-input", "--color"];
41
+ function identities(env) {
42
+ try {
43
+ return listIdentities(env).map((i) => i.id);
44
+ }
45
+ catch {
46
+ return [];
47
+ }
48
+ }
49
+ /** Candidates for the last word, given the words before it (both after `turno-browser`). */
50
+ export function complete(words, subs, env) {
51
+ const cur = words[words.length - 1] ?? "";
52
+ const before = words.slice(0, -1);
53
+ const match = (list) => [...new Set(list)].filter((c) => c.startsWith(cur));
54
+ const visible = Object.keys(subs).filter((s) => !subs[s].hidden);
55
+ const commands = [...visible, "help", "completion"];
56
+ if (before.length === 0)
57
+ return match(cur.startsWith("-") ? GLOBAL_FLAGS : commands);
58
+ const [name, ...rest] = before;
59
+ const prev = before[before.length - 1];
60
+ const value = FLAG_VALUES[prev];
61
+ if (value && before.length > 1) {
62
+ if (value === "file")
63
+ return [":file"];
64
+ return match(value === "identity" ? identities(env) : value);
65
+ }
66
+ if (name === "help")
67
+ return before.length === 1 ? match(visible) : [];
68
+ if (name === "completion")
69
+ return before.length === 1 ? match(SHELLS) : [];
70
+ const sub = subs[name];
71
+ if (!sub)
72
+ return [];
73
+ if (cur.startsWith("-"))
74
+ return match([...(sub.flags ?? []), "--help"]);
75
+ // The positional arguments typed so far, without flags and the values they took.
76
+ const positionals = rest.filter((a, i) => !a.startsWith("-") && !(i > 0 && FLAG_VALUES[rest[i - 1]]));
77
+ const n = positionals.length;
78
+ const nested = NESTED[name];
79
+ if (nested) {
80
+ if (n === 0)
81
+ return match(nested.subs);
82
+ return n === 1 && nested.identity ? match(identities(env)) : [];
83
+ }
84
+ if (name === "setup")
85
+ return n === 0 ? match(SETUP_AGENTS) : [];
86
+ if (name === "import")
87
+ return n === 0 ? [":file"] : [];
88
+ if (IDENTITY_FIRST.has(name) && n === 0)
89
+ return match(identities(env));
90
+ if (name === "do" && n === 1)
91
+ return match(ACTION_NAMES);
92
+ return [];
93
+ }
94
+ /** `turno-browser completion <shell>`: the script, or undefined for an unknown shell. */
95
+ export function completionScript(program, shell) {
96
+ const scripts = completionScripts(program);
97
+ return shell && shell in scripts ? scripts[shell] : undefined;
98
+ }
99
+ export const COMPLETION_USAGE = (program) => [
100
+ `Usage: ${program} completion <zsh|bash|fish>`,
101
+ "",
102
+ "Prints the completion script: commands, identities, flags and do actions. To load it in every shell:",
103
+ ` zsh echo 'source <(${program} completion zsh)' >> ~/.zshrc`,
104
+ ` bash echo 'eval "$(${program} completion bash)"' >> ~/.bashrc`,
105
+ ` fish ${program} completion fish > ~/.config/fish/completions/${program}.fish`,
106
+ ].join("\n");
107
+ //# sourceMappingURL=completion.js.map