@testin-official/xagent 0.3.12 → 0.3.14

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, realpathSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { Command, CommanderError } from "commander";
 import { fileURLToPath } from "node:url";
@@ -13,6 +13,13 @@ import { CliError, XAgentApiError } from "./core/errors.js";
 import { onInterrupt } from "./core/interrupt.js";
 import { CANONICAL_SCRIPT_SCHEMA_VERSION, CONFIG_SCHEMA_VERSION, DEVELOPER_API_VERSION, PRINCIPAL_SCHEMA_VERSION, PROJECT_SCHEMA_VERSION, PUBLIC_SCRIPT_SCHEMA_VERSION, VERSION } from "./core/version.js";
 import { loadProjectConfig } from "./project/config.js";
+import { isTerminalRunStatus, writeRunJUnitFile } from "./run/junit.js";
+import { writeBuildJUnitFile } from "./run/junit-suite.js";
+import { runScriptBatch } from "./run/batch.js";
+import { isMatrixTarget, previewMeetsAvailabilityRequirement } from "./project/target-matrix.js";
+import { collectRunScripts, shouldCollectScripts } from "./run/scripts.js";
+import { inferBuildStart } from "./run/builds.js";
+import { worstExitCode, exitCodeForRunStatus, API_EXIT } from "./run/exit-codes.js";
 import { createRunProgressReporter } from "./run/progress.js";
 import { parseYaml } from "./script/service.js";
 import { XAgentClient } from "./sdk/client.js";
@@ -21,14 +28,6 @@ import { runStdioServer } from "./mcp/server.js";
 import { MCP_MODES } from "./mcp/tools.js";
 import { detectHost, doctorHost, HOSTS, installHost, routeOutput, syncHost, uninstallHost, verifySkillDirectory } from "./integrations/manager.js";
 import { DEFAULT_WORKFLOW_DOMAIN, USER_WORKFLOW_DOMAINS, USER_WORKFLOW_ROUTES, routeForDomain } from "./integrations/routing.js";
-const API_EXIT = {
-    invalid_request: 2, schema_invalid: 2, configuration_invalid: 2, target_not_found: 2, target_invalid: 2,
-    target_hash_mismatch: 2, idempotency_conflict: 2, authoring_state_invalid: 2, revision_conflict: 2, action_in_progress: 2, observation_stale: 2,
-    attempt_in_progress: 2, authentication_required: 3, token_invalid: 3, token_expired: 3, token_revoked: 3,
-    token_type_mismatch: 3, permission_denied: 3, cancelled: 4, device_unavailable: 5, resource_not_found: 5,
-    authoring_session_expired: 5, authoring_session_not_active: 5,
-    test_failed: 1, infrastructure_failed: 6, invalid_response: 6, authoring_session_renewal_failed: 6, timeout: 7,
-};
 // `fail()` runs from the top-level catch, where the parsed options are out of
 // scope. It used to re-derive the output format from `process.argv` — a second
 // source of truth next to the `ctx.json` every other path uses, and the wrong
