turno-cli 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.
Files changed (116) hide show
  1. package/CHANGELOG.md +266 -0
  2. package/README.md +134 -42
  3. package/dist/accounts/audit.js +27 -15
  4. package/dist/accounts/builtin.js +35 -7
  5. package/dist/accounts/delegate.js +30 -7
  6. package/dist/accounts/policy.js +4 -2
  7. package/dist/accounts/registry.js +3 -1
  8. package/dist/agents/adapter.js +22 -0
  9. package/dist/agents/claude.js +54 -3
  10. package/dist/agents/codex.js +94 -6
  11. package/dist/agents/copilot.js +19 -2
  12. package/dist/agents/cursor.js +19 -2
  13. package/dist/agents/index.js +1 -1
  14. package/dist/agents/snippets.js +37 -10
  15. package/dist/cli/args.js +32 -15
  16. package/dist/cli/commands/accounts.js +29 -7
  17. package/dist/cli/commands/auto.js +50 -12
  18. package/dist/cli/commands/browser-do-session.js +170 -0
  19. package/dist/cli/commands/browser-do.js +740 -0
  20. package/dist/cli/commands/browser-flows.js +300 -0
  21. package/dist/cli/commands/browser-identity.js +952 -0
  22. package/dist/cli/commands/browser-live.js +118 -0
  23. package/dist/cli/commands/browser-session.js +102 -0
  24. package/dist/cli/commands/browser-vault.js +193 -0
  25. package/dist/cli/commands/browser.js +303 -62
  26. package/dist/cli/commands/complete.js +13 -3
  27. package/dist/cli/commands/completion.js +4 -0
  28. package/dist/cli/commands/config.js +90 -13
  29. package/dist/cli/commands/demo.js +36 -7
  30. package/dist/cli/commands/doctor.js +170 -36
  31. package/dist/cli/commands/identity.js +101 -12
  32. package/dist/cli/commands/init.js +42 -10
  33. package/dist/cli/commands/limit.js +65 -9
  34. package/dist/cli/commands/mcp-call.js +240 -0
  35. package/dist/cli/commands/mcp-oauth.js +33 -6
  36. package/dist/cli/commands/mcp-observe.js +128 -23
  37. package/dist/cli/commands/mcp-share.js +201 -0
  38. package/dist/cli/commands/mcp.js +203 -42
  39. package/dist/cli/commands/mcpd.js +76 -12
  40. package/dist/cli/commands/open.js +26 -3
  41. package/dist/cli/commands/profile.js +212 -30
  42. package/dist/cli/commands/resolve.js +8 -1
  43. package/dist/cli/commands/run.js +24 -4
  44. package/dist/cli/commands/secret.js +23 -38
  45. package/dist/cli/commands/session.js +16 -5
  46. package/dist/cli/commands/sessions.js +7 -1
  47. package/dist/cli/commands/setup.js +83 -11
  48. package/dist/cli/commands/status.js +67 -15
  49. package/dist/cli/commands/statusline.js +7 -2
  50. package/dist/cli/commands/ui.js +17 -5
  51. package/dist/cli/commands/undo.js +39 -7
  52. package/dist/cli/commands/uninstall.js +24 -5
  53. package/dist/cli/commands/upgrade.js +113 -76
  54. package/dist/cli/commands/usage.js +11 -10
  55. package/dist/cli/commands/version.js +20 -8
  56. package/dist/cli/commands/which.js +5 -3
  57. package/dist/cli/diagnostics.js +184 -0
  58. package/dist/cli/exit.js +65 -0
  59. package/dist/cli/group.js +20 -8
  60. package/dist/cli/help.js +6 -1
  61. package/dist/cli/hints.js +30 -0
  62. package/dist/cli/io.js +24 -8
  63. package/dist/cli/launch.js +31 -2
  64. package/dist/cli/launchers.js +25 -10
  65. package/dist/cli/main.js +52 -18
  66. package/dist/cli/optional.js +144 -0
  67. package/dist/cli/output.js +123 -0
  68. package/dist/cli/picker.js +17 -5
  69. package/dist/cli/registry.js +20 -2
  70. package/dist/cli/safe.js +87 -0
  71. package/dist/cli/secret-input.js +63 -0
  72. package/dist/cli/security.js +31 -9
  73. package/dist/cli/style.js +35 -5
  74. package/dist/cli/topics.js +155 -0
  75. package/dist/core/config.js +39 -3
  76. package/dist/core/fsutil.js +2 -10
  77. package/dist/core/journal.js +19 -11
  78. package/dist/core/manifest.js +28 -1
  79. package/dist/core/paths.js +6 -112
  80. package/dist/core/profiles.js +28 -8
  81. package/dist/core/resolve.js +13 -3
  82. package/dist/core/secrets.js +4 -154
  83. package/dist/core/state-file.js +107 -0
  84. package/dist/core/update.js +14 -11
  85. package/dist/core/version.js +57 -10
  86. package/dist/demo/server.js +10 -2
  87. package/dist/mcpd/cache.js +6 -7
  88. package/dist/mcpd/calllog.js +10 -9
  89. package/dist/mcpd/client-names.js +8 -13
  90. package/dist/mcpd/connectors.js +42 -3
  91. package/dist/mcpd/daemon.js +29 -8
  92. package/dist/mcpd/folder-sets.js +5 -2
  93. package/dist/mcpd/gateway.js +57 -29
  94. package/dist/mcpd/health.js +70 -26
  95. package/dist/mcpd/importer.js +106 -9
  96. package/dist/mcpd/instances.js +70 -32
  97. package/dist/mcpd/jsonrpc.js +3 -1
  98. package/dist/mcpd/middleware.js +156 -0
  99. package/dist/mcpd/modern.js +57 -19
  100. package/dist/mcpd/oauth.js +71 -17
  101. package/dist/mcpd/peerpid.js +63 -17
  102. package/dist/mcpd/pressure.js +4 -1
  103. package/dist/mcpd/rss.js +34 -19
  104. package/dist/mcpd/service.js +28 -4
  105. package/dist/mcpd/share.js +217 -0
  106. package/dist/mcpd/state.js +16 -16
  107. package/dist/mcpd/sync.js +22 -12
  108. package/dist/mcpd/systemd.js +4 -1
  109. package/dist/mcpd/tokens.js +4 -8
  110. package/dist/mcpd/upstream.js +12 -5
  111. package/dist/statusline/cost.js +17 -4
  112. package/dist/statusline/input.js +15 -3
  113. package/dist/ui/fonts.js +1 -1
  114. package/dist/ui/settings.js +6 -1
  115. package/npm-shrinkwrap.json +12 -3
  116. package/package.json +7 -6
