qz-browser-agent 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/args.mjs ADDED
@@ -0,0 +1,137 @@
1
+ import { parseArgs } from "node:util";
2
+ import { QzError } from "./client.mjs";
3
+ import { COMMANDS, commandOptions } from "./commands.mjs";
4
+
5
+ function invalid(message) {
6
+ throw new QzError("invalid_arguments", message);
7
+ }
8
+
9
+ function helpTopic(parts) {
10
+ if (parts.length === 0) return undefined;
11
+ if (!Object.hasOwn(COMMANDS, parts[0]) || parts[0] === "help") invalid(`Unknown help topic: ${parts.join(" ")}. Use qz --help.`);
12
+ if (parts.length === 1) return parts[0];
13
+ invalid("Use qz help COMMAND.");
14
+ }
15
+
16
+ /** Parse syntax only. A prompt or args value of "-" is read from stdin by the caller. */
17
+ export function parseCommand(argv) {
18
+ let parsed;
19
+ try {
20
+ parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
21
+ session: { type: "string", short: "s" }, timeout: { type: "string" },
22
+ title: { type: "string", short: "t" }, client: { type: "string", short: "c" },
23
+ "wait-id": { type: "string" }, format: { type: "string" }, query: { type: "string" },
24
+ start: { type: "string" }, limit: { type: "string" }, scope: { type: "string" }, filename: { type: "string" },
25
+ parent: { type: "string" },
26
+ wait: { type: "boolean" }, stream: { type: "boolean" }, steer: { type: "boolean" },
27
+ json: { type: "boolean" }, plain: { type: "boolean" }, "no-color": { type: "boolean" },
28
+ help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
29
+ } });
30
+ } catch (error) { invalid(error.message); }
31
+
32
+ const options = { ...parsed.values };
33
+ const seen = new Set();
34
+ for (const token of parsed.tokens) {
35
+ if (token.kind !== "option" || token.value === undefined) continue;
36
+ const name = token.name;
37
+ if (seen.has(name)) invalid(`Provide --${name} only once.`);
38
+ seen.add(name);
39
+ }
40
+ if (options.json && options.plain) invalid("Choose --json or --plain.");
41
+ if (options.version) {
42
+ if (parsed.positionals.length || Object.keys(options).some(name => !["version", "json", "plain", "no-color"].includes(name))) {
43
+ invalid("Use qz --version or qz -v without a command.");
44
+ }
45
+ return { command: "version", options };
46
+ }
47
+
48
+ const [originalCommand = "help", ...words] = parsed.positionals;
49
+ if (!Object.hasOwn(COMMANDS, originalCommand)) invalid(`Unknown command: ${originalCommand}. Use qz --help.`);
50
+ const allowed = new Set(commandOptions(originalCommand, words[0]));
51
+ for (const name of Object.keys(options)) {
52
+ if (!allowed.has(name)) invalid(`--${name} is not available for qz ${originalCommand}.`);
53
+ }
54
+ const timeoutSeconds = options.timeout === undefined ? originalCommand === "connect" ? 30 : 180 : Number(options.timeout);
55
+ if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0 || timeoutSeconds > 3600) invalid("--timeout must be greater than 0 and at most 3600 seconds.");
56
+ for (const name of ["session", "client", "wait-id", "parent"]) {
57
+ if (options[name] !== undefined && !options[name].trim()) invalid(`--${name} requires a non-empty ID.`);
58
+ }
59
+ if (options.filename !== undefined && !options.filename.trim()) invalid("--filename requires a non-empty name.");
60
+ if (options.scope !== undefined && !["all", "global", "site", "resident"].includes(options.scope)) invalid("--scope must be all, global, site, or resident.");
61
+ if (options.client !== undefined) {
62
+ options["client-id"] = options.client;
63
+ delete options.client;
64
+ }
65
+ for (const name of ["start", "limit"]) {
66
+ if (options[name] === undefined) continue;
67
+ const value = Number(options[name]);
68
+ if (!options[name].trim() || !Number.isSafeInteger(value) || value < (name === "start" ? 0 : 1) || (name === "limit" && value > 1000000)) {
69
+ invalid(name === "start" ? "--start must be a non-negative integer." : "--limit must be an integer from 1 to 1000000.");
70
+ }
71
+ options[name] = value;
72
+ }
73
+
74
+ if (originalCommand === "help") return { command: "help", helpTopic: helpTopic(words), options, timeoutSeconds };
75
+ if (options.help) {
76
+ const parts = originalCommand === "tasks" && words[0] ? [originalCommand, words[0]] : [originalCommand];
77
+ return { command: "help", helpTopic: helpTopic(parts), options, timeoutSeconds };
78
+ }
79
+
80
+ let command = originalCommand, action, id;
81
+ if (command === "send") {
82
+ id = words[0]; options.prompt = words.slice(1).join(" ");
83
+ if (!id?.trim() || !options.prompt.trim()) invalid('Use qz send TASK_ID "MESSAGE".');
84
+ } else if (command === "data" || command === "images" || command === "skills") {
85
+ action = words[0] || "list";
86
+ const actions = Object.keys(COMMANDS[command].actions);
87
+ const count = action === "list" || action === "tools" ? (words.length === 0 ? 0 : 1) : action === "read" ? 3 : 2;
88
+ if (!actions.includes(action) || words.length !== count || words.some(word => !word.trim())) {
89
+ invalid(`Use qz ${command} ${actions.join("|")}${command === "skills" ? " NAME" : command === "data" ? " TABLE" : " COLLECTION"}.`);
90
+ }
91
+ id = words[1];
92
+ if (command === "skills" && action === "read") { options.path = words[2]; options.start ??= 0; options.limit ??= 20000; }
93
+ if (command === "data" && action === "export") {
94
+ options.format ??= "xlsx";
95
+ if (!["csv", "xlsx"].includes(options.format)) invalid("--format must be csv or xlsx.");
96
+ }
97
+ } else if (command === "settings") {
98
+ action = words[0] || "get";
99
+ if (action === "get") {
100
+ if (words.length > 2 || (words.length === 2 && !words[1].trim())) invalid("Use qz settings get [KEY].");
101
+ id = words[1];
102
+ } else if (action === "set") {
103
+ if (words.length < 2 || words.length > 3 || !words[1].trim()) invalid("Use qz settings set KEY VALUE, or qz settings set JSON|-. ");
104
+ if (words.length === 3) { id = words[1]; options.value = words[2]; }
105
+ else options.args = words[1];
106
+ } else {
107
+ if (words.length !== 1 || !action.trim()) invalid("Use qz settings [get] [KEY], or qz settings set KEY VALUE.");
108
+ id = action; action = "get";
109
+ }
110
+ } else if (command === "automations") {
111
+ action = words[0] || "list";
112
+ if (action === "list" ? words.length > 1 : action !== "run" || words.length !== 2 || !words[1].trim()) invalid("Use qz automations [list], or qz automations run ID.");
113
+ id = words[1];
114
+ } else if (command === "create") {
115
+ options.prompt = words.join(" ");
116
+ if (!options.prompt.trim()) invalid('Provide a prompt, for example: qz create "Summarize the current page."');
117
+ command = "tasks"; action = "create";
118
+ } else if (command === "show" || command === "cancel") {
119
+ if (words.length !== 1 || !words[0].trim()) invalid(`Use qz ${command} TASK_ID.`);
120
+ action = command === "show" ? "get" : "stop";
121
+ command = "tasks"; id = words[0];
122
+ } else if (["approve", "reject", "watch", "submit"].includes(command)) {
123
+ const count = command === "submit" ? 2 : 1;
124
+ if (words.length !== count || words.some(word => !word.trim())) invalid(`Use qz ${command} TASK_ID${command === "submit" ? " JSON" : ""}.`);
125
+ id = words[0];
126
+ if (command === "submit") options.args = words[1];
127
+ if (command === "watch") options.wait = true;
128
+ } else if (command === "tasks") {
129
+ if (words.length) invalid("Use qz tasks to list tasks, qz create PROMPT, qz show ID, or qz cancel ID.");
130
+ action = "list";
131
+ } else if (words.length) {
132
+ invalid(`Use qz ${command} without additional arguments.`);
133
+ }
134
+ if (options.stream) options.wait = true;
135
+ const waitTimeoutSeconds = options.wait && options.timeout !== undefined ? timeoutSeconds : null;
136
+ return { command, action, id, options, timeoutSeconds, waitTimeoutSeconds };
137
+ }
package/src/bin.mjs ADDED
@@ -0,0 +1,25 @@
1
+ #!/usr/bin/env node
2
+ import { realpathSync } from "node:fs";
3
+ import { fileURLToPath } from "node:url";
4
+
5
+ // Keep this entry independent of the runtime and SDK until Node is validated.
6
+ let isEntry = false;
7
+ try { isEntry = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch {}
8
+ if (isEntry) {
9
+ const argv = process.argv.slice(2);
10
+ if (Number(process.versions.node.split(".")[0]) < 24) {
11
+ const error = {
12
+ code: "unsupported_node_version",
13
+ message: `qz requires Node.js 24 or later. Current version: ${process.versions.node}.`,
14
+ hint: "Install Node.js 24 or later, then run qz again.",
15
+ };
16
+ if (argv.includes("--json")) process.stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
17
+ else process.stderr.write(`${error.message}\n${error.hint}\n`);
18
+ process.exitCode = 1;
19
+ } else {
20
+ const { main } = await import("./cli.mjs");
21
+ const controller = new AbortController();
22
+ process.once("SIGINT", () => controller.abort());
23
+ process.exitCode = await main(argv, { signal: controller.signal });
24
+ }
25
+ }