@@ -180,7 +179,28 @@ function billingText(value) {
     return billing ? ` billing=${billing.status} minutes=${billing.billable_minutes} cost=${billing.cost}` : "";
 }
 function emitRun(ctx, run, useStatusExit = true) { emit(ctx, run, `Run ${run.id} status=${run.status}${billingText(run)}`); if (!useStatusExit)
-    return; process.exitCode = { failed: 1, cancelled: 4, infrastructure_failed: 6, timed_out: 7 }[run.status] ?? 0; }
+    return; process.exitCode = exitCodeForRunStatus(run.status, run.reason) ?? 0; }
+function junitIncompleteReason(status, error, aborted = false) {
+    if (isTerminalRunStatus(status))
+        return undefined;
+    if (aborted)
+        return "cancelled";
+    if (error instanceof XAgentApiError && error.code === "timeout")
+        return "wait_timeout";
+    if (error instanceof XAgentApiError && error.code === "cancelled")
+        return "cancelled";
+    return "incomplete";
+}
+async function maybeWriteJUnit(file, run, options) {
+    if (!file || !run)
+        return;
+    try {
+        await writeRunJUnitFile(String(file), run, options);
+    }
+    catch (error) {
+        process.stderr.write(`Warning: unable to write --junit ${file}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}
 function progressReporter(ctx) { return createRunProgressReporter(ctx); }
 /** Human summary for `doctor`, derived from the same checks the JSON reports. */
 function doctorSummary(checks, profile) {
@@ -430,16 +450,44 @@ const targets = program.command("targets");
 targets.command("list").action(async function () { const ctx = context(this); const project = await loadProjectConfig(ctx.projectConfig); emit(ctx, { schema_version: PROJECT_SCHEMA_VERSION, config_path: project.path, default_target: project.defaultTarget, targets: project.listTargets().map((item) => ({ name: item.name, target_hash: item.targetHash, target: item.definition, default: item.name === project.defaultTarget })) }); });
 targets.command("show").argument("<name>").action(async function (name) { const ctx = context(this); const project = await loadProjectConfig(ctx.projectConfig); const item = project.resolveTarget(name); emit(ctx, { schema_version: PROJECT_SCHEMA_VERSION, config_path: project.path, name: item.name, target_hash: item.targetHash, target: item.definition, default: name === project.defaultTarget }); });
 targets.command("validate").argument("[name]").action(async function (name) { const ctx = context(this); const project = await loadProjectConfig(ctx.projectConfig); const selected = name ? [project.resolveTarget(name)] : project.listTargets(); emit(ctx, { valid: true, schema_version: PROJECT_SCHEMA_VERSION, config_path: project.path, targets: selected.map((item) => ({ name: item.name, target_hash: item.targetHash, target: item.definition })) }, `${project.path}: valid (${selected.length} Targets)`); });
-targets.command("preview").argument("<name>").action(async function (name) { const ctx = context(this); const project = await loadProjectConfig(ctx.projectConfig); const item = project.resolveTarget(name); const { profile, client } = await authenticatedClient(ctx); requireProjectCi(profile, "Target preview"); emit(ctx, await client.previewTarget({ schema_version: "xagent-target-preview/v1", target_name: item.name, target_hash: item.targetHash, target: item.definition })); });
+targets.command("preview").argument("<name>").option("--require-available", "Exit with device_unavailable (5) when fewer devices are available than the Target requests").action(async function (name, options) {
+    const ctx = context(this);
+    const project = await loadProjectConfig(ctx.projectConfig);
+    const item = project.resolveTarget(name);
+    const { profile, client } = await authenticatedClient(ctx);
+    requireProjectCi(profile, "Target preview");
+    const preview = await client.previewTarget({ schema_version: "xagent-target-preview/v1", target_name: item.name, target_hash: item.targetHash, target: item.definition });
+    emit(ctx, preview);
+    if (options.requireAvailable && !previewMeetsAvailabilityRequirement(preview)) {
+        const requested = Number(preview?.requested_count);
+        const available = Number(preview?.available_count);
+        if (Number.isInteger(requested) && requested > 1) {
+            process.stderr.write(`Target ${item.name} needs ${requested} devices, ${Number.isInteger(available) ? available : 0} available\n`);
+        }
+        else {
+            process.stderr.write(`Target ${item.name} has no available device\n`);
+        }
+        process.exitCode = API_EXIT.device_unavailable;
+    }
+});
 const apps = program.command("apps");
 apps.command("list").option("--keyword <text>").option("--app-name <name>").option("--package-name <name>").option("--page <number>").option("--page-size <number>").action(async function (options) { const ctx = context(this); const query = { keyword: options.keyword, app_name: options.appName, package_name: options.packageName, page: options.page, page_size: options.pageSize }; const result = await (await authenticatedClient(ctx)).client.listApps(query); emit(ctx, result, `${result.total} application package(s)`); });
 apps.command("show").argument("<packageId>").action(async function (packageId) { const ctx = context(this); const parsed = Number(packageId); if (!Number.isInteger(parsed) || parsed < 1)
     throw new CliError("invalid_request", "package-id must be a positive integer"); const result = await (await authenticatedClient(ctx)).client.getApp(parsed); emit(ctx, result, `${result.package_id}: ${result.package_name}`); });
-apps.command("upload").argument("<apkFile>").option("--upload-timeout <seconds>", undefined, "900").action(async function (apkFile, options) { const ctx = context(this); if (!apkFile.toLowerCase().endsWith(".apk"))
-    throw new CliError("invalid_request", "apps upload requires an APK file"); const { client } = await authenticatedClient(ctx, Number(options.uploadTimeout) * 1000); const result = await client.uploadApp(apkFile, (done, total) => (ctx.json ? process.stderr : process.stdout).write(`APK 分片上传：${done}/${total}\n`)); emit(ctx, result, `Uploaded ${apkFile}: package_id=${result.package_id} package=${result.app?.package_name}`); });
+apps.command("upload").argument("<apkFile>").option("--upload-timeout <seconds>", undefined, "900").option("--promote", "Keep the uploaded package so several Runs can use its package_id").action(async function (apkFile, options) {
+    const ctx = context(this);
+    if (!apkFile.toLowerCase().endsWith(".apk"))
+        throw new CliError("invalid_request", "apps upload requires an APK file");
+    const { client } = await authenticatedClient(ctx, Number(options.uploadTimeout) * 1000);
+    let result = await client.uploadApp(apkFile, (done, total) => (ctx.json ? process.stderr : process.stdout).write(`APK 分片上传：${done}/${total}\n`));
+    if (options.promote)
+        result = await client.promoteApp(String(result.id));
+    emit(ctx, result, `Uploaded ${apkFile}: package_id=${result.package_id} package=${result.app?.package_name} status=${result.status}`);
+});
 apps.command("release").argument("<appUploadId>").action(async function (id) { const ctx = context(this); const { client } = await authenticatedClient(ctx); const result = await client.releaseApp(id); emit(ctx, result, `App upload ${id} status=${result.status}`); });
+apps.command("promote").argument("<appUploadId>").action(async function (id) { const ctx = context(this); const { client } = await authenticatedClient(ctx); const result = await client.promoteApp(id); emit(ctx, result, `App upload ${id} status=${result.status} package_id=${result.package_id}`); });
 program.command("run")
-    .argument("<scriptFile>")
+    .argument("<paths...>", "Script files, directories of xagent-script/v1 YAML, or globs")
     .option("--package-id <id>")
     .option("--app-upload-id <id>")
     .option("--apk <path>")
@@ -448,12 +496,45 @@ program.command("run")
     .option("--idempotency-key <key>")
     .option("--var <assignment>", "Runtime variable NAME=VALUE", (value, previous) => [...previous, value], [])
     .option("--timeout-ms <milliseconds>", undefined, "600000")
+    .option("--device-wait-timeout-ms <milliseconds>", "How long a v2 Run may wait for a busy device before failing (0 disables queueing; default 600000)", "600000")
     .option("--wait")
     .option("--wait-timeout <seconds>", undefined, "900")
     .option("--poll-interval <seconds>", "Seconds between Run status checks while --wait is active", "2")
     .option("--upload-timeout <seconds>", undefined, "900")
-    .action(async function (scriptFile, options) {
+    .option("--run-id-file <path>", "Write the Run ID to this file as soon as the Run is created")
+    .option("--output <path>", "Write the last known Run JSON to this file")
+    .option("--junit <path>", "Write a JUnit XML report for this Run, or a suite report when multiple scripts or a matrix Target are used")
+    .option("--build-id <id>", "Attach created Runs to an existing build")
+    .option("--build <mode>", "Pass auto to start a build, attach every Run, and close it when the command ends")
+    .option("--max-parallel <count>", "How many Runs to submit at once (default 1)", "1")
+    .option("--promote", "Promote --app-upload-id to a reusable package_id before submitting multiple scripts or a matrix Target")
+    .action(async function (paths, options) {
     const ctx = context(this);
+    const maxParallel = Number(options.maxParallel);
+    if (!Number.isInteger(maxParallel) || maxParallel < 1)
+        throw new CliError("invalid_request", "--max-parallel must be a positive integer");
+    let buildAuto = String(options.build ?? "") === "auto";
+    if (options.build !== undefined && !buildAuto)
+        throw new CliError("invalid_request", "--build only accepts auto");
+    if (options.buildId && buildAuto)
+        throw new CliError("invalid_request", "--build-id and --build auto cannot be used together");
+    let useBatch = Boolean(options.buildId) || buildAuto || await shouldCollectScripts(paths);
+    try {
+        const target = (await loadProjectConfig(ctx.projectConfig)).resolveTarget(options.target);
+        if (isMatrixTarget(target.definition)) {
+            useBatch = true;
+            if (!options.buildId && !buildAuto)
+                buildAuto = true;
+        }
+    }
+    catch {
+        // The single-script or batch path will surface a missing or invalid project config.
+    }
+    if (useBatch) {
+        await runBatchFromCli(this, paths, options, maxParallel, buildAuto);
+        return;
+    }
+    const scriptFile = paths[0];
     const parsed = await loadScript(scriptFile);
     const supplied = [options.packageId, options.appUploadId, options.apk].filter((item) => item !== undefined).length;
     if (supplied > 1)
@@ -488,6 +569,11 @@ program.command("run")
     const pollIntervalSeconds = Number(options.pollInterval);
     if (!Number.isFinite(pollIntervalSeconds) || pollIntervalSeconds <= 0)
         throw new CliError("invalid_request", "--poll-interval must be a positive number of seconds");
+    const deviceWaitTimeoutMs = Number(options.deviceWaitTimeoutMs);
+    if (!Number.isInteger(deviceWaitTimeoutMs) || deviceWaitTimeoutMs < 0 || deviceWaitTimeoutMs > 3_600_000)
+        throw new CliError("invalid_request", "--device-wait-timeout-ms must be an integer from 0 to 3600000");
+    if (options.wait && waitTimeoutSeconds * 1000 <= timeoutMs + deviceWaitTimeoutMs)
+        process.stderr.write(`Warning: --wait-timeout ${waitTimeoutSeconds}s is not longer than --timeout-ms ${timeoutMs}ms plus --device-wait-timeout-ms ${deviceWaitTimeoutMs}ms; the CLI may stop waiting while the Run is still queued or running\n`);
     // One definition for "was a key supplied, and does it carry anything": the
     // personal branch tested the raw value while the project_ci branch tested the
     // trimmed one, so `--idempotency-key ""` slipped past the first check.
@@ -518,7 +604,7 @@ program.command("run")
         if (!suppliedIdempotencyKey)
             throw new CliError("invalid_request", "--idempotency-key is required for a project_ci Run");
         const target = (await loadProjectConfig(ctx.projectConfig)).resolveTarget(options.target);
-        request = { schema_version: "xagent-run-create/v2", script, target_name: target.name, target_hash: target.targetHash, target: target.definition, timeout_ms: timeoutMs, source_hash: parsed.sourceHash };
+        request = { schema_version: "xagent-run-create/v2", script, target_name: target.name, target_hash: target.targetHash, target: target.definition, timeout_ms: timeoutMs, device_wait_timeout_ms: deviceWaitTimeoutMs, source_hash: parsed.sourceHash };
     }
     const variables = parseVariables(options.var ?? []);
     if (Object.keys(variables).length)
@@ -530,7 +616,25 @@ program.command("run")
     // Ctrl+C would otherwise skip the finally below and leave both the APK
     // and a Run occupying a device allocated until each expires on its own.
     let createdRunId;
+    let latestRun;
+    let waitStartedAt;
+    const writeRunOutput = async () => {
+        if (!options.output || !latestRun)
+            return;
+        try {
+            await writeFile(options.output, `${JSON.stringify(latestRun, null, 2)}\n`, "utf8");
+        }
+        catch (error) {
+            process.stderr.write(`Warning: unable to write --output ${options.output}: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    };
     const waiting = new AbortController();
+    const writeJUnitOutput = () => maybeWriteJUnit(options.junit, latestRun, {
+        scriptName: typeof parsed.script?.name === "string" ? parsed.script.name : undefined,
+        scriptFile,
+        elapsedSeconds: waitStartedAt === undefined ? undefined : (Date.now() - waitStartedAt) / 1000,
+        incompleteReason: junitIncompleteReason(latestRun?.status, primaryError, waiting.signal.aborted),
+    });
     // `onInterrupt()` registers a cleanup and hands back its deregistration
     // function, so this is "detach", not "release" — calling it does not release
     // anything on its own.
@@ -555,6 +659,8 @@ program.command("run")
                 report(`Release app upload ${uploadedId}`, error);
             }
         }