@@ -1,53 +1,43 @@
1
- import { execFileSync } from "node:child_process";
2
- import { createRequire } from "node:module";
3
- import { join } from "node:path";
4
- import { pathToFileURL } from "node:url";
5
1
  import { paths, tildify } from "../../core/paths.js";
6
- import { DRY_RUN, JSON_FLAG, bool, parseFlags, printJson, str } from "../args.js";
2
+ import { DRY_RUN, JSON_FLAG, bool, parseFlags, str } from "../args.js";
7
3
  import { group } from "../group.js";
8
4
  import { fail, needsAnswer, paint } from "../io.js";
9
- export const INSTALL_HINT = "npm install --global turno-browser";
10
- export const NOT_INSTALLED = `turno-browser is not installed: ${INSTALL_HINT}`;
11
- const SPEC = "turno-browser";
12
- function isMissing(err) {
13
- const code = err.code;
14
- return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED";
15
- }
16
- /** The global npm folder, where `npm install --global turno-browser` puts the package. */
17
- function npmGlobalRoot(env) {
18
- try {
19
- return execFileSync("npm", ["root", "--global"], { env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim() || undefined;
20
- }
21
- catch {
22
- return undefined;
23
- }
5
+ import { OPTIONAL, loadOptional, notInstalled } from "../optional.js";
6
+ import { emit, jsonOutput } from "../output.js";
7
+ import { ACTION_NAMES, DO_DETAILS, DO_JSON, DO_FLAG_NAMES, DO_SYNOPSIS, browserDo, defaultDoDeps, } from "./browser-do.js";
8
+ import * as flowCmd from "./browser-flows.js";
9
+ import * as ident from "./browser-identity.js";
10
+ import * as liveCmd from "./browser-live.js";
11
+ import * as session from "./browser-session.js";
12
+ import { vaultCommand } from "./browser-vault.js";
13
+ /** `turno browser bench --json`: turno-browser's report. */
14
+ const BENCH_JSON = jsonOutput(["version", "startedAt", "finishedAt", "engines", "results", "file"]);
15
+ /** `turno browser identities --json`: one element per identity. */
16
+ const IDENTITIES_JSON = jsonOutput(["id", "inUse", "dir"]);
17
+ /**
18
+ * The API version this turno was built against. Typed by the package's own constant, so a
19
+ * change of its API_VERSION in the workspace fails the typecheck until this line follows.
20
+ */
21
+ export const BROWSER_API = { major: 1, minor: 10 };
22
+ export const INSTALL_HINT = OPTIONAL.browser.install;
23
+ export const NOT_INSTALLED = notInstalled(OPTIONAL.browser);
24
+ /** A turno-browser this command can drive: its API object has the calls every subcommand needs. */
25
+ function isBrowserPackage(mod) {
26
+ const api = mod?.api;
27
+ return (typeof api === "object" &&
28
+ api !== null &&
29
+ Array.isArray(api.ENGINES) &&
30
+ typeof api.listIdentities === "function" &&
31
+ typeof api.runBench === "function");
24
32
  }
25
33
  /**
26
- * Load turno-browser: next to this install first, then (with `global`) from the global npm
27
- * folder, which a Homebrew or npx install of turno cannot see on its own.
34
+ * Load turno-browser's API: next to this install first, then (with `global`) from the global
35
+ * npm folder, which a Homebrew or npx install of turno cannot see on its own (loadOptional). A
36
+ * package whose API_VERSION does not fit is refused with one message that says what to update.
28
37
  */
29
38
  export async function loadBrowser(options = {}) {
30
- try {
31
- return (await import(SPEC));
32
- }
33
- catch (err) {
34
- if (!isMissing(err))
35
- throw err;
36
- }
37
- if (!options.global)
38
- return undefined;
39
- const root = npmGlobalRoot(options.env ?? process.env);
40
- if (!root)
41
- return undefined;
42
- try {
43
- const entry = createRequire(join(root, "noop.js")).resolve(SPEC);
44
- return (await import(pathToFileURL(entry).href));
45
- }
46
- catch (err) {
47
- if (isMissing(err))
48
- return undefined;
49
- throw err;
50
- }
39
+ const mod = await loadOptional(OPTIONAL.browser, { ...options, api: BROWSER_API, guard: isBrowserPackage });
40
+ return mod?.api;
51
41
  }
52
42
  async function askOnTerminal(question) {
53
43
  const { createInterface } = await import("node:readline/promises");
@@ -88,14 +78,16 @@ export const BENCH_PROMPT = "This opens Chrome and visits third-party test pages
88
78
  const URLS_PROMPT = "This opens Chrome and visits the URLs you gave. Continue? [y/N] ";
89
79
  async function bench(mod, args, io, deps) {
90
80
  const p = parseFlags(args, BENCH_FLAGS, 0);
91
- const list = (name) => (p.values[name] ?? []).flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
81
+ const list = (name) => (p.values[name] ?? [])
82
+ .flatMap((v) => v.split(","))
83
+ .map((v) => v.trim())
84
+ .filter(Boolean);
92
85
  const given = list("engine");
93
86
  const urls = p.values.url ?? [];
94
87
  const onlyUrls = bool(p, "only-urls") || bool(p, "no-detectors");
95
88
  const engines = [];
96
89
  for (const e of given) {
97
- // An older turno-browser has no engineId: its ENGINES list is the whole truth.
98
- const id = mod.engineId ? mod.engineId(e) : mod.ENGINES.includes(e) ? e : undefined;
90
+ const id = mod.engineId(e);
99
91
  if (!id)
100
92
  return fail(`unknown engine "${e}" (known: ${mod.ENGINES.join(", ")})`);
101
93
  engines.push(id);
@@ -125,7 +117,7 @@ async function bench(mod, args, io, deps) {
125
117
  onProgress: (m) => io.err(paint(io, m, "2")),
126
118
  });
127
119
  if (bool(p, "json")) {
128
- printJson(io, report);
120
+ emit(io, p, BENCH_JSON, report);
129
121
  }
130
122
  else {
131
123
  io.out(mod.formatBenchTable(report));
@@ -138,7 +130,7 @@ function identities(mod, args, io) {
138
130
  const p = parseFlags(args, JSON_FLAG, 0);
139
131
  const list = mod.listIdentities(io.env);
140
132
  if (bool(p, "json")) {
141
- printJson(io, list.map((i) => ({ id: i.id, inUse: i.inUse, dir: tildify(i.dir, io.env) })));
133
+ emit(io, p, IDENTITIES_JSON, list.map((i) => ({ id: i.id, inUse: i.inUse, dir: tildify(i.dir, io.env) })));
142
134
  return 0;
143
135
  }
144
136
  if (!list.length) {
@@ -153,26 +145,34 @@ function identities(mod, args, io) {
153
145
  return 0;
154
146
  }
155
147
  function add(mod, args, io) {
156
- const p = parseFlags(args, DRY_RUN, 1);
148
+ const p = parseFlags(args, { ...DRY_RUN, ...ident.SETTINGS_FLAGS }, 1);
157
149
  const id = checkId(mod, p.positionals[0], "add");
150
+ const settings = ident.settingsPatch(p);
158
151
  if (bool(p, "dry-run")) {
159
152
  io.out(`(dry run) would create browser identity "${id}"`);
160
153
  return 0;
161
154
  }
162
- const info = mod.addIdentity(id, io.env);
155
+ const info = ident.hasSettings(settings) ? mod.addIdentity(id, io.env, settings) : mod.addIdentity(id, io.env);
163
156
  io.out(`identity "${id}" ready at ${tildify(info.dir, io.env)}`);
157
+ io.out(`settings (time zone, languages, health check) in ${tildify(mod.identitySettingsPath(id, io.env), io.env)}`);
164
158
  io.out(`\nAdd this to ${tildify(paths(io.env).mcpFile, io.env)}, then run \`turno mcp sync\`:\n`);
165
- io.out(mod.manifestSnippet(id));
159
+ io.out(settings.sharing === "tabs" ? mod.manifestSnippet(id, { sharing: "tabs" }) : mod.manifestSnippet(id));
166
160
  io.out(`Sign in to your sites once with \`turno identity login browser:${id}\`.`);
167
161
  return 0;
168
162
  }
169
- function remove(mod, args, io) {
163
+ async function remove(mod, args, io) {
170
164
  const p = parseFlags(args, DRY_RUN, 1);
171
165
  const id = checkId(mod, p.positionals[0], "remove");
172
166
  if (bool(p, "dry-run")) {
173
- io.out(`(dry run) would delete browser identity "${id}" and its saved logins`);
167
+ io.out(`(dry run) would delete browser identity "${id}", its saved logins and its vault credentials`);
174
168
  return 0;
175
169
  }
170
+ if (mod.isInUse(id, io.env))
171
+ return fail(`identity "${id}" is in use by a running Chrome; close it first`);
172
+ // The vault's secret store items first: removeIdentity refuses while they exist.
173
+ const cleared = await mod.vaultClear(id, { env: io.env });
174
+ if (cleared)
175
+ io.out(`deleted ${cleared} vault credential${cleared === 1 ? "" : "s"} of "${id}" from the secret store`);
176
176
  mod.removeIdentity(id, io.env);
177
177
  io.out(`removed identity "${id}" and its saved browser data`);
178
178
  io.out(`Remove its [server.browser-${id}] block from ${tildify(paths(io.env).mcpFile, io.env)} if you added one.`);
@@ -184,6 +184,9 @@ async function login(mod, args, io) {
184
184
  const url = str(p, "url");
185
185
  if (url !== undefined && !/^https?:\/\//.test(url))
186
186
  return fail(`--url must start with http:// or https://: ${url}`);
187
+ const holder = mod.inUseBy(id, io.env);
188
+ if (holder)
189
+ return fail(holder);
187
190
  if (mod.isInUse(id, io.env)) {
188
191
  return fail(`identity "${id}" is in use by a running Chrome (probably an MCP session through mcpd). Close that session or wait for its lease to end, then retry.`);
189
192
  }
@@ -206,17 +209,44 @@ export async function dispatch(mod, sub, rest, io, deps = defaultDeps) {
206
209
  return add(mod, rest, io);
207
210
  case "remove":
208
211
  case "rm":
209
- return remove(mod, rest, io);
212
+ return await remove(mod, rest, io);
210
213
  case "login":
211
214
  return await login(mod, rest, io);
212
215
  case "bench":
213
216
  return await bench(mod, rest, io, deps);
217
+ case "export":
218
+ return await session.exportSession(mod, rest, io);
219
+ case "import":
220
+ return await session.importSession(mod, rest, io, deps);
221
+ case "show":
222
+ return ident.show(mod, checkId(mod, rest.find((a) => !a.startsWith("-")), "show"), rest, io);
223
+ case "set":
224
+ return ident.set(mod, checkId(mod, rest.find((a) => !a.startsWith("-")), "set"), rest, io);
225
+ case "doctor":
226
+ return await ident.doctor(mod, rest, io);
227
+ case "reputation":
228
+ return ident.reputation(mod, rest, io, (id) => checkId(mod, id, "reputation"));
229
+ case "flows":
230
+ return flowCmd.flows(mod, rest, io);
231
+ case "replay":
232
+ return await flowCmd.replay(mod, rest, io);
233
+ case "traces":
234
+ return await flowCmd.traces(mod, rest, io);
235
+ case "record":
236
+ return flowCmd.record(mod, rest, io);
237
+ case "live":
238
+ return await liveCmd.live(mod, rest, io, deps.openUrl);
239
+ case "pause":
240
+ return await liveCmd.pause(mod, rest, io);
241
+ case "resume":
242
+ return await liveCmd.resume(mod, rest, io);
214
243
  default:
215
244
  return fail(`unknown browser command "${sub}"`);
216
245
  }
217
246
  }
218
247
  catch (err) {
219
- if (err.name === "IdentityError")
248
+ const name = err.name;
249
+ if (["IdentityError", "VaultError", "SealError", "FlowError", "LiveError"].includes(name))
220
250
  return fail(err.message);
221
251
  throw err;
222
252
  }
@@ -225,9 +255,25 @@ const FOOTER = `A developer diagnostic for browser engine compatibility. It need
225
255
  turno-browser package (${INSTALL_HINT}).
226
256
  Identities are persistent Chrome profiles served by turno-browser-mcp, one session at a time
227
257
  through mcpd; turno identity manages them too (browser:<id>). Ids use lowercase letters,
228
- digits, "-" and "_", for example "school".`;
258
+ digits, "-" and "_", for example "school".
259
+ turno browser do <id> <action> runs one action (open, snapshot, click, type, read...) on an
260
+ identity's browser through mcpd, for coding agents that prefer shell commands (do --help).`;
261
+ /**
262
+ * `turno browser <id> <action>`, the short form of `turno browser do <id> <action>`: taken when
263
+ * the first word is not a browser subcommand and the second is an action. An identity named like
264
+ * a subcommand (`show`, `flows`) needs the long form, and the docs and the skill use the long form
265
+ * so a later subcommand can never change what a written command does.
266
+ */
267
+ function shortDo(args, subs) {
268
+ const [first, second] = args;
269
+ return (first !== undefined &&
270
+ second !== undefined &&
271
+ !(first in subs) &&
272
+ /^[a-z0-9][a-z0-9_-]*$/.test(first) &&
273
+ ACTION_NAMES.includes(second));
274
+ }
229
275
  /** The `browser` command, with its loader and prompt injectable for tests. */
230
- export function browserCommand(deps = defaultDeps) {
276
+ export function browserCommand(deps = defaultDeps, doDeps = defaultDoDeps) {
231
277
  const withModule = (sub) => async (args, io) => {
232
278
  const mod = await deps.load(io);
233
279
  if (!mod) {
@@ -237,20 +283,215 @@ export function browserCommand(deps = defaultDeps) {
237
283
  return dispatch(mod, sub, args, io, deps);
238
284
  };
239
285
  const subs = {
240
- identities: { summary: "list browser identities and whether they are in use", synopsis: "[--json]", flags: ["--json"], run: withModule("identities") },
286
+ identities: {
287
+ summary: "list browser identities and whether they are in use",
288
+ synopsis: "[--json]",
289
+ flags: ["--json"],
290
+ json: IDENTITIES_JSON,
291
+ run: withModule("identities"),
292
+ },
241
293
  list: { summary: "same as identities", hidden: true, run: withModule("identities") },
242
- add: { summary: "create an identity and print its mcp.toml block", synopsis: "<id> [--dry-run]", flags: ["--dry-run"], run: withModule("add") },
243
- remove: { summary: "delete an identity and its saved logins", synopsis: "<id> [--dry-run]", flags: ["--dry-run"], run: withModule("remove") },
294
+ add: {
295
+ summary: "create an identity (pinned to this time zone) and print its mcp.toml block",
296
+ synopsis: "<id> [--timezone <zone>] [--locale <tag>] [--languages <tag,...>] [--region <CC>] [--health-url <url> --health-text <text>] [--dry-run]",
297
+ flags: ["--dry-run", ...ident.SETTINGS_FLAG_NAMES],
298
+ run: withModule("add"),
299
+ },
300
+ show: {
301
+ summary: "an identity's settings, session health and who holds it",
302
+ synopsis: "<id> [--json]",
303
+ flags: ["--json"],
304
+ json: ident.SHOW_JSON,
305
+ run: withModule("show"),
306
+ },
307
+ set: {
308
+ summary: "change an identity's identity.json (an empty value removes a setting)",
309
+ synopsis: `<id> ${ident.SET_SYNOPSIS}`,
310
+ details: ident.SET_DETAILS,
311
+ flags: ident.SET_FLAG_NAMES,
312
+ json: ident.SET_JSON,
313
+ run: withModule("set"),
314
+ },
315
+ doctor: {
316
+ summary: "check Chrome, a test launch and every identity (settings, lock, sign-in), with fixes",
317
+ synopsis: "[--fix] [--no-launch] [--json]",
318
+ flags: ["--fix", "--no-launch", "--json"],
319
+ json: ident.DOCTOR_JSON,
320
+ run: withModule("doctor"),
321
+ },
322
+ reputation: {
323
+ summary: "challenges each identity met per site (captcha, verify it's you, block) and their trend",
324
+ synopsis: "[<id>] [--json]",
325
+ flags: ["--json"],
326
+ json: ident.REPUTATION_JSON,
327
+ run: withModule("reputation"),
328
+ },
329
+ vault: {
330
+ summary: "credentials browser_login fills without showing them to the agent",
331
+ synopsis: "add|list|remove|submit <id> ...",
332
+ ownHelp: true,
333
+ run: (args, io) => vaultCommand(deps).run(args, io),
334
+ },
335
+ record: {
336
+ summary: "what an identity records (flows, traces, screenshots); turn it on or off",
337
+ synopsis: "<id> [--flows] [--traces] [--screenshots] [--max-size <size>] [--off] [--dry-run] [--json]",
338
+ details: `With no flag, shows what the identity records and where. --flows, --traces and --screenshots
339
+ turn those on (the next Chrome start uses them), --off turns everything off; turn one off with
340
+ turno browser set <id> --record-traces false. All are off by default.
341
+
342
+ flows every session's actions saved as a flow (auto-<time>, newest 20 kept)
343
+ traces a Playwright trace of each browser session (turno browser traces)
344
+ screenshots a screenshot after each action
345
+
346
+ Vault sign-ins never reach a flow, a trace or a screenshot: the trace stops before a fill and
347
+ starts again after the page navigates, and a password or one-time code is never saved.`,
348
+ flags: ["--flows", "--traces", "--screenshots", "--max-size", "--off", "--dry-run", "--json"],
349
+ json: flowCmd.RECORD_JSON,
350
+ run: withModule("record"),
351
+ },
352
+ flows: {
353
+ summary: "an identity's saved flows; name one to see its steps, --remove to delete it",
354
+ synopsis: "<id> [<flow>] [--remove] [--dry-run] [--json]",
355
+ flags: ["--remove", "--dry-run", "--json"],
356
+ json: flowCmd.FLOWS_JSON,
357
+ run: withModule("flows"),
358
+ },
359
+ replay: {
360
+ summary: "run a saved flow on the identity's Chrome, without an agent",
361
+ synopsis: "<id> <flow> [--param <name=value>]... [--from <step>] [--headless] [--json]",
362
+ details: `Runs the flow through turno-browser-mcp, the same way an agent's browser_replay does. A
363
+ sensitive parameter is never a value on the command line: pass --param <name>=keychain:<item>
364
+ (store it once with turno secret set <item>), or type it at the hidden prompt. When a step fails,
365
+ the report says which locators it tried; --from continues at a later step.`,
366
+ flags: ["--param", "--from", "--headless", "--json"],
367
+ json: flowCmd.REPLAY_JSON,
368
+ run: withModule("replay"),
369
+ },
370
+ traces: {
371
+ summary: "an identity's recordings (traces, screenshots); --open shows a trace in the viewer",
372
+ synopsis: "<id> [<recording>] [--open] [--segment <n>] [--json]",
373
+ details: `--open serves the trace on 127.0.0.1 with the trace viewer patchright-core ships and opens it
374
+ in your default browser; Ctrl-C stops it. A recording has one trace per stretch of activity (a
375
+ vault sign-in or the idle limit ends one): --segment picks one, the last by default.`,
376
+ flags: ["--open", "--segment", "--json"],
377
+ json: flowCmd.TRACES_JSON,
378
+ run: withModule("traces"),
379
+ },
380
+ live: {
381
+ summary: "watch the agent in an identity's browser and take the controls (opens the live view)",
382
+ synopsis: "<id> [--no-open] [--json]",
383
+ details: `Shows what the agent is doing (paused or not, its tabs) and opens the live view in your
384
+ default browser: the agent's tab as a picture, Pause and Resume buttons, and while the agent is
385
+ paused, your clicks, keys and scrolls go to the page. The view is served on 127.0.0.1 only; the
386
+ link it opens works once. Off by default: turn it on with turno browser set <id> --live true
387
+ (it starts with the next turno-browser-mcp for the identity).
388
+
389
+ Read mode (Lightpanda) has no pixels, attach mode is your own Chrome, which you already see, and
390
+ 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
391
+ value is never shown until it navigates.`,
392
+ flags: ["--no-open", "--json"],
393
+ json: liveCmd.LIVE_JSON,
394
+ run: withModule("live"),
395
+ },
396
+ pause: {
397
+ summary: "pause the agent in an identity's browser: its next call waits until you resume",
398
+ synopsis: "<id> [--json]",
399
+ details: `A call that is running finishes; the next one waits up to the identity's live wait (2m by
400
+ default), then fails and tells the agent you still have the browser. A batch or replay stops at its
401
+ next step. In a headed Chrome the agent's tab comes to the front. Needs the live view on.`,
402
+ flags: ["--json"],
403
+ json: liveCmd.LIVE_JSON,
404
+ run: withModule("pause"),
405
+ },
406
+ resume: {
407
+ summary: "give the browser back to the agent; each waiting call is told what changed",
408
+ synopsis: "<id> [--json]",
409
+ details: `The waiting calls go on. Each starts with a note: how long the pause lasted and what changed
410
+ (the current tab's URL and title, tabs opened and closed, your input in the view). When something
411
+ changed, a call that does more than read does not run, and the agent gets a fresh snapshot instead.`,
412
+ flags: ["--json"],
413
+ json: liveCmd.LIVE_JSON,
414
+ run: withModule("resume"),
415
+ },
416
+ export: {
417
+ summary: "write an identity's cookies and site storage to a file encrypted with a passphrase",
418
+ synopsis: "<id> --out <file> [--expires 7d] [--force]",
419
+ flags: ["--out", "--expires", "--force"],
420
+ run: withModule("export"),
421
+ },
422
+ import: {
423
+ summary: "replace an identity's session with an export (asks first), or create it",
424
+ synopsis: "<file> [--as <id>] [--yes] [--dry-run]",
425
+ flags: ["--as", "--yes", "--dry-run"],
426
+ run: withModule("import"),
427
+ },
428
+ remove: {
429
+ summary: "delete an identity, its saved logins and its vault",
430
+ synopsis: "<id> [--dry-run]",
431
+ flags: ["--dry-run"],
432
+ run: withModule("remove"),
433
+ },
244
434
  rm: { summary: "same as remove", hidden: true, run: withModule("remove") },
245
- login: { summary: "open the identity's Chrome to sign in by hand once", synopsis: "<id> [--url <url>]", flags: ["--url"], run: withModule("login") },
435
+ login: {
436
+ summary: "open the identity's Chrome to sign in by hand once",
437
+ synopsis: "<id> [--url <url>]",
438
+ flags: ["--url"],
439
+ run: withModule("login"),
440
+ },
441
+ do: {
442
+ summary: "one action on an identity's browser from the shell: open, snapshot, click, type, read...",
443
+ synopsis: DO_SYNOPSIS,
444
+ details: DO_DETAILS,
445
+ ownHelp: true,
446
+ json: DO_JSON,
447
+ flags: [...DO_FLAG_NAMES],
448
+ run: (args, io) => browserDo(args, io, doDeps),
449
+ },
246
450
  bench: {
247
451
  summary: "check how each browser engine loads reference test pages and your URLs (asks first)",
248
452
  synopsis: "[--engine <name>]... [--url <url>]... [--only-urls] [--yes] [--json]",
249
453
  flags: ["--engine", "--url", "--only-urls", "--yes", "--json"],
454
+ json: BENCH_JSON,
250
455
  run: withModule("bench"),
251
456
  },
252
457
  };
253
- return group("browser", "developer tool: compare browser engines (needs turno-browser)", subs, { footer: FOOTER });
458
+ const command = group("browser", "developer tool: compare browser engines (needs turno-browser)", subs, {
459
+ footer: FOOTER,
460
+ examples: [
461
+ "turno browser identities",
462
+ "turno browser add school --languages es-MX,es,en",
463
+ "turno browser show school",
464
+ "turno browser set school --health-url https://mail.example.com/ --health-text Inbox",
465
+ "turno browser set school --tabs-max 5 --tabs-popups keep --settle 250ms",
466
+ "turno browser set school --block-trackers true --cache --json",
467
+ "turno browser set school --humanize light",
468
+ "turno browser set school --sharing tabs",
469
+ "turno browser login school --url https://example.com",
470
+ "turno browser doctor --fix",
471
+ "turno browser reputation school --json",
472
+ "turno browser vault add school mail --url https://mail.example.com --username alice",
473
+ "turno browser record school --flows --traces",
474
+ "turno browser flows school",
475
+ "turno browser replay school submit-timesheet --param password=keychain:school-password",
476
+ "turno browser traces school --open",
477
+ "turno browser set school --live true",
478
+ "turno browser live school",
479
+ "turno browser pause school",
480
+ "turno browser resume school",
481
+ "turno browser export school --out school.session --expires 2d",
482
+ "turno browser import school.session --as school-laptop",
483
+ "turno browser remove school --dry-run",
484
+ "turno browser bench --only-urls --url https://example.com --yes",
485
+ "turno browser do school open https://example.com",
486
+ "turno browser do school snapshot",
487
+ "turno browser do school click e12",
488
+ "turno browser do school end",
489
+ ],
490
+ });
491
+ return {
492
+ ...command,
493
+ run: (args, io) => (shortDo(args, subs) ? browserDo(args, io, doDeps) : command.run(args, io)),
494
+ };
254
495
  }
255
496
  export const command = browserCommand();
256
497
  //# sourceMappingURL=browser.js.map
@@ -48,10 +48,19 @@ async function values(kind, env) {
48
48
  case "server":
49
49
  return safe(() => Object.keys(loadManifest(env).servers), []);
50
50
  case "stamp":
51
- return ["last", ...listJournals(env).filter((j) => j.manifest).map((j) => j.stamp)];
51
+ return [
52
+ "last",
53
+ ...listJournals(env)
54
+ .filter((j) => j.manifest)
55
+ .map((j) => j.stamp),
56
+ ];
52
57
  case "key": {
53
58
  const { CONFIG_KEYS } = await import("./config.js");
54
- return CONFIG_KEYS.flatMap((k) => k.includes("<name>") ? profiles().map((p) => k.replace("<name>", p)) : k.includes("<agent>") ? AGENT_IDS.filter((a) => a !== DEFAULT_AGENT).map((a) => k.replace("<agent>", a)) : [k]);
59
+ return CONFIG_KEYS.flatMap((k) => k.includes("<name>")
60
+ ? profiles().map((p) => k.replace("<name>", p))
61
+ : k.includes("<agent>")
62
+ ? AGENT_IDS.filter((a) => a !== DEFAULT_AGENT).map((a) => k.replace("<agent>", a))
63
+ : [k]);
55
64
  }
56
65
  case "shell":
57
66
  return ["zsh", "bash", "fish"];
@@ -92,7 +101,8 @@ export async function complete(words, env) {
92
101
  return match(comp.flags ?? []);
93
102
  const positionals = args.filter((a, i) => !a.startsWith("-") && !(i > 0 && FLAG_VALUES[args[i - 1]]));
94
103
  const kinds = comp.args ?? [];
95
- const kind = kinds[positionals.length] ?? (kinds[kinds.length - 1] === "profile" && kinds.length === 1 && name === "profile" ? "profile" : undefined);
104
+ const kind = kinds[positionals.length] ??
105
+ (kinds[kinds.length - 1] === "profile" && kinds.length === 1 && name === "profile" ? "profile" : undefined);
96
106
  if (!kind)
97
107
  return [];
98
108
  if (kind === "dir")
@@ -45,6 +45,10 @@ export const command = {
45
45
  " zsh echo 'source <(turno completion zsh)' >> ~/.zshrc",
46
46
  " bash echo 'source <(turno completion bash)' >> ~/.bashrc",
47
47
  " fish turno completion fish > ~/.config/fish/completions/turno.fish",
48
+ "",
49
+ "Examples:",
50
+ " $ turno completion zsh",
51
+ " $ turno completion fish > ~/.config/fish/completions/turno.fish",
48
52
  ].join("\n"),
49
53
  args: ["shell"],
50
54
  async run(args, io) {