+        await writeRunOutput();
+        await writeJUnitOutput();
     });
     try {
         if (options.apk) {
@@ -570,8 +676,19 @@ program.command("run")
             request.app_upload_id = options.appUploadId;
         run = await client.createRun(request, suppliedIdempotencyKey);
         createdRunId = String(run.id ?? "") || undefined;
+        latestRun = run;
+        if (options.runIdFile && createdRunId) {
+            try {
+                await writeFile(options.runIdFile, `${createdRunId}\n`, "utf8");
+            }
+            catch (error) {
+                process.stderr.write(`Warning: unable to write --run-id-file ${options.runIdFile}: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
         if (options.wait) {
-            run = await client.waitRun(run.id, waitTimeoutSeconds, pollIntervalSeconds, progressReporter(ctx), waiting.signal);
+            const reportProgress = progressReporter(ctx);
+            waitStartedAt = Date.now();
+            run = await client.waitRun(run.id, waitTimeoutSeconds, pollIntervalSeconds, (value) => { latestRun = value; reportProgress(value); }, waiting.signal);
             createdRunId = undefined; // reached a terminal state, nothing left to cancel
         }
     }
@@ -580,6 +697,8 @@ program.command("run")
         throw error;
     }
     finally {
+        await writeRunOutput();
+        await writeJUnitOutput();
         if (uploadedId) {
             const releasing = uploadedId;
             // Cleared only on success so an interrupt mid-release still retries it.
@@ -596,12 +715,198 @@ program.command("run")
     }
     emitRun(ctx, run);
 });
+const builds = program.command("builds");
+builds.command("start")
+    .option("--name <name>")
+    .option("--external-id <id>")
+    .option("--commit <sha>")
+    .option("--ref <name>")
+    .option("--source <source>", "gitlab, github, or other")
+    .option("--pipeline-url <url>")
+    .option("--idempotency-key <key>")
+    .action(async function (options) {
+    const ctx = context(this);
+    const profile = await selectedProfile(ctx);
+    requireProjectCi(profile, "builds start");
+    const inferred = inferBuildStart({
+        name: options.name,
+        externalId: options.externalId,
+        commit: options.commit,
+        ref: options.ref,
+        source: options.source,
+        pipelineUrl: options.pipelineUrl,
+        idempotencyKey: options.idempotencyKey,
+    });
+    const key = inferred.idempotency_key;
+    if (!key)
+        throw new CliError("invalid_request", "--idempotency-key is required when CI job metadata is not available");
+    const body = { schema_version: "xagent-build-create/v1", source: inferred.source ?? "other" };
+    if (inferred.name)
+        body.name = inferred.name;
+    if (inferred.external_id)
+        body.external_id = inferred.external_id;
+    if (inferred.commit_sha)
+        body.commit_sha = inferred.commit_sha;
+    if (inferred.ref)
+        body.ref = inferred.ref;
+    if (inferred.pipeline_url)
+        body.pipeline_url = inferred.pipeline_url;
+    const { client } = await authenticatedClient(ctx);
+    const build = await client.createBuild(body, key);
+    emit(ctx, build, `Build ${build.id} status=${build.status}`);
+});
+builds.command("show").argument("<buildId>").action(async function (buildId) {
+    const ctx = context(this);
+    const build = await (await authenticatedClient(ctx)).client.getBuild(buildId);
+    emit(ctx, build, `Build ${build.id} status=${build.status} runs=${(build.runs ?? []).length}`);
+});
+builds.command("wait").argument("<buildId>").option("--timeout <seconds>", undefined, "900").option("--poll-interval <seconds>", undefined, "2").option("--junit <path>", "Write a suite-level JUnit XML report for this build").action(async function (buildId, options) {
+    const ctx = context(this);
+    const started = Date.now();
+    const { client } = await authenticatedClient(ctx);
+    let latest;
+    let primaryError;
+    try {
+        const build = await client.waitBuild(buildId, Number(options.timeout), Number(options.pollInterval), (value) => { latest = value; });
+        latest = build;
+        const codes = (build.runs ?? []).map((item) => exitCodeForRunStatus(item.status, item.reason)).filter((code) => code !== undefined);
+        process.exitCode = codes.length ? worstExitCode(codes) : 0;
+        emit(ctx, build, `Build ${build.id} status=${build.status} runs=${(build.runs ?? []).length}`);
+    }
+    catch (error) {
+        primaryError = error;
+        throw error;
+    }
+    finally {
+        if (options.junit) {
+            try {
+                const build = latest ?? await client.getBuild(buildId);
+                const summaries = Array.isArray(build.runs) ? build.runs : [];
+                const runs = [];
+                for (const summary of summaries) {
+                    try {
+                        runs.push({ run: await client.getRun(String(summary.id)), options: { scriptName: summary.script_name, incompleteReason: junitIncompleteReason(summary.status, primaryError) } });
+                    }
+                    catch {
+                        runs.push({ run: summary });
+                    }
+                }
+                await writeBuildJUnitFile(String(options.junit), build, runs, { elapsedSeconds: (Date.now() - started) / 1000 });
+            }
+            catch (error) {
+                process.stderr.write(`Warning: unable to write --junit ${options.junit}: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+    }
+});
+builds.command("cancel").argument("<buildId>").option("--if-active", "Skip the cancel request when the build is already terminal").action(async function (buildId, options) {
+    const ctx = context(this);
+    const { client } = await authenticatedClient(ctx);
+    if (options.ifActive) {
+        const current = await client.getBuild(buildId);
+        if (["passed", "failed", "infrastructure_failed", "cancelled", "timed_out"].includes(String(current.status))) {
+            emit(ctx, current, `Build ${current.id} status=${current.status}`);
+            return;
+        }
+    }
+    const build = await client.cancelBuild(buildId);
+    emit(ctx, build, `Build ${build.id} status=${build.status} cancel_requested=${build.cancel_requested}`);
+});
 const runs = program.command("runs");
 runs.command("show").argument("<runId>").action(async function (runId) { const ctx = context(this); emitRun(ctx, await (await authenticatedClient(ctx)).client.getRun(runId), false); });
-runs.command("wait").argument("<runId>").option("--timeout <seconds>", undefined, "900").option("--poll-interval <seconds>", undefined, "2").action(async function (runId, options) { const ctx = context(this); const run = await (await authenticatedClient(ctx)).client.waitRun(runId, Number(options.timeout), Number(options.pollInterval), progressReporter(ctx)); emitRun(ctx, run); });
-runs.command("cancel").argument("<runId>").action(async function (runId) { const ctx = context(this); emitRun(ctx, await (await authenticatedClient(ctx)).client.cancelRun(runId), false); });
+runs.command("wait").argument("<runId>").option("--timeout <seconds>", undefined, "900").option("--poll-interval <seconds>", undefined, "2").option("--junit <path>", "Write a JUnit XML report for this Run to this file").action(async function (runId, options) {
+    const ctx = context(this);
+    const started = Date.now();
+    let latest;
+    let primaryError;
+    try {
+        const run = await (await authenticatedClient(ctx)).client.waitRun(runId, Number(options.timeout), Number(options.pollInterval), (value) => { latest = value; progressReporter(ctx)(value); });
+        latest = run;
+        emitRun(ctx, run);
+    }
+    catch (error) {
+        primaryError = error;
+        throw error;
+    }
+    finally {
+        await maybeWriteJUnit(options.junit, latest, { elapsedSeconds: (Date.now() - started) / 1000, incompleteReason: junitIncompleteReason(latest?.status, primaryError) });
+    }
+});
+runs.command("cancel").argument("<runId>").option("--if-active", "Skip the cancel request when the Run is already terminal or cancelling").action(async function (runId, options) {
+    const ctx = context(this);
+    const { client } = await authenticatedClient(ctx);
+    if (options.ifActive) {
+        const current = await client.getRun(runId);
+        if (["passed", "failed", "infrastructure_failed", "cancelled", "timed_out", "cancelling"].includes(String(current.status))) {
+            emitRun(ctx, current, false);
+            return;
+        }
+    }
+    emitRun(ctx, await client.cancelRun(runId), false);
+});
 program.command("mcp").option("--mode <mode>", `Isolated Tool surface: ${MCP_MODES.join(", ")}`, "action").action(async function (options) { const ctx = context(this); if (!MCP_MODES.includes(options.mode))
     throw new CliError("invalid_request", `mcp --mode must be one of: ${MCP_MODES.join(", ")}`); await runStdioServer(ctx.profile, ctx.userConfig, undefined, options.mode); });
+async function runBatchFromCli(command, paths, options, maxParallel, buildAuto) {
+    const ctx = context(command);
+    const scripts = await collectRunScripts(paths);
+    const supplied = [options.packageId, options.appUploadId, options.apk].filter((item) => item !== undefined).length;
+    if (supplied > 1)
+        throw new CliError("invalid_request", "--package-id, --app-upload-id and --apk are mutually exclusive");
+    if (options.apk)
+        throw new CliError("token_type_mismatch", "project_ci Profile must use apps upload and --app-upload-id or --package-id", 3);
+    if (options.deviceId)
+        throw new CliError("token_type_mismatch", "project_ci Profile cannot use --device-id", 3);
+    const packageId = options.packageId ? Number(options.packageId) : undefined;
+    if (options.packageId && (!Number.isInteger(Number(packageId)) || Number(packageId) < 1))
+        throw new CliError("invalid_request", "--package-id must be a positive integer");
+    const timeoutMs = Number(options.timeoutMs);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 28_800_000)
+        throw new CliError("invalid_request", "--timeout-ms must be an integer from 1000 to 28800000");
+    const deviceWaitTimeoutMs = Number(options.deviceWaitTimeoutMs);
+    if (!Number.isInteger(deviceWaitTimeoutMs) || deviceWaitTimeoutMs < 0 || deviceWaitTimeoutMs > 3_600_000)
+        throw new CliError("invalid_request", "--device-wait-timeout-ms must be an integer from 0 to 3600000");
+    const waitTimeoutSeconds = Number(options.waitTimeout);
+    if (!Number.isFinite(waitTimeoutSeconds) || waitTimeoutSeconds < 0)
+        throw new CliError("invalid_request", "--wait-timeout must be a non-negative number of seconds");
+    if (options.wait && waitTimeoutSeconds * 1000 <= timeoutMs + deviceWaitTimeoutMs)
+        process.stderr.write(`Warning: --wait-timeout ${waitTimeoutSeconds}s is not longer than --timeout-ms ${timeoutMs}ms plus --device-wait-timeout-ms ${deviceWaitTimeoutMs}ms; the CLI may stop waiting while the Run is still queued or running\n`);
+    const pollIntervalSeconds = Number(options.pollInterval);
+    if (!Number.isFinite(pollIntervalSeconds) || pollIntervalSeconds <= 0)
+        throw new CliError("invalid_request", "--poll-interval must be a positive number of seconds");
+    const suppliedIdempotencyKey = options.idempotencyKey === undefined ? undefined : String(options.idempotencyKey).trim();
+    if (!suppliedIdempotencyKey)
+        throw new CliError("invalid_request", "--idempotency-key is required for a project_ci Run");
+    const profile = await selectedProfile(ctx);
+    requireProjectCi(profile, "run");
+    const { client } = await authenticatedClient(ctx);
+    const exitCode = await runScriptBatch({
+        ctx,
+        profile,
+        client,
+        scripts,
+        options: {
+            packageId,
+            appUploadId: options.appUploadId,
+            promote: Boolean(options.promote),
+            targetName: options.target,
+            timeoutMs,
+            deviceWaitTimeoutMs,
+            wait: Boolean(options.wait),
+            waitTimeoutSeconds,
+            pollIntervalSeconds,
+            variables: parseVariables(options.var ?? []),
+            baseIdempotencyKey: suppliedIdempotencyKey,
+            buildId: options.buildId,
+            buildAuto,
+            maxParallel,
+            output: options.output,
+            junit: options.junit,
+            resolveTarget: (name) => loadProjectConfig(ctx.projectConfig).then((config) => config.resolveTarget(name)),
+        },
+        emit: (data, human) => emit(ctx, data, human),
+    });
+    process.exitCode = exitCode;
+}
 export async function runCli(argv = process.argv) {
     parsedArgv = argv;
     parsedJsonMode = undefined;